FFmpeg - IceCast Metadata
The **Icecast protocol in FFmpeg** allows you to stream audio to an Icecast server while sending rich metadata such as stream title, genre, description, and visibility flags. These options are supplied as URL parameters or command‑line arguments when pushing a stream.
This article explains the purpose of each option, how to use them in practice, and how to avoid common pitfalls when publishing to Icecast.
1. Overview
Icecast is an open‑source streaming server commonly used for internet radio, live broadcasts, and automated playlists. FFmpeg can act as a source client, sending encoded audio along with metadata that Icecast exposes to listeners and directory services.
This protocol is typically used when:
- Hosting a personal or commercial internet radio stream
- Updating song/track metadata during a broadcast
- Automating multiple stream mountpoints
- Broadcasting in formats such as MP3, OGG, AAC, or Opus
2. Metadata & Connection Options
These options are passed to FFmpeg via -ice_* parameters or embedded in the output URL.
- ice_genre
- Sets the genre associated with the stream.
- ice_name
- The display name of the stream.
- ice_description
- A longer description of the stream.
- ice_url
- The homepage or website URL associated with the stream.
- ice_public
- Controls whether the stream should be listed publicly. Default: 0.
- user_agent
- Overrides the default HTTP User-Agent header.
- password
- Password for the Icecast mountpoint.
- content_type
- Defines the MIME type of the audio stream.
- legacy_icecast
- Enables compatibility with Icecast versions older than 2.4.0.
- tls
- Enables streaming over HTTPS/TLS.
3. URL Format
FFmpeg connects to Icecast using this syntax:
icecast://[username[:password]@]server:port/mountpoint
Basic MP3 Radio Stream
ffmpeg -re -i input.mp3 -c:a libmp3lame -b:a 128k -content_type audio/mpeg -ice_name "Dex FM" -ice_description "Smooth coding tunes." -ice_url "https://dexradio.example" -ice_genre "Chill" -ice_public 1 -f mp3 icecast://source:password@radio.example.com:8000/live
Secure (HTTPS) Stream
ffmpeg -re -i playlist.m3u -c:a libopus -b:a 64k -content_type audio/ogg -tls -f ogg icecast://source:password@radio.example.com:8443/secure
4. Practical Notes & Best Practices
Metadata Updates
You can update metadata dynamically using:
ffmpeg -metadata title="New Track"
Choosing the Right Content Type
- audio/mpeg — MP3
- audio/aac — AAC
- audio/ogg — OGG/Opus/Vorbis
When to Use legacy_icecast
Enable only for pre‑2.4 Icecast servers.
TLS Caveats
Ensure the selected port supports HTTPS.
5. Common Pitfalls
- Incorrect username/password
- Wrong mountpoint
- Missing MIME type
- Using TLS on a non‑TLS port
6. Troubleshooting
Check Icecast Logs
Authentication errors, connection drops, metadata issues.
FFmpeg Debug Output
-loglevel debug
Verify Mountpoint Configuration
Via the Icecast admin interface:
http://server:port/admin/stats
7. Related Articles
- FFmpeg – Streaming to Icecast
- Audio Streaming Formats Overview
- Opus vs MP3 – Choosing the Right Codec
- Troubleshooting Icecast Streams
