dsp.AudioFileReader - Stream from audio file - MATLAB (original) (raw)

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

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, withFilename property set toFilename.

example

`afr` = dsp.AudioFileReader(`Name=Value`) sets properties using one or more name-value arguments. For example, to set the number of samples in audio frame to 2048, setSamplesPerFrame to 2048.

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 therelease function unlocks them.

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

For more information on changing property values, seeSystem 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 tofalse and the file is on MATLAB® path, then you do not need to specify the full name of the file. If FilenameIsTunableInCodegen is set totrue, 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, seeTunable Audio File Name in Generated Code.

The following table lists the supported audio file formats.

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 ofFilename 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 totrue, 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 inFilename (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 inCodegenPrototypeFile. 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:

Dependencies

This property applies only when theFilenameIsTunableInCodegen property is set totrue.

Usage

Syntax

Description

[audio](#d126e242651) = 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](#d126e242651),[eof](#mw%5F78ab9138-e8fb-47bd-8046-f6b14860ad10)] = afr() returns an end-of-file indicator, eof.eof is true each time the outputaudio 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 theSamplesPerFrame 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 a0. A value of 1 is output whenaudio 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:

expand all

Examples

collapse all

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);

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") adw = audioDeviceWriter(afr.SampleRate)

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)

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.

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 outputsEOF 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

expand all

Usage notes and limitations:

• See System Objects in MATLAB Code Generation (MATLAB Coder).
• The executable generated from this System object relies on prebuilt dynamic library files (.dll files) included with MATLAB. Use the packNGo function to package the code generated from this object 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 in R2012a

expand all

These new read-only properties provide additional information about the audio file:

• NumChannels –– Number of audio channels in the file.
• TotalSamples –– Total number of samples per channel in the audio file.
• Duration –– Total duration of the audio file (in seconds).

The dsp.AudioFileReader object supports audio files in the OPUS file format (.opus).