Main Content

audiowrite

Write audio file

collapse all in page

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.

example

Examples

collapse all

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

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

Abbreviation

File Extension

All platforms

Free Lossless Audio Codec

FLAC

.flac

MPEG-1 Audio Layer III
MPEG-2 Audio Layer III
MPEG-2.5 Audio Layer III

MP3

.mp3

OGG Vorbis

OGG

.ogg

OGG Opus

OPUS

.opus

Microsoft WAVE sound

WAV

.wav

Windows® and Mac

MPEG-4 Part 3 AAC

MP4

.m4a
.mp4

Example: 'myFile.m4a'

Example: '../myFile.m4a'

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

When writing MP4 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.

On Linux® platforms, these requirements apply:

  • To write MP3 files with audiowrite, you must have libsndfile 1.1.0 or a later version installed. You must also have the LAME MP3 encoder and the mpg123 MP3 decoder installed.

  • To write OPUS files with audiowrite, you must have libsndfile 1.0.29 or a later version installed. You must also have the OPUS codec installed.

Data Types: char | string

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

WAV

1024

OGG, OPUS

255

FLAC

8

MP3, 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, 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

Sample rate, in hertz, of audio data y, specified as a positive integer scalar greater than 0.

  • When writing to MP3 files, audiowrite supports only sample rates of 48,000 Hz, 44,100 Hz, 32,000 Hz, 24,000 Hz, 22,050 Hz, 16,000 Hz, 12,000 Hz, 11,025 Hz, and 8,000 Hz.

  • When writing to OPUS files, audiowrite supports only sample rates of 48,000 Hz, 24,000 Hz, 16,000 Hz, 12,000 Hz, and 8,000 Hz.

  • When writing to MP4 files on Windows platforms, audiowrite supports only sample rates of 48,000 Hz and 44,100 Hz.

Example: 44100

Data Types: double

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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

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

Only available for FLAC and WAV files. For FLAC files, only 8, 16, or 24 bits per sample are supported.

Example: 'BitsPerSample',32

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 192, 160, 128, and 96.

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

Only available for MP4 files.

Example: 'BitRate',96

Quality setting for MP3, Vorbis, or OPUS compression, 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 MP3, OGG, and OPUS files.

Example: 'Quality',25

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

Data Types: char | string

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

Data Types: char | string

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 does not write the 'Title', 'Artist', or 'Comment' fields to MP4 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 Bits Per Sample

Output Data Type

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

uint8, int16, int32, single, double

8

int8

16

int16

24

int32

MP3, MP4, OGG, OPUS

uint8, int16, int32, single, double

N/A

single

Extended Capabilities

Version History

Introduced in R2012b

expand all

See Also

|

Topics