dsp.AudioFileWriter - Stream to audio file - MATLAB (original) (raw)

Description

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

To write audio samples to an audio file:

Create the dsp.AudioFileWriter object and set its properties.
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

`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 theFilename property set toFilename.

`afw` = dsp.AudioFileWriter(`Name=Value`) sets properties using one or more name-value arguments. For example, to set the quality setting for compression as 50, set Quality to 50.

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 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, setFileFormat to"OGG","OPUS", or"MP3".

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, setFileFormat to"MPEG4".

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

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

Description

afw([audio](#d126e243722)) writes one frame of audio samples, audio, to the output file specified byFilename. 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:

expand all

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

collapse all

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

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

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

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

You can now specify signal quality and signal bitrate in thedsp.AudioFileWriter object for these compressed audio file extensions:

"OGG","OPUS","MP3" –– Signal quality
"MPEG4" –– Signal bit rate

The dsp.AudioFileWriter object supports writing MP3 files (.mp3).

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