dsp.AudioFileWriter

Stream to audio file

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.

Properties

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.

Filename — Name of audio file to which to write

'output.wav' (default) | character vector | string scalar

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.

FileFormat — Audio file format

'WAV' (default) | 'AVI' | 'FLAC' | 'OGG' | 'MPEG4' | 'OPUS' | 'WMA'

Specify which audio file format the object writes. On Microsoft^® platforms, select one of 'AVI', 'WAV', 'FLAC', 'OGG', 'MPEG4', 'OPUS', 'WMA'. On Linux^® platforms, select one of 'AVI', 'WAV', 'FLAC', 'OPUS', or 'OGG'. On macOS platforms, select one of 'AVI', 'WAV', 'FLAC', 'OGG', 'OPUS', or 'MPEG4'. 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

The default is 'WAV'.

SampleRate — Sampling rate of audio data stream

44100 (default) | positive scalar

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

Compressor — Algorithm that compresses audio data

'None (uncompressed)' (default) | 'CCITT A-Law' | 'CCITT u-Law' | 'GSM 6.10' | 'IMA ADPCM' | 'Microsoft ADPCM' | 'PCM'

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.

DataType — Data type of the uncompressed audio

'int16' (default) | 'double' | 'single' | 'inherit' | 'int24' | 'int32' | 'uint8'

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.

Input Arguments

audio — Audio samples

column vector | matrix

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)

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object

Examples

Write an Audio Signal to WAV File

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

Tunable Audio File Name in Generated Code

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:

Windows 7

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

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

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

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

R2022b: Support for OPUS audio file format

The dsp.AudioFileWriter object supports OPUS file format (.opus).