You can attach external audio files to a video source using MFile in MPlatform SDK or MFReader in MFormats SDK. You can select tracks from each external file, choose a starting position, and repeat external audio while the main source continues playing.
External-audio properties
The table lists the properties for attaching external audio files to an MFile or MFReader source. In the properties string passed to FileNameSet or ReaderOpen, use the names without the file:: prefix. When using PropsSet, use the MPlatform column for MFile and the MFormats column for MFReader.
For the initial setup, pass the paths, track selections, offsets, and loop setting together when opening the source. To change track selections or settings for additional external files on an already open source, reopen it with the updated properties string.
For indexed properties, replace N with a positive integer: 1 for the second external file, 2 for the third, and so on. The first file uses the unsuffixed name.
| MFormats property | MPlatform property | Value type / units | Meaning and scope |
|---|---|---|---|
external_audio |
file::external_audio |
String: file path | Attaches the first external audio file. |
external_audio.N |
file::external_audio.N |
String: file path | Attaches an additional external audio file. Configure consecutive file numbers without leaving an empty entry. |
external_audio_track |
file::external_audio_track |
Zero-based integer index or comma-separated index list | Selects audio tracks within the first external file. 0 selects its first audio track; 1 selects its second; 0,1 selects both. The default selection is 0. Use -1 to disable audio from this external file. |
external_audio_track.N |
file::external_audio_track.N |
Zero-based integer index or comma-separated index list | Selects tracks within external file N, using the same values as external_audio_track. The suffix identifies the file, while the value identifies tracks inside it. |
external_audio_offset |
file::external_audio_offset |
Nonnegative decimal number, seconds | Sets the starting position within the first external audio file. For example, 15.0 skips its first 15 seconds; it does not delay the start of the main source. |
external_audio_offset.N |
file::external_audio_offset.N |
Nonnegative decimal number, seconds | Sets the starting position within external file N. |
external_audio_loop |
file::external_audio_loop |
Boolean: true or false
|
Enables or disables repetition when an external audio file reaches its end. This is a reader-wide setting, without a per-file numeric suffix. It requires a supporting SDK build and the MFCodecs reader backend; see Loop external audio. |
Attach an external audio file
You can specify a path with the external_audio property when opening a source. Quote paths inside a properties string, particularly when they contain spaces:
// MPlatform SDK
myFile.FileNameSet(pathToMyFile, @"external_audio='c:\MP3_audio.mp3'");
// MFormats SDK
myReader.ReaderOpen(pathToMyFile, @"external_audio='c:\MP3_audio.mp3'");Or specify the path with PropsSet:
// MPlatform SDK
(myFile as IMProps).PropsSet("file::external_audio", @"c:\MP3_audio.mp3");
// MFormats SDK
myReader.PropsSet("external_audio", @"c:\MP3_audio.mp3"); For a predictable initial configuration, supply the path, track selection, offset, and looping setting together in the opening properties string. MPlatform playback starts with FilePlayStart. In MFormats, continue retrieving and processing frames in your application's normal frame loop after ReaderOpen, releasing each frame after use.
Choose a starting position
Use external_audio_offset to start reading the external audio from a position measured in seconds. With the MFCodecs reader backend, external_audio_offset='15.0' starts the external audio 15 seconds into its file. The main video starts at its configured playback position. Use external_audio_offset.1 to set the starting position for the second external file.
(myFile as IMProps).PropsSet("file::external_audio_offset", "15.0"); // Start from the 15th second of the external file
myReader.PropsSet("external_audio_offset", "15.0"); // MFormats SDKSelect audio tracks
Use external_audio_track to select tracks inside the first external file. Track numbering starts at zero, and the default is 0. Use external_audio_track='1' for the second track, external_audio_track='0,1' for both tracks, or external_audio_track='-1' to disable audio from that external file.
For additional files, use the matching suffix. For example, external_audio_track.1='1' selects the second track in the second external file. Set these options when opening the source.
(myFile as IMProps).PropsSet("file::external_audio_track", "1"); // Use the second audio track
myReader.PropsSet("external_audio_track", "1"); // MFormats SDKFor more than one track, specify their indices as a comma-separated list, such as 0,1. Use external_audio_track for tracks in the external file and audio_track for tracks in the main source.
Attach multiple external audio files
Use external_audio for the first file, external_audio.1 for the second, and external_audio.2 for the third. Keep the entries consecutive because the reader stops at the first empty path. Use the same suffix for the file’s track selection and offset.
string options =
@"external_audio='C:\Media\First Track.mp3' " +
@"external_audio.1='C:\Media\Second Track.mxf' " +
@"external_audio_track.1='0,1' external_audio_offset.1='15.0'";
// MPlatform SDK
myFile.FileNameSet(pathToMyFile, options);
myFile.FilePlayStart();
// MFormats SDK
myReader.ReaderOpen(pathToMyFile, options);
// Continue retrieving and releasing frames in your normal frame loop.Use matching suffixes for each file's track and offset settings. For example, external_audio_track.1 selects tracks inside the second external file, and external_audio_offset.1 sets its starting position. Keep file entries consecutive: reading the list stops at the first empty path.
Loop external audio
Set external_audio_loop=true to repeat external audio independently of the main file. When an external file reaches its end, playback restarts it from the beginning. Timestamps for subsequent passes are advanced by the accumulated external-file duration to keep them on the main playback timeline.
This is useful when a short audio file should continue during a longer video. The setting applies to external audio and does not enable looping of the main source. Setting it to false disables this independent repetition.
Requirements: use an SDK build that supports external_audio_loop and the MFCodecs reader backend, selected with experimental.mfcodecs=true. The legacy reader backend does not implement this option. The external file must report a positive duration and support restarting from its beginning.
The following examples attach external audio, enable repetition, and disable the main source's original audio:
string options =
@"external_audio='C:\Media\Music.mp3' external_audio_track='0' " +
"external_audio_loop='true' audio_track='-1' experimental.mfcodecs='true'";
// MPlatform SDK
myFile.FileNameSet(pathToMyFile, options);
myFile.FilePlayStart();
// MFormats SDK
myReader.ReaderOpen(pathToMyFile, options);
// Continue retrieving and releasing frames in your normal frame loop.The equivalent property names for PropsSet are:
(myFile as IMProps).PropsSet("file::external_audio_loop", "true"); // MPlatform SDK
myReader.PropsSet("external_audio_loop", "true"); // MFormats SDKConfigure the reader backend before opening the source. A property readback can confirm the configured value, but checking output audio across the external file's end is necessary to confirm repetition in your playback workflow.
External-file opening settings
External audio files are opened with default splitter settings. Opening options from the main source, such as mxf.index_path, are not passed to an external .mxf audio file. Use the external-audio properties above to configure file paths, track selection, starting positions, and repetition.
How to disable original audio
Set audio_track='-1' in the properties string passed to FileNameSet or ReaderOpen to disable the main source’s audio. The external tracks selected with external_audio_track remain enabled. The looping example above shows both options together.
// Disable the original audio
// MPlatform SDK
(myFile as IMProps).PropsSet("file::audio_track", "-1");
// MFormats SDK
myReader.PropsSet("audio_track", "-1"); External image for audio files
If you use an audio file as a source and you need to use some cover image during its playback you should specify the img_stub property. You can use a HEX-code of a color or a path to an image as a value for this property:
(myFile as IMProps).PropsSet("file::img_stub", @"c:\myTestBG.png");Usage for MPlaylist and MMixer objects
For a file item in MPlaylist or a file source in MMixer, use the same external audio options as for MFile. Pass the unprefixed options when adding the file through PlaylistAdd or StreamsAdd. You can also set the external audio path on an item whose underlying source is an MFile.
(myItem as IMProps).PropsSet("file::external_audio", @"c:\MP3_audio.mp3");Still have questions?
Tell us what didn’t work or what you’d like clarified.