Source / Input / Active

icecast.server

Start an icecast-compatible server

Type:

(?name : string, ?port : int?, ?password : string?,
 ?dedicated_encoder : bool, ?x_forwarded_for_proxy_ips : [string?]?,
 ?x_forwarded_for : ((
                      {
                        headers : [string * string],
                        ip : string?,
                        protocol : string,
                        proxy_ips : [string?],
                        uri : string
                      }) -> string?)?,
 ?format_options : ((string) -> [string * string])?,
 ?ip_hash : ((string) -> string), ?access_log : string?,
 ?playlist_log : string?, ?admin_user : string?, ?admin_password : string?,
 ?config : string?, ?serve : bool,
 ?serve_auth : ((
                 {
                   body : (?timeout : float) -> string,
                   data : (?timeout : float) -> string,
                   headers : [string * string],
                   http_version : string,
                   method : string,
                   path : string,
                   query : [string * string]
                 }) -> bool)?,
 ?serve_json : (([string * 
                  {
                    bytes_sent : int,
                    connections : int,
                    content_type : string,
                    current_metadata : [string * string],
                    listeners : [
                                 {
                                   bytes_sent : int,
                                   connected_at : float,
                                   duration : float,
                                   id : int,
                                   ip : string,
                                   mount : string,
                                   protocol : string,
                                   referer : string?,
                                   uri : string,
                                   user_agent : string?
                                 }],
                    listening_time : float,
                    mime_type : string?,
                    name : string,
                    peak_listeners : int,
                    started : float
                  }]) -> string)?,
 ?serve_html : (([string * 
                  {
                    bytes_sent : int,
                    connections : int,
                    content_type : string,
                    current_metadata : [string * string],
                    listeners : [
                                 {
                                   bytes_sent : int,
                                   connected_at : float,
                                   duration : float,
                                   id : int,
                                   ip : string,
                                   mount : string,
                                   protocol : string,
                                   referer : string?,
                                   uri : string,
                                   user_agent : string?
                                 }],
                    listening_time : float,
                    mime_type : string?,
                    name : string,
                    peak_listeners : int,
                    started : float
                  }]) -> string)?) -> unit

Arguments:

• name (of type string, which defaults to "icecast.server"): Telnet command namespace
• port (of type int?, which defaults to null): Port to listen on. Overrides <port> from the config file, defaults to 8000.
• password (of type string?, which defaults to null): Source password for authentication. Overrides <source-password> from the config file, defaults to "hackme".
• dedicated_encoder (of type bool, which defaults to false): When true, create a separate encoder instance for each listener. This uses more resources but ensures each listener gets a clean encoder state.
• x_forwarded_for_proxy_ips (of type [string?]?, which defaults to null): List of known reverse-proxy IPs. When set, the X-Forwarded-For header is walked right-to-left and the first non-proxy IP is used as the listener IP in stats. Use only when liquidsoap is behind a trusted reverse proxy.
• x_forwarded_for (of type (( { headers : [string * string], ip : string?, protocol : string, proxy_ips : [string?], uri : string }) -> string?)?, which defaults to null): Advanced: custom callback ({ip, headers, proxy_ips, protocol, uri}) -> string to extract the real listener IP. When set, overrides the default X-Forwarded-For logic. proxy_ips in the record is populated from x_forwarded_for_proxy_ips.
• format_options (of type ((string) -> [string * string])?, which defaults to null): Callback (string) -> [(string * string)] that returns muxer options for a given container format name. When null, falls back to settings.icecast.server.default_muxer_options.
• ip_hash (of type (string) -> string, which defaults to fun (ip) -> ...): Function applied to every listener IP, after X-Forwarded-For resolution, before it reaches callbacks, stats or logs. Defaults to icecast.server.ip_hash, a truncated MD5 digest that is the same across restarts. Pass fun (ip) -> ip to keep plain IPs.
• access_log (of type string?, which defaults to null): Path of an icecast-style access log, - for standard error. Overrides <accesslog> from the config file.
• playlist_log (of type string?, which defaults to null): Path of an icecast-style playlist log, - for standard error. Overrides <playlistlog> from the config file.
• admin_user (of type string?, which defaults to null): User name for the admin listener page. Overrides <admin-user> from the config file.
• admin_password (of type string?, which defaults to null): Password for the admin listener page, which is disabled when no password is set. Overrides <admin-password> from the config file.
• config (of type string?, which defaults to null): Optional path to an icecast XML configuration file
• serve (of type bool, which defaults to true): When false, disable the status page at / and JSON stats at /status.json.
• serve_auth (of type (( { body : (?timeout : float) -> string, data : (?timeout : float) -> string, headers : [string * string], http_version : string, method : string, path : string, query : [string * string] }) -> bool)?, which defaults to null): When provided, called with the request and must return true to allow access to the status endpoints.
• serve_json (of type (([string * { bytes_sent : int, connections : int, content_type : string, current_metadata : [string * string], listeners : [ { bytes_sent : int, connected_at : float, duration : float, id : int, ip : string, mount : string, protocol : string, referer : string?, uri : string, user_agent : string? }], listening_time : float, mime_type : string?, name : string, peak_listeners : int, started : float }]) -> string)?, which defaults to null): When provided, called with the stats list and must return a JSON string for the /status.json endpoint.
• serve_html (of type (([string * { bytes_sent : int, connections : int, content_type : string, current_metadata : [string * string], listeners : [ { bytes_sent : int, connected_at : float, duration : float, id : int, ip : string, mount : string, protocol : string, referer : string?, uri : string, user_agent : string? }], listening_time : float, mime_type : string?, name : string, peak_listeners : int, started : float }]) -> string)?, which defaults to null): When provided, called with the stats list and must return an HTML string for the / endpoint.

