Main Content

dsp.AudioFileReader

Stream from audio file

expand all in page

Description

The dsp.AudioFileReader System object™ reads audio samples from an audio file.

To read audio samples from an audio file:

  1. Create the dsp.AudioFileReader object and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

afr = dsp.AudioFileReader
afr = dsp.AudioFileReader(Filename)
afr = dsp.AudioFileReader(Name,Value)

Description

afr = dsp.AudioFileReader returns an audio file reader System object, afr that reads audio from an audio file.

afr = dsp.AudioFileReader(Filename) returns an audio file reader object, afr, with Filename property set to Filename.

example

afr = dsp.AudioFileReader(Name,Value) returns an audio file reader System object, afr, with each specified property set to the specified value. Enclose each property name in single quotes. Unspecified properties have default values.

example

Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Specify the name of an audio file as a character vector or a string scalar. If FilenameIsTunableInCodegen is set to false and the file is on MATLAB® path, then you do not need to specify the full name of the file. If FilenameIsTunableInCodegen is set to true, then the file name must either exist in the current directory, or you must specify the full file path. The file name can be an http web address like 'http://uk1.internet-radio.com:8355'. For an example, see Read and Play Back Audio File from http Web Address.

The Filename property is tunable in generated code. That is, you can pass the name of the audio file as an input while running the code generated from this object. File attributes such as the audio format, the number of audio channels, the sample rate, and the bit rate are not tunable and must match the attributes of the prototype audio file you specify through the CodegenPrototypeFile property. The specified prototype audio file determines the attributes and the type of audio files that can be read by the generated code. For an example, see Tunable Audio File Name in Generated Code.

The following table lists the supported audio file formats.

PlatformsFile Name Extensions
Windows®.wav, .wma, .avi, .aif, .aifc, .aiff, .mp3, .opus (since R2022b), .au, .snd, .mp4, .m4a, .flac, .ogg, .mov
Non-Windows.avi, .mp3, .mp4, .m4a, .wav, .flac, .ogg, .aif, aifc, .aiff, .opus (since R2022b), .au, .snd, .mov

Specify a positive integer as the number of times to play the file.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Specify the sample range from which to read, as a 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.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Specify the number of samples in an audio frame as a positive, scalar integer value.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Set the data type of the audio data output from the audio file reader object. Specify the data type as 'double', 'single', 'int16', or 'uint8'.

Read-only Properties

This property is read-only.

Sampling rate of the audio file, returned as a positive scalar in Hz.

Data Types: double

Since R2023b

This property is read-only.

Number of channels in the audio file, returned as a positive integer.

Data Types: double

Since R2023b

This property is read-only.

Total number of audio samples per channel, returned as a positive integer.

Data Types: double

Since R2023b

This property is read-only.

Total duration of the audio file, returned as a positive scalar in seconds.

Data Types: double

Code Generation Properties

Set this property to true to enable tunability of Filename in generated C/C++ code. The file with the specified Filename must either exist in the current directory, or you must specify the full file path.

If FilenameIsTunableInCodegen is set to true, file attributes such as the audio format, the number of audio channels, the sample rate, and the bit rate are not tunable and must match the attributes of the prototype audio file you specify through the CodegenPrototypeFile property. The specified prototype audio file determines the attributes and the type of audio files that can be read by the generated code. For example, if the specified prototype file is a .wav file, then the generated code can only read .wav files. If the specified prototype file sample rate is 44100 Hz, then the generated code can read files with a sample rate of 44100 Hz.

Data Types: logical

Specify the name of the prototype audio file used in code generation as a character vector or a string scalar. Specify the full path for the file only if the file is not on the MATLAB path. The file name can be an http web address, like 'http://uk1.internet-radio.com:8355'.

The attributes of the audio file specified in Filename (such as the audio format, the number of audio channels, the sample rate, and the bite rate) must match the attributes of the audio file specified in CodegenPrototypeFile. The specified prototype audio file determines the attributes and the type of audio files that can be read by the generated code. For example, if the specified prototype file is a .wav file, then the generated code can only read .wav files. If the specified prototype file sample rate is 44100 Hz, then the generated code can read files with a sample rate of 44100 Hz.

The following table lists the supported audio file formats:

PlatformsFile Name Extensions
Windows.wav, .wma, .avi, .aif, .aifc, .aiff, .mp3, .opus, .au, .snd, .mp4, .m4a, .flac, .ogg, .mov
Non-Windows.avi, .mp3, .mp4, .m4a, .wav, .flac, .ogg, .aif, .aifc, .aiff, .opus, .au, .snd, .mov

Dependencies

This property applies only when the FilenameIsTunableInCodegen property is set to true.

Usage

Syntax

audio = afr()
[audio,eof] = afr()

Description

audio = afr() outputs one frame of audio samples, audio. You can specify the number of times to play the file using the PlayCount property. After playing the file for the number of times you specify, audio contains silence.

example

[audio,eof] = afr() returns an end-of-file indicator, eof. eof is true each time the output audio contains the last audio sample in the file.

Output Arguments

expand all

One frame of audio samples, returned as a column vector of length equal to the value you specify in the SamplesPerFrame property. The data type of the audio output is specified in the OutputDataType property.

