Media Mappings

File naming convention

This is how you can use simple file naming conventions for finding and categorizing source media files and tracks.

{
  "MediaMappings": {
    "MediaDetection": "Convention",
    "FallbackLanguageCode": "de",
    "FailOnIgnoredFiles": true,
    "FailOnIgnoredTracks": true
  }
}

Property	Description	Use Case	Required?
MediaDetection	If file naming convention or regex should be used for media detection and categorizing.	Set to `Convention` (recommended) to use a simpler way of detecting media.	No. Currently defaults to `Regex`, but `Convention` will be made the default in the future.
FallbackLanguageCode	Language code that is assigned to a language track if one cannot be found in the file name or track metadata	If you want to change the default fallback language code (`en`) or you do not want to use one (in which case the job fails if a language code cannot be detected)	No. Default is `en`.
FailOnIgnoredFiles	Fail the job if any files were not grabbed from the acquisition folder. This usually happens because of unsupported file extensions or mismatching regular expressions.	Safeguard if you know you need all the files from the acquisition folder. We recommend leaving this enabled and only keeping the necessary media files in the acquisition folder.	No. Default is `false`.
FailOnIgnoredTracks	Fail the job if any tracks in the files that were downloaded were not used	Safeguard if you know you need all the tracks from the source media and any of them getting ignored requires investigation	No. Default is `false`.

Regex

This is how you can use regex for finding and mapping source media files, as well as for identifying language codes from filenames. This happens during the Media Mapping Phase.

{
  "MediaMappings": {
    "MediaDetection": "Regex",
    "VideoStreamExpression": "^video.(mp4|avi|mov|mkv|mxf)$",
    "AudioFileLanguageExpression": "^audio-([a-zA-Z0-9\\-]+).mp3$",
    "DescriptiveAudioFileLanguageExpression": "^descriptive_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"],
    "FailOnNoVideoTracks": true,
    "FailOnNoAudioTracks": true,
    "FailOnNoSubtitleTracks": false,
    "FailOnNoCaptionTracks": false
  }
}

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
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.
DescriptiveAudioFileLanguageExpression	A regular expression for finding the descriptive audio files.	Compose this regex if you have descriptive audio tracks as external media files. To specify just one file name, see an example below with `SubtitleFileLanguageExpression`.	No
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
FailOnNoVideoTracks, FailOnNoAudioTracks	Fail the job if no video/ audio tracks are found in any of the acquired files. By default the value used is TRUE.	If you need the job to be processed, if there is no Video/ Audio Track, you can set NO.	No
FailOnNoSubtitleTracks, FailOnNoCaptionTracks	Fail the job if no subtitle/ caption tracks are found in any of the acquired files. By default the value used is NO.	If you need the job to be failed, if there is no subtitle/ caption Track, you can set TRUE.	No

File naming convention​

Regex​

File naming convention

Regex