Skip to content

Input configuration

Jump to bottom
Gustav Grusell edited this page Dec 12, 2025 · 1 revision

Input Configuration

Encore supports multiple input files in a single encoding job, allowing you to combine different media sources into your output. Each input can be configured with specific processing parameters, filters, and stream selection options.

Input Types

Encore provides three input types to match your source material:

AudioVideoInput

Use this type for media files that contain both audio and video streams. This is the most common input type for standard video files.

When to use:

  • Standard video files (MP4, MOV, MXF, etc.) with embedded audio
  • When you want to use both video and audio from the same file
  • When you need to process video and audio together

Example:

{
  "type": "AudioVideo",
  "uri": "/path/to/video.mp4"
}

VideoInput

Use this type when you only want to process the video stream from a file, ignoring any audio.

When to use:

  • You only need the video content
  • Combining video from one source with audio from another
  • Processing video-only files

Example:

{
  "type": "Video",
  "uri": "/path/to/video-only.mp4"
}

AudioInput

Use this type for audio-only files or when you only want to use the audio stream from a file.

When to use:

  • Audio-only files (MP3, AAC, WAV, etc.)
  • Extracting audio from video files
  • Adding alternative audio tracks (multilingual content, audio descriptions)

Example:

{
  "type": "Audio",
  "uri": "/path/to/audio.mp3"
}

Common Input Properties

All three input types share these properties:

uri (required)

The location of your input file. Can be a local file path or an S3 URL.

{
  "uri": "/path/to/local/file.mp4"
}
{
  "uri": "s3://my-bucket/path/to/file.mp4"
}

type (required)

Specifies the input type: "AudioVideo", "Video", or "Audio".

params

FFmpeg input parameters provided as key-value pairs. These parameters are passed directly to FFmpeg before the -i flag.

Common use cases:

  • Raw video format specification
  • Hardware decoder selection
  • Input format hints

Example - Raw video input:

{
  "type": "Video",
  "uri": "/path/to/raw.yuv",
  "params": {
    "f": "rawvideo",
    "video_size": "1920x1080",
    "framerate": "25",
    "pixel_format": "yuv420p"
  }
}

Example - Hardware decoding:

{
  "type": "AudioVideo",
  "uri": "/path/to/video.mp4",
  "params": {
    "hwaccel": "cuda",
    "hwaccel_output_format": "cuda"
  }
}

For more information on hardware acceleration, see Hardware-acceleration.md.

seekTo

Seek to a specific time (in seconds) before decoding the input. This performs an input-level seek, which is faster than output-level seeking but may be less accurate depending on the file format.

{
  "uri": "/path/to/video.mp4",
  "seekTo": 60.0
}

Input seekTo vs Job seekTo:

Encore provides two ways to seek:

  1. Input-level seeking (seekTo in input configuration): Fast but potentially less accurate. FFmpeg seeks in the input stream before decoding begins. Best for formats with good keyframe indexing.

  2. Job-level seeking (seekTo in job configuration): Slower but more accurate. Decodes from the beginning and discards frames until the seek point is reached. Guarantees frame-accurate seeking.

You can combine both methods for optimal results:

{
  "seekTo": 50.0,
  "inputs": [
    {
      "type": "AudioVideo",
      "uri": "/path/to/video.mp4",
      "seekTo": 50.0
    }
  ]
}

This seeks quickly to approximately 50 seconds at the input level, then performs frame-accurate positioning from that point at the output level.

copyTs

Preserve input timestamps when using seekTo. This is useful when seeking to avoid timestamp discontinuities.

{
  "uri": "/path/to/video.mp4",
  "seekTo": 30.0,
  "copyTs": true
}

Video Input Properties

VideoInput and AudioVideoInput support these additional properties:

videoLabel

A label that identifies this video input. Profile outputs can reference inputs by label, allowing you to use multiple video sources in the same job.

Default value: "main"

{
  "type": "Video",
  "uri": "/path/to/main-video.mp4",
  "videoLabel": "main"
}

dar

Display Aspect Ratio override. Use this when the input file has incorrect or missing aspect ratio metadata.

{
  "type": "Video",
  "uri": "/path/to/video.mp4",
  "dar": "16:9"
}

