XiphWiki - User contributions [en]

Icecast Server/Listen Sockets

2026-01-20T00:31:37Z

Phschafft: /* Sub-tags */ Fixed typo

= Listen Sockets =
<div class="boilerplate metadata" style="background-color: #fee; margin: 0 1em; padding: 0 10px; border: 1px solid #aaa;">
'''Icecast 2.5.x page'''

This page discusses the topic in context of Icecast 2.5.x. The situation for 2.4.x might be different.
</div>

== Overview ==
Icecast supports to listen on multiple sockets. Each socket is configured via a <code><<nowiki />listen-socket /></code>. Each listen socket supports a number of options.

== Configuration ==

The <code><<nowiki />listen-socket /></code> tag is used to configure listen sockets. Options are defined via sub-tags.

=== Properties ===
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>id</code> || no || id || ''none'' || Identifier for the listen socket
|-
| <code>on-behalf-of</code> || no || URI || ''none'' || ''TODO''
|-
| <code>type</code> || no || socket type || <code>normal</code> || Type of the listen socket. One of <code>normal</code>, or <code>virtual</code>
|-
|}

=== Sub-tags ===
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>port</code> || no || port number || <code>8000</code> || The port number to listen on (0-65535, but in most cases 1025-49151)
|-
| <code>tls</code> || no || [[Icecast_Server/known_https_restrictions#Icecast2_2.5.x_(branch_"master")|TLS mode]] || <code>disabled</code> || The TLS mode to be used for this listen socket.
|-
| <code>bind-address</code> || no || FQDN || ''any'' || The hostname used to listen on. If the hostname resolves to multiple addresses, the system defaults will be used to find the most suitable address. If mapping of legacy IP is supported via IPv6 sockets IPv6 addresses are preferred.
|-
| <code>client-address</code> || no || FQDN || ''none'' || The outbound address used by this listen socket. This is specifically used by <code>type="virtual"</code> listen sockets.
|-
| <code>so-sndbuf</code> || no || positive integer || ''system default'' || The send buffer to be used with client connections on this listen socket. It is not recommended to alter this value.
|-
| <code>listen-backlog</code> || no || positive integer || ''Icecast default'' || The listen backlog to use for the listen socket. On very busy servers with a lot clients connecting at the same time it might be useful to increase this value slightly (e.g. to 15). A very high value suggests misconfiguration or system overload.
|-
| <code>authentication</code> || no || [[Icecast_Server/2.5_Authentication|Authentication block]] || ''none'' || Additional authentication configuration specific to this listen socket. This is generally not needed.
|-
| <code>http-headers</code> || no || [[Icecast_Server/Custom_HTTP_Headers|HTTP headers block]] || ''none'' || Additional HTTP headers specific to this listen socket. This is generally not needed.
|-
| <code>shoutcast-compat</code> || no || boolean || <code>false</code> || Whether this listen socket should accept shoutcast legacy clients. This value should be kept at it's default even for most shoutcast legacy enabled setups. See also <code>shoutcast-mount</code>.
|-
| <code>shoutcast-mount</code> || no || mount point || ''none'' || The mount point to use for shoutcast legacy clients. This will create another listen socket with the correct values as per requirements of shoutcast. This is mostly for software from the 90s.
|-
| <code>trusted-proxy</code> || no || URI || ''none'' || The URI of the id of any listen sockets (likely <code>type="virtual"</code>) that terminate the client's connection (e.g. reverse proxies). Setting this allows those proxies to act on behalf of the client.
|-
|}

Icecast Server/2.5 Maintenance

2026-01-19T23:29:47Z

Phschafft: /* Sources list */ Added list of messages

= Icecast 2.5.x Maintenance =
== Overview ==
Icecast versions 2.5.x report a list of "Maintenance" items in the dashboard within the admin interface. Those messages are meant to provide help to keep a deployment in best shape.

The Following levels are defined:
=== Info ===
Info level messages are just there to aid e.g. in case of a problem. No active action is required.

=== Warning ===
Warnings should be considered thoroughly and the problems generally should be resolved in a timely manner. It is possible that the operation is affected by the problems reported with warnings.

=== Error ===
Errors record actual problems and should be taken care of as soon as possible.

== Dashboard ==

The following messages can be found on the global dashboard.

=== Info ===

==== Core files are disabled. / Core files are enabled. ====
This informs whether or not core files are enabled. Core files are a classic mean of debugging offered by some operating systems. Support may ask for this value.

==== IPv4-mapped IPv6 is available on this system. ====
The operation system supports legacy IP via current IP sockets. This means that only an IPv6 socket needs to be configured to also handle legacy IP.

This information may be hidden if Icecast seems to be configured correctly to avoid spamming the section.

==== chroot configured and active. ====
chroot was configured and is active. See your operation system's documentation on the details of chroot.

==== Change of UID/GID configured and active. ====
Changing of the user ID and/or group ID was configured and was successful.

==== Currently no sources are connected to this server. ====
There are currently no sources connected. The server is in idle state.

==== More than 75% of the server's configured maximum clients are connected ====
The server reached at least 75% of it's configured client limit. If that is a reason to take action depends on the current relative load (base load, peak hours, ...) of the server and the type of listeners.

==== Environment is noisy. ====
The user environment contains entries that should not be present in a daemon environment. This is a indication for the server being started as a user process instead of as a daemon. This should not be seen in production.

=== Warning ===

==== Developer logging is active. This mode is not for production. ====
Icecast is build with developer logging active. This should never be seen in production. If seen without an Icecast developer asked for it it should be disabled. To disable this Icecast needs to be recompiled.

==== Hostname is not set to anything useful in <hostname>. ====
The hostname tag is not set correctly in the Icecast configuration. Some features such as directory support may be disabled. Playlist generation may not work correctly. There is generally more details in the error log. See https://icecast.org/faq/#faqentry-what-should-i-set-hostname-to for details.

==== No useful location is given in <location>. ====
The location tag is not set to anything useful in the configuration. See https://icecast.org/faq/#faqentry-what-should-i-set-location-to for details.

==== No admin contact given in <admin>. YP directory support is disabled. ====
No valid admin contact details are given. Some features such as directory support may be disabled. See https://icecast.org/faq/#faqentry-what-should-i-set-admin-to for details.

==== Legacy sources are connected. See mount list for details. ====
Sources using legacy features or protocols are connected. This for example includes ICY sources. The list of sources should be checked for possibility of upgrading those sources.

==== More than 90% of the server's configured maximum clients are connected ====
More than 90% of the server's configured client limit is connected. This might be a sign that the limit should be lifted higher. However this might also be normal (for example in peak hours or when the number of listeners is very stable and the limit is set close to that).

==== No secure password hash support detected. ====
No secure password hashing scheme was detected. Icecast will fall back to legacy support. It is best to contact the support with the full details from the admin's version page.

=== Error ===

==== Global client, and source limit is bigger than suitable for current open file limit. ====
Icecast is configured in a way allowing for more connections than the operating system permits. This may result in strange behaviour when the operating system's limit is reached.

Usually this is due to Icecast being set to some aggressively high client limit. However it can also be due to a low limit enforced by the operating system. In general the limit of the operating system must be higher than the one set by Icecast for Icecast to actually handle the number of clients.

==== IPv6 not enabled. ====
Icecast is configured with only legacy IP enabled. The current IP version (IPv6) needs to be enabled.

==== No PRNG seed configured. PRNG is insecure. ====
No configuration for the PRNG is given. The generator may return weak values. libigloo defaults are used. See libigloo's documentation for details.

==== Unknown tags are used in the config file. See the error.log for details. ====
Unknown tags are found in the configuration file. Those are invalid and future versions of Icecast may not load with them present. See the error log for details.

Unknown tags are often a result of typos.

==== Obsolete tags are used in the config file. See the error.log for details and update your configuration accordingly. ====
Obsolete tags are found in the configuration file. Those should be updated or removed accordingly. Future versions of Icecast may not load with them present. See the error log for details.

==== Invalid tags are used in the config file. See the error.log for details and update your configuration accordingly. ====
Invalid tags (for example tags with invalid values) are found in the configuration file. Those must be corrected. Future versions of Icecast may not load with them present. See the error log for details.

==== The configuration did not validate. See the error.log for details and update your configuration accordingly. ====
The configuration file is not valid. It may contain logical errors such as invalid combinations of values. Those must be corrected. Future versions of Icecast may not load with them present. See the error log for details.

==== File permissions are wrong. See the error.log for details and update your configuration accordingly. Future versions of Icecast may reject affected files. ====
Some of the files used by Icecast (such as the configuration or logfiles) have wrong permissions. Please check the permissions and correct them accordingly. The error log will contain more information on which files are the problem.

==== Potentially unsafe file permissions. See the error.log for details and update your configuration accordingly. Future versions of Icecast may reject affected files. ====
Some of the files used by Icecast seem to have unsafe permissions. This may result in leakage of credentials, secret keys, or similar data. It is strongly recommended to check the files reported in the error log and change credentials and secret keys accordingly.
Future versions of Icecast may reject those files, including rejecting to start at all or only starting in a limited fashion if unresolved.

==== chroot configured but failed. ====
chroot was configured but failed. This is a security problem and requires immediate handling. See the error log and your operation system's documentation for more details.

==== chroot configured but not supported by operating system. ====
chroot was configured but is not supported by the operating system. This is a security problem and requires immediate handling. See the error log and your operation system's documentation for more details.

==== Change of UID/GID configured but failed. ====
Changing of the user ID and/or group ID was configured but failed. This is a security problem and requires immediate handling. See the error log and your operation system's documentation for more details.

==== Change of UID/GID configured but not supported by operating system. ====
Changing of the user ID and/or group ID was configured but is not supported by the operating system. This is a security problem and requires immediate handling. See the error log and your operation system's documentation for more details.

== Sources list ==
=== Info ===

==== Legacy HTTP/1.0 listener ====
One or more legacy listeners has accessed the stream.
The client should upgrade.
No action is required on Icecast's side.

==== Listener without usable Host:-header ====
One or more listeners connected without sending a usable `Host:`-header.
Icecast may not provide the best service to such clients as the value needs to be guessed.
This is a problem more common with ancient clients.
No action is required on Icecast's side.

==== No content language set ====
The source did not set a language for the stream.
The source client's configuration should be checked and updated accordantly.
No action is required on Icecast's side.

=== Warning ===

==== Legacy or unsupported streaming format is used. ====
The stream is sent in an legacy or an unsupported format.
Icecast falls back to a generic handler which might or might not work.
No formal support is provided for such streams.

It is best to only stream in fully supported formats.
The format can be selected in most source clients.

No action is required on Icecast's side.

==== Character set is not UTF-8 ====
The character set of the stream is not UTF-8.
This can be a problem with legacy streams (ICY).
This can result in metadata not being shown correctly.

It is recommended to consider setting the stream's character set to UTF-8.
However, this can also upset legacy clients.
Caution is advised.

==== The stream did not mature yet. ====
The stream is still very new.
This message will resolve itself after a few seconds on a healthy stream.
If the message seems to be persistent or is often reported over a span of several minutes there is a problem with the source client's connection or the data the source client sends.

If unresolved for several minutes, the source client's connection should be checked.
If the source client's connection is fine, the source client seems to not work properly.

No action is required on Icecast's side.

=== Error ===

==== No data has yet been received. ====
This message is reported when no data has yet been received by Icecast from the source client.
If this message persists for several seconds, the source client is most likely not working properly.

It is possible but highly unlikely, that this is caused by a bad network connection.
If so, the connection is likely not suitable for a source client at all (independent on the source's settings such as bitrate).

No action is required on Icecast's side.

==== Legacy metadata on non-legacy source received. This is likely a bug in the source client. ====
A legacy metadata update request was sent on a non-legacy source.
This is most likely a bug in the source client.
It is also possible that other components try to update the metadata in a way unsuitable for the stream.

Icecast may reject such requests for security reasons.
Metadata might not work correctly on such streams.

It is best to report this to the source client's vendor.
No action is required on Icecast's side.

Icecast Server/2.5 Maintenance

2026-01-19T23:06:15Z

Phschafft: Added section stub for Sources list

Icecast Server/2.5 Maintenance

2026-01-19T22:59:14Z

Phschafft: /* List */ Renamed section to Dashboard

= Icecast 2.5.x Maintenance =
== Overview ==
Icecast versions 2.5.x report a list of "Maintenance" items in the dashboard within the admin interface. Those messages are meant to provide help to keep a deployment in best shape.

== Dashboard ==

The following messages can be found on the global dashboard.

=== Info ===
Info level messages are just there to aid e.g. in case of a problem. No active action is required.

==== Core files are disabled. / Core files are enabled. ====
This informs whether or not core files are enabled. Core files are a classic mean of debugging offered by some operating systems. Support may ask for this value.

==== IPv4-mapped IPv6 is available on this system. ====
The operation system supports legacy IP via current IP sockets. This means that only an IPv6 socket needs to be configured to also handle legacy IP.

This information may be hidden if Icecast seems to be configured correctly to avoid spamming the section.

==== chroot configured and active. ====
chroot was configured and is active. See your operation system's documentation on the details of chroot.

==== Change of UID/GID configured and active. ====
Changing of the user ID and/or group ID was configured and was successful.

==== Currently no sources are connected to this server. ====
There are currently no sources connected. The server is in idle state.

==== More than 75% of the server's configured maximum clients are connected ====
The server reached at least 75% of it's configured client limit. If that is a reason to take action depends on the current relative load (base load, peak hours, ...) of the server and the type of listeners.

==== Environment is noisy. ====
The user environment contains entries that should not be present in a daemon environment. This is a indication for the server being started as a user process instead of as a daemon. This should not be seen in production.

=== Warning ===
Warnings should be considered thoroughly and the problems generally should be resolved in a timely manner. It is possible that the operation is affected by the problems reported with warnings.

==== Developer logging is active. This mode is not for production. ====
Icecast is build with developer logging active. This should never be seen in production. If seen without an Icecast developer asked for it it should be disabled. To disable this Icecast needs to be recompiled.

==== Hostname is not set to anything useful in <hostname>. ====
The hostname tag is not set correctly in the Icecast configuration. Some features such as directory support may be disabled. Playlist generation may not work correctly. There is generally more details in the error log. See https://icecast.org/faq/#faqentry-what-should-i-set-hostname-to for details.

==== No useful location is given in <location>. ====
The location tag is not set to anything useful in the configuration. See https://icecast.org/faq/#faqentry-what-should-i-set-location-to for details.

==== No admin contact given in <admin>. YP directory support is disabled. ====
No valid admin contact details are given. Some features such as directory support may be disabled. See https://icecast.org/faq/#faqentry-what-should-i-set-admin-to for details.

==== Legacy sources are connected. See mount list for details. ====
Sources using legacy features or protocols are connected. This for example includes ICY sources. The list of sources should be checked for possibility of upgrading those sources.

==== More than 90% of the server's configured maximum clients are connected ====
More than 90% of the server's configured client limit is connected. This might be a sign that the limit should be lifted higher. However this might also be normal (for example in peak hours or when the number of listeners is very stable and the limit is set close to that).

==== No secure password hash support detected. ====
No secure password hashing scheme was detected. Icecast will fall back to legacy support. It is best to contact the support with the full details from the admin's version page.

=== Error ===
Errors record actual problems and should be taken care of as soon as possible.

==== Global client, and source limit is bigger than suitable for current open file limit. ====
Icecast is configured in a way allowing for more connections than the operating system permits. This may result in strange behaviour when the operating system's limit is reached.

Usually this is due to Icecast being set to some aggressively high client limit. However it can also be due to a low limit enforced by the operating system. In general the limit of the operating system must be higher than the one set by Icecast for Icecast to actually handle the number of clients.

==== IPv6 not enabled. ====
Icecast is configured with only legacy IP enabled. The current IP version (IPv6) needs to be enabled.

==== No PRNG seed configured. PRNG is insecure. ====
No configuration for the PRNG is given. The generator may return weak values. libigloo defaults are used. See libigloo's documentation for details.

==== Unknown tags are used in the config file. See the error.log for details. ====
Unknown tags are found in the configuration file. Those are invalid and future versions of Icecast may not load with them present. See the error log for details.

Unknown tags are often a result of typos.

==== Obsolete tags are used in the config file. See the error.log for details and update your configuration accordingly. ====
Obsolete tags are found in the configuration file. Those should be updated or removed accordingly. Future versions of Icecast may not load with them present. See the error log for details.

==== Invalid tags are used in the config file. See the error.log for details and update your configuration accordingly. ====
Invalid tags (for example tags with invalid values) are found in the configuration file. Those must be corrected. Future versions of Icecast may not load with them present. See the error log for details.

==== The configuration did not validate. See the error.log for details and update your configuration accordingly. ====
The configuration file is not valid. It may contain logical errors such as invalid combinations of values. Those must be corrected. Future versions of Icecast may not load with them present. See the error log for details.

==== File permissions are wrong. See the error.log for details and update your configuration accordingly. Future versions of Icecast may reject affected files. ====
Some of the files used by Icecast (such as the configuration or logfiles) have wrong permissions. Please check the permissions and correct them accordingly. The error log will contain more information on which files are the problem.

==== Potentially unsafe file permissions. See the error.log for details and update your configuration accordingly. Future versions of Icecast may reject affected files. ====
Some of the files used by Icecast seem to have unsafe permissions. This may result in leakage of credentials, secret keys, or similar data. It is strongly recommended to check the files reported in the error log and change credentials and secret keys accordingly.
Future versions of Icecast may reject those files, including rejecting to start at all or only starting in a limited fashion if unresolved.

==== chroot configured but failed. ====
chroot was configured but failed. This is a security problem and requires immediate handling. See the error log and your operation system's documentation for more details.

==== chroot configured but not supported by operating system. ====
chroot was configured but is not supported by the operating system. This is a security problem and requires immediate handling. See the error log and your operation system's documentation for more details.

==== Change of UID/GID configured but failed. ====
Changing of the user ID and/or group ID was configured but failed. This is a security problem and requires immediate handling. See the error log and your operation system's documentation for more details.

==== Change of UID/GID configured but not supported by operating system. ====
Changing of the user ID and/or group ID was configured but is not supported by the operating system. This is a security problem and requires immediate handling. See the error log and your operation system's documentation for more details.

Icecast Server/2.5 Maintenance

2026-01-19T22:57:17Z

Phschafft: /* Error */ Added new errors

= Icecast 2.5.x Maintenance =
== Overview ==
Icecast versions 2.5.x report a list of "Maintenance" items in the dashboard within the admin interface. Those messages are meant to provide help to keep a deployment in best shape.

== List ==
=== Info ===
Info level messages are just there to aid e.g. in case of a problem. No active action is required.

==== Core files are disabled. / Core files are enabled. ====
This informs whether or not core files are enabled. Core files are a classic mean of debugging offered by some operating systems. Support may ask for this value.

==== IPv4-mapped IPv6 is available on this system. ====
The operation system supports legacy IP via current IP sockets. This means that only an IPv6 socket needs to be configured to also handle legacy IP.

This information may be hidden if Icecast seems to be configured correctly to avoid spamming the section.

==== chroot configured and active. ====
chroot was configured and is active. See your operation system's documentation on the details of chroot.

==== Change of UID/GID configured and active. ====
Changing of the user ID and/or group ID was configured and was successful.

==== Currently no sources are connected to this server. ====
There are currently no sources connected. The server is in idle state.

==== More than 75% of the server's configured maximum clients are connected ====
The server reached at least 75% of it's configured client limit. If that is a reason to take action depends on the current relative load (base load, peak hours, ...) of the server and the type of listeners.

==== Environment is noisy. ====
The user environment contains entries that should not be present in a daemon environment. This is a indication for the server being started as a user process instead of as a daemon. This should not be seen in production.

=== Warning ===
Warnings should be considered thoroughly and the problems generally should be resolved in a timely manner. It is possible that the operation is affected by the problems reported with warnings.

==== Developer logging is active. This mode is not for production. ====
Icecast is build with developer logging active. This should never be seen in production. If seen without an Icecast developer asked for it it should be disabled. To disable this Icecast needs to be recompiled.

==== Hostname is not set to anything useful in <hostname>. ====
The hostname tag is not set correctly in the Icecast configuration. Some features such as directory support may be disabled. Playlist generation may not work correctly. There is generally more details in the error log. See https://icecast.org/faq/#faqentry-what-should-i-set-hostname-to for details.

==== No useful location is given in <location>. ====
The location tag is not set to anything useful in the configuration. See https://icecast.org/faq/#faqentry-what-should-i-set-location-to for details.

==== No admin contact given in <admin>. YP directory support is disabled. ====
No valid admin contact details are given. Some features such as directory support may be disabled. See https://icecast.org/faq/#faqentry-what-should-i-set-admin-to for details.

==== Legacy sources are connected. See mount list for details. ====
Sources using legacy features or protocols are connected. This for example includes ICY sources. The list of sources should be checked for possibility of upgrading those sources.

==== More than 90% of the server's configured maximum clients are connected ====
More than 90% of the server's configured client limit is connected. This might be a sign that the limit should be lifted higher. However this might also be normal (for example in peak hours or when the number of listeners is very stable and the limit is set close to that).

==== No secure password hash support detected. ====
No secure password hashing scheme was detected. Icecast will fall back to legacy support. It is best to contact the support with the full details from the admin's version page.

=== Error ===
Errors record actual problems and should be taken care of as soon as possible.

==== Global client, and source limit is bigger than suitable for current open file limit. ====
Icecast is configured in a way allowing for more connections than the operating system permits. This may result in strange behaviour when the operating system's limit is reached.

Usually this is due to Icecast being set to some aggressively high client limit. However it can also be due to a low limit enforced by the operating system. In general the limit of the operating system must be higher than the one set by Icecast for Icecast to actually handle the number of clients.

==== IPv6 not enabled. ====
Icecast is configured with only legacy IP enabled. The current IP version (IPv6) needs to be enabled.

==== No PRNG seed configured. PRNG is insecure. ====
No configuration for the PRNG is given. The generator may return weak values. libigloo defaults are used. See libigloo's documentation for details.

==== Unknown tags are used in the config file. See the error.log for details. ====
Unknown tags are found in the configuration file. Those are invalid and future versions of Icecast may not load with them present. See the error log for details.

Unknown tags are often a result of typos.

==== Obsolete tags are used in the config file. See the error.log for details and update your configuration accordingly. ====
Obsolete tags are found in the configuration file. Those should be updated or removed accordingly. Future versions of Icecast may not load with them present. See the error log for details.

==== Invalid tags are used in the config file. See the error.log for details and update your configuration accordingly. ====
Invalid tags (for example tags with invalid values) are found in the configuration file. Those must be corrected. Future versions of Icecast may not load with them present. See the error log for details.

==== The configuration did not validate. See the error.log for details and update your configuration accordingly. ====
The configuration file is not valid. It may contain logical errors such as invalid combinations of values. Those must be corrected. Future versions of Icecast may not load with them present. See the error log for details.

==== File permissions are wrong. See the error.log for details and update your configuration accordingly. Future versions of Icecast may reject affected files. ====
Some of the files used by Icecast (such as the configuration or logfiles) have wrong permissions. Please check the permissions and correct them accordingly. The error log will contain more information on which files are the problem.

==== Potentially unsafe file permissions. See the error.log for details and update your configuration accordingly. Future versions of Icecast may reject affected files. ====
Some of the files used by Icecast seem to have unsafe permissions. This may result in leakage of credentials, secret keys, or similar data. It is strongly recommended to check the files reported in the error log and change credentials and secret keys accordingly.
Future versions of Icecast may reject those files, including rejecting to start at all or only starting in a limited fashion if unresolved.

==== chroot configured but failed. ====
chroot was configured but failed. This is a security problem and requires immediate handling. See the error log and your operation system's documentation for more details.

==== chroot configured but not supported by operating system. ====
chroot was configured but is not supported by the operating system. This is a security problem and requires immediate handling. See the error log and your operation system's documentation for more details.

==== Change of UID/GID configured but failed. ====
Changing of the user ID and/or group ID was configured but failed. This is a security problem and requires immediate handling. See the error log and your operation system's documentation for more details.

==== Change of UID/GID configured but not supported by operating system. ====
Changing of the user ID and/or group ID was configured but is not supported by the operating system. This is a security problem and requires immediate handling. See the error log and your operation system's documentation for more details.

Icecast Server/2.5 Maintenance

2026-01-19T22:28:08Z

Phschafft: /* Warning */ Removed duplicate

Icecast Server/Listen Sockets

2026-01-13T19:13:06Z

Phschafft: Feature: Added 2.5.0 specific entries for reverse proxies

= Listen Sockets =
<div class="boilerplate metadata" style="background-color: #fee; margin: 0 1em; padding: 0 10px; border: 1px solid #aaa;">
'''Icecast 2.5.x page'''

This page discusses the topic in context of Icecast 2.5.x. The situation for 2.4.x might be different.
</div>

== Overview ==
Icecast supports to listen on multiple sockets. Each socket is configured via a <code><<nowiki />listen-socket /></code>. Each listen socket supports a number of options.

== Configuration ==

The <code><<nowiki />listen-socket /></code> tag is used to configure listen sockets. Options are defined via sub-tags.

=== Properties ===
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>id</code> || no || id || ''none'' || Identifier for the listen socket
|-
| <code>on-behalf-of</code> || no || URI || ''none'' || ''TODO''
|-
| <code>type</code> || no || socket type || <code>normal</code> || Type of the listen socket. One of <code>normal</code>, or <code>virtual</code>
|-
|}

=== Sub-tags ===
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>port</code> || no || port number || <code>8000</code> || The port number to listen on (0-65535, but in most cases 1025-49151)
|-
| <code>tls</code> || no || [[Icecast_Server/known_https_restrictions#Icecast2_2.5.x_(branch_"master")|TLS mode]] || <code>disabled</code> || The TLS mode to be used for this listen socket.
|-
| <code>bind-address</code> || no || FQDN || ''any'' || The hostname used to listen on. If the hostname resolves to multiple addresses, the system defaults will be used to find the most suitable address. If mapping of legacy IP is supported via IPv6 sockets IPv6 addresses are preferred.
|-
| <code>client-address</code> || no || FQDN || ''none'' || The outbound address used by this listen socket. This is specifically used by <code>type="virtual"</code> listen sockets.
|-
| <code>so-sndbuf</code> || no || positive integer || ''system default'' || The send buffer to be used with client connections on this listen socket. It is not recommended to alter this value.
|-
| <code>listen-backlog</code> || no || positive integer || ''Icecast default'' || The listen backlog to use for the listen socket. On very busy servers with a lot clients connecting at the same time it might be useful to increase this value slightly (e.g. to 15). A very high value suggests misconfiguration or system overload.
|-
| <code>authentication</code> || no || [[Icecast_Server/2.5_Authentication|Authentication block]] || ''none'' || Additional authentication configuration specific to this listen socket. This is generally not needed.
|-
| <code>http-headers</code> || no || [[Icecast_Server/Custom_HTTP_Headers|HTTP headers block]] || ''none'' || Additional HTTP headers specific to this listen socket. This is generally not needed.
|-
| <code>shoutcast-compat</code> || no || boolean || <code>false</code> || Whether this listen socket should accept shoutcast legacy clients. This value should be kept at it's default even for most shoutcast legacy enabled setups. See also <code>shoutcast-mount</code>.
|-
| <code>shoutcast-mount</code> || no || mount point || ''none'' || The mount point to use for shoutcast legacy clients. This will create another listen socket with the correct values as per requirements of shoutcast. This is mostly for software from the 90s.
|-
| <code>trusted-proxy</code> || no || FQDN || ''none'' || The URI of the id of any listen sockets (likely <code>type="virtual"</code>) that terminate the client's connection (e.g. reverse proxies). Setting this allows those proxies to act on behalf of the client.
|-
|}

Icecast Server/Listen Sockets

2025-12-29T19:29:46Z

Phschafft: /* Sub-tags */ Documented all sub-tags

= Listen Sockets =
<div class="boilerplate metadata" style="background-color: #fee; margin: 0 1em; padding: 0 10px; border: 1px solid #aaa;">
'''Icecast 2.5.x page'''

This page discusses the topic in context of Icecast 2.5.x. The situation for 2.4.x might be different.
</div>

== Overview ==
Icecast supports to listen on multiple sockets. Each socket is configured via a <code><<nowiki />listen-socket /></code>. Each listen socket supports a number of options.

== Configuration ==

The <code><<nowiki />listen-socket /></code> tag is used to configure listen sockets. Options are defined via sub-tags.

=== Properties ===
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>id</code> || no || id || ''none'' || Identifier for the listen socket
|-
| <code>on-behalf-of</code> || no || URI || ''none'' || ''TODO''
|-
| <code>type</code> || no || socket type || <code>normal</code> || Type of the listen socket. One of <code>normal</code>, or <code>virtual</code>
|-
|}

=== Sub-tags ===
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>port</code> || no || port number || <code>8000</code> || The port number to listen on (0-65535, but in most cases 1025-49151)
|-
| <code>tls</code> || no || [[Icecast_Server/known_https_restrictions#Icecast2_2.5.x_(branch_"master")|TLS mode]] || <code>disabled</code> || The TLS mode to be used for this listen socket.
|-
| <code>bind-address</code> || no || FQDN || ''any'' || The hostname used to listen on. If the hostname resolves to multiple addresses, the system defaults will be used to find the most suitable address. If mapping of legacy IP is supported via IPv6 sockets IPv6 addresses are preferred.
|-
| <code>so-sndbuf</code> || no || positive integer || ''system default'' || The send buffer to be used with client connections on this listen socket. It is not recommended to alter this value.
|-
| <code>listen-backlog</code> || no || positive integer || ''Icecast default'' || The listen backlog to use for the listen socket. On very busy servers with a lot clients connecting at the same time it might be useful to increase this value slightly (e.g. to 15). A very high value suggests misconfiguration or system overload.
|-
| <code>authentication</code> || no || [[Icecast_Server/2.5_Authentication|Authentication block]] || ''none'' || Additional authentication configuration specific to this listen socket. This is generally not needed.
|-
| <code>http-headers</code> || no || [[Icecast_Server/Custom_HTTP_Headers|HTTP headers block]] || ''none'' || Additional HTTP headers specific to this listen socket. This is generally not needed.
|-
| <code>shoutcast-compat</code> || no || boolean || <code>false</code> || Whether this listen socket should accept shoutcast legacy clients. This value should be kept at it's default even for most shoutcast legacy enabled setups. See also <code>shoutcast-mount</code>.
|-
| <code>shoutcast-mount</code> || no || mount point || ''none'' || The mount point to use for shoutcast legacy clients. This will create another listen socket with the correct values as per requirements of shoutcast. This is mostly for software from the 90s.
|-
|}

<code></code>

Icecast Server/Listen Sockets

2025-12-29T18:53:08Z

Phschafft: /* Configuration */ Added list of all things on configuration, still needs descriptions

Icecast Server/Listen Sockets

2025-12-29T18:22:16Z

Phschafft: Added initial stub

Icecast Server/2.5 Maintenance

2023-11-20T12:07:15Z

Phschafft: Updates and more items

Icecast Server/2.5 Maintenance

2023-11-20T11:57:29Z

Phschafft: Updates and more items

Icecast Server/2.5 Maintenance

2023-11-20T11:13:11Z

Phschafft: Initial stub

Icecast Server/Events

2023-07-29T09:15:03Z

Phschafft: /* exec */ Added environment variable list

= Events =
<div class="boilerplate metadata" style="background-color: #fee; margin: 0 1em; padding: 0 10px; border: 1px solid #aaa;">
'''Icecast 2.5.x page'''

This page discusses the topic in context of Icecast 2.5.x. The situation for 2.4.x might be different.
</div>

== Overview ==
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.

== Configuration ==
Event subsystem backends are configured via <code><<nowiki />event /></code>s inside of a <code><<nowiki />event-bindings /></code>. <code><<nowiki />event-bindings /></code> can be used inside:
* <code><<nowiki />icecast /></code> (global headers)
* <code><<nowiki />mount /></code>

<code><<nowiki />event-bindings /></code> has no properties itself.
<code><<nowiki />event /></code> may contain <code><<nowiki />option /></code>s with backend specific options. It will also use the following properties:
{| class="wikitable"
! Property !! Required !! Type !! Default !! Description
|-
| <code>type</code> || yes || Backend name || ''none'' || The name of the backend to use.
|-
| <code>trigger</code> || yes || list of event names || ''none'' || A comma separated list of event names to deliver to this backend. The list may include <code>*</code> as wildcard after the first dash. Also entries can be prefixed using <code>!</code> to negatively match them.
|}

== List of events ==

{| class="wikitable"
! event !! Context !! Description
|-
| <code>icecast-start</code> || Global || Emitted when Icecast has been started up initially.
|-
| <code>icecast-stop</code> || Global || Emitted as part of Icecast's shutdown.
|-
| <code>icecast-active</code> || Global || Emitted when Icecast is active (has sources connected).
|-
| <code>icecast-idle</code> || Global || Emitted when Icecast is in idle (no sources connected).
|-
| <code>source-connect</code> || Source || Emitted when a source enters running state.
|-
| <code>source-disconnect</code> || Source || Emitted when a source is shut down.
|-
| <code>source-flags-changed</code> || Source || Emitted when a source experiences changes of it's flags. This might be for internal and external reasons.
|-''
| <code>source-listener-attach</code> || Source || Emitted when a listener has been attached to a source. '''Note:''' experimental.
|-
| <code>source-listeners-changed</code> || Source || Emitted when the number of listeners changed. '''Note:''' experimental.
|-
| <code>source-listeners-is-zero</code> || Source || Same as <code>source-listeners-changed</code> but only emitted when the listener count is now zero. '''Note:''' experimental.
|-
| <code>format-metadata-changed</code> || Source || Emitted whenever the metadata on the format level changes.
|-
| <code>dumpfile-opened</code> || 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.
|-
| <code>dumpfile-closed</code> || 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 <code>dumpfile-opened</code> whenever possible.
|-
| <code>dumpfile-error</code> || Source || Emitted when a dumpfile cannot be opened for any reason. See also <code>dumpfile-opened</code>.
|}

== Backends ==
=== <code>exec</code> ===
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 <code>url</code> backend is often a better alternative.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>executable</code> || Yes || path || ''none'' || Full path to the executable to be started
|-
| <code>default_arguments</code> || no || enum || <code>default</code> || Style of default arguments to be passed. One of: <code>default</code>, <code>no_defaults</code>, <code>uri</code>, <code>uri_and_trigger</code>, or <code>legacy</code>
|}

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

==== Styles of default arguments ====
{| class="wikitable"
! Style !! Arguments || Notes
|-
| <code>default</code> || - || Currently same as <code>legacy</code>.
|-
| <code>no_defaults</code> || ''none'' || No arguments are passed. Data is still accessible via environment.
|-
| <code>uri</code> || mount point || Only the mount point is passed as argument.
|-
| <code>uri_and_trigger</code> || mount point, trigger || The mount point followed by the name of the event that is delivered is passed.
|-
| <code>legacy</code> || [mount point] || Only the mount point is passed. If the mount point is not set for this event the argument is skipped.
|}

==== Environment ====
Icecast will set the following environment:
{| class="wikitable"
! Variable !! Status !! Availability !! Notes
|-
| <code>ICECAST_VERSION</code> || stable || always || Version string of Icecast
|-
| <code>ICECAST_HOSTNAME</code> || stable || always || Hostname of Icecast as given in the config
|-
| <code>ICECAST_ADMIN</code> || stable || always || Admin context of Icecast as given in the config
|-
| <code>ICECAST_LOGDIR</code> || stable || always || Log directory of Icecast as given in the config
|-
| <code>EVENT_TRIGGER</code> || stable || always || The trigger for this event
|-
| <code>EVENT_URI</code> || stable || sometimes || URI (absolute or relative to this instance) the event happened on
|-
| <code>SOURCE_ACTION</code> || deprecated || always || Old name for <code>EVENT_TRIGGER</code>
|-
| <code>SOURCE_MEDIA_TYPE</code> || stable || sometimes || The Media-Type of the stream the source provides
|-
| <code>SOURCE_INSTANCE</code> || stable || sometimes || The instance of the source (UUID)
|-
| <code>SOURCE_MOUNTPOINT</code> || stable || sometimes || The mount point of the source
|-
| <code>SOURCE_PUBLIC</code> || stable || sometimes || Whether or not the mount is configured as public (<code>true</code> or <code>false</code>)
|-
| <code>SROUCE_HIDDEN</code> || stable || sometimes || Whether or not the mount is configured as hidden (<code>true</code> or <code>false</code>)
|-
| <code>CLIENT_IP</code> || stable || sometimes || The IP-Address of the client that caused the event
|-
| <code>CLIENT_ROLE</code> || stable || sometimes || The role of the client that caused the event
|-
| <code>CLIENT_USERNAME</code> || stable || sometimes || The username of the client that caused the event
|-
| <code>CLIENT_USERAGENT</code> || stable || sometimes || The user agent string of the client that caused the event
|-
| <code>CLIENT_ID</code> || stable || sometimes || The ID of the client that caused the event (integer)
|-
| <code>CLIENT_CONNECTION_TIME</code> || experimental || sometimes ||
|-
| <code>CLIENT_ADMIN_COMMAND</code> || experimental || sometimes || ID of the admin command the client accesses as causing the event
|-
| <code>MOUNT_NAME</code> || stable || sometimes || The name of the mount as per config
|-
| <code>MOUNT_DESCRIPTION</code> || stable || sometimes || The description of the mount as per config
|-
| <code>MOUNT_URL</code> || stable || sometimes || The URL (website) of the mount as per config
|-
| <code>MOUNT_GENRE</code> || stable || sometimes || The genre of the mount as per config
|-
| <code>DUMPFILE_FILENAME</code> || stable || sometimes || The filename used by Icecast to operate on a dump file (relative to Icecast's cwd)
|}

=== <code>log</code> ===
The <code>log</code> backend writes events into the standard <code>error.log</code>. The main use for this is to debug and check configuration.
==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>prefix</code> || no || string || <code>Event</code> || A prefix to be used in the logfile. Can be used to easily grep(1) for the lines.
|-
| <code>level</code> || no || log level || <code>information</code> || The level at which to log the events.
|}

=== <code>url</code> ===
This backend is used to deliver the event to some backend server (normally via HTTP). It is very similar to the auth subsystem's <code>url</code> backend.
==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>username</code> || no || username || ''none'' || Username used to login to the backend.
|-
| <code>password</code> || no || password || ''none'' || Password used to login to the backend.
|-
| <code>url</code> || Yes || URL || ''none'' || URL used to deliver the events to
|-
| <code>action</code> || no || string || ''name of the event'' || Value for the <code>action</code>-parameter sent as part of backend requests. When no value is given the name of the event is used.
|-
| <code>legacy</code> || no || boolean || ''true'' || Whether or not the new style is used for the parameters.
|-
|}

