Snapcast — FIFO & TCP PCM Sinks#

This document traces every hop an audio frame takes from the Rockbox C firmware through the Snapcast PCM sinks to a Snapcast server.

Two complementary sinks are available:

The FIFO sink is the traditional approach: rockboxd writes to a named pipe that snapserver reads. The TCP sink connects directly to snapserver's TCP source port — no FIFO, no filesystem dependency, auto-discoverable via mDNS.

Table of contents#

1. Overview
2. Choosing FIFO vs TCP
3. FIFO sink
   • Layer map
   • PCM sink vtable
   • The DMA thread
   • FIFO pre-open strategy
   • stdout mode
   • Track transitions and EOF prevention
   • Startup order
   • Snapserver configuration
4. TCP sink
   • Layer map
   • PCM sink vtable
   • Connection lifecycle
   • Reconnect on error
   • Startup order
   • Snapserver configuration
5. Auto-discovery via mDNS
6. FFI boundary (crates/sys)
7. Settings and startup (crates/settings)
8. Other pipe consumers
9. Gotchas and known limits

Overview#

Both sinks write raw S16LE stereo PCM at 44100 Hz — the same byte stream snapserver expects regardless of source type. There is no Rust crate involved; both are pure-C PCM sinks with a thin Rust FFI wrapper for configuration.

Choosing FIFO vs TCP#

Use FIFO when you want stdout piping or prefer the traditional pipe model.

Use TCP when you want UI-based auto-discovery, multiple snapservers, or don't want a filesystem dependency.

FIFO sink#

FIFO layer map#

┌────────────────────────────────────────────────────────┐
│  Rockbox C firmware  (pcm.c, audio thread)             │
│    pcm_play_data() → sink.ops.play()                   │
│    pcm_play_dma_complete_callback() per chunk          │
└───────────────────┬────────────────────────────────────┘
                    │ raw S16LE stereo PCM chunks
┌───────────────────▼────────────────────────────────────┐
│  firmware/target/hosted/pcm-fifo.c                     │
│    pcm_fifo_set_path()  — pre-creates FIFO, opens fd   │
│    sink_dma_start()     — spawns fifo_thread           │
│    fifo_thread()        — blocking write() loop        │
│    sink_dma_stop()      — signals thread, keeps fd     │
└───────────────────┬────────────────────────────────────┘
                    │ blocking write() to FIFO or stdout
┌───────────────────▼────────────────────────────────────┐
│  Named FIFO  (/tmp/snapfifo)  or  stdout               │
└───────────────────┬────────────────────────────────────┘
                    │ read()
