audioread — Read audio samples from a file.
audioread(filename) decodes audio samples into an N-by-C tensor, where rows are sample frames and columns are channels. [y, Fs] = audioread(filename) also returns the sample rate in Hz.
Syntax
y = audioread(filename)
[y, Fs] = audioread(filename)
y = audioread(filename, samples)
[y, Fs] = audioread(filename, samples, datatype)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
filename | StringScalar | Yes | — | Audio file path. |
samples | NumericArray | No | — | One-based inclusive frame range [first last]. |
datatype | StringScalar | No | "double" | Output class; "native" preserves representable source classes. |
Returns
| Name | Type | Description |
|---|---|---|
y | NumericArray | Decoded samples as an N-by-C matrix. |
Fs | NumericScalar | Sample rate in Hz. |
Returned values from audioread depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:audioread:InvalidArgument | Filename, sample range, datatype, or output count is invalid. | audioread: invalid argument |
RunMat:audioread:Io | The audio file cannot be read. | audioread: unable to read file |
RunMat:audioread:UnsupportedFormat | The file is not a supported audio container, uses unsupported audio coding, or is malformed. | audioread: unsupported or invalid audio file |
How audioread works
- Accepts scalar string, scalar string-array, or row character-vector filenames and reads through RunMat's filesystem abstraction.
- Supports WAV/RF64 containers with PCM 8-bit unsigned, PCM 16/24/32-bit signed, IEEE float 32-bit, IEEE float 64-bit, and WAVE_FORMAT_EXTENSIBLE PCM/float subformats.
- By default, PCM samples are returned as normalized double values. Unsigned 8-bit PCM maps around zero, and signed PCM maps by the signed full-scale denominator.
- The optional sample range is a two-element double, one-based inclusive frame range:
audioread(filename, [first last]). A last value ofInfreads through the final frame; typed-integer ranges reject. - The optional datatype argument supports
"double"and"native". For supported WAV/RF64 files, native output uses exactuint8storage for 8-bit unsigned PCM,int16storage for 16-bit signed PCM, left-alignedint32storage for 24-bit signed PCM, ordinaryint32storage for 32-bit signed PCM,singlefor 32-bit IEEE float, anddoublefor 64-bit IEEE float. - Compressed containers such as FLAC, MP3, Ogg/Vorbis, and AIFF metadata are recognized by
audioinfo; sample decoding for those codecs is not currently implemented.
Does RunMat run audioread on the GPU?
audioread does not dispatch provider kernels and is not fusion eligible. GPU-resident inputs reject before provider access because the public API has no interactive GPU-array surface; decoded sample tensors remain on the host.
GPU memory and residency
audioread always returns host-resident tensors because file I/O and audio decoding occur on the CPU. Use gpuArray after reading if later processing should use device residency.
Examples
Read samples and sample rate
[y, Fs] = audioread("speech.wav");
size(y)Read a frame range
clip = audioread("speech.wav", [16001 32000]);Preserve native representable class
raw = audioread("tones.wav", "native");
class(raw)Using audioread with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how audioread changes the result.
Run a small audioread example, explain the result, then change one input and compare the output.
FAQ
What shape does audioread return?⌄
It returns an N-by-C tensor where N is the number of decoded frames and C is the number of channels. Mono audio is N-by-1.
Does audioread use the active filesystem provider?⌄
Yes. The implementation reads bytes through RunMat's filesystem abstraction, so sandbox, remote, and native providers can all supply audio files.
Does audioread decode MP3 or FLAC samples?⌄
Not yet. RunMat currently parses metadata for those containers through audioinfo; audioread decodes WAV/RF64 PCM and IEEE-float audio samples.
Related Io functions
Audio
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · mkdir · movefile · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how audioread is executed, line by line, in Rust.
- View the source for audioread in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.