From Multimedia File

Stream from multimedia file

Libraries:
Audio Toolbox / Sources
DSP System Toolbox / Sources

Description

The From Multimedia File block reads audio samples, video frames, or both from a multimedia file and generates a signal with one of the following data types and amplitude ranges.

Output Data Type	Output Amplitude Range
`double`	±1
`single`	±1
`int16`	−32768 to 32767 (−2¹⁵ to 2¹⁵ − 1)
`uint8`	0 to 255

The block imports data from the file into a Simulink^® model.

Note

This block supports code generation for a host computer that has file I/O available. You cannot use this block with Simulink Desktop Real-Time™ software because that product does not support file I/O. The generated code for this block relies on prebuilt library files. For more details, see Code Generation.

Examples

Sample Rate Conversion of Audio Signal

Convert the sample rate of the input audio signal.

Open Model

Decrease Underrun

Examine the Audio Device Writer block in a Simulink® model, determine underrun, and decrease underrun.

Open Script

Mimic Acoustic Environments

Examine the Reverberator block in a Simulink® model and tune parameters. The reverberation parameters in this model mimic a large room with hard walls, such as a gymnasium.

(Audio Toolbox)

Apply Frequency Weighting

Examine the Weighting Filter (Audio Toolbox) block in a Simulink® model and tune parameters.

(Audio Toolbox)

Limitations

To support OPUS file format on a Linux^® machine, you must have libsndfile 1.0.29 or a later version installed. On Windows^® and Mac, this file is shipped with MATLAB^® and is available under $MATLABROOT/bin/<platform>.

Ports

The output ports of the From Multimedia File block change according to the content of the multimedia file. If the file contains only video frames, the Image port, intensity I port, R,G,B ports, or Y,Cb,Cr ports appear based on the settings on the block dialog box. If the file contains only audio samples, the Audio port appears on the block. If the file contains both audio and video, you can select the data to emit. This section describes these ports in more detail.

Output

expand all

Image — Color image or video frame
array

Color image or video frame, returned as an M-by-N-by-P array. M and N are the number of rows and columns in each image. P is the number of color channels in each image.

Dependencies

To enable this port:

Set the File name parameter to the name of a multimedia file that contains video or image data. If the specified file contains both audio and video data, set the Multimedia outputs parameter to Video only or Video and audio.
Set the Output color format parameter to RGB and Image signal parameter to One multidimensional signal.
This port is named as Simulink Image if the Output color format parameter is set to RGB and the Image signal parameter is set to Simulink image signal.

I — Grayscale image or video frame
matrix

Grayscale image or video frame, returned as an M-by-N matrix. M and N are the number of rows and columns in the grayscale image.

Dependencies

To enable this port:

Set the File name parameter to the name of a multimedia file that contains video or image data. If the specified file contains both audio and video data, set the Multimedia outputs parameter to Video only or Video and audio.
Set the Output color format parameter to Intensity.

R — Red color component of image or video frame
matrix

Red color component of the image or video frame, returned as an M-by-N matrix. M and N are the number of rows and columns in the image.

Outputs from the R, G, or B ports must have the same dimensions.

Dependencies

To enable this port:

Set the File name parameter to the name of a multimedia file that contains video or image data. If the specified file contains both audio and video data, set the Multimedia outputs parameter to Video only or Video and audio.
Set the Output color format parameter to RGB and Image signal parameter to Separate color signals.

G — Green color component of image or video frame
matrix

Green color component of the image or video frame, returned as an M-by-N matrix. M and N are the number of rows and columns in the image.

Outputs from the R, G, or B ports must have the same dimensions.

Dependencies

To enable this port:

Set the File name parameter to the name of a multimedia file that contains video or image data. If the specified file contains both audio and video data, set the Multimedia outputs parameter to Video only or Video and audio.
Set the Output color format parameter to RGB and Image signal parameter to Separate color signals.

B — Blue color component of image or video frame
matrix

Blue color component of the image or video frame, returned as an M-by-N matrix. M and N are the number of rows and columns in the image.