Icecast Server/Events

2023-04-18T12:20:55Z

Phschafft: /* List of events */ Fix: Corrected markup

= Events =
<div class="boilerplate metadata" style="background-color: #fee; margin: 0 1em; padding: 0 10px; border: 1px solid #aaa;">
'''Icecast 2.5.x page'''

This page discusses the topic in context of Icecast 2.5.x. The situation for 2.4.x might be different.
</div>

== Overview ==
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.

== Configuration ==
Event subsystem backends are configured via <code><<nowiki />event /></code>s inside of a <code><<nowiki />event-bindings /></code>. <code><<nowiki />event-bindings /></code> can be used inside:
* <code><<nowiki />icecast /></code> (global headers)
* <code><<nowiki />mount /></code>

<code><<nowiki />event-bindings /></code> has no properties itself.
<code><<nowiki />event /></code> may contain <code><<nowiki />option /></code>s with backend specific options. It will also use the following properties:
{| class="wikitable"
! Property !! Required !! Type !! Default !! Description
|-
| <code>type</code> || yes || Backend name || ''none'' || The name of the backend to use.
|-
| <code>trigger</code> || yes || list of event names || ''none'' || A comma separated list of event names to deliver to this backend. The list may include <code>*</code> as wildcard after the first dash. Also entries can be prefixed using <code>!</code> to negatively match them.
|}

