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.
• 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

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

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 a certificate path and an optional private key path and returns an HTTP transport.

Type:

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