--- title: HF Radio MultiSource emoji: 📻 colorFrom: purple colorTo: pink sdk: docker app_port: 7860 pinned: false hf_oauth: true short_description: "MiniMax Music 3 and ACE-Step community radio." --- # HF Radio MultiSource A live community radio streaming AI-generated songs from the Hugging Face community. The radio builds an hourly rotation from multiple public Hugging Face music catalogs, streams it as a shared live MP3 broadcast, inserts short jingles between songs, and lets signed-in listeners help shape what comes back. MiniMax Music 3 has a default target of 70% of community-music airtime, with ACE-Step at 30%. MiniMax community songs receive a three-second linear fade-out at the end of the live broadcast audio. The broadcaster probes the actual file duration (cached for repeated playback), because catalog durations are rounded; if probing fails, it falls back to metadata and retries next time. The fade follows mastering, remains aligned after a stream restart/seek, and changes volume only. Complete files play to EOF without trimming or overlap. ACE-Step, custom tracks, jingles and segments retain their existing processing. Source bucket files and Studio's original-audio previews remain unchanged. Listen from the Space UI, or open the direct MP3 stream in your favorite audio player: ```text https://fffiloni-hf-radio-multisource.hf.space/stream.mp3 ``` ## This deployment This Space runs independently at `fffiloni/HF-Radio-MultiSource` on CPU Basic. Its private persistent vote bucket is `fffiloni/hf-radio-multisource-likes`, seeded once from the original radio. The paired private [Studio](https://huggingface.co/spaces/fffiloni/HF-Radio-Studio-MultiSource) edits five private buckets `fffiloni/hf-radio-multisource-{control,jingles,segments,cover-overrides,custom-tracks}`, mounted read-only here. Original editorial data were copied once; subsequent changes are independent. Consumed approvals are acknowledged in `/likes/next_rotation_archive` with `RADIO_DELETE_CONSUMED_ROTATION=false` so Radio never needs write access to editorial controls. ## Listen live Open the Space and click **Listen**. The web interface includes: - live radio playback; - current track title, cover art, metadata, tags, description, and lyrics; - a source badge identifying the generating model and linking to its creation Space; - a waveform visualizer; - a progress line for the current track; - countdown to the next hourly mix refresh; - Banger, upvote, downvote, report, and download actions; - connected listener count; - Hugging Face OAuth avatars for signed-in listeners; - local radio jingles between tracks. ## Direct MP3 stream You can also listen from VLC, mpv, a browser, or another audio player using the direct MP3 stream: ```text https://fffiloni-hf-radio-multisource.hf.space/stream.mp3 ``` Listening through the direct stream plays the radio, but web-only features such as votes, reports, OAuth avatars, and listener tracking are only available from the Space UI. ## Add your own song Want your song on the radio? Create and share a track with [MiniMax Music 3 Jam](https://huggingface.co/spaces/victor/MiniMax-Music3-Jam) or [ACE-Step Jam](https://huggingface.co/spaces/victor/ace-step-jam). Only songs published to the community buckets are eligible. New songs get a shot every hour, and community votes help shape what comes back. ## Broadcast architecture The radio uses a shared broadcast architecture. Instead of spawning one `ffmpeg` process per listener, the backend runs one global broadcast engine: ```text RadioState ↓ BroadcastEngine ↓ single FFmpeg MP3 stream ↓ all connected listeners ``` This makes the Space more CPU-friendly and more stable for multiple listeners. The radio state decides what should play next. The broadcast engine handles audio streaming and distributes the same live MP3 chunks to all connected stream subscribers. ## Track rotation The enabled catalogs and their target proportions are defined in `music_sources.json`: | Source | Bucket | Default airtime target | | --- | --- | --- | | MiniMax Music 3 | `victor/minimax-music3-community` | 70% | | ACE-Step | `victor/ace-step-community` | 30% | Source proportions apply to **community music time**, excluding jingles, editorial segments and the separate custom-track quota. They are approximate because songs play in full. Moderation, the score floor and repeat avoidance run before source selection. Within the selected source, existing vote/boost weighting still chooses the song. The recent-track quota also remains in effect. If a source is empty, filtered out, exhausted or unavailable, the remaining sources fill the rotation. If no catalog can be read, an existing active rotation is retained. Studio-approved rotations retain their approved order and take precedence over automatic source proportions. The Studio's own catalog and draft generator require a separate multi-source update; this change only updates Radio. ### Add another source Append an entry to the `sources` array in `music_sources.json` and restart the Space: ```json { "id": "another-model", "label": "Another Model", "model_id": "organization/model", "bucket_id": "owner/community-music", "space_url": "https://huggingface.co/spaces/owner/music-jam", "weight": 20, "enabled": true } ``` Positive weights are relative: 70/30/20 become approximately 58.3%/25%/16.7%. Set `enabled` to `false` to exclude a source. A new source must follow the bucket structure documented below; a different storage format needs an adapter. The player uses the registry labels and links automatically. Never rename a source ID or reassign it to another catalog after votes have been recorded. New track IDs are namespaced, for example `minimax-music3:0000f7508623`. ACE-Step deliberately retains its original IDs using `legacy_ids: true`, so existing votes, overrides and approved playlists keep working. Only one source may use legacy IDs. APIs expose `source_id`, `source_label`, `source_model_id`, `source_bucket_id`, `source_space_url` and `source_track_id` on each community song. `/api/sources` returns the registry; status and rotation endpoints also expose per-source airtime summaries. Jingles, segments and custom uploads have separate player labels. At startup, the backend immediately builds the first rotation pack. After that, the rotation refreshes automatically at every full UTC hour. Example: ```text Server starts at 14:37 UTC → initial rotation is built immediately → next automatic refresh starts at 15:00 UTC → then 16:00, 17:00, etc. ``` The hourly refresh runs in the background. If a rotation is already playing, listeners should not see a loading screen during refresh. ## Hourly rotation pack Each rotation is built as an estimated 60-minute pack. Default target: ```text ROTATION_TARGET_SECONDS=3600 ``` The backend selects tracks using: - track duration from metadata; - estimated jingle duration; - Banger count; - upvote count; - downvote count; - report count; - track creation date; - a maximum track count as a safety limit. Default safety limit: ```text MAX_TRACKS=150 ``` The selected pack is shuffled once, then played sequentially. This means randomness happens when the pack is built, not after every song. This avoids replaying the same track too soon and makes the rotation behave more like a real radio program. ## Recent track quota To encourage new community submissions, part of the hourly rotation is reserved for recent tracks. Defaults: ```text RECENT_TRACK_QUOTA=0.15 RECENT_TRACK_WINDOW_HOURS=72 ``` This means roughly 15% of the hourly pack is reserved for tracks created in the last 72 hours, when enough recent tracks are available. Recent tracks still go through the normal moderation filter. ## Community voting The radio uses several lightweight community signals. ```text Banger / heart → strong positive signal → for standout tracks that should come back Upvote ↑ → soft positive signal → means the track fits the radio well Downvote ↓ → soft negative signal → means the track should play less often Report ⚑ → moderation signal → for problematic tracks ``` These signals influence future hourly rotations, not the currently playing song. ## Bangers Signed-in Hugging Face users can mark the current track as a **Banger**. Banger votes are stored server-side in a persistent JSON file: ```text /likes/likes.json ``` Banger votes are a strong positive signal in the rotation algorithm. The weighting is intentionally capped so the radio does not become a popularity contest. Defaults: ```text LIKE_WEIGHT_PER_LIKE=0.35 LIKE_WEIGHT_MAX=2.0 ``` So Banger votes help, but no track can become overwhelmingly dominant. ## Upvotes and downvotes Signed-in Hugging Face users can also upvote or downvote the current track. Upvotes and downvotes are softer signals than Banger votes. They are meant to capture radio fit: ```text ↑ → this works well in the station ↓ → this should play less often ``` A listener can only have one active radio-fit vote per track in the browser session: upvote or downvote. Radio-fit votes can be renewed after a 24-hour cooldown. These votes are also stored in: ```text /likes/likes.json ``` The rotation algorithm uses them as a moderate bonus or penalty when building future hourly packs. ## Reports Reports are used as a lightweight moderation signal. Only signed-in Hugging Face PRO users can report or undo a report. Reports are stored in the same JSON file as Banger, upvote, and downvote counts: ```text /likes/likes.json ``` A track is excluded from future rotations when it reaches the report threshold. Default: ```text REPORT_HIDE_THRESHOLD=2 ``` So a track with 2 or more reports is filtered out during the next rotation refresh. Important: reporting a track does not skip it immediately. This prevents the report button from becoming an abuseable skip button. ## Report undo If a PRO user reports a track by mistake, they can undo the report from the same browser session. The frontend keeps local report state with `localStorage`, while the backend updates the persistent report count. ## Hugging Face OAuth This Space uses Hugging Face OAuth. OAuth is enabled in the Space metadata with: ```yaml hf_oauth: true ``` Listeners can listen anonymously, but interactions are gated: ```text Anonymous user → can listen Signed-in Hugging Face user → can listen → can mark Banger → can upvote → can downvote Signed-in Hugging Face PRO user → can listen → can mark Banger → can upvote → can downvote → can report / undo report ``` The backend enforces these permissions. The frontend only reflects them in the UI. ## Listener avatars When users listen while signed in with Hugging Face, their public avatar can appear in the listener row. Anonymous listeners are counted in the listener total, but do not show an avatar. The frontend sends a heartbeat while listening, and the backend removes inactive listeners after a TTL. Default: ```text LISTENER_TTL_SECONDS=45 ``` ## Jingles The radio can insert short local jingles between songs. Jingles are stored locally in the Space under: ```text static/jingles/ ``` Files matching this pattern are loaded automatically: ```text jingle_hf_radio_*.wav ``` Default behavior: ```text MIN_SONGS_BETWEEN_JINGLES=6 MAX_SONGS_BETWEEN_JINGLES=10 JINGLE_PROBABILITY_AFTER_MIN=0.25 ``` The backend avoids playing the same jingle twice in a row when multiple jingles are available. Jingle volume can be adjusted independently from songs: ```text JINGLE_VOLUME=2.00 ``` Jingle duration is estimated and included when building the 60-minute rotation pack. ## Progress line, countdown, and audio watchdog The player shows a lightweight progress line under the waveform. It uses: ```text status.elapsed / status.track.duration ``` This progress follows the backend radio state. The CTA also displays a countdown to the next hourly mix refresh. Because browser audio can occasionally buffer or drift behind the live stream, the frontend includes a small watchdog that reconnects to the live stream if playback appears stalled or too far behind. The backend also includes a broadcast watchdog. If the shared FFmpeg stream becomes silent or stalls, the server can kill the stuck process and recover automatically. ## API endpoints Main endpoints: ```text GET /stream.mp3 GET /api/status GET /api/me GET /api/tracks GET /api/likes POST /api/listener/start/{listener_id} POST /api/listener/heartbeat/{listener_id} POST /api/listener/stop/{listener_id} POST /api/like/{song_id} POST /api/upvote/{song_id} POST /api/unupvote/{song_id} POST /api/downvote/{song_id} POST /api/undownvote/{song_id} POST /api/report/{song_id} POST /api/unreport/{song_id} POST /api/refresh POST /api/mode/random POST /api/mode/loop ``` ## Environment variables ### Bucket and rotation ```text MUSIC_SOURCES_FILE=music_sources.json RADIO_MODE=random DEFAULT_DURATION=180 MAX_TRACKS=150 ROTATION_TARGET_SECONDS=3600 META_LOAD_WORKERS=16 ``` `RADIO_MODE=random` means the rotation pack is selected and shuffled during refresh, then played sequentially. `MUSIC_SOURCES_JSON` can provide the complete versioned JSON configuration directly and takes precedence over `MUSIC_SOURCES_FILE`. With neither set, the bundled configuration is used. For older deployments, `BUCKET_ID=victor/ace-step-community` still enables the bundled two-source configuration; a different legacy `BUCKET_ID` retains a single unnamed community catalog until an explicit music-source configuration is supplied. The old singular bucket fields in the status API remain for compatibility; use `music_sources` for the complete list. ### Feedback, reports, and weighting ```text LIKES_DIR=/likes LIKES_FILE=likes.json REPORT_HIDE_THRESHOLD=2 LIKE_WEIGHT_PER_LIKE=0.35 LIKE_WEIGHT_MAX=2.0 UPVOTE_WEIGHT_PER_UPVOTE=0.12 UPVOTE_WEIGHT_MAX=0.6 DOWNVOTE_WEIGHT_PER_DOWNVOTE=0.15 DOWNVOTE_WEIGHT_MAX=0.7 TRACK_WEIGHT_MIN=0.25 TRACK_WEIGHT_MAX=2.0 ``` ### Recent tracks ```text RECENT_TRACK_QUOTA=0.15 RECENT_TRACK_WINDOW_HOURS=72 ``` ### Streaming ```text STREAM_BITRATE=128k STREAM_SAMPLE_RATE=44100 STREAM_SEEK_EPSILON_SECONDS=0.08 BROADCAST_QUEUE_MAX_CHUNKS=256 BROADCAST_NO_TRACK_SLEEP_SECONDS=1.0 BROADCAST_SUBSCRIBER_TIMEOUT_SECONDS=15.0 ``` ### Broadcast watchdog ```text BROADCAST_STALL_TIMEOUT_SECONDS=25.0 BROADCAST_WATCHDOG_INTERVAL_SECONDS=5.0 BROADCAST_PROCESS_START_TIMEOUT_SECONDS=20.0 ``` ### Listeners ```text LISTENER_TTL_SECONDS=45 ``` ### Jingles ```text ENABLE_JINGLES=true JINGLES_DIR=static/jingles JINGLES_GLOB=jingle_hf_radio_*.wav DEFAULT_JINGLE_DURATION=6 JINGLE_VOLUME=2.00 MIN_SONGS_BETWEEN_JINGLES=6 MAX_SONGS_BETWEEN_JINGLES=10 JINGLE_PROBABILITY_AFTER_MIN=0.25 ``` ## Expected bucket structure Each public song bucket is expected to use this structure: ```text songs/ {song_id}/ meta.json {song_id}.wav thumb.png ``` Each `meta.json` can provide track metadata such as: ```json { "title": "Example Song", "description": "A short description of the song", "lyrics": "...", "tags": ["pop", "folk", "instrumental"], "duration": 180.0, "created_at": "2026-05-16T12:00:00Z", "audio_url": "https://...", "thumb_url": "https://..." } ``` The radio uses this metadata to display the current track and build the hourly rotation. `tags` may also be a comma-separated string. `caption` is retained and used as a description fallback. Cover art is optional (`thumb_url: null`). Model/source attribution comes from the registry, not song metadata. ## Validation Run `python -m unittest discover -s tests -v` from the repository root, with FastAPI and `httpx` installed. The tests replace Hub reads with an in-memory filesystem and use temporary local vote/control stores. They do not start the stream, invoke OAuth or contact a live Space. Tests cover source identity collisions, airtime proportions with unequal catalogs and song lengths, filtering, repeat avoidance, partial outages, live-track preservation, old votes, approved ordering and public API provenance. With FFmpeg installed, the suite also checks the MiniMax fade on generated audio: unchanged samples before the last three seconds, preservation of the full decoded duration, silence at EOF, short tracks and resuming inside the fade. Integration checks verify source isolation, accurate duration probing, cached probes and the metadata fallback. Run `node tests/test_player.js` for the player's attribution, links and editorial-item transitions. An optional desktop/mobile browser check is available as `python tests/check_player.py` (Playwright and Chromium required); it mocks every request and writes screenshots under the ignored `test-artifacts/` directory. ## Technical overview The Space runs a FastAPI server. Main components: - Hugging Face bucket scanning via `HfFileSystem`; - server-side hourly rotation pack builder; - shared MP3 broadcast via `ffmpeg`; - backend broadcast watchdog for stream recovery; - local jingle insertion; - persistent Banger/upvote/downvote/report storage; - listener heartbeat tracking; - Hugging Face OAuth for signed-in users; - static frontend with audio player, visualizer, progress line, countdown, and listener avatars. ## Current limitations This is an experimental community radio prototype. Known limitations: - Browser audio can buffer or drift behind the live stream. The frontend watchdog helps by reconnecting when needed. - Reports are simple count-based moderation signals, not a full moderation queue. - Banger/report state uses backend persistence and browser `localStorage` to prevent repeated actions from the same browser session. - Upvote/downvote state uses browser `localStorage` with a 24-hour cooldown. - Hourly packs target roughly 60 minutes, but the app does not cut tracks to fit exactly. ## Goal HF Radio explores what a lightweight, open, community-driven AI radio experience can feel like on Hugging Face Spaces. The goal is to make community-generated music feel alive, discoverable, and fun to listen to. Not just a playlist. A community-shaped AI radio.