ICY metadata

ICY metadata is the name for the mechanism used to update metadata in icecast’s source streams. The techniques is primarily intended for data formats that do not support in-stream metadata, such as mp3 or AAC. However, it appears that icecast also supports ICY metadata update for ogg/vorbis streams.

When using the ICY metadata update mechanism, new metadata are submitted separately from the stream’s data, via a http GET request. The format of the request depends on the protocol you are using (ICY for shoutcast and icecast 1 or HTTP for icecast 2).

Starting with 1.0, you can do several interesting things with icy metadata updates in liquidsoap. We list some of those here.

Enable/disable ICY metadata updates

You can enable or disable icy metadata update in output.icecast by setting the send_icy_metadata parameter to null(),trueorfalse. The default value isnull()` and does the following:

  • Set true for: mp3, aac, aac+, wav
  • Set false for any format using the ogg container

In some cases, liquidsoap might not be able to detect if ICY metadata need to be enabled, in which case it will ask you to set a true or false value for this parameter.

song metadata

Most Icecast listeners expect a song metadata to be generated. This metadata should combine both artist and title metadata and will be played preferably.

We provide a default implementation that returns artist or title metadata when only one of these two is available and $(artist) - $(title) otherwise.

You can use the icy_song parameter to use your own implementation. Returning null() from that function disables the metadata altogether.

Update metadata manually

The function icy.update_metadata implements a manual metadata update using the ICY mechanism. It can be used independently from the icy_metadata parameter described above, provided icecast supports ICY metadata for the intended stream.

For instance the following script registers a telnet command name metadata.update that can be used to manually update metadata:

def icy_update(v) =
  # Parse the argument
  l = string.split(separator=",", v)
  def split(l, v) =
    v = string.split(separator="=", v)
    if
      list.length(v) >= 2
    then
      list.append(l, [(list.nth(v, 0, default=""), list.nth(v, 1, default=""))])
    else
      l
    end
  end
  meta = list.fold(split, [], l)

  # Update metadata
  icy.update_metadata(
    mount="/mystream", password="hackme", host="myserver.net", meta
  )
  "Done !"
end

server.register(
  "update",
  namespace="metadata",
  description=
    "Update metadata",
  usage=
    "update title=foo,album=bar,..",
  icy_update
)

As usual, liquidsoap -h icy.update_metadata lists all the arguments of the function.