audiowrite

Write audio file

Syntax

audiowrite(filename,y,Fs)

audiowrite(filename,y,Fs,Name,Value)

Description

audiowrite(filename,y,Fs) writes a matrix of audio data, y, with sample rate Fs to a file called filename. The filename input also specifies the output file format. The output data type depends on the output file format and the data type of the audio data, y.

example

audiowrite(filename,y,Fs,Name,Value) uses additional options specified by one or more Name,Value pair arguments.

Examples

collapse all

Write an Audio File

Open Script

Create a WAVE file from the example file handel.mat, and read the file back into MATLAB®.

Write a WAVE (.wav) file in the current folder.

load handel.mat

filename = 'handel.wav';
audiowrite(filename,y,Fs);
clear y Fs

Read the data back into MATLAB using audioread.

[y,Fs] = audioread(filename);

Listen to the audio.

sound(y,Fs);

Specify Bits Per Sample and Metadata

Open Live Script

Create a FLAC file from the example file handel.mat and specify the number of output bits per sample and a comment.

load handel.mat

filename = 'handel.flac';
audiowrite(filename,y,Fs,'BitsPerSample',24,...
'Comment','This is my new audio file.');
clear y Fs

View information about the new FLAC file by using the audioinfo function

info = audioinfo(filename) ;

The info structure contains the following information fields: Filename, CompressionMethod, NumChannels, SampleRate, TotalSamples, Duration, Title, Comment, Artist, and BitsPerSample.

Input Arguments

collapse all

`filename` — Name of file to write
character vector | string scalar

Name of file to write, or the full path to the file, specified as a character vector or string scalar that includes the file extension.

Depending on the location you are writing to, filename can take on one of these forms.

Location

Form

Current folder

To write to the current folder, specify the name of the file in filename.

Example:'sample_audio.wav'

Other folders

To write to a folder different from the current folder, specify the full or relative path name in filename.

Example: 'C:\myFolder\sample_audio.mp3'

Example: 'myFolder\sample_audio.wav'

Remote Location

To write to a remote location, filename must contain the full path of the file specified as a uniform resource locator (URL) of the form:

scheme_name://path_to_file/my_file.ext

Based on your remote location, scheme_name can be one of the values in this table.

Remote Location	`scheme_name`
Amazon S3™	`s3`
Windows Azure^® Blob Storage	`wasb`, `wasbs`
HDFS™	`hdfs`

For more information, see Work with Remote Data.

Example: 's3://bucketname/path_to_file/sample_audio.mp3'

audiowrite supports the following file formats.

Platform Support	File Format
All platforms	WAVE (`.wav`)
	OGG (`.ogg`)
	FLAC (`.flac`)
Windows^® and Mac	MPEG-4 AAC (`.m4a`, `.mp4`)

Example: 'myFile.m4a'

Example: '../myFile.m4a'

Example: 'C:\temp\myFile.m4a'

When writing AAC files on Windows, audiowrite pads the front and back of the output signal with extra samples of silence. The Windows AAC encoder also places a very sharp fade-in and fade-out on the audio. This results in audio with an increased number of samples after being written to disk.

Data Types: char | string

`y` — Audio data to write
real matrix

Audio data to write, specified as an m-by-n real matrix, where m is the number of audio samples to write and n is the number of audio channels to write.

If either m or n is 1, then audiowrite assumes that this dimension specifies the number of audio channels, and the other dimension specifies the number of audio samples.

The maximum number of channels depends on the file format.

File Format	Maximum Number of Channels
WAVE (`.wav`)	1024
OGG (`.ogg`)	255
FLAC (`.flac`)	8
MPEG-4 AAC (`.m4a`, `.mp4`)	2

The valid range for the data in y depends on the data type of y.

Data Type of y	Valid Range for y
`uint8`	0 ≤ `y` ≤ 255
`int16`	-32768 ≤ `y` ≤ +32767
`int32`	-2^31 ≤ `y` ≤ 2^31–1
`single`	-1.0 ≤ `y` ≤ +1.0
`double`	-1.0 ≤ `y` ≤ +1.0

Data beyond the valid range is clipped.

If y is single or double, then audio data in y should be normalized to values in the range −1.0 and 1.0, inclusive.

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

`Fs` — Sample rate
positive integer scalar

Sample rate, in hertz, of audio data y, specified as a positive integer scalar greater than 0. When writing to .m4a or .mp4 files on Windows platforms, audiowrite supports only samples rates of 44100 and 48000.

Example: 44100

Data Types: double

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'Title','Symphony No. 9','Artist','My Orchestra' instructs audiowrite to write an audio file with the title “Symphony No. 9” and the artist information “My Orchestra.”

`'BitsPerSample'` — Number of output bits per sample
16 (default) | 8 | 24 | 32 | 64

Number of output bits per sample, specified as the comma-separated pair consisting of 'BitsPerSample' and an integer.

Only available for WAVE (.wav) and FLAC (.flac) files. For FLAC files, only 8, 16, or 24 bits per sample are supported.

