---

name: matlab-play-record-audio description: Reference for MATLAB audiostreamer (Audio Toolbox R2025a+). Without this skill, agents consistently default to legacy audioDeviceWriter/audioDeviceReader or base MATLAB sound(), producing less capable code. Use when writing code for audio playback, recording, full-duplex device I/O, real-time audio measurements, or audio I/O processing with callbacks. Also use when debugging audiostreamer errors, dropouts, or latency issues, or migrating from audioDeviceReader, audioDeviceWriter, audioPlayerRecorder, or audioplayer/audiorecorder. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

audiostreamer — MATLAB Audio Device I/O (R2025a+)

audiostreamer is the unified replacement for audioDeviceWriter, audioDeviceReader, and audioPlayerRecorder. It provides player-only, recorder-only, or full-duplex modes with callbacks, pre-buffering, transport control, and measurement helpers.

Version requirements: audiostreamer requires Audio Toolbox R2025a or later. The start and write methods were added in R2026a.

When to Use

• Playing audio through a sound card or USB audio device
• Recording audio from a microphone or audio interface
• Full-duplex playback + recording (e.g., acoustic measurements, loopback tests)
• Listing or selecting audio devices and drivers
• Any workflow that involves audio hardware I/O in MATLAB

When NOT to Use

• Playing a single isolated sound — sound or soundsc is fine for one-shot playback of a short clip with no sequencing. For sequential playback (e.g., before/after comparison), use audiostreamer — its play() calls queue automatically, whereas overlapping sound calls play simultaneously.
• Code generation (codegen) — audiostreamer does not yet support codegen; use legacy APIs if targeting codegen
• Simulink models — Simulink still uses the existing audio I/O blocks, not audiostreamer
• Audio Toolbox not available — fall back to sound/soundsc, audioplayer/audiorecorder, or audioDeviceWriter (DSP System Toolbox) if the user lacks Audio Toolbox
• File I/O only — reading/writing audio files without device playback or recording uses audioread/audiowrite, not this skill
• DAQ hardware — National Instruments or similar data acquisition devices use DAQ Toolbox and the daq object
• MIDI-only devices — MIDI control uses mididevice/midicontrols, not audiostreamer

Construction

Use Name-Value pairs for Mode and SampleRate (positional shorthand exists but does not support tab-completion):

The default Mode is "player". You MUST set Mode explicitly if recording — either Mode="recorder" or Mode="full-duplex". Mode is not inferred from other properties like Recorder or RecorderChannels.

as = audiostreamer                                          % default: player mode, 44100 Hz
as = audiostreamer(Mode="player", SampleRate=fs)            % player at fs Hz
as = audiostreamer(Mode="recorder", SampleRate=fs)          % recorder at fs Hz
as = audiostreamer(Mode="full-duplex", SampleRate=fs)       % simultaneous play + record
as = audiostreamer(Mode="full-duplex", SampleRate=48000, Driver="ASIO", ...
    Player="Focusrite USB ASIO", Recorder="Focusrite USB ASIO", ...
    PlayerChannels=[1 2], RecorderChannels=[1 2])

Properties

Device Configuration (set BEFORE streaming starts)

| Property | Type | Default | Notes | |----------|------|---------|-------| | Mode | "player" / "recorder" / "full-duplex" | "player" | Set at construction or via property | | Driver | "DirectSound" / "ASIO" / "WASAPI" (Win); "CoreAudio" (Mac); "ALSA" (Linux) | OS default | Only set on Windows (Mac/Linux have one driver each). Setting at construction selects the default device for that driver. | | Player | string | System default for driver | Output device name. Omit to use the default device for the selected driver. | | Recorder | string | System default for driver | Input device name. Omit to use the default device for the selected driver. | | SampleRate | positive scalar | 44100 | Hz | | DeviceBufferSize | positive int or "auto" | "auto" | Fixed for ASIO (use asiosettings). | | DeviceBitFormat | "single" / "int24" / "int16" | "int24" | int16 on ASIO silently uses int24 | | PlayerChannels | row vector or "auto" | "auto" | 1-based mapping. "auto" upmixes mono→stereo; for N≥2 channels, opens N channels on the device | | RecorderChannels | row vector | 1 | 1-based mapping. Records 1 channel by default — set e.g. 1:2 for stereo | | ExclusiveMode | on/off | "on" | WASAPI only — disables OS mixing/resampling | | ConstantLatency | "off" / "dropPlayer" / "dropRecorder" | "off" | Full-duplex dropout handling |

IMPORTANT: Mode, SampleRate, Driver, DeviceBufferSize, DeviceBitFormat, ExclusiveMode, ConstantLatency, PlayerChannels, and RecorderChannels lock once streaming starts. Call release(as) before changing any of these properties to avoid an automatic release with a warning.

Callback Properties

| Property | Signature | Trigger | |----------|-----------|---------| | PlayerFcn | @(obj, event) | Player buffer drops below PlayerMinSamples | | PlayerMinSamples | positive int (default 16384) | Threshold for PlayerFcn trigger | | RecorderFcn | @(obj, event) | Recorder buffer exceeds RecorderMinSamples | | RecorderMinSamples | positive int (default 1024) | Threshold for RecorderFcn trigger | | PlayerCompletedFcn | @(obj, event) | Output queue empties | | RecorderCompletedFcn | @(obj, event) | Fixed-length recording finishes | | PlayerUnderrunFcn | @(obj, event) | Player underrun occurs |

ALL callbacks MUST accept exactly 2 arguments. First arg = the audiostreamer object. Second arg = event struct with .Type field. Use @(obj, ~) if you don't need the event.

Event struct fields by type:

• PlayerFcn: event.Type = "Player", event.NumPlayerSamples
• RecorderFcn: event.Type = "Recorder", event.NumRecorderSamples
• PlayerCompletedFcn: event.Type = "PlayerCompleted", event.StreamTime
• RecorderCompletedFcn: event.Type = "RecorderCompleted", event.StreamTime
• PlayerUnderrunFcn: event.Type = "PlayerUnderrun", event.SamplesUnderrun

Read-Only Status

| Property | Description | |----------|-------------| | NumPlayerSamples | Samples currently queued in output buffer | | NumRecorderSamples | Samples available to read() without blocking | | MaxPlayerChannels | Max output channels on selected device | | MaxRecorderChannels | Max input channels on selected device |

Methods

Playback

| Method | Description | |--------|-------------| | play(obj, x) | Queue x and play. Blocks until output buffer <= PlayerMinSamples (up to PlayerMinSamples samples remain unplayed when it returns). Call waitfor(as) after the last play to ensure complete playback before release. | | play(obj, x, "non-blocking") | Queue x and return immediately regardless of buffer level. | | play(obj) | Start PlayerFcn callback loop (no data argument). | | write(obj, x) | [R2026a+] Queue x to output buffer WITHOUT starting playback. Use with start(). | | write(obj, x, "non-blocking") | [R2026a+] Queue x and return immediately regardless of buffer level. |

Recording

| Method | Description | |--------|-------------| | record(obj) | Start recording indefinitely. Warns if unread samples remain in the buffer. To avoid: stop(as) (or stop(as, "recorder") in full-duplex), then read(as) to flush. Not needed if samples were already consumed by a callback or read. | | record(obj, numSamples) | Record exactly numSamples then stop. Same unread-samples warning applies. | | read(obj) | Return all available recorded samples immediately (non-blocking). Returns empty if none available. | | read(obj, numSamples) | Blocks until numSamples available, then returns them. |

Full-Duplex

| Method | Description | |--------|-------------| | playrec(obj, x) | Play x and record simultaneously. Non-blocking — recording continues in the background; retrieve data with read. | | playrec(obj, x, numSamples) | Play x and record numSamples. Blocking — returns recorded matrix. | | playrec(obj) | Start callback-driven full-duplex (requires RecorderFcn and/or PlayerFcn). |

playrec pauses both player and recorder, queues audio, then resumes both simultaneously for repeatable latency. This is critical for measurements with impzest.

Transport Control

| Method | Description | |--------|-------------| | start(obj) | [R2026a+] Start streaming in current mode. | | start(obj, Mode="player") | [R2026a+] Start only player (full-duplex). | | start(obj, Mode="recorder", SamplesToRecord=N) | [R2026a+] Start recorder with fixed count. | | stop(obj) | Stop all streaming. Preserves unread input samples. Resets underrun count (as does getUnderrunCount). | | stop(obj, "player"/"recorder"/"both") | Stop specific side. | | pause(obj) / pause(obj, "player"/"recorder"/"both") | Pause with state preservation. | | resume(obj) / resume(obj, "player"/"recorder"/"both") | Resume from pause. | | waitfor(obj) / waitfor(obj, "player"/"recorder"/"both") | Block until complete. | | release(obj) | Stop, flush, close device, tear down. Deletes unread samples. |

Query / Diagnostics

| Method | Description | |--------|-------------| | isPlaying(obj) | Returns OnOffSwitchState | | isRecording(obj) | Returns OnOffSwitchState | | isPlayerPaused(obj) | Returns OnOffSwitchState | | isRecorderPaused(obj) | Returns OnOffSwitchState | | getUnderrunCount(obj) | Underrun sample count since last call. Resets counter (as does stop). | | getStreamTime(obj) | Elapsed stream time in seconds. | | getStreamTime(obj, "reset") | Reset stream timer. | | measureLoopbackLatency(obj) | Full-duplex only, single channel. Returns delay in samples. |

Static Device Enumeration

audiostreamer.getDrivers()              % Available drivers for this OS
audiostreamer.getPlayerNames()          % All output devices
audiostreamer.getPlayerNames("ASIO")    % Output devices for specific driver
audiostreamer.getRecorderNames()        % All input devices
audiostreamer.getRecorderNames("ASIO")  % Input devices for specific driver
audiostreamer.getAudioDevices()         % Struct array: Name, Driver, MaxRecorderChannels, MaxPlayerChannels, SampleRate (channel counts are int32)

Note: getAudioDevices() returns int32 for MaxRecorderChannels and MaxPlayerChannels. Cast to double() before using these values in UI components (e.g., uispinner Limits) or arithmetic that expects double.

CRITICAL: There is NO setup() Method

The audiostreamer does NOT have a public setup() method. Device initialization happens implicitly on the first play(), record(), playrec(), or start() call. Do NOT call setup() — it will error.

If PlayerFcn is set, the first streaming call invokes it repeatedly to pre-buffer at least 8192 samples (or PlayerMinSamples, whichever is greater) before the device opens.

Common Patterns

Pattern 1: Simple Blocking Measurement (Sweep + IR)

as = audiostreamer(Mode="full-duplex", SampleRate=48000, ...
    PlayerChannels=1, RecorderChannels=1);
x = sweeptone(2, 1, 48000);
y = playrec(as, x, size(x, 1));  % blocking: returns recorded audio
underruns = getUnderrunCount(as);
ir = impzest(x, y);
release(as);

Pattern 2: Non-Blocking Play + Record with waitfor

as = audiostreamer(Mode="full-duplex", SampleRate=48000);
x = sweeptone(3, 2, 48000);
playrec(as, x);          % non-blocking (no output arg)
waitfor(as);             % block until done
y = read(as);            % retrieve recorded data