┌───────────────────▼────────────────────────────────────┐
│  snapserver  (pipe:// source)                          │
│  — or —                                                │
│  ffplay / aplay / custom consumer                      │
└────────────────────────────────────────────────────────┘

PCM sink vtable (pcm-fifo.c)#

firmware/target/hosted/pcm-fifo.c implements struct pcm_sink:

fifo_pcm_sink is registered at index PCM_SINK_FIFO = 1 in firmware/pcm.c.

The DMA thread#

sink_dma_start(addr, size) stores the initial PCM pointer/length under the mutex, then spawns fifo_thread. The thread mimics a hardware DMA interrupt loop:

while not stopped:
    1. lock → grab (data, size) → clear pcm_data/pcm_size → unlock
    2. while size > 0 and not stopped:
           n = write(fifo_fd, data, size)
           handle EINTR/EAGAIN (retry)
           advance data pointer, decrement size
    3. lock → pcm_play_dma_complete_callback(OK, &pcm_data, &pcm_size) → unlock
    4. if no more data: break
    5. pcm_play_dma_status_callback(STARTED)

Pacing comes naturally from the blocking FIFO write — the kernel suspends the thread until the reader drains data, locking throughput to the consumer's rate.

FIFO pre-open strategy#

pcm_fifo_set_path(path) is called once at startup:

1. Create the FIFO#

mkfifo(path, 0666);   // EEXIST is ignored

2. Open with a permanent writer reference#

fd = open(path, O_RDWR | O_NONBLOCK);
// then clear O_NONBLOCK:
fcntl(fd, F_SETFL, flags & ~O_NONBLOCK);

Why O_RDWR? Opening O_WRONLY blocks until a reader is present. O_RDWR succeeds immediately and keeps the open-writer-count at ≥1 for the process lifetime — snapserver never sees premature EOF between tracks.

Why clear O_NONBLOCK? Writes must block when the kernel buffer is full to provide natural back-pressure. Leaving O_NONBLOCK set would produce EAGAIN and corrupt the stream.

stdout mode#

When fifo_path = "-", the sink writes to stdout:

rockboxd | ffplay -f s16le -ar 44100 -ac 2 -

pcm_fifo_set_path("-") redirects fd 1 to stderr before any PCM is written so internal printf() output never pollutes the PCM stream.

Track transitions and EOF prevention#

sink_dma_stop() does not close fifo_fd. On POSIX, a named FIFO's read end sees EOF only when all write-side fds are closed. By keeping fifo_fd open across track boundaries, snapserver sees a continuous stream with no gaps.

Startup order (FIFO)#

rockboxd must start before snapserver.

1. rockboxd starts  → pcm_fifo_set_path() → FIFO created, O_RDWR fd held
2. snapserver starts → opens FIFO O_RDONLY → blocks until data flows
3. Playback begins  → fifo_thread writes → snapserver distributes to clients

Snapserver configuration (FIFO)#

# /etc/snapserver.conf  (or /usr/local/etc/snapserver.conf on macOS)
[stream]
source = pipe:///tmp/snapfifo?name=default&sampleformat=44100:16:2

On macOS, snapserver ≥ v0.35.0 ignores the -s CLI flag. Use the config file.

TCP sink#

TCP layer map#

┌────────────────────────────────────────────────────────┐
│  Rockbox C firmware  (pcm.c, audio thread)             │
│    pcm_play_data() → sink.ops.play()                   │
│    pcm_play_dma_complete_callback() per chunk          │
└───────────────────┬────────────────────────────────────┘
                    │ raw S16LE stereo PCM chunks
┌───────────────────▼──────────────────────────────────────┐
│  firmware/target/hosted/pcm-tcp.c                        │
│    pcm_tcp_set_host() / pcm_tcp_set_port()               │
│    sink_dma_start()  — connects if needed, spawns thread │
│    tcp_thread()      — blocking write() loop             │
│    sink_dma_stop()   — signals thread, keeps socket      │
└───────────────────┬──────────────────────────────────────┘
                    │ blocking write() over TCP
┌───────────────────▼────────────────────────────────────┐
│  TCP socket  (snapserver host:port)                    │
└───────────────────┬────────────────────────────────────┘
                    │ recv()
┌───────────────────▼────────────────────────────────────┐
│  snapserver  (tcp:// source, server mode)              │
│      │                                                 │
│  ┌───┴──────┬──────────┐                               │
│  ▼          ▼          ▼                               │
│ snapclient snapclient snapclient                       │
└────────────────────────────────────────────────────────┘

PCM sink vtable (pcm-tcp.c)#

firmware/target/hosted/pcm-tcp.c implements struct pcm_sink:

tcp_pcm_sink is registered at index PCM_SINK_SNAPCAST_TCP = 6 in firmware/pcm.c.

Connection lifecycle#

sink_dma_start() calls tcp_connect_once() if tcp_fd < 0:

static int tcp_connect_once(void)
{
    // getaddrinfo(tcp_host, port) → socket() → connect()
    // returns fd on success, -1 on failure (logs error, drops audio)
}

The socket is kept open across stop() → play() transitions, just as the FIFO fd is. snapserver's reader sees a continuous stream between tracks.

Reconnect on error#

If write() returns a hard error (EPIPE, ECONNRESET, etc.), tcp_thread closes the socket (tcp_fd = -1) and sets tcp_stop = true. The next call to sink_dma_start() finds tcp_fd < 0 and attempts a fresh connect(). This handles snapserver restarts gracefully — the connection is re-established automatically on the next track or resume.

Startup order (TCP)#

snapserver must be running and listening before playback starts.

1. snapserver starts  → listens on tcp://0.0.0.0:4953
2. rockboxd starts    → pcm_tcp_set_host/port() stores config
3. Playback begins    → sink_dma_start() → tcp_connect_once() → connects
4. tcp_thread writes  → snapserver receives → distributes to clients

Unlike the FIFO sink there is no permanent pre-connection at startup. The socket is opened on the first play() call.

Snapserver configuration (TCP)#

# /etc/snapserver.conf  (or /usr/local/etc/snapserver.conf on macOS)
[stream]
source = tcp://0.0.0.0:4953?name=default&sampleformat=44100:16:2

settings.toml (manual config, not needed when selecting from the UI):

audio_output      = "snapcast_tcp"
snapcast_tcp_host = "192.168.1.x"   # IP of the machine running snapserver
snapcast_tcp_port = 4953            # default snapserver TCP source port

Auto-discovery via mDNS#

snapserver advertises itself via mDNS as _snapcast._tcp.local.. rockboxd scans for this service at startup via scan_snapcast_servers() in crates/server/src/scan.rs, which browses _snapcast._tcp.local. using the mdns-sd crate and adds discovered servers to the shared devices list.

Discovered servers appear immediately in:

• Web UI — the device picker in the control bar (lime-green radio icon)
• Desktop app (GPUI) — the device picker popup

Clicking a discovered server calls PUT /devices/:id/connect, which:

1. Calls pcm_tcp_set_host(device.ip) and pcm_tcp_set_port(device.port).
2. Calls pcm_switch_sink(PCM_SINK_SNAPCAST_TCP).
3. Persists audio_output = "snapcast_tcp", snapcast_tcp_host, and snapcast_tcp_port to settings.toml so the selection survives restart.

No manual settings.toml editing is needed when using the UI.

FFI boundary (crates/sys)#

FIFO#

// crates/sys/src/lib.rs
extern "C" { fn pcm_fifo_set_path(path: *const c_char); }

// crates/sys/src/sound/pcm.rs
pub fn fifo_set_path(path: &str) {
    let cpath = CString::new(path).expect("path must not contain null bytes");
    unsafe { crate::pcm_fifo_set_path(cpath.as_ptr()) }
    std::mem::forget(cpath);  // C code stores and re-reads pointer at runtime
}

TCP#

// crates/sys/src/lib.rs
extern "C" {
    fn pcm_tcp_set_host(host: *const c_char);
    fn pcm_tcp_set_port(port: c_ushort);
}

// crates/sys/src/sound/pcm.rs
pub fn tcp_set_host(host: &str) {
    let chost = CString::new(host).expect("host must not contain null bytes");
    unsafe { crate::pcm_tcp_set_host(chost.as_ptr()) }
    std::mem::forget(chost);
}

pub fn tcp_set_port(port: u16) {
    unsafe { crate::pcm_tcp_set_port(port) }
}

std::mem::forget is used in both cases because the C code stores the raw pointer and reads it later (in sink_dma_start's connect / fallback path). Dropping the CString would free the memory while C holds a dangling pointer. Since these are startup-time config calls, leaking is acceptable.

Settings and startup (crates/settings)#

crates/settings/src/lib.rs:load_settings() handles both sinks:

Some("fifo") => {
    let path = settings.fifo_path.as_deref().unwrap_or("/tmp/rockbox.fifo");
    pcm::fifo_set_path(path);
    pcm::switch_sink(pcm::PCM_SINK_FIFO);
}
Some("snapcast_tcp") => {
    if let Some(ref host) = settings.snapcast_tcp_host {
        let port = settings.snapcast_tcp_port.unwrap_or(4953);
        pcm::tcp_set_host(host);
        pcm::tcp_set_port(port);
        pcm::switch_sink(pcm::PCM_SINK_SNAPCAST_TCP);
    }
}

All Snapcast settings keys#

Other pipe consumers#

Since both sinks carry raw S16LE stereo 44100 Hz PCM, the FIFO sink works with any tool that accepts that format:

# Play directly with ffplay (stdout mode)
rockboxd | ffplay -f s16le -ar 44100 -ac 2 -

# Encode on the fly
rockboxd | ffmpeg -f s16le -ar 44100 -ac 2 -i - output.mp3

# Play with sox
rockboxd | play -t raw -r 44100 -e signed -b 16 -c 2 -

# Inspect levels with aplay (Linux)
rockboxd | aplay -f S16_LE -r 44100 -c 2

All of these require fifo_path = "-" and are only available with the FIFO sink. The TCP sink does not support stdout mode.

Gotchas and known limits#

1. Startup order is critical for both sinks#

• FIFO: rockboxd must open the FIFO before snapserver. Reverse order causes snapserver to hold the only writer reference; when it closes, readers see EOF. Restart snapserver if this happens.
• TCP: snapserver must be listening before playback starts. If snapserver is not yet running, sink_dma_start logs a warning and drops audio for that buffer. It reconnects automatically on the next play call.

2. Fixed 44100 Hz, S16LE stereo#

Neither sink resamples. set_freq is a no-op. The firmware resamples tracks internally before they reach the sink, but the output is always 44100 Hz. Configure sampleformat=44100:16:2 on the snapserver side.

3. No volume control through the sink#

Volume is applied by the Rockbox DSP pipeline before PCM reaches the sink. Adjust volume through the Rockbox API or client applications.

4. Consumer back-pressure controls playback speed#

Both sinks use blocking write(). A slow or stalled consumer stalls write(), which stalls the DMA callback loop, which pauses decoding. This is correct for synchronized output but means a crashed consumer freezes playback. Restart snapserver to recover.

5. macOS snapserver.conf vs CLI flag#

The -s flag to snapserver is silently ignored on macOS (≥ v0.35.0). Always use the config file for both pipe:// and tcp:// sources.

6. TCP reconnect drops in-flight buffer#

When the write loop detects EPIPE it closes the socket immediately. The current audio buffer is discarded. Reconnection happens on the next sink_dma_start() call, so there will be a brief audio gap when snapserver restarts.

7. Logging uses tracing, never println!#

All Rust-side diagnostic output must go through tracing. println! and eprintln! bypass the log filter and — in stdout/FIFO mode — can corrupt the PCM stream. Use RUST_LOG=debug rockboxd to see debug output on stderr.