Video Conversion

This guide explains how to configure the Video Service node in your pipelines to convert and process video files.

Overview

The Video Service processes video files using either FFmpeg or HandBrake converters. When adding a Video Service node to your pipeline, you need to configure:

• Input source - Where to read the source video file
• Output source - Where to save the processed video file
• Additional parameters - Converter type, configuration name, and config file location

Additional Parameters

The additional parameters field is a JSON object with three required fields:

{
  "converter_type": "ffmpeg" | "handbrake",
  "config_name": "preset-name",
  "config_source": { FileSource object }
}

Parameter Fields

Field	Type	Description
converter_type	string	Video converter to use: "ffmpeg" or "handbrake"
config_name	string	Name of the encoding preset/configuration to use
config_source	FileSource	Location of the configuration file

Converter Type:

• "ffmpeg" - Use FFmpeg encoder (flexible, supports multiple inputs/outputs)
• "handbrake" - Use HandBrake encoder (standard single-file transcoding)

Config Name:

• For HandBrake: The name of the preset to use from your HandBrake configuration file
• For FFmpeg: An identifier for the configuration (should match the name field in your FFmpeg config file for clarity)

Config Source:

• A FileSource object pointing to your encoding preset configuration file
• See File Sources for details on FileSource format

Input and Output Sources

In addition to additional parameters, you must specify where to read input files and write output files using FileSource objects.

• Input Source - Where the Video Service reads the source video file
• Output Source - Where the processed video is saved

For complete details on FileSource syntax and supported storage types (local filesystem, remote via SSH), see File Sources.

Additional Parameters Examples

Example: HandBrake with Remote Config

{
  "converter_type": "handbrake",
  "config_name": "1080p H.264 High Quality Films **",
  "config_source": {
    "source_type": "ST_REMOTE_SOURCE",
    "remote_source": {
      "source": "[email protected]:/mnt/tank/main_data/main/Handbrake_1080p_High_Quality.json"
    }
  }
}

What this configures:

• Uses HandBrake converter
• Applies the "1080p H.264 High Quality Films **" preset
• Loads HandBrake configuration from remote server via SSH

Example: FFmpeg with Local Config

{
  "converter_type": "ffmpeg",
  "config_name": "h264-standard",
  "config_source": {
    "source_type": "ST_LOCAL_SOURCE",
    "local_source": {
      "source": "/etc/mediamoth/configs/h264-standard.json"
    }
  }
}

What this configures:

• Uses FFmpeg converter
• Applies the h264-standard configuration
• Loads FFmpeg configuration from local filesystem

TIP

In the MediaMoth web UI, you can pass the additional_parameters as a JSON object directly - no need to escape it as a string.

Configuration Files

Configuration files define how the video converter processes your media:

• FFmpeg configurations - Custom JSON format with template variables
• HandBrake configurations - Native HandBrake preset JSON files

For complete details on creating encoding presets, see Video Encoding Presets.

Simple FFmpeg Example

{
  "name": "h264-standard",
  "description": "Standard H.264 encoding with CRF 23",
  "template": [
    "-i", "{{.Input0}}",
    "-c:v", "libx264",
    "-preset", "medium",
    "-crf", "23",
    "-c:a", "aac",
    "-b:a", "128k",
    "-movflags", "+faststart",
    "{{.Output0}}"
  ]
}

Simple HandBrake Example

HandBrake configurations are exported directly from the HandBrake application. See the HandBrake Presets Guide for details.

Choosing FFmpeg vs HandBrake

Use FFmpeg when:

• You need multiple inputs or outputs
• You want advanced control over encoding parameters
• You need custom filters or complex processing
• You want to use template variables for dynamic configurations

Use HandBrake when:

• You prefer HandBrake's preset system
• You're converting a single input to a single output
• You want to use HandBrake-optimized encoding profiles
• You're already familiar with HandBrake settings

Typical Workflow

1. Prepare configuration file:

   • Create FFmpeg or HandBrake configuration file
   • Upload to accessible location (local filesystem or remote server via SSH)

2. Add Video Service node to pipeline:

   • Open pipeline editor in MediaMoth web UI
   • Add Video Service node

3. Configure node parameters:

   • Set input_source - Where to read source video
   • Set output_source - Where to save processed video
   • Set additional_parameters:
     • Choose converter_type ("ffmpeg" or "handbrake")
     • Set config_name (preset name)
     • Set config_source (location of config file)

4. Queue job:

   • Select media to process
   • Queue job with your configured pipeline
   • Monitor job progress

Next Steps

• Video Encoding Presets - Create FFmpeg and HandBrake configurations
• File Sources - Understand file source types and syntax
• Creating Pipelines - Build workflows with video conversion nodes
• Common Workflows - Example pipeline patterns