cropTo

Crop the input video to the specified aspect ratio before processing. This removes content from the edges to achieve the target aspect ratio.

{
  "type": "Video",
  "uri": "/path/to/4-3-video.mp4",
  "cropTo": "16:9"
}

This crops a 4:3 video by removing content from the top and bottom to achieve 16:9.

padTo

Pad the input video to the specified aspect ratio by adding black bars. This preserves all content while achieving the target aspect ratio.

{
  "type": "Video",
  "uri": "/path/to/4-3-video.mp4",
  "padTo": "16:9"
}

This adds black bars to the sides of a 4:3 video to achieve 16:9 (letterboxing).

Note: You can use both cropTo and padTo together. Encore will first crop, then pad. This is useful for converting between different aspect ratios while centering the content.

videoFilters

A list of FFmpeg video filters to apply to all video outputs derived from this input. Filters are applied in the order specified.

{
  "type": "Video",
  "uri": "/path/to/video.mp4",
  "videoFilters": [
    "unsharp=5:5:1.0:5:5:0.0",
    "eq=contrast=1.1:brightness=0.05"
  ]
}

Use cases:

  • Logo overlays
  • Color correction
  • Sharpening or blurring
  • Custom processing specific to this input

Filters specified here apply to all outputs that use this input. For output-specific filters, configure filters in your encoding profile instead.

videoStream

The index of the video stream to use when the input file contains multiple video streams.

{
  "type": "Video",
  "uri": "/path/to/multi-stream.mxf",
  "videoStream": 1
}

Stream indices start at 0. If not specified, Encore uses the first video stream.

probeInterlaced

Whether to probe the input for interlaced content. When enabled, Encore will detect interlacing and apply deinterlacing filters automatically.

Default value: true

{
  "type": "Video",
  "uri": "/path/to/video.mp4",
  "probeInterlaced": false
}

Set to false if you know your content is progressive to skip interlacing detection.

Audio Input Properties

AudioInput and AudioVideoInput support these additional properties:

audioLabel

A label that identifies this audio input. Profile outputs can reference inputs by label, allowing you to use multiple audio sources in the same job.

Default value: "main"

{
  "type": "Audio",
  "uri": "/path/to/german-audio.mp3",
  "audioLabel": "german"
}

channelLayout

A hint for the channel layout when the input file contains mono audio streams that need to be combined into a multichannel layout. If the input has fewer channels than specified in the layout, Encore will use default (silent) channels for the missing positions.

Available layouts: "mono", "stereo", "5.1", "5.1(side)", "7.1", and many more. See the ChannelLayout enum in the codebase for the full list.

{
  "type": "Audio",
  "uri": "/path/to/six-mono-streams.mxf",
  "channelLayout": "5.1"
}

This is particularly useful for professional broadcast formats where audio is stored as separate mono streams.

audioFilters

A list of FFmpeg audio filters to apply to all audio outputs derived from this input. Filters are applied in the order specified.

{
  "type": "Audio",
  "uri": "/path/to/audio.mp3",
  "audioFilters": [
    "volume=1.5",
    "highpass=f=200"
  ]
}

Use cases:

  • Volume normalization
  • Equalization
  • Noise reduction
  • Custom audio processing specific to this input

audioStream

The index of the audio stream to use when the input file contains multiple audio streams.

{
  "type": "Audio",
  "uri": "/path/to/multi-audio.mxf",
  "audioStream": 2
}

Stream indices start at 0. If not specified, Encore uses the first audio stream.

Using Multiple Inputs with Labels

Labels allow you to use multiple video and audio sources in a single encoding job. Your encoding profile can reference specific inputs by their labels.

Example: Multilingual Audio

Create outputs with different audio tracks from separate audio files:

{
  "profile": "multilingual-output",
  "baseName": "content",
  "outputFolder": "/output",
  "inputs": [
    {
      "type": "AudioVideo",
      "uri": "/path/to/main-video.mp4",
      "videoLabel": "main",
      "audioLabel": "english"
    },
    {
      "type": "Audio",
      "uri": "/path/to/german-audio.mp3",
      "audioLabel": "german"
    },
    {
      "type": "Audio",
      "uri": "/path/to/spanish-audio.mp3",
      "audioLabel": "spanish"
    }
  ]
}