Methods:

• get_config (of type (string) -> { format : string?, streams : [ { channel_layout? : string, channels? : int, codec : string, field : string, frame_rate? : float?, height? : int, pixel_format? : string, samplerate? : int, type : string, width? : int }]}?)
• get_source (of type (string) -> source('a)?)
• mounts (of type () -> [string])
• on_listener_connect (of type (?synchronous : bool, (( { bytes_sent : int, connected_at : float, duration : float, id : int, ip : string, mount : string, protocol : string, referer : string?, uri : string, user_agent : string? }) -> unit)) -> unit): Register a handler called when a listener connects. Receives a record with id, mount, ip (hashed), user_agent, referer, uri, protocol, connected_at, duration and bytes_sent fields.
• on_listener_disconnect (of type (?synchronous : bool, (( { bytes_sent : int, connected_at : float, duration : float, id : int, ip : string, mount : string, protocol : string, referer : string?, uri : string, user_agent : string? }) -> unit)) -> unit): Register a handler called when a listener disconnects, with the same record as on_listener_connect and final duration and bytes_sent. Synchronous handlers are called exactly once per listener, after its connect handlers.
• on_metadata (of type (?synchronous : bool, (({listeners : int, metadata : [string * string], mount : string}) -> unit)) -> unit): Register a handler called on metadata updates of a mount. Receives a record with mount, metadata, and listeners (count) fields.
• on_source_connect (of type (?synchronous : bool, (( { format : string?, headers : [string * string], mount : string, source : source('a) .{ on_disconnect : (synchronous : bool, (() -> unit)) -> {release : () -> unit} }, streams : [ { channel_layout? : string, channels? : int, codec : string, field : string, frame_rate? : float?, height? : int, pixel_format? : string, samplerate? : int, type : string, width? : int }] }) -> unit)) -> unit): Register a handler called when a source connects. Receives a record with mount, source, format, streams, and headers fields.
• on_source_disconnect (of type (?synchronous : bool, (({mount : string}) -> unit)) -> unit): Register a handler called when a source disconnects. Receives a record with a mount field.
• reload (of type () -> unit): Read the config file again and apply it without disconnecting sources or listeners. Also called on SIGHUP when config is set. Raises and keeps the current config if the file is invalid.
• stats (of type () -> [string * { bytes_sent : int, connections : int, content_type : string, current_metadata : [string * string], listeners : [ { bytes_sent : int, connected_at : float, duration : float, id : int, ip : string, mount : string, protocol : string, referer : string?, uri : string, user_agent : string? }], listening_time : float, mime_type : string?, name : string, peak_listeners : int, started : float }]): Returns a list of (mount, stats) pairs. Each stats record contains: name, content_type, mime_type, started, listeners, peak_listeners, connections, listening_time, bytes_sent and current_metadata.

icecast.server.ip_hash

Default listener IP hash for icecast.server: an MD5 digest of the address with a fixed public key, truncated to 16 hex characters. It keeps addresses out of logs and pages but does not resist someone testing guessed addresses: pass your own ip_hash if that matters.

Type:

(string) -> string

Arguments:

• (unlabeled) (of type string)

icecast.server.ssl_transport

SSL transport for icecast.server using http.transport.ssl. Overrides TLS transport when both are available.

Type:

({string?}, {string?}) -> http_transport

Arguments:

• (unlabeled) (of type {string?})
• (unlabeled) (of type {string?})

Methods:

• default_port (of type int): Transport default port
• name (of type string): Transport name
• protocol (of type string): Transport protocol
• reload (of type () -> unit): Read the certificate and key again and use them for new connections. Open connections keep the previous ones. Raises and keeps the previous ones if they cannot be loaded. Does nothing until a server port using the transport has opened.

icecast.server.tls_transport

TLS transport for icecast.server using http.transport.tls.

Type:

({string?}, {string?}) -> http_transport

Arguments:

• (unlabeled) (of type {string?})
• (unlabeled) (of type {string?})

Methods:

• default_port (of type int): Transport default port
• name (of type string): Transport name
• protocol (of type string): Transport protocol
• reload (of type () -> unit): Read the certificate and key again and use them for new connections. Open connections keep the previous ones. Raises and keeps the previous ones if they cannot be loaded. Does nothing until a server port using the transport has opened.

icecast.server.x_forwarded_for

Default X-Forwarded-For IP extraction for icecast.server. Walks the X-Forwarded-For header from right to left, skipping any IP present in proxy_ips, and returns the first non-proxy IP. When proxy_ips is empty, returns the rightmost entry unconditionally (trust-all mode).

Type:

('a.{headers : [string * string], ip : string?, proxy_ips : [string?]}) ->
string?

Arguments:

• (unlabeled) (of type 'a.{headers : [string * string], ip : string?, proxy_ips : [string?]})

settings.icecast.server.default_muxer_options

Default muxer options applied when remuxing incoming streams via copy_encoder, keyed by container format name. Used to enable live/streaming-compatible output for formats that require explicit opt-in.

Type:

() -> [string * [string * string]]

settings.icecast.server.tls_transport

Preferred TLS transport for icecast.server. A pair of (name, factory) where factory takes getters of a certificate path and of an optional private key path and returns an HTTP transport with a reload method.

Type:

() ->
string *
(('a, 'b) -> http_transport
 .{default_port : int, name : string, protocol : string, reload : () -> unit
 })