Main Content

dsp.AudioFileWriter

Stream to audio file

expand all in page

Description

The dsp.AudioFileWriter System object™ writes audio samples to an audio file.

To write audio samples to an audio file:

  1. Create the dsp.AudioFileWriter 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

afw = dsp.AudioFileWriter
afw = dsp.AudioFileWriter(Filename)
afw = dsp.AudioFileWriter(Name,Value)

Description

afw = dsp.AudioFileWriter returns an audio file writer System object, afw. This object writes audio samples to an audio file.

afw = dsp.AudioFileWriter(Filename) returns an audio file writer System object, afw. This object has the Filename property set to Filename.

afw = dsp.AudioFileWriter(Name,Value) returns an audio file writer object 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 the audio file as a character vector or a string scalar.

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. For an example, see Tunable Audio File Name in Generated Code.

Specify which audio file format the object writes. On Microsoft® platforms, select one of 'AVI', 'WAV', 'FLAC', 'OGG', 'MPEG4', 'OPUS', 'WMA', or 'MP3'. On Linux® platforms, select one of 'AVI', 'WAV', 'FLAC', 'OPUS', 'OGG', or 'MP3'. On macOS platforms, select one of 'AVI', 'WAV', 'FLAC', 'OGG', 'OPUS', 'MPEG4', or 'MP3'. These abbreviations correspond to the following file formats:

  • 'AVI' –– Audio-Video Interleave

  • 'WAV' –– Microsoft WAVE Files

  • 'WMA' –– Windows Media® Audio

  • 'FLAC' –– Free lossless audio Codec

  • 'OGG' –– Ogg/Vorbis compressed audio file

  • 'OPUS' –– Opus compressed audio file

  • 'MPEG4' –– MPEG-4 AAC File — You can use both .m4a and .mp4 extensions

  • 'MP3' –– MP3 compressed audio file

The default is 'WAV'.

Since R2024a

Quality setting for variable bitrate compression, specified as a scalar in the range [0,100], where 0 is lower quality and higher compression, and 100 is higher quality and lower compression.

MATLAB® encodes 'OGG', 'OPUS', and 'MP3' files with variable bitrate (VBR) codecs. These codecs select the appropriate bit rate for each encoded frame depending on the perceptual complexity of the signal and the value you specify for the Quality property.

Dependencies

To enable this property, set FileFormat to 'OGG', 'OPUS', or 'MP3'.

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

Since R2024a

Bit rate of compressed audio files in kilobits per second (kb/s), specified as 64, 96, 128, 160, 192, 256, or 320. On a Windows® system, the only valid values are 192, 160,128, or 96.

In general, a larger BitRate value results in higher perceived audio quality.

Dependencies

To enable this property, set FileFormat to 'MPEG4'.

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

Specify the sample rate of the input audio data as a positive, numeric scalar value.

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

Specify the type of compression algorithm the audio file writer uses to compress the audio data. Compression reduces the size of the audio file. Select 'None (uncompressed)' to save uncompressed audio data to the file. The other options available reflect the audio compression algorithms installed on your system. You can use tab completion to query valid Compressor options for your computer by typing H.Compressor = ' and then pressing the tab key.

Dependencies

This property applies when writing WAV or AVI files on Windows platforms.

Specify the type of uncompressed audio data written to the file as 'int16', 'double', 'single', 'inherit', 'int24', 'int32', or 'uint8'.

Dependencies

This property only applies when writing uncompressed WAV files.

Usage

Syntax

afw(audio)

Description

afw(audio) writes one frame of audio samples, audio, to the output file specified by Filename. audio is either a vector for mono audio input or an M-by-N matrix for N-channel audio input respectively.

example

Input Arguments

expand all

One frame of audio samples, returned as a column vector or a matrix. A column vector input indicates a mono audio input. An M-by-N matrix indicates an N-channel audio input.

If the input is fixed-point, the input must be a signed fixed-point input with power-of-two slope and zero bias.

Data Types: single | double | int16 | int32 | uint8 | fi

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

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

Decimate an audio signal, and write it to disk as a WAV file.

afr = dsp.AudioFileReader('OutputDataType',...
   'double');
firdec = dsp.FIRDecimator; % decimate by 2
afw = dsp.AudioFileWriter...
   ('speech_dft.wav', ...
   'SampleRate', afr.SampleRate/2);

while ~isDone(afr)
     audio = afr();
     audiod = firdec(audio);
     afw(audiod);
end

release(afr);
release(afw);
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

The following platform-specific restrictions apply when writing these files:

Versions Windows 7 and later

  • Only sample rates of 44100 Hz and 48000 Hz are supported for the MPEG-4 AAC file format. For other file formats, there is no restriction on the sample rate.

  • Only mono or stereo outputs are allowed for the MPEG-4 AAC file format. For all other formats, more than two audio output channels are allowed.

  • The output data is padded on both the front and back of the signal, with extra samples of silence.

    Windows AAC encoder places sharp fade-in and fade-out on audio signals, causing the signals to be slightly longer in samples when written to disk.

  • A minimum of 1025 samples per channel must be written to the MPEG-4 AAC file.

macOS

  • Only mono or stereo outputs are allowed for MPEG-4 AAC file format. For all other formats, more than two audio output channels are allowed.

  • Not all sampling rates are supported, although the Mac Audio Toolbox™ API does not explicitly specify a restriction.

Linux

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

  • To write MP3 files on Linux, you must have libsndfile 1.1.0 or a later version installed.

Algorithms

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

  • The object FileFormat property does not support video-only file formats.

  • The object has no corresponding property for the Write parameter. The object writes only audio content to files.

  • The object has no corresponding property for the Video compressor parameter.

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

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

Extended Capabilities

Version History

Introduced in R2012a

expand all

See Also

Objects

Topics