== List of events ==

{| class="wikitable"
! event !! Context !! Description
|-
| <code>icecast-start</code> || Global || Emitted when Icecast has been started up initially.
|-
| <code>icecast-stop</code> || Global || Emitted as part of Icecast's shutdown.
|-
| <code>icecast-active</code> || Global || Emitted when Icecast is active (has sources connected).
|-
| <code>icecast-idle</code> || Global || Emitted when Icecast is in idle (no sources connected).
|-
| <code>source-connect</code> || Source || Emitted when a source enters running state.
|-
| <code>source-disconnect</code> || Source || Emitted when a source is shut down.
|-
| <code>source-flags-changed</code> || Source || Emitted when a source experiences changes of it's flags. This might be for internal and external reasons.
|-''
| <code>source-listener-attach</code> || Source || Emitted when a listener has been attached to a source. '''Note:''' experimental.
|-
| <code>source-listeners-changed</code> || Source || Emitted when the number of listeners changed. '''Note:''' experimental.
|-
| <code>source-listeners-is-zero</code> || Source || Same as <code>source-listeners-changed</code> but only emitted when the listener count is now zero. '''Note:''' experimental.
|-
| <code>format-metadata-changed</code> || Source || Emitted whenever the metadata on the format level changes.
|-
| <code>dumpfile-opened</code> || 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.
|-
| <code>dumpfile-closed</code> || 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 <code>dumpfile-opened</code> whenever possible.
|-
| <code>dumpfile-error</code> || Source || Emitted when a dumpfile cannot be opened for any reason. See also <code>dumpfile-opened</code>.
|}

== Backends ==
=== <code>exec</code> ===
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 <code>url</code> backend is often a better alternative.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>executable</code> || Yes || path || ''none'' || Full path to the executable to be started
|-
| <code>default_arguments</code> || no || enum || <code>default</code> || Style of default arguments to be passed. One of: <code>default</code>, <code>no_defaults</code>, <code>uri</code>, <code>uri_and_trigger</code>, or <code>legacy</code>
|}

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

==== Styles of default arguments ====
{| class="wikitable"
! Style !! Arguments || Notes
|-
| <code>default</code> || - || Currently same as <code>legacy</code>.
|-
| <code>no_defaults</code> || ''none'' || No arguments are passed. Data is still accessible via environment.
|-
| <code>uri</code> || mount point || Only the mount point is passed as argument.
|-
| <code>uri_and_trigger</code> || mount point, trigger || The mount point followed by the name of the event that is delivered is passed.
|-
| <code>legacy</code> || [mount point] || Only the mount point is passed. If the mount point is not set for this event the argument is skipped.
|}

=== <code>log</code> ===
The <code>log</code> backend writes events into the standard <code>error.log</code>. The main use for this is to debug and check configuration.
==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>prefix</code> || no || string || <code>Event</code> || A prefix to be used in the logfile. Can be used to easily grep(1) for the lines.
|-
| <code>level</code> || no || log level || <code>information</code> || The level at which to log the events.
|}

=== <code>url</code> ===
This backend is used to deliver the event to some backend server (normally via HTTP). It is very similar to the auth subsystem's <code>url</code> backend.
==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>username</code> || no || username || ''none'' || Username used to login to the backend.
|-
| <code>password</code> || no || password || ''none'' || Password used to login to the backend.
|-
| <code>url</code> || Yes || URL || ''none'' || URL used to deliver the events to
|-
| <code>action</code> || no || string || ''name of the event'' || Value for the <code>action</code>-parameter sent as part of backend requests. When no value is given the name of the event is used.
|-
| <code>legacy</code> || no || boolean || ''true'' || Whether or not the new style is used for the parameters.
|-
|}

Icecast Server/Events

2023-04-18T12:20:03Z

Phschafft: /* List of events */ Update: Added experimental events

= Events =
<div class="boilerplate metadata" style="background-color: #fee; margin: 0 1em; padding: 0 10px; border: 1px solid #aaa;">
'''Icecast 2.5.x page'''

This page discusses the topic in context of Icecast 2.5.x. The situation for 2.4.x might be different.
</div>

== Overview ==
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.

== Configuration ==
Event subsystem backends are configured via <code><<nowiki />event /></code>s inside of a <code><<nowiki />event-bindings /></code>. <code><<nowiki />event-bindings /></code> can be used inside:
* <code><<nowiki />icecast /></code> (global headers)
* <code><<nowiki />mount /></code>

<code><<nowiki />event-bindings /></code> has no properties itself.
<code><<nowiki />event /></code> may contain <code><<nowiki />option /></code>s with backend specific options. It will also use the following properties:
{| class="wikitable"
! Property !! Required !! Type !! Default !! Description
|-
| <code>type</code> || yes || Backend name || ''none'' || The name of the backend to use.
|-
| <code>trigger</code> || yes || list of event names || ''none'' || A comma separated list of event names to deliver to this backend. The list may include <code>*</code> as wildcard after the first dash. Also entries can be prefixed using <code>!</code> to negatively match them.
|}

== List of events ==

{| class="wikitable"
! event !! Context !! Description
|-
| <code>icecast-start</code> || Global || Emitted when Icecast has been started up initially.
|-
| <code>icecast-stop</code> || Global || Emitted as part of Icecast's shutdown.
|-
| <code>icecast-active</code> || Global || Emitted when Icecast is active (has sources connected).
|-
| <code>icecast-idle</code> || Global || Emitted when Icecast is in idle (no sources connected).
|-
| <code>source-connect</code> || Source || Emitted when a source enters running state.
|-
| <code>source-disconnect</code> || Source || Emitted when a source is shut down.
|-
| <code>source-flags-changed</code> || Source || Emitted when a source experiences changes of it's flags. This might be for internal and external reasons.
|-
| <code>source-listener-attach</code> || Source || Emitted when a listener has been attached to a source. **Note:** experimental.
|-
| <code>source-listeners-changed</code> || Source || Emitted when the number of listeners changed. **Note:** experimental.
|-
| <code>source-listeners-is-zero</code> || Source || Same as <code>source-listeners-changed</code> but only emitted when the listener count is now zero. **Note:** experimental.
|-
| <code>format-metadata-changed</code> || Source || Emitted whenever the metadata on the format level changes.
|-
| <code>dumpfile-opened</code> || 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.
|-
| <code>dumpfile-closed</code> || 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 <code>dumpfile-opened</code> whenever possible.
|-
| <code>dumpfile-error</code> || Source || Emitted when a dumpfile cannot be opened for any reason. See also <code>dumpfile-opened</code>.
|}

== Backends ==
=== <code>exec</code> ===
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 <code>url</code> backend is often a better alternative.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>executable</code> || Yes || path || ''none'' || Full path to the executable to be started
|-
| <code>default_arguments</code> || no || enum || <code>default</code> || Style of default arguments to be passed. One of: <code>default</code>, <code>no_defaults</code>, <code>uri</code>, <code>uri_and_trigger</code>, or <code>legacy</code>
|}

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

==== Styles of default arguments ====
{| class="wikitable"
! Style !! Arguments || Notes
|-
| <code>default</code> || - || Currently same as <code>legacy</code>.
|-
| <code>no_defaults</code> || ''none'' || No arguments are passed. Data is still accessible via environment.
|-
| <code>uri</code> || mount point || Only the mount point is passed as argument.
|-
| <code>uri_and_trigger</code> || mount point, trigger || The mount point followed by the name of the event that is delivered is passed.
|-
| <code>legacy</code> || [mount point] || Only the mount point is passed. If the mount point is not set for this event the argument is skipped.
|}