Data Types: single | double | int16 | uint8

End-of-file indicator, returned as either a 1 or a 0. A value of 1 is output when audio contains the last audio sample in the file.

Data Types: logical

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

expand all

infoInformation about specific audio file
isDoneEnd-of-file status (logical)
stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object

Examples

collapse all

Open Live Script

Read and play back an audio file using the standard audio output device.

You can choose to read the entire data or specify a range of data to read from using the ReadRange property. By default, ReadRange is set to [1 inf], indicating the file reader to read the entire data from the source. In this example, set ReadRange to 3Fs, indicating the file reader to read the first 3 seconds of the data.

afr = dsp.AudioFileReader('speech_dft.mp3','ReadRange',[1 3*22050]);
adw = audioDeviceWriter('SampleRate', afr.SampleRate);

while ~isDone(afr)
    audio = afr();
    adw(audio);
end
release(afr); 
release(adw);
Open Live Script

Read audio data from an http web address using the dsp.AudioFileReader System object™. Play back the data using the audioDeviceWriter System object.

Initialization

Create an audio file reader which reads data from http://uk1.internet-radio.com:8355. Set the sample rate of the audio device writer to be the same as that of the audio file reader.

afr = dsp.AudioFileReader('http://uk1.internet-radio.com:8355')
afr = 
  dsp.AudioFileReader with properties:

           Filename: 'http://uk1.internet-radio.com:8355'
          PlayCount: 1
          ReadRange: [1 Inf]
    SamplesPerFrame: 1024
     OutputDataType: 'double'

  Show all properties

adw = audioDeviceWriter(afr.SampleRate)
adw = 
  audioDeviceWriter with properties:

        Driver: 'DirectSound'
        Device: 'Default'
    SampleRate: 44100

  Show all properties

Read and Play Back

Read a specific amount of data from the web address directly and play the data back using the audio device writer.

for i = 1:1000 
    audio = afr();
    adw(audio);
end

Close the input file and the audio output device.

release(afr)
release(adw)
Open Live Script

Generate a MEX file from a function named writeAudio. This function reads an audio signal from the funky-stereo.wav file, decimates the signal by a factor of 2, and writes the decimated signal to a specified output file.

The dsp.AudioFileReader object reads the audio signal from funky-stereo.wav file. The funky-stereo.wav file has two channels, a sample rate of 44100 Hz, and a bit rate of 1411 kbps. The CodegenPrototypeFile property of the object is set to rock-stereo.wav file. The rock-stereo.wav file has the same file attributes, such as the number of audio channels, sample rate, and bit rate, as the funky-stereo.wav file. The dsp.FIRDecimator object decimates the input audio signal by a factor of 2. The dsp.AudioFileWriter object writes the decimated signal to the output file myoutput.wav. Due to the decimation process, the output file has a sample rate of 22050 Hz and a bit rate of 2822 kbps.

type writeAudio.m
function writeAudio(readfile,writefile)

afr = dsp.AudioFileReader('FilenameIsTunableInCodegen',true,...
    'CodegenPrototypeFile','rock-stereo.wav');
afr.Filename = readfile;
% Filename is funky-stereo.wav and CodegenPrototypeFile is
% rock-stereo.wav.

firdec = dsp.FIRDecimator(2,'auto'); % decimate by 2

afw = dsp.AudioFileWriter('SampleRate',22050);
afw.Filename = writefile;
while ~isDone(afr)
    audio = afr();
    audiod = firdec(audio);
    afw(audiod);
end

release(afr);
release(afw);

end

For generating code, specify file names to be variable-length character vectors of maximum length 500.

readfilename = coder.typeof('a',[1 500],[0 1]);
writefilename = coder.typeof('b',[1 500],[0 1]);

Generate a MEX file using the codegen function.

codegen writeAudio -args {readfilename,writefilename}
Code generation successful.

writeAudio_mex('funky-stereo.wav','myoutput.wav');

Limitations

  • For MP3, MPEG-4 AAC, and AVI audio files on Windows 7 or later and Linux® platforms, dsp.AudioFileReader object can read fewer samples than expected. On Windows platforms, this is due to a limitation in the underlying Media Foundation framework. On Linux platforms, this is due to a limitation in the underlying GStreamer framework. If you require sample-accurate reading, work with WAV or FLAC files.

  • To read OPUS files on a Linux machine, ensure that you have installed libsndfile 1.0.29 or a later version. On Windows and Mac, this file is shipped with MATLAB and is available under $MATLABROOT/bin/<platform>.

Algorithms

This object implements the algorithm, inputs, and outputs described on the From Multimedia File block reference page. The object properties correspond to the block parameters, except:

  • The object has no corresponding property for the Inherit sample time from file block parameter. The object always inherits the sample time from the file.

  • The object has no corresponding property for the Output end-of-file indicator parameter. The object always outputs EOF as the last output.

  • The object has no corresponding property for the Multimedia Outputs parameter because audio is the only supported output.

  • The object has no corresponding property for the Image signal block parameter.

  • The object has no corresponding property for the Output color format parameter.

  • The object has no corresponding property for the Video output data type parameter.

Extended Capabilities

Version History

Introduced in R2012a

expand all

See Also

Functions

Objects

Topics