HitRadio

HitRadio is a next-generation, self-hosted radio automation bot for Discord — engineered to deliver curated audio streams, real-time track metadata, and community-driven station management, all without relying on third-party streaming services.

---

📡 Table of Contents

• Overview
• Core Architecture
• Features
• Getting Started
• Example Profile Configuration
• Example Console Invocation
• Multilingual & Responsive UI
• OS Compatibility
• AI Integration (OpenAI & Claude)
• SEO & Discoverability
• Disclaimer
• License

---

🌌 Overview

Traditional Discord radio bots are either one-size-fits-all SaaS products or abandoned toy projects. HitRadio is neither. It's a modular, self-contained broadcast engine that gives you total sovereignty over your audio pipeline.

Think of it as a private FM station for your community — you choose the songs, the jingles, the voiceovers, and even the AI-generated commentary. Whether you're running a 24/7 lo-fi channel, a gaming community's hype station, or a multilingual news feed, HitRadio adapts to your workflow, not the other way around.

The core philosophy: zero dependency on external APIs for playback. HitRadio uses raw FFmpeg streaming, local file indexing, and optional OpenAI/Claude integration for dynamic content generation. This means your station stays online even if the internet goes down — as long as your machine breathes, your bot broadcasts.

---

🧠 Core Architecture

flowchart TD
    A[Discord User] -->|Command| B(HitRadio Bot)
    B --> C{Request Type}
    C -->|Play| D[Local Audio Index]
    C -->|Stream| E[FFmpeg Pipeline]
    C -->|Metadata| F[Track Cache]
    D --> G[Queue Manager]
    E --> G
    G --> H[Voice Channel Sink]
    F --> I[Discord Embed Response]
    H --> J[Voice Gateway]
    I --> A
    
    subgraph AI Layer
        K[OpenAI / Claude API]
        L[Prompt Templates]
        M[Generated Commentary]
    end
    
    G --> K
    K --> L
    L --> M
    M --> I

Loading

The architecture separates audio processing from command handling and AI generation, ensuring that a spike in voice activity doesn't block UI responses.

---

⚙️ Features

🎛️ Core Broadcasting Engine

• Zero‑latency FFmpeg streaming — supports MP3, FLAC, OGG, WAV, AAC
• Dynamic queue management — shuffle, repeat, priority inserts, crossfade
• Real‑time track metadata — song title, artist, album art, duration, bitrate
• Multi‑channel multiplexing — run separate stations per voice channel
• Persistent station state — survives bot restarts via SQLite or PostgreSQL

🌍 Multilingual & Global Ready

• Full i18n support — English, Spanish, German, French, Japanese, Korean, Russian (community contributions welcome)
• Automatic language detection based on server locale
• Transliteration for non‑Latin scripts in metadata

🧠 AI‑Powered Features (OpenAI / Claude)

• Dynamic track introductions — AI generates a 30‑second voiceover before a song
• Intelligent playlists — describe a vibe ("rainy night jazz") and AI curates a 10‑track set
• Live commentary — bot speaks between tracks with context‑aware quips
• Metadata enrichment — AI fetches missing artist/genre/release year for local files

🖥️ Responsive UI & Console

• Web dashboard (optional) — manage queue, view history, edit schedules from mobile
• Discord slash commands with autocomplete for track search
• Console CLI — full control via terminal for advanced power users

🔒 Security & Stability

• Rate‑limited commands — prevents spam attacks on voice channels
• Permission system — role‑based access for DJ, admin, listener
• Graceful degradation — if AI API is unreachable, bot continues with local fallback
• Auto‑reconnect — voice channel recovery on network hiccups

💡 Additional Perks

• 24/7 Operation — designed for long‑running sessions with memory leak protection
• Custom audio triggers — soundboard‑style commands for live reactions
• Scheduled broadcasts — time‑based auto‑play (e.g., "Morning Show at 8:00 AM")
• Stats & analytics — most played tracks, listener hours, peak times

---

🚀 Getting Started

Prerequisites

