How Spotycast works

The core streaming chain

At runtime, Spotycast is not a single monolith. It is a pipeline. Each component has a narrow role, which keeps the architecture understandable and easier to troubleshoot.

What spotifyd does

In the standard Free path, spotifyd is the upstream playback endpoint used by the stack on the Spotify side. It participates in the Spotify-facing playback flow and receives the Spotify audio inside the runtime environment.

What Liquidsoap does

Liquidsoap is the stream-routing core of the architecture. It reads the audio coming from the local playback path, then applies the publishing logic that turns this audio into one or more outbound streams.

• Read the local audio source
• Route audio to one or more output definitions
• Encode, remux, or preserve the stream depending on profile and target format
• Forward the result to Icecast
• Maintain mountpoints while playback is active
• Carry or update stream metadata when supported by the pipeline and player

What Icecast does

Icecast is the publishing layer. Its role is not to discover Spotify devices or manage playback logic. Its role is to expose the finished stream through stable HTTP endpoints on the network.

http://<HOST>:28000
http://<HOST>:28000/spotify.aac

http://<HOST>:28000/flac

How players consume the stream

Once a mountpoint exists, the player side becomes simple. Roon, LMS, Volumio, moOde and other compatible clients just consume a stream URL. They do not need to participate in the Spotify-side logic of the runtime chain.

Stable lossy path vs advanced audio path

Spotycast can be operated with different output profiles depending on the intended use case and the target players. The technical distinction is not only about product tiers; it is about how the stream is published and how the downstream system consumes it.

Why this architecture is more resilient

The architecture reduces coupling between the Spotify-facing control layer and the final playback layer. That does not eliminate every possible issue, but it narrows failure domains and makes the system easier to reason about.

• The player only needs an HTTP stream, not deep Spotify integration
• Publishing is handled by Icecast, not by each playback device individually
• Routing and output logic live in one place inside the stream pipeline
• Troubleshooting becomes more modular: discovery, routing and publishing can be isolated more easily

Ops and runtime checks

A clean diagnosis starts by locating the failing layer. First verify Icecast, then Liquidsoap, then the audio path, then the player consuming the final HTTP endpoint.

What to verify first

• Icecast is reachable on the expected port
• At least one mountpoint appears when playback is active
• Liquidsoap is actually publishing to Icecast
• The player can open the published mountpoint URL
• Metadata updates if the issue is about now-playing information

tail -n 200 /var/log/spotify-roon-bridge/liquidsoap.stderr.log || true
tail -n 200 /var/log/spotify-roon-bridge/icecast2.stderr.log || true
tail -n 200 /var/log/spotify-roon-bridge/pulseaudio.stderr.log || true

curl --max-time 5 http://127.0.0.1:28000/status-json.xsl || true
ss -ltnp | grep 28000 || true