# audio_player

A RocketRide audio node that plays incoming audio through the system's default output device in real time.

## What it does

Accepts container-format audio bytes (for example WAV or MP3, identified by MIME type) on its `audio` lane and plays them through the machine's default speakers. Video input is also accepted on the `video` lane: the audio track is extracted and played while video frames are discarded. This is a terminal node with no output lanes.

Incoming bytes are piped through **ffmpeg** (the binary bundled with `imageio_ffmpeg`, so no host ffmpeg install is required), which decodes any common container/codec to raw PCM. Playback is handled by **sounddevice** (PortAudio) via a low-latency output stream at 44,100 Hz stereo int16.

Playback is serialized engine-wide: a shared `threading.Lock` created at node startup ensures only one stream plays at a time. Because the node drives a physical audio device, it carries the `nosaas` capability and is not available in SaaS deployments (local only).

---

## Configuration

### Lanes

| Lane    | Direction | Behavior                                                             |
|---------|-----------|----------------------------------------------------------------------|
| `audio` | input     | Decoded and played through the default output device                 |
| `video` | input     | Audio track extracted and played; video frames are discarded         |

Neither lane produces downstream output. The node is a sink.

### Fields

No configuration options: the node exposes no fields and uses a single empty `default` profile. Playback settings are fixed in the implementation:

| Parameter   | Value                                              |
|-------------|----------------------------------------------------|
| Sample rate | 44,100 Hz                                          |
| Channels    | Stereo (2)                                         |
| Format      | PCM int16 (internal playback format after decode)  |
| Latency     | Low (`latency='low'`, blocksize 1024 frames)       |
| Chunk size  | 16 KB per queued buffer                            |
| Queue depth | 32 chunks maximum (~512 KB, roughly 3 s of audio)  |

---

## Playback behavior

Decoded PCM is accumulated into 16 KB chunks and placed into a bounded queue. When the queue holds 32 chunks, upstream writes block, providing natural backpressure that prevents unbounded memory growth.

On stop, the node polls until the queue and the internal playback buffer are both fully drained before closing the stream, so buffered audio plays to completion. One known limitation: the final partial frame smaller than the callback blocksize (1024 frames, about 24 ms at 44.1 kHz) is dropped rather than padded with silence. Roughly the last 24 ms of a stream may be cut off.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

_No configuration fields._

## Dependencies

- `imageio_ffmpeg`
- `sounddevice`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/audio_player)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->