Icecast Server/Events

From XiphWiki
Jump to navigation Jump to search



Icecast 2.5.x features an event subsystem. This subsystem is used to deliver information on certain events that happen within the server to backends. In it's nature it is very similar to the auth subsystem. However in contrast to the auth subsystem it cannot modify the server state in any way. This makes it much more performant at the cost of slightly less usecases. Events in the event subsystem are inherently delivered asynchronously. Therefore they may arrive at some handler in any order. However information regarding their causality is preserved via their data.


Event subsystem backends are configured via <event />s inside of a <event-bindings />. <event-bindings /> can be used inside:

  • <icecast /> (global headers)
  • <mount />

<event-bindings /> has no properties itself. <event /> may contain <option />s with backend specific options. It will also use the following properties:

Property Required Type Default Description
type yes Backend name none The name of the backend to use.
trigger yes list of event names none A comma separated list of event names to deliver to this backend. The list may include * as wildcard after the first dash. Also entries can be prefixed using ! to negatively match them.

List of events

event Context Description
icecast-start Global Emitted when Icecast has been started up initially.
icecast-stop Global Emitted as part of Icecast's shutdown.
icecast-active Global Emitted when Icecast is active (has sources connected).
icecast-idle Global Emitted when Icecast is in idle (no sources connected).
source-connect Source Emitted when a source enters running state.
source-disconnect Source Emitted when a source is shut down.
source-flags-changed Source Emitted when a source experiences changes of it's flags. This might be for internal and external reasons.
source-listener-attach Source Emitted when a listener has been attached to a source. Note: experimental.
source-listeners-changed Source Emitted when the number of listeners changed. Note: experimental.
source-listeners-is-zero Source Same as source-listeners-changed but only emitted when the listener count is now zero. Note: experimental.
format-metadata-changed Source Emitted whenever the metadata on the format level changes.
dumpfile-opened Source Emitted when a dumpfile was just opened. At the time this is emitted any operations on the dumpfile as per the operating systems specification on open files are allowed. This usually includes renaming the file and moving it between directories on the same volume.
dumpfile-closed Source Emitted when a dumpfile is closed. Note: At this point Icecast knows hardly anything about the dumpfile anymore. So not all information is available to handlers of this event. Any operation should be done via dumpfile-opened whenever possible.
dumpfile-error Source Emitted when a dumpfile cannot be opened for any reason. See also dumpfile-opened.



The exec backend is used to start local executables. As this comes with many per-operating system and deployment specific restrictions it is generally best avoided. The url backend is often a better alternative.


Option Required Type Default Description
executable Yes path none Full path to the executable to be started
default_arguments no enum default Style of default arguments to be passed. One of: default, no_defaults, uri, uri_and_trigger, or legacy

In addition options with no name but type="argument" can be added. The values of those options are passed to the executable as arguments after the options passed as per default_arguments.

Styles of default arguments

Style Arguments Notes
default - Currently same as legacy.
no_defaults none No arguments are passed. Data is still accessible via environment.
uri mount point Only the mount point is passed as argument.
uri_and_trigger mount point, trigger The mount point followed by the name of the event that is delivered is passed.
legacy [mount point] Only the mount point is passed. If the mount point is not set for this event the argument is skipped.


The log backend writes events into the standard error.log. The main use for this is to debug and check configuration.


Option Required Type Default Description
prefix no string Event A prefix to be used in the logfile. Can be used to easily grep(1) for the lines.
level no log level information The level at which to log the events.


This backend is used to deliver the event to some backend server (normally via HTTP). It is very similar to the auth subsystem's url backend.


Option Required Type Default Description
username no username none Username used to login to the backend.
password no password none Password used to login to the backend.
url Yes URL none URL used to deliver the events to
action no string name of the event Value for the action-parameter sent as part of backend requests. When no value is given the name of the event is used.
legacy no boolean true Whether or not the new style is used for the parameters.