---
title: Speaker Access
description: Play audio through speakers and other output devices from WendyOS apps
---

## 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:

```bash
wendy project entitlements add audio
```

## Inspect Output Devices

List audio devices on the target:

```bash
wendy device audio list
```

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

```bash
wendy device audio set-default --id 2
```

In an interactive terminal, omit `--id` to choose from the audio device list:

```bash
wendy device audio set-default
```

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:

```bash
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:

```bash
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](../../hardware/bluetooth/)), then:

```bash
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:

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

Then deploy:

```bash
wendy run
```

<CliShot flow="run" step="deploy" alt="The Wendy CLI deploying an audio-output app to a WendyOS device" />