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(File name)
afr = dsp.AudioFileReader(Name,Value)

Description

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

example

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

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.

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. 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://audio.wgbh.org:8004/'. For an example, see Read and Play Back Audio File from http Web Address.

The following table lists the supported audio file formats:

PlatformsFile Name Extensions
Windows®.wav, .wma, .avi, .aif, .aifc, .aiff, .mp3, .au, .snd, .mp4, .m4a, .flac, .ogg, .mov
Non-Windows.avi, .mp3, .mp4, .m4a, .wav, .flac, .ogg, .aif, .aifc, .aiff, .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

This property is read-only.

This property displays the sampling rate, in Hz, of the audio file.

Data Types: double

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'.

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

Usage

Syntax

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

Description

example

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.

[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.

Note: If you are using R2016a or an earlier release, replace each call to the object with the equivalent step syntax. For example, obj() becomes step(obj).

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://audio.wgbh.org:8004/. Set the sample rate of the audio device writer to be the same as that of the audio file reader.

afr = dsp.AudioFileReader('http://audio.wgbh.org:8004/')
afr = 
  dsp.AudioFileReader with properties:

           Filename: 'http://audio.wgbh.org:8004/'
          PlayCount: 1
    SamplesPerFrame: 1024
     OutputDataType: 'double'
         SampleRate: 44100
          ReadRange: [1 Inf]


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)

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.

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

See Also

Functions

Objects

Topics

Introduced in R2012a

DSP System Toolbox Documentation

Support