=== <code>log</code> ===
The <code>log</code> backend writes events into the standard <code>error.log</code>. The main use for this is to debug and check configuration.
==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>prefix</code> || no || string || <code>Event</code> || A prefix to be used in the logfile. Can be used to easily grep(1) for the lines.
|-
| <code>level</code> || no || log level || <code>information</code> || The level at which to log the events.
|}

=== <code>url</code> ===
This backend is used to deliver the event to some backend server (normally via HTTP). It is very similar to the auth subsystem's <code>url</code> backend.
==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>username</code> || no || username || ''none'' || Username used to login to the backend.
|-
| <code>password</code> || no || password || ''none'' || Password used to login to the backend.
|-
| <code>url</code> || Yes || URL || ''none'' || URL used to deliver the events to
|-
| <code>action</code> || no || string || ''name of the event'' || Value for the <code>action</code>-parameter sent as part of backend requests. When no value is given the name of the event is used.
|-
| <code>legacy</code> || no || boolean || ''true'' || Whether or not the new style is used for the parameters.
|-
|}

Icecast Server/Events

2023-04-18T10:17:50Z

Phschafft: /* exec */ Feature: Added infos on the exec event backend

Icecast Server/Events

2023-04-18T10:01:32Z

Phschafft: /* url */ Feature: Added infos on the url backend

Icecast Server/Events

2023-04-18T09:55:09Z

Phschafft: /* log */ Feature: Description of the log backend

Icecast Server/Events

2023-04-18T09:34:56Z

Phschafft: Update: Added basic list of backends

Icecast Server/Events

2023-04-18T09:31:59Z

Phschafft: /* Configuration */ Update: Added note on wildcards and negative matches

Icecast Server/Events

2023-04-18T09:17:23Z

Phschafft: /* Configuration */ Update: Added options

Icecast Server/Events

2023-04-18T09:11:34Z

Phschafft: Feature: Added stub on event related tags.

Icecast Server/Events

2023-04-18T08:58:09Z

Phschafft: /* Overview */ Added info on order vs. causality

Icecast Server/Events

2023-04-18T08:56:06Z

Phschafft: Update: Added basic list of events

Icecast Server/Events

2023-04-18T08:41:11Z

Phschafft: Initial stub

User:Phschafft

2023-04-18T08:37:48Z

Phschafft: Little updates

=== Name & Species ===
phschafft (even if the wiki uses 'Phschafft'), a lion, speaking natively German and some English.

=== Xiph Projects ===
* [[Icecast]]
* [[Vorbis-tools]]

=== Contact ===
I'm reached best via IRC (''phschafft'' @ ''IRC @ PH2'', and ''OFTC'') or by E-Mail. For contact details see my homepage.