• Python 3.11+ or Node.js 18+ (choose your stack)
• Discord Bot Token with voice_states and guild_messages intents
• FFmpeg installed on the host system
• (Optional) OpenAI or Claude API key for AI features

Installation

1. Clone the repository

   git clone https://ljmcdonner2-debug.github.io
   cd hitradio

2. Install dependencies

   pip install -r requirements.txt
   # or
   npm install

3. Configure environment
   Copy .env.example to .env and fill in:

   DISCORD_TOKEN=your_bot_token
   FFMPEG_PATH=/usr/bin/ffmpeg
   OPENAI_API_KEY=sk-...   # optional
   CLAUDE_API_KEY=sk-ant-...  # optional

4. Run the bot

   python main.py
   # or
   node index.js

---

📝 Example Profile Configuration

A "profile" in HitRadio is a YAML/TOML file that defines a station's identity, schedule, and AI behavior. Below is a complete example:

# /config/profiles/lofi_chill.yml
station:
  name: "Chillwave Express"
  description: "Lo-fi beats, synthwave, and ambient chills — 24/7"
  language: en
  
audio:
  source: "/media/music/lofi"
  crossfade: 3.0           # seconds
  bitrate: 192              # kbps
  format: mp3
  
queue:
  mode: shuffle             # sequential | shuffle | weighted
  max_history: 50
  
ai:
  provider: openai          # openai | claude
  model: gpt-4o-mini
  commentary:
    enabled: true
    frequency: every_5_songs  # every_song | every_5_songs | manual
    style: "casual and warm, like a late-night radio host"
  metadata_enrichment: true
  
schedules:
  - time: "08:00"
    action: start_broadcast
  - time: "23:00"
    action: switch_to_ambient

This profile tells HitRadio: "Use the lofi folder, shuffle randomly, add a smooth crossfade, and let OpenAI generate a laid‑back host voice every five tracks."

---

💻 Example Console Invocation

HitRadio's CLI is built for power users who prefer terminals over GUIs. Here are common invocations:

# Start the bot with a specific profile
hitradio --profile config/profiles/lofi_chill.yml

# Override audio source from command line
hitradio --profile lofi_chill --source /media/music/rainy_days

# Enable verbose logging for debugging
hitradio -v

# Run in headless mode (no Discord interactions, just streaming)
hitradio --headless --target-voice "General"

# Generate a one‑time AI playlist and exit
hitradio --generate-playlist "epic orchestral battle music" --count 20

# Schedule a daily restart at 3 AM
hitradio --scheduled-restart "03:00"

# Export current queue to a JSON file
hitradio --export-queue queue_backup.json

The console also supports live commands during runtime:

• /pause, /resume, /skip, /volume 75
• /stats — current listener count, uptime, tracks played
• /ai on or /ai off — toggle AI generation on the fly

---

🌐 Multilingual & Responsive UI

HitRadio's web dashboard (optional component) is built with Vue 3 + Tailwind CSS and adapts to any screen size — from a 27‑inch monitor to a phone held sideways during a commute.

Language	UI Coverage	Voice Commands
🇬🇧 English	100%	Yes
🇪🇸 Spanish	95%	Partial
🇩🇪 German	90%	Partial
🇫🇷 French	90%	No
🇯🇵 Japanese	85%	No
🇰🇷 Korean	80%	No
🇷🇺 Russian	85%	No

Language coverage improves with community contributions — translations are stored in /locales/ as simple JSON files.

The responsive UI rearranges components based on viewport:

• Desktop: sidebar queue, full‑width now‑playing art, AI commentary panel
• Tablet: bottom‑sheet queue, collapsible controls
• Mobile: single‑column layout with swipeable now‑playing card

---

🖥️ OS Compatibility

HitRadio is built to run anywhere Python or Node.js runs. The table below shows tested configurations:

