vimix/docs/TRANSCODER_USAGE.md

Transcoder Usage

The Transcoder class provides simple video transcoding functionality using GStreamer.

Features

• Transcodes any video format to H.264/MP4
• Automatically generates output filename (non-destructive)
• Provides progress monitoring
• Asynchronous operation

Basic Usage

#include "Transcoder.h"

// Create transcoder with input file
Transcoder transcoder("/path/to/input/video.mov");

// Output filename is automatically generated
std::cout << "Output will be: " << transcoder.outputFilename() << std::endl;
// Output: /path/to/input/video_transcoded.mp4

// Start transcoding with default options
if (!transcoder.start()) {
    std::cerr << "Failed to start: " << transcoder.error() << std::endl;
    return 1;
}

// Monitor progress
while (!transcoder.finished()) {
    double progress = transcoder.progress();  // 0.0 to 1.0
    std::cout << "Progress: " << (progress * 100) << "%" << std::endl;
    std::this_thread::sleep_for(std::chrono::milliseconds(500));
}

// Check result
if (transcoder.success()) {
    std::cout << "Success! Output: " << transcoder.outputFilename() << std::endl;
} else {
    std::cerr << "Failed: " << transcoder.error() << std::endl;
}

Advanced Usage with Options

#include "Transcoder.h"

// Create transcoder
Transcoder transcoder("/path/to/animation.mov");

// Configure transcoding options
TranscoderOptions options;
options.force_keyframes = true;              // Keyframe every second for easier editing
options.psy_tune = PsyTuning::ANIMATION;     // Optimize for animation content

// Start with options
if (!transcoder.start(options)) {
    std::cerr << "Failed: " << transcoder.error() << std::endl;
    return 1;
}

// Wait for completion...
while (!transcoder.finished()) {
    std::this_thread::sleep_for(std::chrono::milliseconds(500));
}

Common Configuration Examples

For Video Editing (Maximum Keyframes)

TranscoderOptions options;
options.force_keyframes = true;  // Keyframe every ~1 second
// Makes timeline scrubbing and frame-accurate editing much easier
transcoder.start(options);

For Film Content

TranscoderOptions options;
options.psy_tune = PsyTuning::FILM;  // Optimized for film/camera footage
transcoder.start(options);

For Animation

TranscoderOptions options;
options.psy_tune = PsyTuning::ANIMATION;  // Optimized for flat colors and sharp edges
transcoder.start(options);

For Grain Preservation

TranscoderOptions options;
options.psy_tune = PsyTuning::GRAIN;  // Preserve film grain detail
transcoder.start(options);

API Reference

Constructor

Transcoder(const std::string& input_filename)

Creates a transcoder for the specified input file. Output filename is automatically generated.

Enums and Structs

PsyTuning enum

Psycho-visual tuning options for x264 encoder:

• NONE - No specific tuning (default)
• FILM - Optimize for film/live action content
• ANIMATION - Optimize for animation with flat colors and sharp edges
• GRAIN - Preserve film grain detail
• STILL_IMAGE - Optimize for slideshow-style content

TranscoderOptions struct

Configuration options for transcoding:

• bool force_keyframes - Force keyframe every ~1 second (default: false)
  • When enabled: sets key-int-max=30 (keyframe every second at 30fps)
  • When disabled: sets key-int-max=250 (default, less frequent)
  • Useful for video editing to enable frame-accurate seeking
• PsyTuning psy_tune - Psycho-visual tuning preset (default: NONE)

Methods

bool start(const TranscoderOptions& options = TranscoderOptions())

Start the transcoding process with optional configuration.

• Parameters:
  • options - Transcoding configuration (keyframes, tuning, etc.)
• Returns: true if started successfully, false on error

bool finished() const

Check if transcoding has completed.

• Returns: true when transcoding is done (success or error)

bool success() const

Check if transcoding completed successfully.

• Returns: true only if finished AND successful

double progress() const

Get current transcoding progress.

• Returns: Value between 0.0 (starting) and 1.0 (complete)

const std::string& inputFilename() const

Get the input filename.

const std::string& outputFilename() const

Get the generated output filename.

const std::string& error() const

Get error message if transcoding failed.

• Returns: Error message string, empty if no error

Output Filename Generation

The transcoder automatically generates output filenames:

• Input: /path/to/video.mov
• Output: /path/to/video_transcoded.mp4

If the file exists, it adds a number:

• /path/to/video_transcoded_1.mp4
• /path/to/video_transcoded_2.mp4
• etc.

Technical Details

Pipeline

The transcoder uses the following GStreamer pipeline:

filesrc → decodebin → videoconvert → x264enc → mp4mux → filesink
                   ├→ audioconvert → avenc_aac ┘

Encoding Settings

• Video codec: H.264 (x264enc)
• Audio codec: AAC (avenc_aac)
• Container: MP4
• Speed preset: medium
• Keyframes: Configurable via force_keyframes option
  • Default: key-int-max=250 (keyframe every 250 frames)
  • Force mode: key-int-max=30 (keyframe every 30 frames, ~1 second at 30fps)
• Psycho-visual tuning: Configurable via psy_tune option

Requirements

• GStreamer 1.0+
• gstreamer-base
• gstreamer-pbutils
• x264 encoder plugin
• AAC encoder plugin