Repository navigation
docs(nodes): migrate the media nodes, and document eight that never had a README #1976
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 8 commits
c1d960a
d8fdab6
39cdc04
cee0a9e
ed44460
652fa74
77ed886
667b741
1a48927
aa33744
28e05de
ffb4791
a429a01
e110b48
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,50 +1,46 @@ | ||
| # audio_player | ||
|
|
||
| A RocketRide audio node that plays incoming audio through the system's default output device in real time. | ||
| A RocketRide audio sink that plays incoming audio or a video's audio track | ||
| through the system output device. | ||
|
|
||
| ## 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. | ||
| The node passes incoming `audio` and `video` streams to a PCM player and has no | ||
| downstream lane. Choose it when a local pipeline needs to play a stream rather | ||
| than transform it, transcribe it, or generate speech. It serializes playback | ||
| across node instances with one shared lock. | ||
|
|
||
| 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. | ||
| ## Lanes | ||
|
|
||
| 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). | ||
|
|
||
| --- | ||
| | Lane in | Lane out | Description | | ||
| | --- | --- | --- | | ||
| | `audio` | — | Pass the audio stream to the player. | | ||
| | `video` | — | Pass the video stream to the player. | | ||
|
|
||
| ## 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 | ||
| This node exposes no configuration fields. It has one empty `default` profile; | ||
| playback behavior is fixed by the implementation. | ||
|
|
||
| No configuration options: the node exposes no fields and uses a single empty `default` profile. Playback settings are fixed in the implementation: | ||
| ## Limitations | ||
|
|
||
| | 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) | | ||
| The `nosaas` capability means this node is excluded from SaaS deployments. It | ||
| opens an output stream through `sounddevice`, so it is intended for a runtime | ||
| that can access an audio output device. | ||
|
|
||
| --- | ||
| ## Notes | ||
|
|
||
| ## Playback behavior | ||
| ### Fixed playback format and buffering | ||
|
|
||
| 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. | ||
| The player is configured for 44,100 Hz, two-channel, signed 16-bit PCM output | ||
| with a low-latency stream and 1,024-frame callback blocks. It accumulates input | ||
| into 16 KiB chunks and enqueues at most 32 chunks; a full queue blocks incoming | ||
| writes. When stopped, it waits for the queue and callback buffer to drain. | ||
|
|
||
| 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. | ||
| If playback has ended with less than a complete callback frame buffered, the | ||
| callback stops rather than padding silence. The source notes that this can cut | ||
| off the final roughly 24 ms of audio. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
node_dir="nodes/src/nodes/audio_player"
rg -n -C 8 '44100|44100|channels|callback|1024|16384|16 KiB|32|queue|block|drain|truncate|sounddevice' "$node_dir"Repository: rocketride-org/rocketride-server Length of output: 16295 🏁 Script executed: #!/bin/bash
set -euo pipefail
node_dir="nodes/src/nodes/audio_player"
printf '%s\n' '--- player.py ---'
cat -n "$node_dir/player.py" | sed -n '33,175p'
printf '%s\n' '--- service declarations ---'
fd -i 'services.*\.json$' nodes/src/nodes/audio_player -x sh -c 'echo "--- $1"; cat -n "$1"' sh {}
printf '%s\n' '--- README structure and prose ---'
cat -n "$node_dir/README.md" | sed -n '1,48p'Repository: rocketride-org/rocketride-server Length of output: 11011 🏁 Script executed: #!/bin/bash
set -euo pipefail
python3 - <<'PY'
from dataclasses import dataclass
class CallbackStop(Exception):
pass
`@dataclass`
class Model:
queue_items: list
callback_buffer: bytearray
playback_finished: bool = False
def callback(self, frames, channels=2, bytes_per_sample=2):
required_bytes = frames * channels * bytes_per_sample
buf = self.callback_buffer
if self.playback_finished:
if len(buf) == 0:
raise CallbackStop()
else:
while len(buf) < required_bytes:
chunk = self.queue_items.pop(0)
if chunk is None:
self.playback_finished = True
break
buf.extend(chunk)
if self.playback_finished and len(buf) < required_bytes:
raise CallbackStop()
self.callback_buffer = buf[required_bytes:]
return len(buf)
def stop_condition(self):
return bool(self.queue_items) or len(self.callback_buffer) > 0 or not self.playback_finished
# This models the implementation's callback with one terminal partial buffer.
m = Model([b"x" * 1000, None], bytearray())
try:
m.callback(frames=1024)
except CallbackStop:
pass
print({
"required_bytes": 1024 * 2 * 2,
"playback_finished": m.playback_finished,
"callback_buffer_bytes_after_terminal_partial": len(m.callback_buffer),
"stop_condition_after_callback_stop": m.stop_condition(),
})
PYRepository: rocketride-org/rocketride-server Length of output: 320 🏁 Script executed: #!/bin/bash
set -euo pipefail
python3 - <<'PY'
from dataclasses import dataclass
CHUNK = 16 * 1024
CALLBACK_BYTES = 1024 * 2 * 2
`@dataclass`
class ReachablePlayer:
queue_items: list
accumulator: bytearray
callback_buffer: bytearray
playback_finished: bool = False
def on_data(self, data):
if not data:
self.queue_items.append(None)
return
self.accumulator.extend(data)
while len(self.accumulator) >= CHUNK:
self.queue_items.append(bytes(self.accumulator[:CHUNK]))
del self.accumulator[:CHUNK]
def callback(self):
buf = self.callback_buffer
while len(buf) < CALLBACK_BYTES and not self.playback_finished:
chunk = self.queue_items.pop(0)
if chunk is None:
self.playback_finished = True
break
buf.extend(chunk)
if self.playback_finished and len(buf) < CALLBACK_BYTES:
return "CallbackStop", len(buf)
del buf[:CALLBACK_BYTES]
self.callback_buffer = buf
return "played", len(buf)
def stop_condition(self):
return bool(self.queue_items) or bool(self.callback_buffer) or not self.playback_finished
p = ReachablePlayer([], bytearray(), bytearray())
p.on_data(b"x" * (CHUNK + 1000))
p.on_data(b"")
events = []
while p.queue_items:
events.append(p.callback())
print({
"queued_chunk_sizes": [len(x) for x in p.queue_items if x is not None],
"accumulator_bytes_at_eos": len(p.accumulator),
"callback_events": events,
"callback_buffer_bytes_at_eos": len(p.callback_buffer),
"playback_finished": p.playback_finished,
"stop_condition": p.stop_condition(),
"trailing_bytes_dropped": len(p.accumulator),
})
PYRepository: rocketride-org/rocketride-server Length of output: 462 Document the reachable end-of-stream behavior The fixed PCM format, callback size, 16 KiB chunks, 32-chunk queue, and blocking behavior match 🤖 Prompt for AI AgentsSource: Path instructions |
||
|
|
||
| --- | ||
|
|
||
| <!-- ROCKETRIDE:GENERATED:PARAMS START --> | ||
| <!-- Generated by nodes:docs-generate. Do not edit by hand. --> | ||
|
|
||
Uh oh!
There was an error while loading. Please reload this page.