Outputs from the R, G, or B ports must have the same dimensions.

Dependencies

To enable this port:

Set the File name parameter to the name of a multimedia file that contains video or image data. If the specified file contains both audio and video data, set the Multimedia outputs parameter to Video only or Video and audio.
Set the Output color format parameter to RGB and Image signal parameter to Separate color signals.

Y — Luma component of image or video frame
matrix

Luma component of the image or video frame, returned as an M-by-N matrix. M and N are the number of rows and columns in the image.

Dependencies

To enable this port:

Set the File name parameter to the name of a multimedia file that contains video or image data. If the specified file contains both audio and video data, set the Multimedia outputs parameter to Video only or Video and audio.
Set the Output color format parameter to YCbCr 4:2:2.

Cb — Blue-difference chrominance component of image or video frame
matrix

Blue-difference chrominance component of the image or video frame, returned as an M-by-N/2 matrix. M and N are the number of rows and columns in the input image.

Dependencies

To enable this port:

Set the File name parameter to the name of a multimedia file that contains video or image data. If the specified file contains both audio and video data, set the Multimedia outputs parameter to Video only or Video and audio.
Set the Output color format parameter to YCbCr 4:2:2.

Cr — Red-difference chrominance component of image or video frame
matrix

Red-difference chrominance component of the image or video frame, returned as an M-by-N/2 matrix. M and N are the number of rows and columns in each input image.

Dependencies

To enable this port:

Set the File name parameter to the name of a multimedia file that contains video or image data. If the specified file contains both audio and video data, set the Multimedia outputs parameter to Video only or Video and audio.
Set the Output color format parameter to YCbCr 4:2:2.

Audio — Audio signal
vector | matrix

Audio signal, returned as an M-element vector or an M-by-N matrix. M is the number of samples in each channel and N is the number of channels.

Dependencies

To enable this port, set the File name parameter to the name of a multimedia file that contains audio data. If the specified file contains both audio and video data, set the Multimedia outputs parameter to Audio only or Video and audio.

Data Types: single | double | int16 | uint8

EOF — End-of-file indicator
scalar

End-of-file indicator, returned as a logical scalar for each video frame or audio sample. The end-of-file indicator is 1 when the block outputs the final video frame or audio sample from the file, and is 0 otherwise.

Dependencies

To enable this port, select the Output end-of-file indicator parameter.

Data Types: Boolean

Parameters

expand all

Main Tab

File name — Name of multimedia file
`speech_dft.mp3` (default) | character vector

Specify the name of the multimedia file for the block to read. The block determines the type of file (audio and video, audio only, or video only) and provides the associated parameters.

If the location of the file does not appear on the MATLAB path, use the Browse button to specify the full path. If the location of the file appears on the MATLAB path, enter only the file name.

On Windows platforms, this parameter supports URLs that point to MMS (Microsoft Media Server) streams.

Inherit sample time from file — Inherit sample time from file
on (default) | off

Specify whether the block inherits the sample time from the multimedia file or uses a specified sample time. When you select this parameter, the block inherits the sample time from the input multimedia file. When you clear this parameter, the block uses the sample time that you specify in the Desired sample time parameter.

Tip

Select this parameter when you do not know the intended sample rate of the multimedia file.

Desired sample time — Block sample time
`1/30` (default) | real positive scalar

Specify the block sample time.

Dependencies

To enable this parameter, clear the Inherit sample time from file parameter.

Number of times to play file — Number of times to play multimedia file
`inf` (default) | positive integer

Specify the number of times to play the input multimedia file. The default value of inf specifies that the block repeats playing the multimedia file until the simulation stop time.

Read range — Range of audio samples
`[1 Inf]` (default) | two-element vector

Specify the sample range from which to read as a two-element row vector in the form of [StartSample EndSample], where StartSample is the sample at which file reading starts, and EndSample is the sample at which file reading stops.

Dependencies

To enable this parameter, set the File name parameter to the name of a multimedia file that contains audio data. If the specified file contains both audio and video data, set the Multimedia outputs parameter to Audio only.