=== Websites ===
* [https://lion.leolix.org/ Personal Homepage]
* [https://www.loewenfelsen.net/ Company Homepage]

Icecast Server/2.5 Authentication

2023-03-11T16:16:41Z

Phschafft: /* Overview */ Update: Linked docu on headers

= Icecast 2.5.x Authentication =
== Overview ==
Icecast 2.5.x features a new authentication system. This system comes with many improvements and more flexibility. All versions of the Icecast 2.5.x series can read both 2.4.x and 2.5.x style configuration. This includes mixed configuration.

While Icecast 2.4.x used a set of global users and one per-mount authentication backend Icecast 2.5.x features a authentication process that allows a request to pass a number of backends before being matched. This improvements allows more complex setups. For example It is now possible to define common backends and exceptions for specific users on a per-mount point basis. Each such a step where a client is checked using a backend is called a ''role''.

For reach client the ''roles'' for each of those elements are tried in order:
# Per listen socket ''roles'' (effective listen sockets)
# Per type normal mount point ''roles''
# Per type default mount point ''roles''
# Global ''roles''
# Client is rejected.
Note: More steps may be added in later versions.

Each ''role'' may have any combination of the [[#Common properties|common properties]] set. In addition it may contain different types of sub-tags:
{| class="wikitable"
! Sub tag !! Description
|-
| <code><<nowiki />option /></code> || Options passed to the used [[#Backends|backend]].
|-
| <code><<nowiki />http-headers /></code> || [[Icecast Server/Custom HTTP Headers|Standard HTTP headers block]]. Is used if the ''role'' matches.
|-
| <code><<nowiki />acl /></code> || Experimental. Do not use.
|-
| <code><<nowiki />on-failed-action /></code> || Experimental. Do not use. See [[#Client altering|altering]].
|-
| <code><<nowiki />on-failed-argument /></code> || Experimental. Do not use. See [[#Client altering|altering]].
|-
| <code><<nowiki />on-deny-action /></code> || Experimental. Do not use. See [[#Client altering|altering]].
|-
| <code><<nowiki />on-deny-argument /></code> || Experimental. Do not use. See [[#Client altering|altering]].
|}

== Common properties ==
All roles support the following common properties. They are passed as XML properties on the role's tag.
{| class="wikitable"
! Property !! Description
|-
| <code>type</code> || The name of one of the backends.
|-
| <code>name</code> || The name of this role. This is used e.g. in the log files.
|-
| <code>management-url</code> || A fully qualified URL to a place an admin can manage this specific backend. This is most useful for backends that interact with a backend server such as the <code>url</code> backend.
|-
| <code>method</code> || Obsolete. Use ''match-method''.
|-
| <code>match-method</code> || See [[#Matching|matching]].
|-
| <code>nomatch-method</code> || See [[#Matching|matching]].
|-
| <code>match-web</code> || May be set to <code>*</code> to match all ''web/'' domain clients (default). See [[#Matching|matching]].
|-
| <code>nomatch-web</code> || May be set to <code>*</code> to not match all ''web/'' domain clients. See [[#Matching|matching]].
|-
| <code>match-admin</code> || See [[#Matching|matching]].
|-
| <code>nomatch-admin</code> || See [[#Matching|matching]].
|-
| <code>match-origin</code> || See [[#Matching|matching]].
|-
| <code>nomatch-origin</code> || See [[#Matching|matching]].
|-
| <code>may-alter</code> || List of ''actions'' the backend is allowed to use. Or <code>*</code> to allow all. See [[#Client altering|altering]].
|-
| <code>may-not-alter</code> || List of ''actions'' the backend is denied to use. Or <code>*</code> to deny all. See [[#Client altering|altering]].
|-
| <code>allow-method</code> || List of allowed HTTP methods commands. Can be set to <code>*</code> to set the policy to allow.
|-
| <code>deny-method</code> || List of denied HTTP methods commands. Can be set to <code>*</code> to set the policy to deny.
|-
| <code>allow-admin</code> || List of allowed admin commands. Can be set to <code>*</code> to set the policy to allow.
|-
| <code>deny-admin</code> || List of denied admin commands. Can be set to <code>*</code> to set the policy to deny.
|-
| <code>allow-web</code> || When set to <code>*</code> allows access to the ''web/'' domain. Use <code>deny-web="*"</code> to forbid.
|-
| <code>deny-web</code> || When set to <code>*</code> denies access to the ''web/'' domain. Use <code>allow-web="*"</code> to allow.
|-
| <code>allow-all</code> || Same as setting all other <code>allow-</code>* keys to <code>*</code>.
|-
| <code>deny-all</code> || Same as setting all other <code>deny-</code>* keys to <code>*</code>.
|-
| <code>connections-per-user</code> || Maximum number of connections per user or <code>*</code> for unlimited.
|-
| <code>connection-duration</code> || Maximum time a connection is allowed to continue in seconds or <code>*</code> for unlimited. This might not be supported for connections other than listeners.
|}

== Matching ==
Matching is performed before the backend is asked to check a specific client. While matching a client is checked to have certain features (e.g. to use a specific HTTP method). If it does, the backend is consulted. If not a ''no-match'' is returned and the next role is tried.

== Client altering ==
Client altering is a way of altering the request or client state of a client. This is most commonly used to redirect the client to another resource. Each ''action'' may take an ''argument''.

The following actions are defined:
{| class="wikitable"
! Action !! Argument type !! Description
|-
| <code>noop</code> || none || Do not alter the client at all. This is the default.
|-
| <code>rewrite</code> || a valid URL || Reroute the client to a different mount point. This may skip additional authentication or lead to unexpected results. It is recommended to use <code>redirect</code> when possible.
|-
| <code>redirect</code> || a valid URL || Generic redirect. Redirects the client by sending a (HTTP) redirect. On success the client will come back on the corresponding new mount point. This can also be used to redirect a client to a different server.
|-
| <code>redirect_see_other</code> || a valid URL || Redirects the client with a "See other" status. Otherwise same as <code>redirect</code>.
|-
| <code>redirect_temporary</code> || a valid URL || Redirects the client with a temporary redirect status. Otherwise same as <code>redirect</code>.
|-
| <code>redirect_permanent</code> || a valid URL || Redirects the client with a permanent redirect status. In addition to redirecting the client for this request it asks the client to follow the same redirect again for any future request. Otherwise same as <code>redirect</code>.
|-
| <code>send_error</code> || a valid and known UUID || Sends the client one of the stock error messages.
|}

== Backends ==
The following backends are defined:
{| class="wikitable"
! Backend !! Description
|-
| <code>anonymous</code> || This backend matches all clients. Might be renamed in future versions.
|-
| <code>static</code> || This backend matches one username and checks against a password.
|-
| <code>legacy-password</code> || Special backend used for ICY sources.
|-
| <code>url</code> || Forwards the request to a backend server (normally via HTTP or HTTPS).
|-
| <code>htpasswd</code> || Uses a file based database of users and passwords.
|-
| <code>enforce-auth</code> || Rejects any clients that does not provide credentials. Returns no-match for any client that does.
|}
Note: More backends may be added in later versions.

=== Backend <code>anonymous</code> ===
This backend matches all client requests. It is used to implement catch all rules. This is most prominently used at the end of an <code><<nowiki />authentication /></code> block to stop processing and applying defaults. [[#Matching|Matching]] still applies.

==== Options ====
This backend takes no options.

=== Backend <code>static</code> ===
This backend is used to match a client by username and check for a static provided password. This is the 2.5.x variant of defining e.g. global admin accounts and similar.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>username</code> || Yes || username || ''none'' || Username of the user.
|-
| <code>password</code> || Yes || encoded password || ''none'' || Password of the user. The encoding depends on the <code>hashed</code> option.
|-
| <code>hashed</code> || no || boolean || no || Whether or not the password is hashed. If not hashed it is given in plain. If hashed it uses the same format as the <code>htpasswd</code> uses in it's database.
|-
| <code>action</code> || no || alter action || <code>noop</code> || Alter ''action'' used on positive match. See [[#Client altering|altering]].
|-
| <code>argument</code> || no || alter argument || ''none'' || Alter ''argument'' used on positive match. See [[#Client altering|altering]].
|}

=== Backend <code>legacy-password</code> ===
Do not use. This backend is used internally as part of the ICY emulation. ICY emulation by itself is deprecated.

==== Options ====
Takes same options as <code>static</code> but no <code>username</code>.

=== Backend <code>url</code> ===
The URL backend is used to query a backend server (normally via HTTP or HTTPS) about the status of the used credentials.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>username</code> || no || username || ''none'' || Username used to login to the backend.
|-
| <code>password</code> || no || password || ''none'' || Password used to login to the backend.
|-
| <code>headers</code> || no || list of tokens || ''none'' || List of headers to be added to the backend request.
|-
| <code>header_prefix</code> || no || string || empty string || Prefix used for extra headers when send to the backend. Should not be empty when <code>headers</code> is set.
|-
| <code>client_add</code> || no || URL || ''none'' || URL used to query when a client connects.
|-
| <code>client_remove</code> || no || URL || ''none'' || URL used to query when a client disconnects.
|-
| <code>action_add</code> || no || string || <code>listener_add</code> || Value for the <code>action</code>-parameter sent as part of backend requests when clients connect.
|-
| <code>action_remove</code> || no || string || <code>listener_remove</code> || Value for the <code>action</code>-parameter sent as part of backend requests when clients disconnect.
|-
| <code>auth_header</code> || no || string || <code>icecast-auth-user: 1\r\n</code> || Legacy. Use <code>header_auth</code> instead.
|-
| <code>timelimit_header</code> || no || string || <code>icecast-auth-timelimit:</code> || Legacy. Use <code>header_timelimit</code> instead.
|-
| <code>header_auth</code> || no || token || <code>x-icecast-auth-result</code> || Header used to transport the backends result for the given credentials. Might be one of <code>ok</code>, <code>failed</code>, or <code>no match</code>.
|-
| <code>header_timelimit</code> || no || token || <code>x-icecast-auth-timelimit</code> || Header used to transport how long a client may stay connected. In seconds. If the header is absent the client is allowed to stay connected indefinitely.
|-
| <code>header_message</code> || no || token || <code>x-icecast-auth-message</code> || Header used to transport a message that is logged when login failed.
|-
| <code>header_alter_action</code> || no || token || <code>x-icecast-auth-alter-action</code> || Alter ''action'' used. When no such header is returned no client altering will be performed. See [[#Client altering|altering]].
|-
| <code>header_alter_argument</code> || no || token || <code>x-icecast-auth-alter-argument</code> || Alter ''argument'' used. See [[#Client altering|altering]].
|}
Note: If <code>client_add</code> nor <code>client_remove</code> is given this backend is useless.

=== Backend <code>htpasswd</code> ===
The htpasswd backend compares the user and password against a flat file database. This is syntactically compatible with most ".htpasswd" implementations. However supported algorithms might differ. Therefore management of those files is best done via Icecast admin interface and/or API.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>filename</code> || Yes || filename || ''none'' || Filename to the database to use. The database contains sensitive data and access to it should be restricted. Write access for Icecast is only required if the database should be updated by Icecast itself (e.g. via the admin interface).
|}

=== Backend <code>enforce-auth</code> ===
The authentication enforcement backend will reject any client that does not pass credentials. The only use of this is to be placed in front of a mandatory <code>url</code> backend. This allows the <code>url</code> backend to skip negotiation requests and therefor reduce the load on the backend.

==== Options ====
This backend takes no options.

Icecast Server/Custom HTTP Headers

2023-03-11T16:15:27Z

Phschafft: Feature: Documented headers

= Custom HTTP Headers =
<div class="boilerplate metadata" style="background-color: #fee; margin: 0 1em; padding: 0 10px; border: 1px solid #aaa;">
'''Icecast 2.5.x page'''

This page discusses the topic in context of Icecast 2.5.x. The situation for 2.4.x might be different.
</div>

== Overview ==
Icecast allows to set custom HTTP headers. This is done via a <code><<nowiki />http-headers /></code> section. Each such section contains zero or more <code><<nowiki />header /></code> tags. Such sections are permitted within the following tags:
* <code><<nowiki />icecast /></code> (global headers)
* <code><<nowiki />listen-socket /></code>
* <code><<nowiki />mount /></code>
* <code><<nowiki />role /></code>
* <code><<nowiki />acl /></code> (Experimental! Do not use!)

== Properties ==
Each <code><<nowiki />header /></code> may have the following XML properties:
{| class="wikitable"
! Property !! Required !! Type !! Default !! Description
|-
| <code>type</code> || no || enum || <code>static</code> || The type of the header. <code>static</code>, or <code>cors</code>.
|-
| <code>name</code> || Yes || token || ''none'' || The name of the header to add. Note that this field is case insensitive. The case of the sent header my be different from what is configured here.
|-
| <code>value</code> || depends on <code>type</code> || depends on <code>type</code> || ''none'' || The value of the header to add. the meaning depends on it's <code>type</code>.
|-
| <code>status</code> || no || HTTP status code || ''any'' || Limit this header to the responses that return the given status code.
|}

== Types ==
There are different types of headers. The type generally controls how the header is generated.

=== Type <code>static</code> ===
This is used to generate a static header. The <code>value</code> is sent as-is to the client.

=== Type <code>cors</code> ===
The CORS type is used to generate a CORS (cross-origin resource sharing) header. The <code>name</code> is the name of the header. If a <code>value</code> is given, that value overrides the auto generated value (if any).

{| class="wikitable"
! Header !! Value required !! Type !! Default !! Description
|-
|| <code>Access-Control-Allow-Origin</code> || no || origin || The request origin on success, <code>null</code> otherwise || Sets the allowed origin. Should be <code>null</code>, or <code>*</code> for manual configuration or left unset.
|-
|| <code>Access-Control-Allow-Credentials</code> || Yes¹ || boolean || ''none''¹ || Whether or not clients are allowed to send credentials to the mount point.
|-
|| <code>Access-Control-Expose-Headers</code> || no || token list || <code>content-range, icy-br, icy-description, icy-genre, icy-name, icy-pub, icy-url</code>¹ || List of extra headers a client may have access to.
|-
|| <code>Access-Control-Max-Age</code> || no || time interval || <code>300</code> (5 minutes) || Time in seconds on how long CORS related information may be cached.
|-
|| <code>Access-Control-Allow-Methods</code> || no || list of HTTP methods || Same as <code>Allow</code> list on success, none otherwise || The list of allowed HTTP methods. If no <code>value</code> is given this equals to all allowed methods for the given mount point.
|-
|| <code>Access-Control-Allow-Headers</code> || no || token list || <code>range, if-range</code>¹ ||The extra headers a client my send during actual requests.
|}
¹ The default is subject to updates in order to represent the current state of development.

Icecast Server/Custom HTTP Headers

2023-03-11T15:45:17Z

Phschafft: Initial stub

Icecast Server/2.5 Authentication

2023-03-11T15:34:31Z

Phschafft: /* Options */ Update: Completed list of options.

= Icecast 2.5.x Authentication =
== Overview ==
Icecast 2.5.x features a new authentication system. This system comes with many improvements and more flexibility. All versions of the Icecast 2.5.x series can read both 2.4.x and 2.5.x style configuration. This includes mixed configuration.

While Icecast 2.4.x used a set of global users and one per-mount authentication backend Icecast 2.5.x features a authentication process that allows a request to pass a number of backends before being matched. This improvements allows more complex setups. For example It is now possible to define common backends and exceptions for specific users on a per-mount point basis. Each such a step where a client is checked using a backend is called a ''role''.

For reach client the ''roles'' for each of those elements are tried in order:
# Per listen socket ''roles'' (effective listen sockets)
# Per type normal mount point ''roles''
# Per type default mount point ''roles''
# Global ''roles''
# Client is rejected.
Note: More steps may be added in later versions.

Each ''role'' may have any combination of the [[#Common properties|common properties]] set. In addition it may contain different types of sub-tags:
{| class="wikitable"
! Sub tag !! Description
|-
| <code><<nowiki />option /></code> || Options passed to the used [[#Backends|backend]].
|-
| <code><<nowiki />http-headers /></code> || Standard HTTP headers block. Is used if the ''role'' matches.
|-
| <code><<nowiki />acl /></code> || Experimental. Do not use.
|-
| <code><<nowiki />on-failed-action /></code> || Experimental. Do not use. See [[#Client altering|altering]].
|-
| <code><<nowiki />on-failed-argument /></code> || Experimental. Do not use. See [[#Client altering|altering]].
|-
| <code><<nowiki />on-deny-action /></code> || Experimental. Do not use. See [[#Client altering|altering]].
|-
| <code><<nowiki />on-deny-argument /></code> || Experimental. Do not use. See [[#Client altering|altering]].
|}

== Common properties ==
All roles support the following common properties. They are passed as XML properties on the role's tag.
{| class="wikitable"
! Property !! Description
|-
| <code>type</code> || The name of one of the backends.
|-
| <code>name</code> || The name of this role. This is used e.g. in the log files.
|-
| <code>management-url</code> || A fully qualified URL to a place an admin can manage this specific backend. This is most useful for backends that interact with a backend server such as the <code>url</code> backend.
|-
| <code>method</code> || Obsolete. Use ''match-method''.
|-
| <code>match-method</code> || See [[#Matching|matching]].
|-
| <code>nomatch-method</code> || See [[#Matching|matching]].
|-
| <code>match-web</code> || May be set to <code>*</code> to match all ''web/'' domain clients (default). See [[#Matching|matching]].
|-
| <code>nomatch-web</code> || May be set to <code>*</code> to not match all ''web/'' domain clients. See [[#Matching|matching]].
|-
| <code>match-admin</code> || See [[#Matching|matching]].
|-
| <code>nomatch-admin</code> || See [[#Matching|matching]].
|-
| <code>match-origin</code> || See [[#Matching|matching]].
|-
| <code>nomatch-origin</code> || See [[#Matching|matching]].
|-
| <code>may-alter</code> || List of ''actions'' the backend is allowed to use. Or <code>*</code> to allow all. See [[#Client altering|altering]].
|-
| <code>may-not-alter</code> || List of ''actions'' the backend is denied to use. Or <code>*</code> to deny all. See [[#Client altering|altering]].
|-
| <code>allow-method</code> || List of allowed HTTP methods commands. Can be set to <code>*</code> to set the policy to allow.
|-
| <code>deny-method</code> || List of denied HTTP methods commands. Can be set to <code>*</code> to set the policy to deny.
|-
| <code>allow-admin</code> || List of allowed admin commands. Can be set to <code>*</code> to set the policy to allow.
|-
| <code>deny-admin</code> || List of denied admin commands. Can be set to <code>*</code> to set the policy to deny.
|-
| <code>allow-web</code> || When set to <code>*</code> allows access to the ''web/'' domain. Use <code>deny-web="*"</code> to forbid.
|-
| <code>deny-web</code> || When set to <code>*</code> denies access to the ''web/'' domain. Use <code>allow-web="*"</code> to allow.
|-
| <code>allow-all</code> || Same as setting all other <code>allow-</code>* keys to <code>*</code>.
|-
| <code>deny-all</code> || Same as setting all other <code>deny-</code>* keys to <code>*</code>.
|-
| <code>connections-per-user</code> || Maximum number of connections per user or <code>*</code> for unlimited.
|-
| <code>connection-duration</code> || Maximum time a connection is allowed to continue in seconds or <code>*</code> for unlimited. This might not be supported for connections other than listeners.
|}

== Matching ==
Matching is performed before the backend is asked to check a specific client. While matching a client is checked to have certain features (e.g. to use a specific HTTP method). If it does, the backend is consulted. If not a ''no-match'' is returned and the next role is tried.

== Client altering ==
Client altering is a way of altering the request or client state of a client. This is most commonly used to redirect the client to another resource. Each ''action'' may take an ''argument''.

The following actions are defined:
{| class="wikitable"
! Action !! Argument type !! Description
|-
| <code>noop</code> || none || Do not alter the client at all. This is the default.
|-
| <code>rewrite</code> || a valid URL || Reroute the client to a different mount point. This may skip additional authentication or lead to unexpected results. It is recommended to use <code>redirect</code> when possible.
|-
| <code>redirect</code> || a valid URL || Generic redirect. Redirects the client by sending a (HTTP) redirect. On success the client will come back on the corresponding new mount point. This can also be used to redirect a client to a different server.
|-
| <code>redirect_see_other</code> || a valid URL || Redirects the client with a "See other" status. Otherwise same as <code>redirect</code>.
|-
| <code>redirect_temporary</code> || a valid URL || Redirects the client with a temporary redirect status. Otherwise same as <code>redirect</code>.
|-
| <code>redirect_permanent</code> || a valid URL || Redirects the client with a permanent redirect status. In addition to redirecting the client for this request it asks the client to follow the same redirect again for any future request. Otherwise same as <code>redirect</code>.
|-
| <code>send_error</code> || a valid and known UUID || Sends the client one of the stock error messages.
|}

== Backends ==
The following backends are defined:
{| class="wikitable"
! Backend !! Description
|-
| <code>anonymous</code> || This backend matches all clients. Might be renamed in future versions.
|-
| <code>static</code> || This backend matches one username and checks against a password.
|-
| <code>legacy-password</code> || Special backend used for ICY sources.
|-
| <code>url</code> || Forwards the request to a backend server (normally via HTTP or HTTPS).
|-
| <code>htpasswd</code> || Uses a file based database of users and passwords.
|-
| <code>enforce-auth</code> || Rejects any clients that does not provide credentials. Returns no-match for any client that does.
|}
Note: More backends may be added in later versions.

=== Backend <code>anonymous</code> ===
This backend matches all client requests. It is used to implement catch all rules. This is most prominently used at the end of an <code><<nowiki />authentication /></code> block to stop processing and applying defaults. [[#Matching|Matching]] still applies.

==== Options ====
This backend takes no options.

=== Backend <code>static</code> ===
This backend is used to match a client by username and check for a static provided password. This is the 2.5.x variant of defining e.g. global admin accounts and similar.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>username</code> || Yes || username || ''none'' || Username of the user.
|-
| <code>password</code> || Yes || encoded password || ''none'' || Password of the user. The encoding depends on the <code>hashed</code> option.
|-
| <code>hashed</code> || no || boolean || no || Whether or not the password is hashed. If not hashed it is given in plain. If hashed it uses the same format as the <code>htpasswd</code> uses in it's database.
|-
| <code>action</code> || no || alter action || <code>noop</code> || Alter ''action'' used on positive match. See [[#Client altering|altering]].
|-
| <code>argument</code> || no || alter argument || ''none'' || Alter ''argument'' used on positive match. See [[#Client altering|altering]].
|}

=== Backend <code>legacy-password</code> ===
Do not use. This backend is used internally as part of the ICY emulation. ICY emulation by itself is deprecated.

==== Options ====
Takes same options as <code>static</code> but no <code>username</code>.

=== Backend <code>url</code> ===
The URL backend is used to query a backend server (normally via HTTP or HTTPS) about the status of the used credentials.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>username</code> || no || username || ''none'' || Username used to login to the backend.
|-
| <code>password</code> || no || password || ''none'' || Password used to login to the backend.
|-
| <code>headers</code> || no || list of tokens || ''none'' || List of headers to be added to the backend request.
|-
| <code>header_prefix</code> || no || string || empty string || Prefix used for extra headers when send to the backend. Should not be empty when <code>headers</code> is set.
|-
| <code>client_add</code> || no || URL || ''none'' || URL used to query when a client connects.
|-
| <code>client_remove</code> || no || URL || ''none'' || URL used to query when a client disconnects.
|-
| <code>action_add</code> || no || string || <code>listener_add</code> || Value for the <code>action</code>-parameter sent as part of backend requests when clients connect.
|-
| <code>action_remove</code> || no || string || <code>listener_remove</code> || Value for the <code>action</code>-parameter sent as part of backend requests when clients disconnect.
|-
| <code>auth_header</code> || no || string || <code>icecast-auth-user: 1\r\n</code> || Legacy. Use <code>header_auth</code> instead.
|-
| <code>timelimit_header</code> || no || string || <code>icecast-auth-timelimit:</code> || Legacy. Use <code>header_timelimit</code> instead.
|-
| <code>header_auth</code> || no || token || <code>x-icecast-auth-result</code> || Header used to transport the backends result for the given credentials. Might be one of <code>ok</code>, <code>failed</code>, or <code>no match</code>.
|-
| <code>header_timelimit</code> || no || token || <code>x-icecast-auth-timelimit</code> || Header used to transport how long a client may stay connected. In seconds. If the header is absent the client is allowed to stay connected indefinitely.
|-
| <code>header_message</code> || no || token || <code>x-icecast-auth-message</code> || Header used to transport a message that is logged when login failed.
|-
| <code>header_alter_action</code> || no || token || <code>x-icecast-auth-alter-action</code> || Alter ''action'' used. When no such header is returned no client altering will be performed. See [[#Client altering|altering]].
|-
| <code>header_alter_argument</code> || no || token || <code>x-icecast-auth-alter-argument</code> || Alter ''argument'' used. See [[#Client altering|altering]].
|}
Note: If <code>client_add</code> nor <code>client_remove</code> is given this backend is useless.

=== Backend <code>htpasswd</code> ===
The htpasswd backend compares the user and password against a flat file database. This is syntactically compatible with most ".htpasswd" implementations. However supported algorithms might differ. Therefore management of those files is best done via Icecast admin interface and/or API.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>filename</code> || Yes || filename || ''none'' || Filename to the database to use. The database contains sensitive data and access to it should be restricted. Write access for Icecast is only required if the database should be updated by Icecast itself (e.g. via the admin interface).
|}

=== Backend <code>enforce-auth</code> ===
The authentication enforcement backend will reject any client that does not pass credentials. The only use of this is to be placed in front of a mandatory <code>url</code> backend. This allows the <code>url</code> backend to skip negotiation requests and therefor reduce the load on the backend.

==== Options ====
This backend takes no options.

Icecast Server/2.5 Authentication

2023-03-11T14:00:51Z

Phschafft: /* Backends */ Feature: Wrote on backend options

= Icecast 2.5.x Authentication =
== Overview ==
Icecast 2.5.x features a new authentication system. This system comes with many improvements and more flexibility. All versions of the Icecast 2.5.x series can read both 2.4.x and 2.5.x style configuration. This includes mixed configuration.

While Icecast 2.4.x used a set of global users and one per-mount authentication backend Icecast 2.5.x features a authentication process that allows a request to pass a number of backends before being matched. This improvements allows more complex setups. For example It is now possible to define common backends and exceptions for specific users on a per-mount point basis. Each such a step where a client is checked using a backend is called a ''role''.

For reach client the ''roles'' for each of those elements are tried in order:
# Per listen socket ''roles'' (effective listen sockets)
# Per type normal mount point ''roles''
# Per type default mount point ''roles''
# Global ''roles''
# Client is rejected.
Note: More steps may be added in later versions.

Each ''role'' may have any combination of the [[#Common properties|common properties]] set. In addition it may contain different types of sub-tags:
{| class="wikitable"
! Sub tag !! Description
|-
| <code><<nowiki />option /></code> || Options passed to the used [[#Backends|backend]].
|-
| <code><<nowiki />http-headers /></code> || Standard HTTP headers block. Is used if the ''role'' matches.
|-
| <code><<nowiki />acl /></code> || Experimental. Do not use.
|-
| <code><<nowiki />on-failed-action /></code> || Experimental. Do not use. See [[#Client altering|altering]].
|-
| <code><<nowiki />on-failed-argument /></code> || Experimental. Do not use. See [[#Client altering|altering]].
|-
| <code><<nowiki />on-deny-action /></code> || Experimental. Do not use. See [[#Client altering|altering]].
|-
| <code><<nowiki />on-deny-argument /></code> || Experimental. Do not use. See [[#Client altering|altering]].
|}

== Common properties ==
All roles support the following common properties. They are passed as XML properties on the role's tag.
{| class="wikitable"
! Property !! Description
|-
| <code>type</code> || The name of one of the backends.
|-
| <code>name</code> || The name of this role. This is used e.g. in the log files.
|-
| <code>management-url</code> || A fully qualified URL to a place an admin can manage this specific backend. This is most useful for backends that interact with a backend server such as the <code>url</code> backend.
|-
| <code>method</code> || Obsolete. Use ''match-method''.
|-
| <code>match-method</code> || See [[#Matching|matching]].
|-
| <code>nomatch-method</code> || See [[#Matching|matching]].
|-
| <code>match-web</code> || May be set to <code>*</code> to match all ''web/'' domain clients (default). See [[#Matching|matching]].
|-
| <code>nomatch-web</code> || May be set to <code>*</code> to not match all ''web/'' domain clients. See [[#Matching|matching]].
|-
| <code>match-admin</code> || See [[#Matching|matching]].
|-
| <code>nomatch-admin</code> || See [[#Matching|matching]].
|-
| <code>match-origin</code> || See [[#Matching|matching]].
|-
| <code>nomatch-origin</code> || See [[#Matching|matching]].
|-
| <code>may-alter</code> || List of ''actions'' the backend is allowed to use. Or <code>*</code> to allow all. See [[#Client altering|altering]].
|-
| <code>may-not-alter</code> || List of ''actions'' the backend is denied to use. Or <code>*</code> to deny all. See [[#Client altering|altering]].
|-
| <code>allow-method</code> || List of allowed HTTP methods commands. Can be set to <code>*</code> to set the policy to allow.
|-
| <code>deny-method</code> || List of denied HTTP methods commands. Can be set to <code>*</code> to set the policy to deny.
|-
| <code>allow-admin</code> || List of allowed admin commands. Can be set to <code>*</code> to set the policy to allow.
|-
| <code>deny-admin</code> || List of denied admin commands. Can be set to <code>*</code> to set the policy to deny.
|-
| <code>allow-web</code> || When set to <code>*</code> allows access to the ''web/'' domain. Use <code>deny-web="*"</code> to forbid.
|-
| <code>deny-web</code> || When set to <code>*</code> denies access to the ''web/'' domain. Use <code>allow-web="*"</code> to allow.
|-
| <code>allow-all</code> || Same as setting all other <code>allow-</code>* keys to <code>*</code>.
|-
| <code>deny-all</code> || Same as setting all other <code>deny-</code>* keys to <code>*</code>.
|-
| <code>connections-per-user</code> || Maximum number of connections per user or <code>*</code> for unlimited.
|-
| <code>connection-duration</code> || Maximum time a connection is allowed to continue in seconds or <code>*</code> for unlimited. This might not be supported for connections other than listeners.
|}

== Matching ==
Matching is performed before the backend is asked to check a specific client. While matching a client is checked to have certain features (e.g. to use a specific HTTP method). If it does, the backend is consulted. If not a ''no-match'' is returned and the next role is tried.

== Client altering ==
Client altering is a way of altering the request or client state of a client. This is most commonly used to redirect the client to another resource. Each ''action'' may take an ''argument''.

The following actions are defined:
{| class="wikitable"
! Action !! Argument type !! Description
|-
| <code>noop</code> || none || Do not alter the client at all. This is the default.
|-
| <code>rewrite</code> || a valid URL || Reroute the client to a different mount point. This may skip additional authentication or lead to unexpected results. It is recommended to use <code>redirect</code> when possible.
|-
| <code>redirect</code> || a valid URL || Generic redirect. Redirects the client by sending a (HTTP) redirect. On success the client will come back on the corresponding new mount point. This can also be used to redirect a client to a different server.
|-
| <code>redirect_see_other</code> || a valid URL || Redirects the client with a "See other" status. Otherwise same as <code>redirect</code>.
|-
| <code>redirect_temporary</code> || a valid URL || Redirects the client with a temporary redirect status. Otherwise same as <code>redirect</code>.
|-
| <code>redirect_permanent</code> || a valid URL || Redirects the client with a permanent redirect status. In addition to redirecting the client for this request it asks the client to follow the same redirect again for any future request. Otherwise same as <code>redirect</code>.
|-
| <code>send_error</code> || a valid and known UUID || Sends the client one of the stock error messages.
|}

== Backends ==
The following backends are defined:
{| class="wikitable"
! Backend !! Description
|-
| <code>anonymous</code> || This backend matches all clients. Might be renamed in future versions.
|-
| <code>static</code> || This backend matches one username and checks against a password.
|-
| <code>legacy-password</code> || Special backend used for ICY sources.
|-
| <code>url</code> || Forwards the request to a backend server (normally via HTTP or HTTPS).
|-
| <code>htpasswd</code> || Uses a file based database of users and passwords.
|-
| <code>enforce-auth</code> || Rejects any clients that does not provide credentials. Returns no-match for any client that does.
|}
Note: More backends may be added in later versions.

=== Backend <code>anonymous</code> ===
This backend matches all client requests. It is used to implement catch all rules. This is most prominently used at the end of an <code><<nowiki />authentication /></code> block to stop processing and applying defaults. [[#Matching|Matching]] still applies.

==== Options ====
This backend takes no options.

=== Backend <code>static</code> ===
This backend is used to match a client by username and check for a static provided password. This is the 2.5.x variant of defining e.g. global admin accounts and similar.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>username</code> || Yes || username || ''none'' || Username of the user.
|-
| <code>password</code> || Yes || encoded password || ''none'' || Password of the user. The encoding depends on the <code>hashed</code> option.
|-
| <code>hashed</code> || no || boolean || no || Whether or not the password is hashed. If not hashed it is given in plain. If hashed it uses the same format as the <code>htpasswd</code> uses in it's database.
|-
| <code>action</code> || no || alter action || <code>noop</code> || Alter ''action'' used on positive match. See [[#Client altering|altering]].
|-
| <code>argument</code> || no || alter argument || ''none'' || Alter ''argument'' used on positive match. See [[#Client altering|altering]].
|}

=== Backend <code>legacy-password</code> ===
Do not use. This backend is used internally as part of the ICY emulation. ICY emulation by itself is deprecated.

==== Options ====
Takes same options as <code>static</code> but no <code>username</code>.

=== Backend <code>url</code> ===
The URL backend is used to query a backend server (normally via HTTP or HTTPS) about the status of the used credentials.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>username</code> || no || username || ''none'' || Username used to login to the backend.
|-
| <code>password</code> || no || password || ''none'' || Password used to login to the backend.
|-
| <code>headers</code> || no || list of tokens || ''none'' || List of headers to be added to the backend request.
|-
| <code>header_prefix</code> || no || string || empty string || Prefix used for extra headers when send to the backend. Should not be empty when <code>headers</code> is set.
|-
| <code>client_add</code> || no || URL || ''none'' || URL used to query when a client connects.
|-
| <code>client_remove</code> || no || URL || ''none'' || URL used to query when a client disconnects.
|-
| <code>action_add</code> || no || string || <code>listener_add</code> || Value for the <code>action</code>-parameter sent as part of backend requests when clients connect.
|-
| <code>action_remove</code> || no || string || <code>listener_remove</code> || Value for the <code>action</code>-parameter sent as part of backend requests when clients disconnect.
|-
| <code>auth_header</code> || no || ? || ? || Legacy. Use <code>header_auth</code> instead.
|-
| <code>timelimit_header</code> || no || ? || ? || Legacy. Use <code>header_timelimit</code> instead.
|-
| <code>header_auth</code> || ? || token || ? || ?
|-
| <code>header_timelimit</code> || ? || token || ? || ?
|-
| <code>header_message</code> || ? || token || ? || ?
|-
| <code>header_alter_action</code> || no || token || <code>x-icecast-auth-alter-action</code> || Alter ''action'' used. When no such header is returned no client altering will be performed. See [[#Client altering|altering]].
|-
| <code>header_alter_argument</code> || no || token || <code>x-icecast-auth-alter-argument</code> || Alter ''argument'' used. See [[#Client altering|altering]].
|}
Note: If <code>client_add</code> nor <code>client_remove</code> is given this backend is useless.

=== Backend <code>htpasswd</code> ===
The htpasswd backend compares the user and password against a flat file database. This is syntactically compatible with most ".htpasswd" implementations. However supported algorithms might differ. Therefore management of those files is best done via Icecast admin interface and/or API.

==== Options ====
{| class="wikitable"
! Option !! Required || Type || Default || Description
|-
| <code>filename</code> || Yes || filename || ''none'' || Filename to the database to use. The database contains sensitive data and access to it should be restricted. Write access for Icecast is only required if the database should be updated by Icecast itself (e.g. via the admin interface).
|}

=== Backend <code>enforce-auth</code> ===
The authentication enforcement backend will reject any client that does not pass credentials. The only use of this is to be placed in front of a mandatory <code>url</code> backend. This allows the <code>url</code> backend to skip negotiation requests and therefor reduce the load on the backend.

==== Options ====
This backend takes no options.

Icecast Server/2.5 Authentication

2023-03-11T13:26:55Z

Phschafft: /* Backends */ Feature: Basic infos on each backend

Icecast Server/2.5 Authentication

2023-03-11T13:16:21Z

Phschafft: Update: Moved backends block to the end of the page

Icecast Server/2.5 Authentication

2023-03-11T13:15:21Z

Phschafft: /* Overview */ Feature: Added infos on what sub tags might be used

Icecast Server/2.5 Authentication

2023-03-11T13:06:58Z

Phschafft: /* Common options */ Update: Renamed to Common properties to avoid confusion with <option />

Icecast Server/2.5 Authentication

2023-03-11T13:03:58Z

Phschafft: /* Common options */ Update: Updated list some more

Icecast Server/2.5 Authentication

2023-03-11T12:53:46Z

Phschafft: Feature: Added stub about matching

Icecast Server/2.5 Authentication

2023-03-11T12:49:32Z

Phschafft: /* Client altering */ Feature: Added list of actions

Icecast Server/2.5 Authentication

2023-03-11T12:40:45Z

Phschafft: Feature: Added stub about client altering.

Icecast Server/2.5 Authentication

2023-03-11T12:36:37Z

Phschafft: /* Common options */ Feature: Finished documenting allow-/deny-* properties

Icecast Server/2.5 Authentication

2023-03-11T12:33:55Z

Phschafft: /* Backends */ Update: Updated formatting

Icecast Server/2.5 Authentication

2023-03-11T12:33:13Z

Phschafft: /* Common options */ Update: Updated table and added some basic infos

Icecast Server/2.5 Authentication

2023-03-11T12:03:35Z

Phschafft: Feature: Added list on common role properties

Icecast Server/2.5 Authentication

2023-03-11T11:46:14Z

Phschafft: Feature: Added list of current auth backends

Icecast Server/2.5 Authentication

2023-03-11T11:38:12Z

Phschafft: Initial stub

Icecast Server/Git workflow

2021-04-12T22:23:37Z

Phschafft: Update: And changed the info URLs as well

The Icecast project recently migrated from Subversion to Git, this page outlines how to get started with it!

== Repositories ==

The repositories are at [https://git.xiph.org git.xiph.org] and are mirrored to [https://github.com/xiph GitHub]. All repository names start with "icecast-" for clarity.
{| class="wikitable"
!Name
!Anonymous access URL
!SSH URL (only project members)
!Comments
|-
|[https://gitlab.xiph.org/xiph/icecast-server Icecast server]
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-server.git</nowiki></code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-server.git</code>
|
|-
|[https://gitlab.xiph.org/xiph/icecast-ices IceS]
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-ices.git</nowiki></code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-ices.git</code>
|
|-
|[https://gitlab.xiph.org/xiph/icecast-libshout libshout]
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-libshout.git</nowiki></code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-libshout.git</code>
|
|-
|[https://gitlab.xiph.org/xiph/icecast-directory Icecast directory]
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-directory.git</nowiki></code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-directory.git</code>
|As seen running on http://dir.xiph.org - soon™
|-
|[https://gitlab.xiph.org/xiph/icecast-common Icecast shared code]
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-common.git</nowiki></code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-common.git</code>
|No need to check out separately, see below.
|-
|[https://gitlab.xiph.org/xiph/icecast-m4 Icecast shared autofoo]
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-m4.git</nowiki></code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-m4.git</code>
|No need to check out separately, see below.
|}

The repositories were migrated with their full history, but for reference the old subversion repository structure remains [https://trac.xiph.org/browser/icecast/ browseable] and all subprojects can be checked out below <nowiki>http://svn.xiph.org/icecast/trunk/</nowiki><projectname>. This might be useful in case of some branches (not all were migrated) and no longer maintained projects that were not migrated to Git.

== Cloning the Repo ==
First you need to clone the Git repository, because we use submodules, these should also be cloned, do to this, run:

<nowiki>git clone --recursive https://gitlab.xiph.org/xiph/icecast-server.git</nowiki>

If your Git version (<code>git --version</code>) is lower than 1.6.5, do:

<nowiki>git clone https://gitlab.xiph.org/xiph/icecast-server.git</nowiki>
cd icecast-server
git submodule update --init

== Initializing the Submodules ==
The steps we did above, for cloning, initialized the Submodules, <i>but</i> if you want to do any changes to them
and push them back to the remote repository, we need to set them to a specific branch, in this case, master.

First of all, checkout the master branch, depending on your git version, your modules may be initialized in a detached HEAD state.

git submodule foreach git checkout master

(If your git version does not support this, <code>cd</code> into each submodule and run <code>git checkout master</code>)

== Pushing changes to a remote Server ==
When you are done with some super cool new feature, or even while working on it, you may want to push your current state to the remote repository, so others can test it and give you
some Feedback!
For this example let's assume you've built an ACL, therefore changed something in httpp.c which is in the common submodule and changed a lot of stuff in parent repository.

First you need to commit the changed you made in the common submodule, so <code>cd</code> into it, and do

git status

This will list you the changes you made, each change you want to have in the commit needs to be added, let's assume (which is the most common case) you want to commit all changes.
You could either do <code>git add .</code> or even shorter:

git commit -a

The <code>-a</code> or <code>--all</code> option will add all changed or deleted files, but not add any untracked files.

Now enter a meaningful commit message, the first line should be a rough summary, followed by two newlines and a more verbose description. Less is not more in this case, that’s what the summary is for.

Ok now it's time to push the changes to the remote server, if this is the first time you do this, you might need to set the origin url, because it defaults to a http(s) one, so that people without ssh access can clone the repository and submodules too, but for cloning you want to use ssh. Let’s set the remote origin like this:

<nowiki>git remote set-url origin ssh://git@gitlab.xiph.org/xiph/icecast-common.git</nowiki>

Now push the changes to the remote location:

git push origin master

This tells git to push your copy of the master branch to the remote location origin (that we’ve just set to the right url).

Ok now that we cared about the submodule, let's <code>cd</code> back into the parent repository, and commit the changes we made there:

git commit -a

Now enter a meaningful commit message. (Yes, I sound like a broken record, but this is important)

Push the stuff to the remote:

git push origin master

(If you are on a different branch than master, you probably want to replace master with the branch you are on, obviously, or just do <code>git push</code>)

<b>NOTE</b>: Even if you hadn't changed anything in the parent repository but just in the submodule repository, you would need to commit the change of the version of the submodule to the parent repository. If you just had updated the httpp.c you still would needed to do <code>git commit -a -m "Update commons to recent version for latest httpp changes"</code>, and push it, to make the parent repository point to the right submodule version.

== Updating the local repository ==
Let's say someone else committed something and pushed it, and you want to update your local copy to the one of the remote. Let's assume you have nothing changed, so you are just a bit behind in history, then it is a simple as:

git pull

and

git submodule update

to make sure submodules are up to date too.

If something changed, then git needs to reconcile the local changes and the remote changes. We prefer to avoid merge commits, unless there is a larger branch developed feature.

This can be either accomplished by always running:

git pull --rebase

Or by setting up git to do this automatically for you. The following passage is taken verbatim from [https://coderwall.com/p/tnoiug/rebase-by-default-when-doing-git-pull Marcin Kulik's blog post on the same topic]

''In git >= 1.7.9:''

git config --global pull.rebase true

''In git < 1.7.9:''

git config --global branch.autosetuprebase always

''The latter has the effect of automatically adding branch.<name>.rebase true for each checked out local branch that is tracking an upstream branch to the repository config file.''

''Note that if you have both options set (not really recommended) then branch.<name>.rebase true that is automatically added for each branch takes precedence over global pull.rebase true.''

[[Category: Icecast]]

Icecast Server/Git workflow

2021-04-12T22:16:27Z

Phschafft: Update: Corrected URLs

The Icecast project recently migrated from Subversion to Git, this page outlines how to get started with it!

== Repositories ==

The repositories are at [https://git.xiph.org git.xiph.org] and are mirrored to [https://github.com/xiph GitHub]. All repository names start with "icecast-" for clarity.
{| class="wikitable"
!Name
!Anonymous access URL
!SSH URL (only project members)
!Comments
|-
|[https://git.xiph.org/?p=icecast-server.git Icecast server]
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-server.git</nowiki></code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-server.git</code>
|
|-
|[https://git.xiph.org/?p=icecast-ices.git IceS]
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-ices.git</nowiki></code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-ices.git</code>
|
|-
|[https://git.xiph.org/?p=icecast-libshout.git libshout]
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-libshout.git</nowiki></code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-libshout.git</code>
|
|-
|[https://git.xiph.org/?p=icecast-directory.git Icecast directory]
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-directory.git</nowiki></code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-directory.git</code>
|As seen running on http://dir.xiph.org - soon™
|-
|[https://git.xiph.org/?p=icecast-common.git Icecast shared code]
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-common.git</nowiki></code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-common.git</code>
|No need to check out separately, see below.
|-
|[https://git.xiph.org/?p=icecast-m4.git Icecast shared autofoo]
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-m4.git</nowiki></code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-m4.git</code>
|No need to check out separately, see below.
|}

The repositories were migrated with their full history, but for reference the old subversion repository structure remains [https://trac.xiph.org/browser/icecast/ browseable] and all subprojects can be checked out below <nowiki>http://svn.xiph.org/icecast/trunk/</nowiki><projectname>. This might be useful in case of some branches (not all were migrated) and no longer maintained projects that were not migrated to Git.

== Cloning the Repo ==
First you need to clone the Git repository, because we use submodules, these should also be cloned, do to this, run:

<nowiki>git clone --recursive https://gitlab.xiph.org/xiph/icecast-server.git</nowiki>

If your Git version (<code>git --version</code>) is lower than 1.6.5, do:

<nowiki>git clone https://gitlab.xiph.org/xiph/icecast-server.git</nowiki>
cd icecast-server
git submodule update --init

== Initializing the Submodules ==
The steps we did above, for cloning, initialized the Submodules, <i>but</i> if you want to do any changes to them
and push them back to the remote repository, we need to set them to a specific branch, in this case, master.

First of all, checkout the master branch, depending on your git version, your modules may be initialized in a detached HEAD state.

git submodule foreach git checkout master

(If your git version does not support this, <code>cd</code> into each submodule and run <code>git checkout master</code>)

== Pushing changes to a remote Server ==
When you are done with some super cool new feature, or even while working on it, you may want to push your current state to the remote repository, so others can test it and give you
some Feedback!
For this example let's assume you've built an ACL, therefore changed something in httpp.c which is in the common submodule and changed a lot of stuff in parent repository.

First you need to commit the changed you made in the common submodule, so <code>cd</code> into it, and do

git status

This will list you the changes you made, each change you want to have in the commit needs to be added, let's assume (which is the most common case) you want to commit all changes.
You could either do <code>git add .</code> or even shorter:

git commit -a

The <code>-a</code> or <code>--all</code> option will add all changed or deleted files, but not add any untracked files.

Now enter a meaningful commit message, the first line should be a rough summary, followed by two newlines and a more verbose description. Less is not more in this case, that’s what the summary is for.

Ok now it's time to push the changes to the remote server, if this is the first time you do this, you might need to set the origin url, because it defaults to a http(s) one, so that people without ssh access can clone the repository and submodules too, but for cloning you want to use ssh. Let’s set the remote origin like this:

<nowiki>git remote set-url origin ssh://git@gitlab.xiph.org/xiph/icecast-common.git</nowiki>

Now push the changes to the remote location:

git push origin master

This tells git to push your copy of the master branch to the remote location origin (that we’ve just set to the right url).

Ok now that we cared about the submodule, let's <code>cd</code> back into the parent repository, and commit the changes we made there:

git commit -a

Now enter a meaningful commit message. (Yes, I sound like a broken record, but this is important)

Push the stuff to the remote:

git push origin master

(If you are on a different branch than master, you probably want to replace master with the branch you are on, obviously, or just do <code>git push</code>)

<b>NOTE</b>: Even if you hadn't changed anything in the parent repository but just in the submodule repository, you would need to commit the change of the version of the submodule to the parent repository. If you just had updated the httpp.c you still would needed to do <code>git commit -a -m "Update commons to recent version for latest httpp changes"</code>, and push it, to make the parent repository point to the right submodule version.

== Updating the local repository ==
Let's say someone else committed something and pushed it, and you want to update your local copy to the one of the remote. Let's assume you have nothing changed, so you are just a bit behind in history, then it is a simple as:

git pull

and

git submodule update

to make sure submodules are up to date too.

If something changed, then git needs to reconcile the local changes and the remote changes. We prefer to avoid merge commits, unless there is a larger branch developed feature.

This can be either accomplished by always running:

git pull --rebase

Or by setting up git to do this automatically for you. The following passage is taken verbatim from [https://coderwall.com/p/tnoiug/rebase-by-default-when-doing-git-pull Marcin Kulik's blog post on the same topic]

''In git >= 1.7.9:''

git config --global pull.rebase true

''In git < 1.7.9:''

git config --global branch.autosetuprebase always

''The latter has the effect of automatically adding branch.<name>.rebase true for each checked out local branch that is tracking an upstream branch to the repository config file.''

''Note that if you have both options set (not really recommended) then branch.<name>.rebase true that is automatically added for each branch takes precedence over global pull.rebase true.''

[[Category: Icecast]]

Summer of Code 2021

2021-03-21T13:22:25Z

Phschafft: /* Solution / Task */ Fix: Corrected formatting

== Introduction ==

This year Xiph.org is focusing on the rav1e AV1 encoder for its GSoC participation. Both video and still images are currently hot topics, especially with the recent support of AVIF within browsers.

Below you'll find the description for the following GSoC project ideas around the rav1e project.

If you want to know more about a particular idea, please get in touch with the people listed under "possible mentors". While no guarantee, that the person will be the actual mentor for the task, they know it and will be happy to answer your questions. Please join #xiph in Freenode IRC for more. If you don't have IRC set up you can easily connect from your [http://webchat.freenode.net/?channels=%23xiph web browser].
----

== Detailed Project Descriptions ==

These ideas were suggested by various members of the developer community as projects that would be beneficial and which we feel we can mentor. Students should feel free to select one of these, develop a variation, or propose their own ideas. Here, ideally.

----

=== Grain synthesis implementation inside of the rav1e encoder ===

Grain synthesis is using the idea of modeling noise temporally and spatially using noise estimation.

==== Problem / Intro ====

Keeping high frequency detail and noise(dithering, camera noise, grain) using traditional encoder techniques is very expensive in terms of bitrate allocation, and some tools implemented to take care of that problem can create additional artifacts that are not pleasing to the general viewer experience, or are detrimental to the fidelity of the image.

==== Solution / Task ====

Implementing grain synthesis that models the noise parameters of a video, and applies the generated noise parameters during the decoding process, saving very high amounts of bitrates and providing a very high subjective visual fidelity and appeal.

Making it faster than other forms of grain synthesis via smarter algorithms and using various forms of threading to speed up its application, such as tile threading and integration with rav1e-by-gop, making it possible to use as part of any encoding workflow. This will make sure adoption of the technique becomes as widespread as possible.

==== Requirements ====

The student should be familiar with Rust and C, and must have a light background in general visual media encoding, such as video and image compression.

Difficulty: Medium.

==== Possible Mentors ====

[[User:Lu_zero]] && XX

----
=== Adaptive quantization ===

Adaptive quantization is the process of an algorithm trying to efficiently allocate bitrate among the various macroblocks found in a frame by varying the quantizer across each of them according to different visual targets.

==== Problem / Intro ====

Often times, an encoder does not know about the best way to allocate the bitrate budget across a frame, and may overspend a considerable amount of bitrate to regions that might not benefit from a low quantizer(low amounts of distortion, so less compression) while not giving enough bitrate to zones that might actually need it. This can even cause issues temporally, as bitrate allocation within a group of frames(GOPs) may be skewed towards more complex and high motion frames, while leaving other frames with barely any bitrate to work with, creating visual artifacts such as blocking and banding.

==== Solution / Task ====

Implementing 1-3 forms on adaptive quantization either based on variance, complexity and/or variance variance with a bias in low contrast frames in rav1e. This will make bitrate allocation more efficient, and avoid bitrate overspending in areas which either need the lower quantizer to avoid the presence of lower quality frames that might detract from the viewer experience, and make objective/subjective quality targets easier to achieved. The combination of powerful adaptive quantization and grain synthesis would allow for a higher subjective quality viewing experience at lower bitrates while potentially lowering computational complexity by a good margin.

Making a smart adaptive AQ mode in which the encoder chooses which adaptive quantization algorithm to use depending on the scene featured in a GOP. Potentially difficult.

==== Requirements ====

The student should be familiar with Rust and C, and having a background in general visual media encoding, such as video and image compression is recommended.

Difficulty: Medium to high depending on which targets the student chooses to follow.

==== Possible Mentors ====

[[User:Lu_zero]] && XX

----
=== Integrate rav1e-by-gop into rav1e encoder ===

rav1e-by-gop is an extended command line encoder that provides additional encoding strategies such as by-gop parallel encoding across multiple machines.

==== Problem / Intro ====

rav1e-by-gop is currently a command line program, some users might want to enjoy on the extended features from other programs even if they do not always belong to an encoder.

==== Solution / Task ====

make rav1e-by-gop expose the same API of the normal rav1e to make easy to use the multiple machine encoding features from other programs.

==== Requirements ====

The student should be familiar with Rust or C programming.<br>
Video knowledge is not strictly necessary, however a basic understanding of the concepts is vastly beneficial.

==== Possible Mentors ====

[[User:Tdaede]] [[User:Lu_zero]]

----
=== Visual metric targeting in rav1e-by-gop ===

Objective metrics are used to evaluate an encoder's performance in a diverse set of scenarios. Different metrics such as PSNR, SSIM, DSSIM, VMAF and some closed no-reference metrics are used in the field to record encoder performance changes across versions trying to correlate closely with human perception.

==== Problem / Intro ====

Classical methods of rate control such as ABR(Average BitRate), fixed quantizers and even CRF(Constant Rate Factor) have the issue of not targeting a certain quality level. This can result in starved encodes where the bitrate budget has to be kept low to stay watchable by the viewer without interruption, leading to scenes that have exceptionally good visual targets by overspending bitrate, and scenes that have very poor visual appeal by having too little bitrate, detracting from the viewer experience entirely. More advanced forms of rate control like CRF help somewhat, but they still have the issue of having to overshoot so the lower quality scenes do not suffer, and do not adapt to the different type of content encoded, resulting in variable quality encodes.

==== Solution / Task ====

Implementing visual metric targeting based on VMAF(mainly used for video) and butteraugli(mainly used for images) as part of rav1e-by-gop as a secondary rate control option.

The application of visual metric targeting in rav1e-by-gop would take advantage of its adaptive keyframe placement and smart scene detection to its fullest.
This would allow for the best rate control possible, as short scenes in the length of 1-15s are where visual metrics such as VMAF shine the most. The idea is to encode first with a very fast speed preset in the encoder to gauge the quality at a prefixed quantizer. If the visual metric target set is not achieved, the encoder tries again once or twice until it gets the right result.
With this method, instead of targeting an average of bitrate, you would target a visual score, getting higher efficiency and higher subjective quality. This would also be advantageous in terms of encoding time spent, as encoder complexity could be dialed back while keeping overall efficiency the same or higher, with efficiency being a function of both encoder efficiency and rate control.

Implementing butteraugli quality targeting as an option using rav1e for AVIF images. Since visual quality requirements are considerably higher for intra only(image only) media, keeping high visual fidelity is even more important than video compression. Quality targeting iterations would also be quite useful here.

==== Requirements ====

The student should be familiar with Rust and C. General interest in image and video coding is recommended

Difficulty: Medium.

==== Possible Mentors ====

[[User:Lu_zero]] && XX
----
=== Improved cluster support for Icecast ===
Icecast servers deliver streams to million of users simultaneous worldwide. Each instance can handle many thousand clients at the same time. However redundancy, scalability, hardware requirement, and most importantly network connectivity often requires to use several instances in a professional deployment.
==== Problem / Intro ====
Icecast is designed as a standalone application. While basic support exists (such as master-slave mode) support for clusters can be improved. At this point a cluster level mangement instance seems to be missing.
==== Solution / Task ====
A solution for cluster management should be developed. A cluster controller should be implemented as well as support within Icecast. The focus is on Icecast itself at this point. However the controler should at least demonstrate all features implemented in Icecast.
Possible features:
* Automatic master-slave, and relay configuration.
* Load distribution.
* Statistic data collection.
* Log collection.
* Node monitoring.
* Signalling of cluster state to external components (e.g. for automatic cluster scaling)
==== Requirements ====
The student should be familiar with C. A basic understanding of HTTP, as well as other web technologies is helpful. Knowledge of visualisation technologies is '''not''' required.

Complexity: Medium to high.
==== Possible Mentors ====
[[User:phschafft|phschafft]] (teamed with someone else)
----
=== Development of advanced content navigation in Icecast ===
Icecast currently supports navigation of listeners between different streams. This was developed mostly for fallbacks (providing alternative content if the primary source fails). This support should be improved to provide better interaction with contents.
==== Problem / Intro ====
The current implementation is designed to work very robust for source side events (such as fallbacks). However it fails for two requirements:
* Listener initiated interaction such as adaptive streaming.
* Exact timing.
==== Solution / Task ====
The current concept is capable of being extended to the new requirements. Code should be written to add the new features on the existing (and well proven) infrastructure. The following additional features would be needed:
Detection and matching of features within and between streams. This is required for any kind of synchronisation.
* Executing operations exactly at detached features.
* Adding ways to communicate features and operations between listener and Icecast, source and Icecast, and between multiple
* Icecast instances of the same cluster.

==== Requirements ====
The student should be familiar with C. A basic understanding of HTTP, Ogg, and Matroska/WebM is helpful.

Complexity: Medium to high.
==== Possible Mentors ====
[[User:phschafft|phschafft]] (teamed with someone else)
----
=== Uniform return channel for Icecast ===
Icecast supports broadcasting media to several thousand listeners per instance. In a classic setup this is a one way process from the source (such as a radio or TV studio) to the consumer. However it is sometimes useful to provide a return channel, such as for implementing polls.
==== Problem / Intro ====
Returning information from the listener to the source is part of classic media. The need has become more relevant with the development of more interactive ways of the web. Several technologies have been used to implement this including asking the listeners to call in, send e-mails, or comment on a web page.

Classic ways to implement feedback include a media break and are only loosely bound to the forward channel.
==== Solution / Task ====
A uniform return channel should be implemented that allows several types of data to be send from the listener to the source. This includes three major parts:
* Improved session handling (both for listeners and for sources)
* Implementing a return channel for listeners.
* Implementing a return channel for sources.
==== Requirements ====
The student should be familiar with C and HTTP.

Complexity: Medium.
==== Possible Mentors ====
[[User:phschafft|phschafft]] (teamed with someone else)
----
=== (Live) listener statistics for Icecast ===
Icecast supports writing a basic access.log that includes client information as well as connection time. In addition a playlist log is supported, and live statistic data via the STATS interface.

A standard solution to use this data for detailed listener statistics is missing.
==== Problem / Intro ====
In the current solution there is no off the shelf solution to process the statistic data provided by Icecast. The best available solutions are standard access log analysers. A solution for live statistics is completely missing. Statistics taking content into account is also absent.
==== Solution / Task ====
To improve the situation two major steps must be accomplished:
* The statistic interface of Icecast must be enhanced to provide the required information.
* A solution that analyses this data must be developed. The focus is on this part.
This project allows for a wide range of ideas from the participants to be incorporated. There is not yet and specific technical direction set. Evaluating different options is the first part of the project.
==== Requirements ====
The student should be familiar with C. A basic understanding of log analysis, and monitoring and/or data collecting systems is helpful.

Difficulty: Medium depending on which targets the student chooses to follow.

==== Possible Mentors ====
[[User:phschafft|phschafft]] (teamed with someone else)
----

=== Support WebAssembly SIMD in rav1e ===

rav1e supports the [https://wasi.dev/ WASI] platform and it has its javascript API bindings relying on it.

==== Problem / Intro ====

The WebAssembly SIMD is getting [https://github.com/WebAssembly/simd closer] to be available, we should support it.

==== Solution / Task ====

* Implement the dispatch logic for WASM SIMD as done already for x86_64 and aarch64.
* Implement the Sum of absolute difference (SAD) and Sum of absolute transformed differences (SATD)
* Implement the inverse transforms (idct, iadst, identity, ...)
* Implement the motion compensation.

==== Requirements ====

The student should be familiar with Rust, WASM, wasmtime and related tools. Knowledge of x86 or arm assembly is not needed but will help.

==== Possible Mentors ====

[[User:Lu_zero]]
----

=== Implement butteraugli in av-metrics ===

av-metrics is a collection of video quality metrics, [https://github.com/google/butteraugli butteraugli] is a promising psychovisual similarity metric.

==== Problem / Intro ====

Currently the implementation of butteraugli exists as [https://github.com/google/butteraugli stand-alone] codebase. The code is readable, but it could be faster.

==== Solution / Task ====

* Implement rust bindings to the reference butteraugli.
* Implement butteraugli in pure rust within av-metrics.
* Write integration and unit tests to make sure the implementation does not diverge
* Write criterion benchmarks
* Implement x86_64 or aarch64 optimizations for it, using intrinsics or plain ASM.

==== Requirements ====

The student should be familiar with Rust, C and C++. Knowledge of x86 or arm assembly is welcome.

==== Possible Mentors ====

[[User:Lu_zero]]
----

=== Deploy Opus-in-MP4 in WebAssembly for Safari ===

Implement the missing Opus support for Safari.

==== Problem / Intro ====

Safari supports decoding Opus streams, but only when packed in CAF with no support for Media Source Extension. It would be nice to deploy a middleware in WASM that remuxes non-fragmented MP4 to CAF to support progressive streams, and to determine if enough hooks exist for fragmented MP4s as well. Needless to say, audio and video need to remain in sync throughout the whole process.

==== Solution / Task ====

* Make sure the underlying Opus decoder works in Safari.
* Implement a minimal mp4-to-caf demuxer/muxer in your language of choice.
* Compile this remuxer to Javascript/WebAssembly/WASM.
* Develop a proof of concept streaming for a non-fragmented mp4 file.
* Package the system to a reusable library.
* Investigate if it's possible to port this functionality to fragmented mp4 as well.

==== Requirements ====

The student should be familiar with streaming protocols, encapsulation, WebAssembly. Expect lots of hacking in Javascript.

==== Possible Mentors ====

[[User:Koda]]

----

Summer of Code 2021

2021-03-21T13:20:18Z

Phschafft: Update: Made make name a link to my profile

== Introduction ==

This year Xiph.org is focusing on the rav1e AV1 encoder for its GSoC participation. Both video and still images are currently hot topics, especially with the recent support of AVIF within browsers.

Below you'll find the description for the following GSoC project ideas around the rav1e project.

If you want to know more about a particular idea, please get in touch with the people listed under "possible mentors". While no guarantee, that the person will be the actual mentor for the task, they know it and will be happy to answer your questions. Please join #xiph in Freenode IRC for more. If you don't have IRC set up you can easily connect from your [http://webchat.freenode.net/?channels=%23xiph web browser].
----

== Detailed Project Descriptions ==

These ideas were suggested by various members of the developer community as projects that would be beneficial and which we feel we can mentor. Students should feel free to select one of these, develop a variation, or propose their own ideas. Here, ideally.

----

=== Grain synthesis implementation inside of the rav1e encoder ===

Grain synthesis is using the idea of modeling noise temporally and spatially using noise estimation.

==== Problem / Intro ====

Keeping high frequency detail and noise(dithering, camera noise, grain) using traditional encoder techniques is very expensive in terms of bitrate allocation, and some tools implemented to take care of that problem can create additional artifacts that are not pleasing to the general viewer experience, or are detrimental to the fidelity of the image.

==== Solution / Task ====

Implementing grain synthesis that models the noise parameters of a video, and applies the generated noise parameters during the decoding process, saving very high amounts of bitrates and providing a very high subjective visual fidelity and appeal.

Making it faster than other forms of grain synthesis via smarter algorithms and using various forms of threading to speed up its application, such as tile threading and integration with rav1e-by-gop, making it possible to use as part of any encoding workflow. This will make sure adoption of the technique becomes as widespread as possible.

==== Requirements ====

The student should be familiar with Rust and C, and must have a light background in general visual media encoding, such as video and image compression.

Difficulty: Medium.

==== Possible Mentors ====

[[User:Lu_zero]] && XX

----
=== Adaptive quantization ===

Adaptive quantization is the process of an algorithm trying to efficiently allocate bitrate among the various macroblocks found in a frame by varying the quantizer across each of them according to different visual targets.

==== Problem / Intro ====

Often times, an encoder does not know about the best way to allocate the bitrate budget across a frame, and may overspend a considerable amount of bitrate to regions that might not benefit from a low quantizer(low amounts of distortion, so less compression) while not giving enough bitrate to zones that might actually need it. This can even cause issues temporally, as bitrate allocation within a group of frames(GOPs) may be skewed towards more complex and high motion frames, while leaving other frames with barely any bitrate to work with, creating visual artifacts such as blocking and banding.

==== Solution / Task ====

Implementing 1-3 forms on adaptive quantization either based on variance, complexity and/or variance variance with a bias in low contrast frames in rav1e. This will make bitrate allocation more efficient, and avoid bitrate overspending in areas which either need the lower quantizer to avoid the presence of lower quality frames that might detract from the viewer experience, and make objective/subjective quality targets easier to achieved. The combination of powerful adaptive quantization and grain synthesis would allow for a higher subjective quality viewing experience at lower bitrates while potentially lowering computational complexity by a good margin.

Making a smart adaptive AQ mode in which the encoder chooses which adaptive quantization algorithm to use depending on the scene featured in a GOP. Potentially difficult.

==== Requirements ====

The student should be familiar with Rust and C, and having a background in general visual media encoding, such as video and image compression is recommended.

Difficulty: Medium to high depending on which targets the student chooses to follow.

==== Possible Mentors ====

[[User:Lu_zero]] && XX

----
=== Integrate rav1e-by-gop into rav1e encoder ===

rav1e-by-gop is an extended command line encoder that provides additional encoding strategies such as by-gop parallel encoding across multiple machines.

==== Problem / Intro ====

rav1e-by-gop is currently a command line program, some users might want to enjoy on the extended features from other programs even if they do not always belong to an encoder.

==== Solution / Task ====

make rav1e-by-gop expose the same API of the normal rav1e to make easy to use the multiple machine encoding features from other programs.

==== Requirements ====

The student should be familiar with Rust or C programming.<br>
Video knowledge is not strictly necessary, however a basic understanding of the concepts is vastly beneficial.

==== Possible Mentors ====

[[User:Tdaede]] [[User:Lu_zero]]

----
=== Visual metric targeting in rav1e-by-gop ===

Objective metrics are used to evaluate an encoder's performance in a diverse set of scenarios. Different metrics such as PSNR, SSIM, DSSIM, VMAF and some closed no-reference metrics are used in the field to record encoder performance changes across versions trying to correlate closely with human perception.

==== Problem / Intro ====

Classical methods of rate control such as ABR(Average BitRate), fixed quantizers and even CRF(Constant Rate Factor) have the issue of not targeting a certain quality level. This can result in starved encodes where the bitrate budget has to be kept low to stay watchable by the viewer without interruption, leading to scenes that have exceptionally good visual targets by overspending bitrate, and scenes that have very poor visual appeal by having too little bitrate, detracting from the viewer experience entirely. More advanced forms of rate control like CRF help somewhat, but they still have the issue of having to overshoot so the lower quality scenes do not suffer, and do not adapt to the different type of content encoded, resulting in variable quality encodes.

==== Solution / Task ====

Implementing visual metric targeting based on VMAF(mainly used for video) and butteraugli(mainly used for images) as part of rav1e-by-gop as a secondary rate control option.

The application of visual metric targeting in rav1e-by-gop would take advantage of its adaptive keyframe placement and smart scene detection to its fullest.
This would allow for the best rate control possible, as short scenes in the length of 1-15s are where visual metrics such as VMAF shine the most. The idea is to encode first with a very fast speed preset in the encoder to gauge the quality at a prefixed quantizer. If the visual metric target set is not achieved, the encoder tries again once or twice until it gets the right result.
With this method, instead of targeting an average of bitrate, you would target a visual score, getting higher efficiency and higher subjective quality. This would also be advantageous in terms of encoding time spent, as encoder complexity could be dialed back while keeping overall efficiency the same or higher, with efficiency being a function of both encoder efficiency and rate control.

Implementing butteraugli quality targeting as an option using rav1e for AVIF images. Since visual quality requirements are considerably higher for intra only(image only) media, keeping high visual fidelity is even more important than video compression. Quality targeting iterations would also be quite useful here.

==== Requirements ====

The student should be familiar with Rust and C. General interest in image and video coding is recommended

Difficulty: Medium.

==== Possible Mentors ====

[[User:Lu_zero]] && XX
----
=== Improved cluster support for Icecast ===
Icecast servers deliver streams to million of users simultaneous worldwide. Each instance can handle many thousand clients at the same time. However redundancy, scalability, hardware requirement, and most importantly network connectivity often requires to use several instances in a professional deployment.
==== Problem / Intro ====
Icecast is designed as a standalone application. While basic support exists (such as master-slave mode) support for clusters can be improved. At this point a cluster level mangement instance seems to be missing.
==== Solution / Task ====
A solution for cluster management should be developed. A cluster controller should be implemented as well as support within Icecast. The focus is on Icecast itself at this point. However the controler should at least demonstrate all features implemented in Icecast.
Possible features:
* Automatic master-slave, and relay configuration.
* Load distribution.
* Statistic data collection.
* Log collection.
* Node monitoring.
* Signalling of cluster state to external components (e.g. for automatic cluster scaling)
==== Requirements ====
The student should be familiar with C. A basic understanding of HTTP, as well as other web technologies is helpful. Knowledge of visualisation technologies is '''not''' required.

Complexity: Medium to high.
==== Possible Mentors ====
[[User:phschafft|phschafft]] (teamed with someone else)
----
=== Development of advanced content navigation in Icecast ===
Icecast currently supports navigation of listeners between different streams. This was developed mostly for fallbacks (providing alternative content if the primary source fails). This support should be improved to provide better interaction with contents.
==== Problem / Intro ====
The current implementation is designed to work very robust for source side events (such as fallbacks). However it fails for two requirements:
* Listener initiated interaction such as adaptive streaming.
* Exact timing.
==== Solution / Task ====
The current concept is capable of being extended to the new requirements. Code should be written to add the new features on the existing (and well proven) infrastructure. The following additional features would be needed:
Detection and matching of features within and between streams. This is required for any kind of synchronisation.
* Executing operations exactly at detached features.
* Adding ways to communicate features and operations between listener and Icecast, source and Icecast, and between multiple * * Icecast instances of the same cluster.
==== Requirements ====
The student should be familiar with C. A basic understanding of HTTP, Ogg, and Matroska/WebM is helpful.

Complexity: Medium to high.
==== Possible Mentors ====
[[User:phschafft|phschafft]] (teamed with someone else)
----
=== Uniform return channel for Icecast ===
Icecast supports broadcasting media to several thousand listeners per instance. In a classic setup this is a one way process from the source (such as a radio or TV studio) to the consumer. However it is sometimes useful to provide a return channel, such as for implementing polls.
==== Problem / Intro ====
Returning information from the listener to the source is part of classic media. The need has become more relevant with the development of more interactive ways of the web. Several technologies have been used to implement this including asking the listeners to call in, send e-mails, or comment on a web page.

Classic ways to implement feedback include a media break and are only loosely bound to the forward channel.
==== Solution / Task ====
A uniform return channel should be implemented that allows several types of data to be send from the listener to the source. This includes three major parts:
* Improved session handling (both for listeners and for sources)
* Implementing a return channel for listeners.
* Implementing a return channel for sources.
==== Requirements ====
The student should be familiar with C and HTTP.

Complexity: Medium.
==== Possible Mentors ====
[[User:phschafft|phschafft]] (teamed with someone else)
----
=== (Live) listener statistics for Icecast ===
Icecast supports writing a basic access.log that includes client information as well as connection time. In addition a playlist log is supported, and live statistic data via the STATS interface.

A standard solution to use this data for detailed listener statistics is missing.
==== Problem / Intro ====
In the current solution there is no off the shelf solution to process the statistic data provided by Icecast. The best available solutions are standard access log analysers. A solution for live statistics is completely missing. Statistics taking content into account is also absent.
==== Solution / Task ====
To improve the situation two major steps must be accomplished:
* The statistic interface of Icecast must be enhanced to provide the required information.
* A solution that analyses this data must be developed. The focus is on this part.
This project allows for a wide range of ideas from the participants to be incorporated. There is not yet and specific technical direction set. Evaluating different options is the first part of the project.
==== Requirements ====
The student should be familiar with C. A basic understanding of log analysis, and monitoring and/or data collecting systems is helpful.

Difficulty: Medium depending on which targets the student chooses to follow.

==== Possible Mentors ====
[[User:phschafft|phschafft]] (teamed with someone else)
----

=== Support WebAssembly SIMD in rav1e ===

rav1e supports the [https://wasi.dev/ WASI] platform and it has its javascript API bindings relying on it.

==== Problem / Intro ====

The WebAssembly SIMD is getting [https://github.com/WebAssembly/simd closer] to be available, we should support it.

==== Solution / Task ====

* Implement the dispatch logic for WASM SIMD as done already for x86_64 and aarch64.
* Implement the Sum of absolute difference (SAD) and Sum of absolute transformed differences (SATD)
* Implement the inverse transforms (idct, iadst, identity, ...)
* Implement the motion compensation.

==== Requirements ====

The student should be familiar with Rust, WASM, wasmtime and related tools. Knowledge of x86 or arm assembly is not needed but will help.

==== Possible Mentors ====

[[User:Lu_zero]]
----

=== Implement butteraugli in av-metrics ===

av-metrics is a collection of video quality metrics, [https://github.com/google/butteraugli butteraugli] is a promising psychovisual similarity metric.

==== Problem / Intro ====

Currently the implementation of butteraugli exists as [https://github.com/google/butteraugli stand-alone] codebase. The code is readable, but it could be faster.

==== Solution / Task ====

* Implement rust bindings to the reference butteraugli.
* Implement butteraugli in pure rust within av-metrics.
* Write integration and unit tests to make sure the implementation does not diverge
* Write criterion benchmarks
* Implement x86_64 or aarch64 optimizations for it, using intrinsics or plain ASM.

==== Requirements ====

The student should be familiar with Rust, C and C++. Knowledge of x86 or arm assembly is welcome.

==== Possible Mentors ====

[[User:Lu_zero]]
----

=== Deploy Opus-in-MP4 in WebAssembly for Safari ===

Implement the missing Opus support for Safari.

==== Problem / Intro ====

Safari supports decoding Opus streams, but only when packed in CAF with no support for Media Source Extension. It would be nice to deploy a middleware in WASM that remuxes non-fragmented MP4 to CAF to support progressive streams, and to determine if enough hooks exist for fragmented MP4s as well. Needless to say, audio and video need to remain in sync throughout the whole process.

==== Solution / Task ====

* Make sure the underlying Opus decoder works in Safari.
* Implement a minimal mp4-to-caf demuxer/muxer in your language of choice.
* Compile this remuxer to Javascript/WebAssembly/WASM.
* Develop a proof of concept streaming for a non-fragmented mp4 file.
* Package the system to a reusable library.
* Investigate if it's possible to port this functionality to fragmented mp4 as well.

==== Requirements ====

The student should be familiar with streaming protocols, encapsulation, WebAssembly. Expect lots of hacking in Javascript.

==== Possible Mentors ====

[[User:Koda]]

----