The Media Mappings section of the job description contains various settings which help the Encoding Service to map the files properly during the Media Mapping phase

Media Mappings

Table of Contents

This job request section defines rules (regular expressions) for finding and mapping source media files, as well as for identifying language codes from filenames. This happens during the Media Mapping Phase.

{
    "MediaMappings": {
        "VideoStreamExpression": "^video.(mp4|avi|mov|mkv|mxf)$",
        "AudioMappings": {
            "VideoStreamAudioTracks": [
                {
                    "TrackIndices": [1,2],
                    "Language": "en"
                },
                {
                    "TrackIndices": [3, 4, 5, 6, 7, 8],
                    "Language": "en"
                }
            ]
        },
        "AudioFileLanguageExpression": "^audio-([a-zA-Z0-9\\-]+).mp3$",
        "SubtitleFileLanguageExpression": "^subtitle-([a-zA-Z0-9\\-]+).(vtt|ttml|srt)$",
        "CaptionFileLanguageExpression": "^caption-([a-zA-Z0-9\\-]+).(vtt|ttml|srt)$",
        "AudioStreams": [
            {
                "Language": "en",
                "FileNameExpression": "audio-en.mp3"
            },
            {
                "Language": "fr",
                "FileNameExpression": "audio-fr.mp3"
            }
        ],
        "SubtitleStreams": [
            {
                "Language": "en",
                "FileNameExpression": "subtitle-en.vtt"
            },
            {
                "Language": "fr",
                "FileNameExpression": "subtitle-fr.vtt"
            }
        ],
        "CaptionStreams": [
            {
                "Language": "en",
                "FileNameExpression": "caption-en.vtt"
            },
            {
                "Language": "fr",
                "FileNameExpression": "caption-fr.vtt"
            }
        ],
        "AudioLanguages": ["en", "fr"],
        "SubtitleLanguages": ["en", "fr"],
        "CaptionLanguages": ["en", "fr"]
    }
}
Property Description Use Case Required?

VideoStreamExpression

A regular expression for finding the main video file.

You must always provide this expression. Otherwise, Encoding is unable to find the video stream.

To specify just one file name, see an example below with SubtitleFileLanguageExpression.

Yes

AudioMappings

Specify which audio tracks in the video file are used and which characteristics they have. See Specifying the Audio Tracks for details about this feature.

If the autodetection of audio tracks is not sufficient for the video file, e.g. if each audio track in the file is simply a mono audio track. (In which case the encoder cannot know if the audio track is a part of a mono, stereo, 5.1 or other audio layout.)

Other use cases include: if you need to specify which audio tracks to take from the video file, or if you need to overwrite the video file’s audio track’s language value.

No. By default, the encoder will map the audio tracks automatically and usually this will suffice.

AudioFileLanguageExpression

A regular expression for finding the audio files.

Compose this regex if you have audio tracks as external media files. If you want to encode a video with an embedded audio track, remove this property from the job request.

To specify just one file name, see an example below with SubtitleFileLanguageExpression.

No by default. Required if you provide the AudioStreams list.

SubtitleFileLanguageExpression

A regular expression for finding the subtitles files.

Compose this regex if you have subtitles tracks in external files. Usually, they are external.

To search for exactly one subtitle file (language-en.vtt) and nothing else, use the regex: ^language-(en)\\.vtt Where (en) is the language code. The language code must be in its own regex group.

No by default. Required if you provide the SubtitleStreams list.

CaptionFileLanguageExpression

A regular expression for finding the captions files.

Same as for subtitles, but for captions.

No by default. Required if you provide the CaptionStreams list.

AudioStreams, SubtitleStreams, CaptionStreams

A list of objects defining per-language regular expressions for files.

If you have multiple external tracks with different file names, you can define this list to map each track to a language individually.

No

AudioLanguages, SubtitleLanguages, CaptionLanguages

A list of allowed languages for processing.

If you have source content in many languages, but want to pick only a few of them, you can pass this list of allowed languages. Other languages are then ignored. Note that you can provide only one of each file types (audio, subtitles, caption) with the same language code. If the same language code is used in multiple files, only one of them is used.

No

Revision History

The table below lists the document versions and any changes to them.

Version Date Description

1.0

October 20, 2020

* Initial version.

1.1

April 5, 2021

* Note about the AudioFileLanguageExpression property.

1.2

August 19, 2021

* Some notes for the VideoStreamExpression, AudioFileLanguageExpression, and SubtitleFileLanguageExpression properties.

1.3

January 17, 2023

* Added the AudioMappings feature.

1.4

February 28, 2024

* Removed name and sound from AudioMappings. (Sound is now calculated automatically.)