Your encoding profile would reference these labels in its output configuration to create separate files for each language.

Example: Sign Language Video Overlay

Combine a main video with a smaller sign language interpretation video:

{
  "profile": "sign-language-overlay",
  "baseName": "accessible-content",
  "outputFolder": "/output",
  "inputs": [
    {
      "type": "AudioVideo",
      "uri": "/path/to/main-content.mp4",
      "videoLabel": "main",
      "audioLabel": "main"
    },
    {
      "type": "Video",
      "uri": "/path/to/sign-language.mp4",
      "videoLabel": "sign"
    }
  ]
}

Your encoding profile would use video filters to overlay the sign language video in the corner of the main video.

Example: Separate Video and Audio Sources

Use video from one file and audio from another:

{
  "profile": "video-with-replacement-audio",
  "baseName": "output",
  "outputFolder": "/output",
  "inputs": [
    {
      "type": "Video",
      "uri": "/path/to/video.mp4",
      "videoLabel": "main"
    },
    {
      "type": "Audio",
      "uri": "/path/to/better-audio.wav",
      "audioLabel": "main"
    }
  ]
}

Complete Input Configuration Example

Here's a comprehensive example showing many input properties:

{
  "profile": "advanced-encoding",
  "baseName": "output",
  "outputFolder": "/output/path",
  "seekTo": 1.0,
  "duration": 30.0,
  "inputs": [
    {
      "type": "Video",
      "uri": "/path/to/main-video.mp4",
      "videoLabel": "main",
      "videoStream": 0,
      "seekTo": 1.0,
      "dar": "16:9",
      "cropTo": "16:9",
      "videoFilters": [
        "eq=contrast=1.1"
      ],
      "params": {
        "hwaccel": "cuda"
      }
    },
    {
      "type": "Audio",
      "uri": "/path/to/surround-audio.mxf",
      "audioLabel": "main",
      "audioStream": 0,
      "channelLayout": "5.1",
      "seekTo": 1.0,
      "audioFilters": [
        "volume=1.2"
      ]
    },
    {
      "type": "Audio",
      "uri": "/path/to/german-audio.mp3",
      "audioLabel": "german",
      "seekTo": 1.0
    }
  ]
}

Best Practices

  1. Use appropriate input types: Choose VideoInput, AudioInput, or AudioVideoInput based on what you actually need from each file. This makes your intent clear and can improve processing efficiency.

  2. Label your inputs meaningfully: Use descriptive labels like "german", "sign", or "commentary" rather than generic names. This makes profiles more readable and maintainable.

  3. Consistent seeking: When using multiple inputs, apply the same seekTo value to all inputs to keep them synchronized.

  4. Input-specific filters: Use videoFilters and audioFilters in the input configuration for processing that should apply to all outputs using that input. Use profile-level filters for output-specific processing.

  5. Hardware acceleration: Configure hardware decoders in the params property of the input that will benefit most. For more details, see Hardware-acceleration.md.

  6. Stream selection: When working with complex media files (like MXF or multi-stream MP4), explicitly specify videoStream and audioStream to ensure you're using the correct streams.

  7. Aspect ratio handling: Use cropTo when you want to remove content to change aspect ratio, and padTo when you want to preserve all content. Combine them when converting between significantly different aspect ratios (e.g., 4:3 to 16:9).

Related Documentation

Troubleshooting

Problem: "Inputs contains duplicate audio labels" error

Solution: Ensure each audio input has a unique audioLabel. If you have multiple AudioInput or AudioVideoInput entries, they must all have different audio labels.

Problem: "Inputs contains duplicate video labels" error

Solution: Ensure each video input has a unique videoLabel. If you have multiple VideoInput or AudioVideoInput entries, they must all have different video labels.

Problem: Seeking is not accurate

Solution: Use a combination of input-level and job-level seeking. Set seekTo on the input for fast seeking, then set seekTo on the job for frame-accurate positioning.

Problem: Audio and video are out of sync

Solution: Ensure all inputs have the same seekTo value, or use copyTs: true to preserve timestamps when seeking.

Clone this wiki locally