SnapRadio

SnapRadio is a modern, web-based interface for playing global Internet radio and Twitch streams on headless systems.

It designed for seamless integration with Snapcast via PipeWire/PulseAudio FIFOs allowing you to sned Internet radio or Twitch streams to your snapcast server.

Built with FastAPI and Tailwind CSS, it provides a responsive mobile-friendly experience for managing your radio listening and media downloads.

Features

• Global Radio Discovery: Browses tens of thousands of stations worldwide via the Radio-Browser.info API.
• Configurable Defaults: Set your preferred default country in .env using the 2-code country alpha code (e.g., DEFAULT_COUNTRY=GB). Country Codes .
• Snapcast Ready: Orchestrates audio routing to local FIFOs for multi-room synchronization.
• Favourites: Save your favourite stations for quick access
• Track History: Automatically logs played tracks from radio stations (where information is available from the stream)
• Recording Function: Record stream to local mp3
• Local Player: Basic player to play on the local device. For those times when you have your speakers connected via Bluetooth
• Twitch Integration: Play your followed Twitch audio streams.
• Media Downloader: A versatile background downloader for Mixcloud, YouTube, and other platforms with automatic MP3 conversion, ID3 tagging, and artwork embedding.
• Mobile Optimized: A clutter-free, responsive UI that works perfectly on phones and tablets.

Scrennshots

Screenshots

Architecture

• FastAPI Backend: For concurrency and speed.
• Global Data Source: Pulls live data from the Radio-Browser community project.

Audio Routing

SnapRadio routes audio to the following PipeWire/PulseAudio devices (configured in .env):

Source	Default FIFO	Purpose
Radio Player	/tmp/snapcastDAB	Main radio stream output
Twitch Player	/tmp/Twitch	Dedicated Twitch audio output

---

Requirements

System Packages

• ffmpeg: Required for audio transcoding and downloading.
• pw-cat: Required for PipeWire audio playback.
• python3-venv: Required for Running the application

apt install ffmpeg pipewire-bin python3-venv

Python Environment

SnapRadio requires Python 3.10+.

python3 -m venv ~/venv
source ~/venv/bin/activate
pip install -r requirements.txt

---

Installation & Setup

1. Clone & Prepare

git clone https://github.com/GenXStreamer/Snapradio.git /opt/Snapradio
cd /opt/Snapradio
cp .env_example .env

2. PipeWire Configuration

Create PipeWire pulse-sink configurations to host the FIFOs. Example for snapcastDAB:

File: ~/.config/pipewire/pipewire-pulse.conf.d/snapcastDAB.conf

pulse.cmd = [
  { cmd = "load-module"
    args = "module-pipe-sink file=/tmp/snapcastDAB sink_name=snapcastDAB format=s16le rate=48000 channels=2"
  }
]

File: ~/.config/pipewire/pipewire-pulse.conf.d/Twitch.conf

pulse.cmd = [
  { cmd = "load-module"
    args = "module-pipe-sink file=/tmp/Twitch sink_name=Twitch format=s16le rate=48000 channels=2"
  }
]

3. Running the Application

The main entry point is main.py.

source ~/venv/bin/activate
python main.py

By default, the UI is available at http://localhost:8882. Configurable in .env

Alternatively, start/stop via systemd

Important it is presumed you have a active logged user session on your device; by default pipewire runs on logged in user sessions; and the systemd user services start on user login. I belive it is possible to run pipewire without requiring a logged in session, but I have not explored this option. Pipewire Headless

In my setup (Mint Linux) I autologin my snapcast user to a minimal desktop.

---

Media Downloader

The built-in Downloader supports a wide range of URLs thanks to yt-dlp.

• Processes jobs in a background queue.
• Shows real-time status: Queued → Downloading → Encoding → Done.
• Status persists across page refreshes and navigation.
• Saves tagged MP3s to the downloads/ directory.

Twitch Setup

To use Twitch features, you must provide a Client ID and Secret in your .env.

1. Register an app at Twitch Dev Console.
2. Important: Set the OAuth Redirect URL in the Twitch console to http://localhost:8889/callback.
3. Fill in TWITCH_CLIENT_ID and TWITCH_CLIENT_SECRET in your .env file.
4. Run the token helper script to authorize your account and generate tokens:

   python get_twitch_tokens.py

   This script will automatically update your .env with the required TWITCH_USER_TOKEN and TWITCH_REFRESH_TOKEN.
5. You also need to find your numeric Twitch User ID (e.g. using an online lookup tool) and add it to TWITCH_USER_ID in .env to see your followed channels. https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/

Snapserver Configuration

Setup your FIFO inputs in snapcast server.

source entries in /etc/snapserver.conf:

source = pipe:///tmp/snapcastDAB?name=Radio&mode=read
source = pipe:///tmp/Twitch?name=Twitch&mode=read

---

Acknowledgements

• Radio-Browser.info: For providing the incredible open-source station database.
• Snapcast: The foundation of this multi-room setup.
• ffmpeg: THE audio and video converter!
• Streamlink: pipes video streams from various services
• yt-dlp: Powering the media downloader.

License

TBA