fffiloni's picture
Fade out the final three seconds of complete MiniMax tracks during broadcast
01a3b02 verified
|
Raw History Blame Contribute Delete
18.2 kB
metadata
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:

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 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:

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 or 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:

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:

{
  "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:

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:

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:

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:

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.

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:

/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:

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:

↑
β†’ 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:

/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:

/likes/likes.json

A track is excluded from future rotations when it reaches the report threshold.

Default:

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:

hf_oauth: true

Listeners can listen anonymously, but interactions are gated:

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:

LISTENER_TTL_SECONDS=45

Jingles

The radio can insert short local jingles between songs.

Jingles are stored locally in the Space under:

static/jingles/

Files matching this pattern are loaded automatically:

jingle_hf_radio_*.wav

Default behavior:

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:

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:

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:

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

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

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

RECENT_TRACK_QUOTA=0.15
RECENT_TRACK_WINDOW_HOURS=72

Streaming

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

BROADCAST_STALL_TIMEOUT_SECONDS=25.0
BROADCAST_WATCHDOG_INTERVAL_SECONDS=5.0
BROADCAST_PROCESS_START_TIMEOUT_SECONDS=20.0

Listeners

LISTENER_TTL_SECONDS=45

Jingles

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:

songs/
  {song_id}/
    meta.json
    {song_id}.wav
    thumb.png

Each meta.json can provide track metadata such as:

{
  "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.