Output end-of-file indicator — End-of-file indicator
off (default) | on

Use this parameter to determine whether the output is the last video frame or audio sample in the multimedia file. When you select this parameter, a Boolean output port labeled EOF appears on the block. The output from the EOF port defaults to 1 when the last video frame or audio sample is output from the block. Otherwise, the output from the EOF port defaults to 0.

Multimedia outputs — Type of media
`Audio only` (default) | `Video and audio` | `Video only`

Specify the type of media to read from a file containing both video and audio data.

Dependencies

To enable this parameter, set the File name parameter to the name of a multimedia file that contains both audio and video data.

Samples per audio channel — Samples per audio channel
`1024` (default) | positive integer

Specify number of samples per audio channel. This parameter becomes available for files containing audio.

Dependencies

Output color format — Color format of video
`RGB` (default) | `Intensity` | `YCbCr 4:2:2`

Specify the output color format of the input video data. The block supports the RGB, Intensity, and YCbCr 4:2:2 color formats.

If you select RGB, use the Image signal parameter to specify how to output a color signal.

Dependencies

To enable this parameter, set the File name parameter to the name of a multimedia file that contains video data. If the specified file contains both audio and video data, set the Multimedia outputs parameter to Video only or Video and audio.

Image signal — Output port configuration for RGB video
`One multidimensional signal` (default) | `Separate color signals` | `Simulink image signal`

Specify how the block outputs an RGB color video. If you select:

One multidimensional signal –– The block outputs an M-by-N-by-P color video signal through the Image port, where P is the number of color planes.
Separate color signals –– The block outputs the video data using three separate color channels, divided across the R, G, and B ports. Each port outputs one M-by-N plane of an RGB video stream.
Simulink image signal –– The block outputs a video in Simulink.ImageType datatype.

Dependencies

To enable this parameter:

Set the File name parameter to the name of a multimedia file that contains video data. If the specified file contains both audio and video data, set the Multimedia outputs parameter to Video only or Video and audio.
Set the Output color format parameter to RGB.

Data Types Tab

Audio output data type — Audio output data type
`double` (default) | `single` | `int16` | `uint8`

Specify the data type for the audio samples output at the Audio port.

Dependencies

Video output data type — Video output data type
`single` (default) | `double` | `int8` | `uint8` | `int16` | `uint16` | `int32` | `uint32` | `Inherit from file`

Specify the data type of the video frames output at the R, G, B, or Image ports..

Dependencies

Block Characteristics

Data Types	`double` \| `integer^a` \| `single`
Direct Feedthrough	`no`
Multidimensional Signals	`no`
Variable-Size Signals	`no`
Zero-Crossing Detection	`no`
^a Supports 16- and 32-bit signed and 8-bit unsigned integers.

More About

expand all

Supported Platforms and File Types

The supported file formats available to you depends on the codecs installed on your system.

Windows Platforms Supported File Formats

With the necessary Windows DirectShow codecs installed on your system, the From Multimedia File Block supports many video and audio file formats. This block performs best on platforms with Version 9.0 or later of DirectX^® software.

The following table lists the most common file formats.

Multimedia Types	File Name Extensions
Image files	`.jpg`, `.bmp`, `.png`
Video files	`.qt`, `.mov`, `.avi`, `.asf`, `.asx`, `.wmv`, `.mpg`, `.mpeg`, `.mp2`, `.mp4`, `.m4v`
Audio files	`.wav`, `.wma`, `.avi`, `.aif`, `.aifc`, `.aiff`, `.mp3`, `.au`, `.snd`, `.mp4`, `.m4a`, `.flac`, `.ogg`, `.opus`

The default for image files is .png, for video files is .avi, and for audio files is .mp3.

Windows 7 and later versions of Windows ship with a limited set of 64-bit video and audio codecs. If the From Multimedia File block cannot work on a compressed multimedia file, save the multimedia file to a file format supported by the block.