Example: 'BitsPerSample',32

`'BitRate'` — Kilobits per second (kbit/s)
128 (default) | 64 | 96 | 160 | 192 | 256 | 320

Number of kilobits per second (kbit/s) used for compressed audio files, specified as the comma-separated pair consisting of 'BitRate' and an integer. On Windows 7 or later, the only valid values are 96, 128, 160, and 192.

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

Only available for MPEG-4 (.m4a, .mp4) files.

Example: 'BitRate',96

`'Quality'` — Quality setting for the Ogg Vorbis Compressor
75 (default) | value in the range [0 100]

Quality setting for the Ogg Vorbis Compressor, specified as the comma-separated pair consisting of 'Quality' and a number in the range [0 100], where 0 is lower quality and higher compression, and 100 is higher quality and lower compression.

Only available for OGG (.ogg) files.

Example: 'Quality',25

`'Title'` — Title information
`[]` (default) | character vector | string scalar

Title information, specified as the comma-separated pair consisting of 'Title' and a character vector or string scalar.

Data Types: char | string

`'Artist'` — Artist information
`[]` (default) | character vector | string scalar

Artist information, specified as the comma-separated pair consisting of 'Artist' and a character vector or string scalar.

Data Types: char | string

`'Comment'` — Additional information
`[]` (default) | character vector | string scalar

Additional information, specified as the comma-separated pair consisting of 'Comment' and a character vector or string scalar.

Data Types: char | string

Note

On Mac platforms, audiowrite writes metadata to WAVE, OGG, and FLAC files only, and will not write the 'Title', 'Author', or 'Comment' fields to MPEG-4 AAC files.

Algorithms

The output data type is determined by the file format, the data type of y, and the specified output BitsPerSample.

File Formats	Data Type of y	Output BitsPerSample	Output Data Type
WAVE (`.wav`),	`uint8`, `int16`, `int32`, `single`, `double`	8	`uint8`
		16	`int16`
		24	`int32`
	`uint8`, `int16`, `int32`	32	`int32`
	`single`, `double`	32	`single`
	`single`, `double`	64	`double`
FLAC (`.flac`)	`uint8`, `int16`, `int32`, `single`, `double`	8	`int8`
		16	`int16`
		24	`int32`
MPEG-4 (`.m4a`, `.mp4`), OGG (`.ogg`)	`uint8`, `int16`, `int32`, `single`, `double`	N/A	`single`

Documentation

audiowrite

Syntax

Description

Examples

Write an Audio File

Specify Bits Per Sample and Metadata

Input Arguments

`filename` — Name of file to write
character vector | string scalar

`y` — Audio data to write
real matrix

`Fs` — Sample rate
positive integer scalar

Name-Value Pair Arguments

`'BitsPerSample'` — Number of output bits per sample
16 (default) | 8 | 24 | 32 | 64

`'BitRate'` — Kilobits per second (kbit/s)
128 (default) | 64 | 96 | 160 | 192 | 256 | 320

`'Quality'` — Quality setting for the Ogg Vorbis Compressor
75 (default) | value in the range [0 100]

`'Title'` — Title information
`[]` (default) | character vector | string scalar

`'Artist'` — Artist information
`[]` (default) | character vector | string scalar

`'Comment'` — Additional information
`[]` (default) | character vector | string scalar

Algorithms

See Also

Topics

MATLAB Documentation

Support

Documentation

audiowrite

Syntax

Description

Examples

Write an Audio File

Specify Bits Per Sample and Metadata

Input Arguments

filename — Name of file to write character vector | string scalar

y — Audio data to write real matrix

Fs — Sample rate positive integer scalar

Name-Value Pair Arguments

'BitsPerSample' — Number of output bits per sample 16 (default) | 8 | 24 | 32 | 64

'BitRate' — Kilobits per second (kbit/s) 128 (default) | 64 | 96 | 160 | 192 | 256 | 320

'Quality' — Quality setting for the Ogg Vorbis Compressor 75 (default) | value in the range [0 100]

'Title' — Title information [] (default) | character vector | string scalar

'Artist' — Artist information [] (default) | character vector | string scalar

'Comment' — Additional information [] (default) | character vector | string scalar

Algorithms

See Also

Topics

MATLAB Documentation

Support

`filename` — Name of file to write
character vector | string scalar

`y` — Audio data to write
real matrix

`Fs` — Sample rate
positive integer scalar

`'BitsPerSample'` — Number of output bits per sample
16 (default) | 8 | 24 | 32 | 64

`'BitRate'` — Kilobits per second (kbit/s)
128 (default) | 64 | 96 | 160 | 192 | 256 | 320

`'Quality'` — Quality setting for the Ogg Vorbis Compressor
75 (default) | value in the range [0 100]

`'Title'` — Title information
`[]` (default) | character vector | string scalar

`'Artist'` — Artist information
`[]` (default) | character vector | string scalar

`'Comment'` — Additional information
`[]` (default) | character vector | string scalar