Speaker Access

Speaker Access

Speakers, USB audio interfaces, and other playback devices use the same audio entitlement as microphones. Add it when your app needs to play sounds, speak responses, emit alerts, or run full-duplex voice interactions.

Add the entitlement from your project directory:

wendy project entitlements add audio

Inspect Output Devices

List audio devices on the target:

wendy device audio list

Choose the speaker or output device ID, then set it as default:

wendy device audio set-default --id 2

The selected output becomes the default sink, which is what apps play through unless they name a device explicitly.

Device IDs come from the audio graph and are not stable across reconnects — a speaker that sleeps and wakes, or switches profile, comes back under a different ID. List the devices again rather than reusing an ID you saw earlier.

Test Audio Routing

The Wendy CLI can stream microphone input back to your local machine:

wendy device audio listen

The CLI auto-selects a microphone or shows a picker if multiple devices are available. Pass --id to specify a device explicitly.

USB speakerphones usually expose both an input and output device, so wendy device audio list is the fastest way to confirm WendyOS sees both sides.

Playing Audio From Your App

WendyOS routes audio through PipeWire. Play through PipeWire or its PulseAudio compatibility layer — pw-play, paplay, GStreamer's pulsesink, or any library that targets the default output:

pw-play alert.wav

The audio entitlement also bind-mounts /dev/snd, so aplay and other raw ALSA tools work, but they only reach sound cards. A Bluetooth speaker has no sound card behind it, so aplay cannot play to one no matter how it is configured. Prefer a PipeWire-aware player unless you specifically need a wired card.

Bluetooth Speakers

A paired Bluetooth speaker appears in wendy device audio list alongside wired outputs once it is connected, and can be made the default the same way. Your app needs the audio entitlement to reach it — the bluetooth entitlement governs scanning and pairing, not playback.

Pair and connect the speaker first (see Bluetooth Access), then:

wendy device audio list
wendy device audio set-default --id <speaker id>

Outputs that report no connected display — HDMI ports with nothing plugged in, for example — are not listed, because there is nothing to play to.

App Configuration

A minimal speaker app uses:

{
  "appId": "com.example.speaker",
  "platform": "linux",
  "version": "1.0.0",
  "entitlements": [
    { "type": "audio" }
  ]
}

Then deploy:

wendy run