Skip to content

Home

Jump to bottom
code edited this page Mar 2, 2026 · 4 revisions

Grimnir Radio Wiki

Welcome to the Grimnir Radio documentation. Grimnir Radio is a modern, production-ready broadcast automation system built in Go with multi-instance scaling, comprehensive observability, and flexible deployment options.

🚀 Quick Links

📋 Features

Core Features

  • Smart Blocks - Rule-based playlist generation with criteria filtering and artist separation
  • Clock Scheduling - Hour templates with slot-based repeating patterns
  • Live Broadcasting - DJ handover with priority system and graceful fallback
  • Webstream Relay - Built-in HTTP stream relay with ICY metadata, HLS support, and automatic failover
  • Multi-Mount Support - Multiple output streams per station
  • Media Management - Local filesystem or S3-compatible storage

Enterprise Features

  • Multi-Instance Scaling - Horizontal scaling with Redis/NATS
  • Leader Election - Automatic leader election for scheduler
  • Health Monitoring - Prometheus metrics and OpenTelemetry tracing
  • Event Bus - Distributed events with Redis or NATS JetStream
  • 5-Tier Priority System - Emergency, Live Override, Live Scheduled, Automation, Fallback

🏗️ Architecture

Grimnir Radio uses a two-binary architecture. The control plane handles scheduling, the REST API, and stream relay. The media engine handles all audio processing via GStreamer and exposes its own HTTP stream output.

┌─────────────────┐     ┌──────────────────────────────┐
│  Control Plane  │────▶│        Media Engine          │
│   (REST API)    │gRPC │  (GStreamer + HTTP output)   │
│  Webstream Relay│     └──────────────────────────────┘
└─────────────────┘
         │
         ├──────────────┐
         ▼              ▼
    ┌────────┐    ┌──────────┐
    │  RDBMS │    │  Redis   │
    └────────┘    └──────────┘
  • Control Plane (cmd/grimnirradio): Go HTTP API, scheduler, executor, authentication, webstream relay
  • Media Engine (cmd/mediaengine): GStreamer-based audio processing with built-in HTTP stream output; controlled via gRPC
  • Storage: PostgreSQL/MySQL/SQLite for metadata, filesystem/S3 for media files
  • Event Bus: Redis or NATS for multi-instance coordination

The media engine provides its own HTTP stream output directly — there is no Icecast dependency. The control plane's webstream relay can additionally proxy and rebroadcast external streams with automatic failover, ICY metadata forwarding, and HLS support.

📚 Documentation Sections

Getting Started

Core Concepts

Administration

Integration

Operations

Reference

🤝 Community

📝 Version Information

See CHANGELOG for version history and Roadmap for upcoming features.

🛠️ Technology Stack

  • Language: Go 1.24+
  • Media Processing: GStreamer 1.0 (built-in HTTP stream output, no Icecast required)
  • Database: PostgreSQL 12+ (or MySQL 8+, SQLite 3.35+)
  • Event Bus: Redis 6+ or NATS 2.9+
  • Object Storage: S3-compatible (AWS S3, MinIO, Spaces, B2)
  • Stream Relay: Built-in ICY + HLS support with auto-detection (added HLS metadata polling in v1.18.62)
  • Observability: Prometheus, OpenTelemetry

📖 Additional Resources

Grimnir Radio Wiki

Getting Started

Core Concepts

Scheduling

Deployment

Integration

Operations

Development

Reference

Clone this wiki locally