Media Detection
As of this time, file naming convention is supported only in our REST API. It will be coming also to Mosaic Video Service soon.
There are two methods for specifying which source files get picked up and what their additional* properties (language code and if they are Closed Caption ("CC") or Descriptive Audio ("AD") tracks): file naming convention (recommended) and regex (more versatile).
Note: currently, regex is the default method when using the REST API.
* We also analyze the metadata of all the media tracks and take the necessary information from there if it is not signalled using the convention or the regex expressions
File naming convention (recommended)
In this mode, all files with supported file types are picked up and analysed.
If all the properties you need are already present in the source media metadata then you generally don't need to do anything else.
If you want to specify or overwrite the language code or other properties, use the following markers in the file names:
| Marker | Situated At | Example | Comments |
|---|---|---|---|
| Language code | end | subtitle-en.vtt | See more information |
ad | middle end | audio-ad-en.m4a audio-ad.m4a | Descriptive Audio Must be an audio track |
cc | beginning middle end | cc-en.vtt movie-cc-en.vtt movie-cc.vtt | Closed Captions Must be a text track |
Unless marked as CC, text tracks are considered as subtitles.
All conventions are case-insensitive (-cc- is the same as -CC-).
Regex (more versatile)
In this mode, all files that are matched with the regular expressions are picked up.
Use a regex group to mark the language code in the file name and name this group lang. Use the different regexes to mark the tracks in the file as CC or AD.
To use this mode, set MediaDetection to Regex (currently the default when using REST API).
Note: for historical reasons, if you do not assign the name lang to a regex group the first group in the expression is considered to contain the language code.
Language code
| File name | Regex | Meaning | Comments |
|---|---|---|---|
| audio-en-US.m4a subtitle-de-de.vtt | ^(audio|subtitle)[^-]*-(?<lang>[a-zA-Z0-9-]+).(m4a|vtt)$ | Language code group is named lang | Dash is allowed with regex Language group named <lang> does not have to be first |
| audio-en-US.m4a video-de-de.mp4 | ^[^-]*-([a-zA-Z0-9-]+).(m4a|mp4)$ | Language code group is first group | If lang is not used, language code must be in first group |
Video
Only the tracks in the files that were matched with VideoStreamExpression are picked up.
Audio
Only the tracks in the files that were matched with AudioFileLanguageExpression or VideoStreamExpression are picked up.
(VideoStreamExpression is considered in order to detect audio tracks embedded in the video container.)
Descriptive Audio
Only the tracks in the files that were matched with DescriptiveAudioFileLanguageExpression or VideoStreamExpression and not with AudioFileLanguageExpression are picked up.
(We ignore files that were also matched with AudioFileLanguageExpression to reduce false-positives for AD tracks.)
Text
Subtitles
Only the tracks in the files that were matched with SubtitleFileLanguageExpression or VideoStreamExpression are picked up.
(VideoStreamExpression is considered in order to detect text tracks embedded in the video container.)
Captions
Only the tracks in the files that were matched with CaptionFileLanguageExpression and not SubtitleFileLanguageExpression are picked up.