If you use Windows, use Windows Media^® Player Version 11 or later with this block for best results.

Non- Windows Platform Supported File Formats

The following table lists the most common file formats.

Multimedia Types	File Name Extensions
Video files	`.avi`, `.mj2`, `.mov`, `.mp4`, `.m4v`
Audio files	`.avi`, `.mp3`, `.mp4`, `.m4a`, `.wav`, `.flac`, `.ogg`, `.aif`, `.aifc`, `.aiff`, `.au`, `.opus`, `.snd`

The default for video files is .avi and for audio files is .mp3.

Sample Rates

The sample rate that the block uses depends on the audio and video sample rate. While the From Multimedia File block operates at a single rate in Simulink, the underlying audio and video streams can produce different rates. In some cases, when the block outputs both audio and video, it makes a small adjustment to the video rate.

Sample Time Calculations Used for Video and Audio Files

Sample time =

\frac{c e i l (\frac{A u d i o S a m p l e R a t e}{F P S})}{A u d i o S a m p l e R a t e}

.
When the audio sample time

\frac{A u d i o S a m p l e R a t e}{F P S}

is noninteger, the equation cannot reduce to

\frac{1}{F P S}

.

In this case, to prevent synchronization problems, the block drops the corresponding video frame when the audio stream leads the video stream by more than

\frac{1}{F P S}

.
In summary, the block outputs one video frame at each Simulink time step. To calculate the number of audio samples to output at each time step, the block divides the audio sample rate by the video frame rate (fps). If the audio sample rate does not divide evenly by the number of video frames per second, the block rounds the number of audio samples up to the nearest whole number. If necessary, the block periodically drops a video frame to maintain synchronization for large files.

Running Executable Outside MATLAB

To run your generated standalone executable application in Shell, you need to set your environment to the following:

Platform Command

Mac

Platform	Command
Mac	`setenv DYLD_LIBRARY_PATH "${DYLD_LIBRARY_PATH}:$MATLABROOT/bin/maca64" (csh/tcsh on Apple silicon)` `export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$MATLABROOT/bin/maca64 (Bash on Apple silicon)` `setenv DYLD_LIBRARY_PATH "${DYLD_LIBRARY_PATH}:$MATLABROOT/bin/maci64" (csh/tcsh on Mac Intel^®)` `export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$MATLABROOT/bin/maci64 (Bash on Mac Intel)` For more information, see Append library path to "DYLD_LIBRARY_PATH" in MAC.
Linux	`setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:$MATLABROOT/bin/glnxa64 (csh/tcsh)` `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$MATLABROOT/bin/glnxa64 (Bash)`
Windows	`set PATH=%PATH%;%MATLABROOT%\bin\win64`

setenv DYLD_LIBRARY_PATH "${DYLD_LIBRARY_PATH}:$MATLABROOT/bin/maca64" (csh/tcsh on Apple silicon)

export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$MATLABROOT/bin/maca64 (Bash on Apple silicon)

setenv DYLD_LIBRARY_PATH "${DYLD_LIBRARY_PATH}:$MATLABROOT/bin/maci64" (csh/tcsh on Mac Intel^®)

export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$MATLABROOT/bin/maci64 (Bash on Mac Intel)

For more information, see Append library path to "DYLD_LIBRARY_PATH" in MAC.

Linux

setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:$MATLABROOT/bin/glnxa64 (csh/tcsh)

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$MATLABROOT/bin/glnxa64 (Bash)

Windows

set PATH=%PATH%;%MATLABROOT%\bin\win64

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using Simulink® Coder™.

Usage notes and limitations:

Host computer only. Excludes Simulink Desktop Real-Time code generation.
The executable generated from this block relies on prebuilt dynamic library files (.dll files) included with MATLAB. Use the packNGo function to package the code generated from this block and all the relevant files in a compressed ZIP file. Using this ZIP file, you can relocate, unpack, and rebuild your project in another development environment where MATLAB is not installed. For more details, see How To Run a Generated Executable Outside MATLAB.

Version History

