{"id":25948787,"url":"https://github.com/michochieng/web-radio","last_synced_at":"2026-05-11T09:54:35.054Z","repository":{"id":280543932,"uuid":"941892723","full_name":"MichOchieng/web-radio","owner":"MichOchieng","description":"Starter kit for a simple web-radio station","archived":false,"fork":false,"pushed_at":"2025-03-04T01:47:26.000Z","size":75,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-04T02:33:20.331Z","etag":null,"topics":["broadcast","docker","docker-compose","icecast2","liquidsoap","radio"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MichOchieng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-03T08:25:02.000Z","updated_at":"2025-03-04T01:47:29.000Z","dependencies_parsed_at":"2025-03-04T02:33:23.118Z","dependency_job_id":"04fe9b82-f3d1-417f-9d0e-4df03c76bfad","html_url":"https://github.com/MichOchieng/web-radio","commit_stats":null,"previous_names":["michochieng/web-radio"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichOchieng%2Fweb-radio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichOchieng%2Fweb-radio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichOchieng%2Fweb-radio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichOchieng%2Fweb-radio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MichOchieng","download_url":"https://codeload.github.com/MichOchieng/web-radio/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241837065,"owners_count":20028304,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["broadcast","docker","docker-compose","icecast2","liquidsoap","radio"],"created_at":"2025-03-04T11:22:33.152Z","updated_at":"2026-05-11T09:54:35.007Z","avatar_url":"https://github.com/MichOchieng.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Web Radio Setup Guide\n\nThis is an overview of the streaming infrastructure design for an internet radio station using Docker, Caddy, Icecast2, and Liquidsoap.\n\n## Requirements\n\n- Docker and Docker Compose\n- Caddy v2.6+\n- Icecast2 (run in Docker)\n- Liquidsoap (run in Docker)\n- Audio Hijack or similar broadcast software\n\n## System Architecture\n\nThe system consists of the following components:\n\n1. **Audio Source**: Audio Hijack or similar software sending a stream to Liquidsoap\n2. **Liquidsoap**: Handles stream processing, silence detection, and fallback to backup music\n3. **Icecast2**: Streaming server that delivers the content to listeners\n4. **Caddy**: Reverse proxy that handles SSL, authentication, and routing\n\n![Stream Architecture Diagram](/public/stream.png)\n\n## Quick Start\n\n### Clone or download the configuration files\n\n```bash\ngit clone https://github.com/MichOchieng/web-radio.git\ncd web-radio\n```\n\n### Add backup music\n\n```bash\ncp /path/to/your/music/*.mp3 ./backup_music/\n```\n\n### Start the server\n\n```bash\ndocker compose up -d\n```\nYour streaming server is now running 🎉\n\n## Docker Configuration\n\nThe setup leverages Docker Compose to orchestrate the services:\n\n- **Icecast Container**: Handles the streaming server functionality\n    - Exposes port 8000 internally\n    - Configured with environment variables for passwords\n    - Mounts external configuration and log directories\n- **Liquidsoap Container**: Manages audio processing and fallback logic\n    - Depends on the Icecast container\n    - Exposes port 8010 for the incoming audio stream\n    - Mounts the Liquidsoap script and backup music directory\n\nThese containers communicate through a dedicated Docker network.\n\n## Icecast Configuration\n\nThe Icecast configuration handles:\n\n- **Stream Mounts**: Two mount points are configured:\n    - `/live.mp3` for MP3 format streaming\n    - `/stream.aac` for AAC format streaming\n- **Authentication**:\n    - Source password for Liquidsoap to connect\n    - Admin password for web admin panel access\n- **Networking**:\n    - Listens on port 8000 for HTTP connections\n    - Optional SSL socket on port 8443\n\n## Liquidsoap Configuration\n\nLiquidsoap provides these key functions:\n\n- **Harbor Input**: Listens on port 8010 for incoming streams from Audio Hijack\n- **Silence Detection**: Monitors the live stream for silence\n    - If silence exceeds 60 seconds, switches to backup source\n    - Threshold set to -50dB to detect true silence\n- **Backup System**: Provides a reliable fallback system\n    - Uses a randomized playlist from the backup directory\n    - If playlist fails, falls back to an emergency track\n- **Dual Format Output**: Sends the stream to Icecast in both formats\n    - MP3 stream at 128kbps\n    - AAC stream at 96kbps\n\n## Caddy Setup\n\nCaddy serves as the frontend for listeners and handles:\n\n- **SSL/TLS**: Automatic HTTPS certificate management\n- **Stream Routing**:\n    - `/mp3` route serves the MP3 stream\n    - `/aac` route serves the AAC stream\n    - Root path `/` redirects to the MP3 stream\n- **Security**:\n    - Admin panel access restricted to specific IP range (ex: 142.207.50.0/24)\n    - Proper headers for streaming (Range, proxy configuration, etc.)\n- **Proxy Configuration**:\n    - Uses HTTP/1.1 for compatibility with streaming\n    - Disables buffering for real-time streaming\n    - Sets appropriate headers for cross-origin access\n\n## Security Considerations\n\n- Passwords are stored as environment variables, not in configuration files\n- Admin access is restricted by IP\n- HTTPS is enforced for all connections\n- Authentication is required for source connections\n\n## Monitoring and Maintenance\n\n- Icecast provides a status page for monitoring active listeners\n- Logs are stored in mounted volumes for persistence\n- Container health can be monitored via Docker\n\n### Check server status\n\n```bash\ndocker compose ps\n```\n\n### View logs\n\n```bash\ndocker compose logs\n```\n\n## Stream Client Configuration\n\nAudio Hijack (or similar software) should be configured to:\n\n- Connect to the server's public IP or hostname\n- Use port 8010 (Liquidsoap's harbor input)\n- Use the mount point \"live\" (without extension)\n- Authenticate with the harbor password\n- Stream in MP3 format (128kbps or higher recommended)\n\n## Troubleshooting Tips\n\n- Check Docker container logs for issues:\n    - `docker-compose logs liquidsoap`\n    - `docker-compose logs icecast`\n- Verify stream connection with:\n    - `curl -I http://localhost:8000/live.mp3`\n- Test playlist playback by stopping the live source\n- Monitor silence detection by temporarily muting the input","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichochieng%2Fweb-radio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichochieng%2Fweb-radio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichochieng%2Fweb-radio/lists"}