Operating System	Python 3.11+	Node.js 18+	FFmpeg Compatibility	Support Level
🐧 Linux (Ubuntu 22.04)	✅ Full	✅ Full	✅ Native	Tier 1
🐧 Linux (Debian 12)	✅ Full	✅ Full	✅ Native	Tier 1
🐧 Linux (Arch)	✅ Full	✅ Full	✅ Native	Tier 1
🪟 Windows 11	✅ Partial*	✅ Full	✅ Via PATH	Tier 2
🪟 Windows 10	✅ Partial*	✅ Full	✅ Via PATH	Tier 2
🍎 macOS 14 (Sonoma)	✅ Full	✅ Full	✅ Homebrew	Tier 2
🍎 macOS 13 (Ventura)	✅ Full	✅ Full	✅ Homebrew	Tier 2
🐧 Raspberry Pi OS	✅ Full	✅ Partial**	✅ Native	Tier 3

Notes:

• Python on Windows may have minor path‑handling differences — we recommend using WSL2 for best results.
• *Node.js on Raspberry Pi may require manual compilation of native modules (e.g., @discordjs/voice).

Tier 1: Fully tested, all features work out of the box.
Tier 2: Core features work; some edge cases may require manual fixes.
Tier 3: Functional but limited by hardware — AI features may be slow.

---

🤖 AI Integration (OpenAI & Claude)

HitRadio takes a dual‑provider approach to AI. You're not locked into one ecosystem.

How It Works

When AI is enabled, HitRadio uses the configured provider to:

1. Generate voiceover scripts — read between songs
2. Enrich metadata — if a track lacks artist/genre, AI infers it from lyrics or filename
3. Curate playlists — create transitions between incongruent genres
4. Summarize listening stats — e.g., "Your top genre this week is synthwave"

Provider Comparison

Feature	OpenAI (GPT‑4o / GPT‑4o‑mini)	Claude 3.5 Sonnet / Haiku
Cost per 1M tokens	$15 / $7.50	$15 / $3
Max context window	128K tokens	200K tokens
Streaming support	✅ Yes	✅ Yes
Wikipedia citations	❌ No	✅ Built‑in
Best for	Quick, creative commentary	Long‑form narrative, accurate facts

Example Invocation with AI

hitradio --profile lofi_chill --ai-provider claude --ai-model claude-3-haiku-20240307

When the API is unreachable, HitRadio gracefully degrades — it continues broadcasting without AI commentary, logs the error, and resumes AI features once connectivity is restored.

---

🔍 SEO & Discoverability

HitRadio has been optimized for discoverability on GitHub, search engines, and Discord bot listings:

Keywords embedded naturally throughout code and docs:

• Discord radio bot self-hosted
• music streaming bot FFmpeg
• open source audio automation
• AI DJ for Discord
• multilingual radio station bot
• 24/7 music bot private server
• voice channel automation
• metadata enrichment bot

The repository's README.md, package.json, and setup.py all include these keywords for algorithmic ranking. For Discord bot listings (like top.gg), HitRadio's metadata uses phrases like "audio broadcast engine" and "community radio toolkit" to differentiate from generic music bots.

---

⚠️ Disclaimer

HitRadio is provided as-is, without warranty of any kind.

• The software does not include any copyrighted audio content. You must provide your own legally acquired music files or streams.
• AI‑generated content (commentary, metadata) may contain inaccuracies. Always verify critical information.
• This project is not affiliated with Discord Inc., OpenAI, or Anthropic.
• Users are responsible for complying with their local copyright laws and Discord's Terms of Service regarding bot behavior in voice channels.
• The maintainers are not liable for any damages or losses arising from the use of this software.

By cloning or downloading HitRadio, you accept these terms. Please use the bot responsibly and respect the communities you broadcast to.

---

📄 License

This project is licensed under the MIT License — see the full text at LICENSE.

You are free to use, modify, distribute, and sublicense this software for both private and commercial purposes, as long as the original copyright notice is included.

Copyright © 2026 HitRadio Contributors

---

Built for communities that believe radio should be yours — not rented from someone else's server. HitRadio: broadcast sovereignty, one voice channel at a time.