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(File name)
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(File name) returns an audio file writer System object, afw. This object has the Filename property set to File name.

example

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

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.

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

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

The default is 'WAV'.

Specify the sampling 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

example

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

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

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

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

Limitations

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

Windows 7 macOS

  • 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 MPEG-4 AAC file format. For all other formats, more than two audio output channels are allowed.

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

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

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

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

See Also

Objects

Topics

Introduced in R2012a

DSP System Toolbox Documentation

Support