Stream Selection and Routing

Media Streams

An input container lists the video, audio and subtitle streams to include in the composition.

Each input stream in the composition is matched with a video, audio or subtitle track in the container. By default each stream is matched with the next track present in the container.

For example the following composition matches the video track v1 and the first two audio tracks a1 and a2 in the input1 container:

---
input:
  container:
  - name: input1
    video:
    - name: v1
    audio:
    - name: a1
    - name: a2

{
  "input": {
    "container": [
      {
        "name": "input1",
        "video": [
          {
            "name": "v1"
          }
        ],
        "audio": [
          {
            "name": "a1"
          },
          {
            "name": "a2"
          }
        ]
      }
    ]
  }
}

Stream Selection

Use the select operator to match an input stream to a specific track number in the container.

Tracks are numbered sequentially (starting at 1) for each media type. For example the following composition selects audio tracks a7 and a8 (excluding audio tracks 1 - 6):

---
input:
  container:
  - name: input1
    video:
    - name: v1
    audio:
    - name: a7
      select:
        track: 7
    - name: a8
      select:
        track: 8

{
  "input": {
    "container": [
      {
        "name": "input1",
        "video": [
          {
            "name": "v1"
          }
        ],
        "audio": [
          {
            "name": "a7",
            "select": {
              "track": 7
            }
          },
          {
            "name": "a8",
            "select": {
              "track": 8
            }
          }
        ]
      }
    ]
  }
}

The select operator can also match a track using an ISO 639 alpha-2 en or alpha-3 eng language code, for example::

---
input:
  container:
  - name: input1
    audio:
    - name: spanish
      select:
        language: spa

{
  "input": {
    "container": [
      {
        "name": "input1",
        "audio": [
          {
            "name": "spanish",
            "select": {
              "language": "spa"
            }
          }
        ]
      }
    ]
  }
}

See the Stream Operators reference for a complete list of stream selection methods.

Stream Routing

By default all of the streams selected from an input are automatically routed to the output container. Specific input streams can be routed to an output using the stream name, for example:

---
input:
  container:
  - name: input1
    audio:
    - name: a1
output:
  container:
  - name: output1
    audio:
    - name: a1

{
  "input": {
    "container": [
      {
        "name": "input1",
        "audio": [
          {
            "name": "a1"
          }
        ]
      }
    ]
  },
  "output": {
    "container": [
      {
        "name": "output1",
        "audio": [
          {
            "name": "a1"
          }
        ]
      }
    ]
  }
}

Use the route operator to explicitly route an input stream to an output stream. The previous example is equivalent to the following:

---
input:
  container:
  - name: input1
    audio:
    - name: a1
output:
  container:
  - name: output1
    audio:
    - route:
        name: a1

{
  "input": {
    "container": [
      {
        "name": "input1",
        "audio": [
          {
            "name": "a1"
          }
        ]
      }
    ]
  },
  "output": {
    "container": [
      {
        "name": "output1",
        "audio": [
          {
            "route": {
              "name": "a1"
            }
          }
        ]
      }
    ]
  }
}

Optional Streams

An input stream may be treated as optional. If the input stream is not present then any output stream referencing that input is removed from the composition.

For example the following composition has an optional Spanish language track:

---
input:
  container:
  - name: input1
    audio:
    - name: a1
    - name: a2
      optional: true
      select:
        language: 'spa'  
output:
  container:
  - name: output1
    audio:
    - route:
        name: a1
    - route:
        name: a2

{
  "input": {
    "container": [
      {
        "name": "input1",
        "audio": [
          {
            "name": "a1"
          },
          {
            "name": "a2",
            "optional": true,
            "select": {
              "language": "spa"
            }
          }
        ]
      }
    ]
  },
  "output": {
    "container": [
      {
        "name": "output1",
        "audio": [
          {
            "route": {
              "name": "a1"
            }
          },
          {
            "route": {
              "name": "a2"
            }
          }
        ]
      }
    ]
  }
}

Stream Exclusion

Input streams can be excluded from the composition by specifying an empty array. For example the following composition will exclude all video streams from the input container (only audio and subtitles will be routed to the outputs):

---
input:
  container:
  - name: input1
    video: []

{
  "input": {
    "container": [
      {
        "name": "input1",
        "video": []
      }
    ]
  }
}

Streams can be excluded from an output using the same notation. The following example excludes audio stream from the output container:

---
input:
  container:
  - name: input1
output:
  container:
  - name: output1
    type: 'mp4 '
    audio: []

{
  "input": {
    "container": [
      {
        "name": "input1"
      }
    ]
  },
  "output": {
    "container": [
      {
        "name": "output1",
        "type": "mp4 ",
        "audio": []
      }
    ]
  }
}