FFmpeg - IceCast Metadata: Difference between revisions

From PiRho Knowledgebase
Jump to navigationJump to search
← Older edit
Dex (talk | contribs)
279 edits
Dex (talk | contribs)
279 edits
No edit summary
 
Line 1: Line 1:
This protocol accepts the following options:
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
; ice_genre
: Set the stream genre.
: Sets the genre associated with the stream.


; ice_name
; ice_name
: Set the stream name.
: The display name of the stream.


; ice_description
; ice_description
: Set the stream description.
: A longer description of the stream.


; ice_url
; ice_url
: Set the stream website URL.
: The homepage or website URL associated with the stream.


; ice_public
; ice_public
: Set if the stream should be public. The default is 0 (not public).
: Controls whether the stream should be listed publicly. Default: 0.


; user_agent
; user_agent
: Override the User-Agent header. If not specified a string of the form "Lavf/<version>" will be used.
: Overrides the default HTTP User-Agent header.


; password
; password
: Set the Icecast mountpoint password.
: Password for the Icecast mountpoint.


; content_type
; content_type
: Set the stream content type. This must be set if it is different from audio/mpeg.
: Defines the MIME type of the audio stream.


; legacy_icecast
; legacy_icecast
: This enables support for Icecast versions < 2.4.0, that do not support the HTTP PUT method but the SOURCE method.
: Enables compatibility with Icecast versions older than 2.4.0.


; tls
; tls
: Establish a TLS (HTTPS) connection to Icecast.
: Enables streaming over HTTPS/TLS.
 
== 3. URL Format ==
FFmpeg connects to Icecast using this syntax:


<pre>
<pre>
icecast://[username[:password]@]server:port/mountpoint
icecast://[username[:password]@]server:port/mountpoint
</pre>
</pre>
Reference: [[https://ffmpeg.org/ffmpeg-protocols.html#Icecast FFmpeg: FFmpeg Protocols Documentation]]
 
=== Basic MP3 Radio Stream ===
<pre>
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
</pre>
 
=== Secure (HTTPS) Stream ===
<pre>
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
</pre>
 
== 4. Practical Notes & Best Practices ==
=== Metadata Updates ===
You can update metadata dynamically using:
<pre>
ffmpeg -metadata title="New Track"
</pre>
 
=== 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 ===
<pre>
-loglevel debug
</pre>
 
=== Verify Mountpoint Configuration ===
Via the Icecast admin interface:
<pre>
http://server:port/admin/stats
</pre>
 
== 7. Related Articles ==
* [[FFmpeg – Streaming to Icecast]]
* [[Audio Streaming Formats Overview]]
* [[Opus vs MP3 – Choosing the Right Codec]]
* [[Troubleshooting Icecast Streams]]
 
== 8. References ==
* https://ffmpeg.org/ffmpeg-protocols.html#Icecast
* https://icecast.org

Latest revision as of 15:54, 14 March 2026

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

8. References

Retrieved from "https://knowledgebase.pirho.net/index.php?title=FFmpeg_-_IceCast_Metadata&oldid=333"