Introduced before R2006a

expand all

R2022b: Support for OPUS audio file format

The From Multimedia File block supports audio files in the OPUS file format (.opus).

From Multimedia File

Description

Examples

Sample Rate Conversion of Audio Signal

Decrease Underrun

Mimic Acoustic Environments

Apply Frequency Weighting

Limitations

Ports

Output

Image — Color image or video frame array

Dependencies

I — Grayscale image or video frame matrix

Dependencies

R — Red color component of image or video frame matrix

Dependencies

G — Green color component of image or video frame matrix

Dependencies

B — Blue color component of image or video frame matrix

Dependencies

Y — Luma component of image or video frame matrix

Dependencies

Cb — Blue-difference chrominance component of image or video frame matrix

Dependencies

Cr — Red-difference chrominance component of image or video frame matrix

Dependencies

Audio — Audio signal vector | matrix

Dependencies

EOF — End-of-file indicator scalar

Dependencies

Parameters

Main Tab

File name — Name of multimedia file speech_dft.mp3 (default) | character vector

Inherit sample time from file — Inherit sample time from file on (default) | off

Desired sample time — Block sample time 1/30 (default) | real positive scalar

Dependencies

Number of times to play file — Number of times to play multimedia file inf (default) | positive integer

Read range — Range of audio samples [1 Inf] (default) | two-element vector

Dependencies

Output end-of-file indicator — End-of-file indicator off (default) | on

Multimedia outputs — Type of media Audio only (default) | Video and audio | Video only

Dependencies

Samples per audio channel — Samples per audio channel 1024 (default) | positive integer

Dependencies

Output color format — Color format of video RGB (default) | Intensity | YCbCr 4:2:2

Dependencies

Image signal — Output port configuration for RGB video One multidimensional signal (default) | Separate color signals | Simulink image signal

Dependencies

Data Types Tab

Audio output data type — Audio output data type double (default) | single | int16 | uint8

Dependencies

Video output data type — Video output data type single (default) | double | int8 | uint8 | int16 | uint16 | int32 | uint32 | Inherit from file

Dependencies

Block Characteristics

More About

Supported Platforms and File Types

Sample Rates

Sample Time Calculations Used for Video and Audio Files

Running Executable Outside MATLAB

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using Simulink® Coder™.

Version History

R2022b: Support for OPUS audio file format

See Also

Blocks

Topics

Image — Color image or video frame
array

I — Grayscale image or video frame
matrix

R — Red color component of image or video frame
matrix

G — Green color component of image or video frame
matrix

B — Blue color component of image or video frame
matrix

Y — Luma component of image or video frame
matrix

Cb — Blue-difference chrominance component of image or video frame
matrix

Cr — Red-difference chrominance component of image or video frame
matrix

Audio — Audio signal
vector | matrix

EOF — End-of-file indicator
scalar

File name — Name of multimedia file
`speech_dft.mp3` (default) | character vector

Inherit sample time from file — Inherit sample time from file
on (default) | off

Desired sample time — Block sample time
`1/30` (default) | real positive scalar

Number of times to play file — Number of times to play multimedia file
`inf` (default) | positive integer

Read range — Range of audio samples
`[1 Inf]` (default) | two-element vector

Output end-of-file indicator — End-of-file indicator
off (default) | on

Multimedia outputs — Type of media
`Audio only` (default) | `Video and audio` | `Video only`

Samples per audio channel — Samples per audio channel
`1024` (default) | positive integer

Output color format — Color format of video
`RGB` (default) | `Intensity` | `YCbCr 4:2:2`

Image signal — Output port configuration for RGB video
`One multidimensional signal` (default) | `Separate color signals` | `Simulink image signal`

Audio output data type — Audio output data type
`double` (default) | `single` | `int16` | `uint8`

Video output data type — Video output data type
`single` (default) | `double` | `int8` | `uint8` | `int16` | `uint16` | `int32` | `uint32` | `Inherit from file`

C/C++ Code Generation
Generate C and C++ code using Simulink® Coder™.