# 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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.

```json
{
  "uri": "/path/to/local/file.mp4"
}
```

```json
{
  "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:**
```json
{
  "type": "Video",
  "uri": "/path/to/raw.yuv",
  "params": {
    "f": "rawvideo",
    "video_size": "1920x1080",
    "framerate": "25",
    "pixel_format": "yuv420p"
  }
}
```

**Example - Hardware decoding:**
```json
{
  "type": "AudioVideo",
  "uri": "/path/to/video.mp4",
  "params": {
    "hwaccel": "cuda",
    "hwaccel_output_format": "cuda"
  }
}
```

For more information on hardware acceleration, see [Hardware-acceleration.md](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.

```json
{
  "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:
```json
{
  "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.

```json
{
  "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"`

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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`

```json
{
  "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"`

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](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

- [Encoding-profiles.md](Encoding-profiles.md) - Learn how to create profiles that reference your inputs
- [Hardware-acceleration.md](Hardware-acceleration.md) - Configure hardware encoders and decoders
- [API-reference.md](API-reference.md) - Complete API documentation for job submission

## 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.