Liquidsoap

https://www.liquidsoap.info/doc-2.3.3
Admin
Liquidsoap is a powerful open-source tool for building complex audio and video stream generators,...
Tokens:649,009
Snippets:4,565
Trust Score:8.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Live stream relay command

Source: https://www.liquidsoap.info/doc-2.3.3/complete_case.html

A command-line example to start a live stream relay using ALSA input.

```bash
liquidsoap 'output.icecast(%vorbis, \
  mount="live.ogg",host="...",password="...",input.alsa())'
```

--------------------------------

### Install Liquidsoap via OPAM

Source: https://www.liquidsoap.info/doc-2.3.3/install.html

Install Liquidsoap along with the recommended ffmpeg package for full functionality.

```bash
opam install ffmpeg liquidsoap
```

--------------------------------

### Install FFmpeg OCaml bindings

Source: https://www.liquidsoap.info/doc-2.3.3/ffmpeg.html

Use opam to install the ffmpeg package for Liquidsoap integration.

```bash
opam install ffmpeg
```

--------------------------------

### MP3 Encoding Examples

Source: https://www.liquidsoap.info/doc-2.3.3/encoding_formats.html

Examples demonstrating different MP3 encoding configurations including CBR, VBR, and ABR modes.

```liquidsoap
%mp3(bitrate=128)
```

```liquidsoap
%mp3.vbr(quality=7,samplerate=22050)
```

```liquidsoap
%mp3.abr(bitrate=128,max_bitrate=192,id3v2=true)
```

--------------------------------

### SSH login session example

Source: https://www.liquidsoap.info/doc-2.3.3/server.html

Example output of an SSH session authenticated as the restricted user.

```text
11:27 toots@leonard % ssh liq-user@localhost
liq-user@localhost's password:
Linux leonard 2.6.32-4-amd64 #1 SMP Mon Apr 5 21:14:10 UTC 2010 x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Oct  5 11:26:52 2010 from localhost
help
Available commands:
(...)
| exit
| help [<command>]
| list
| quit
| request.alive
| request.all
| request.metadata <rid>
| request.on_air
| request.resolving
| request.trace <rid>
| uptime
| var.get <variable>
| var.list
| var.set <variable> = <value>
| version

Type "help <command>" for more information.
END
exit
Bye!
END
Connection to localhost closed.
```

--------------------------------

### input

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Creates an audio source with configurable start behavior, callbacks, and fallibility settings.

```APIDOC
## input

### Description
Input an audio stream using the default operator.

### Signature
(?id : string?, ?start : bool, ?on_start : (() -> unit), ?on_stop : (() -> unit), ?fallible : bool) -> source(audio=pcm('A))

### Arguments
- **id** (string?) - Optional - Force the value of the source ID.
- **start** (bool) - Optional - Automatically start outputting whenever possible.
- **on_start** (() -> unit) - Optional - Callback executed when outputting starts.
- **on_stop** (() -> unit) - Optional - Callback executed when outputting stops.
- **fallible** (bool) - Optional - Allow the child source to fail.
```

--------------------------------

### Startup log with caching

Source: https://www.liquidsoap.info/doc-2.3.3/language.html

Example log output showing the reduced startup time when the script is loaded from cache.

```text
2024/07/03 14:32:59 [startup:3] main script hash computation: 0.02s
2024/07/03 14:32:59 [startup:3] Loading main script from cache!
2024/07/03 14:32:59 [startup:3] main script cache retrieval: 0.05s
```

--------------------------------

### Apply Guided Filter

Source: https://www.liquidsoap.info/doc-2.3.3/reference-extras.html

Applies a guided filter with dynamic input support for audio and video streams.

```liquidsoap
(?radius : int?, ?eps : float?, ?mode : int?, ?sub : int?, ?guidance : int?,
 ?planes : int?, ffmpeg.filter.graph, [ffmpeg.filter.audio],
 [ffmpeg.filter.video]) -> ffmpeg.filter.video
```

--------------------------------

### server.harbor

Source: https://www.liquidsoap.info/doc-2.3.3/reference-extras.html

Starts an interface for the telnet server over HTTP.

```APIDOC
## server.harbor

### Description
Starts an interface for the “telnet” server over http.

### Signature
(?transport : http_transport.{default_port : int, name : string, protocol : string}, ?port : int, ?uri : string) -> unit

### Arguments
- **transport** (http_transport) - Optional - Http transport. Use `http.transport.ssl` or `http.transport.secure_transport` to enable HTTPS. Defaults to `<unix_transport>.{default_port=80, protocol="http", name="unix"}`.
- **port** (int) - Optional - Port of the server. Defaults to `8000`.
- **uri** (string) - Optional - URI of the server. Defaults to `"/telnet"`.
```

--------------------------------

### Install Optional Dependencies

Source: https://www.liquidsoap.info/doc-2.3.3/install.html

Add optional features like Opus encoding by installing the corresponding package and recompiling Liquidsoap.

```bash
opam install opus
```

--------------------------------

### Startup log without caching

Source: https://www.liquidsoap.info/doc-2.3.3/language.html

Example log output showing the time taken for typechecking without script caching enabled.

```text
2024/07/03 14:31:41 [startup:3] main script hash computation: 0.03s
2024/07/03 14:31:41 [startup:3] main script cache retrieval: 0.03s
2024/07/03 14:31:41 [startup:3] stdlib hash computation: 0.03s
2024/07/03 14:31:41 [startup:3] stdlib cache retrieval: 0.03s
2024/07/03 14:31:41 [startup:3] Typechecking stdlib: 3.37s
2024/07/03 14:31:41 [startup:3] Typechecking main script: 0.00s
```

--------------------------------

### Create Guided FFmpeg Filter

Source: https://www.liquidsoap.info/doc-2.3.3/reference-extras.html

Initializes a guided filter instance independently of its inputs to allow for command processing.

```liquidsoap
(?radius : int?, ?eps : float?, ?mode : int?, ?sub : int?, ?guidance : int?,
 ?planes : int?, ffmpeg.filter.graph) -> unit
```

--------------------------------

### Start Liquidsoap via init script

Source: https://www.liquidsoap.info/doc-2.3.3/in_production.html

Use the system init script to manage production Liquidsoap services.

```bash
/etc/init.d/liquidsoap start
```

--------------------------------

### Enable the web-based server interface

Source: https://www.liquidsoap.info/doc-2.3.3/server.html

Starts a web interface at http://localhost:8000/telnet that emulates the telnet server.

```liquidsoap
server.harbor()
```

--------------------------------

### Schedule sources

Source: https://www.liquidsoap.info/doc-2.3.3/cookbook.html

Examples of source switching and fallback logic for scheduling.

```liquidsoap
# A fallback switch
s = fallback([playlist("http://my/playlist"), single("/my/jingle.ogg")])
```

```liquidsoap
# A scheduler, assuming you have defined the night and day sources
s = switch([({0h-7h}, night), ({7h-24h}, day)])
```

--------------------------------

### Compile Liquidsoap with Dune

Source: https://www.liquidsoap.info/doc-2.3.3/build.html

Execute this command to initiate the build process after installing all necessary dependencies.

```bash
dune build
```

--------------------------------

### Initialize the web interface

Source: https://www.liquidsoap.info/doc-2.3.3/server.html

Starts a web server to manage interactive variables, typically called after all variables are defined.

```liquidsoap
interactive.harbor()
```

--------------------------------

### Demonstrate string escape sequences

Source: https://www.liquidsoap.info/doc-2.3.3/language.html

Example showing various escape sequences including octal and hexadecimal representations.

```liquidsoap
# "\" \t \045 \x2f \u4f32";;
- : string = "\" \t % / 2"
```

--------------------------------

### output.harbor

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Configures and starts a Harbor output stream for audio data.

```APIDOC
## output.harbor

### Description
Creates a Harbor output that streams audio to a specified mount point. It supports authentication, custom headers, and various network configuration parameters.

### Parameters
- **id** (string?) - Optional - Force the value of the source ID.
- **auth** ((address : string, string, string) -> bool?) - Optional - Authentication function.
- **buffer** (int) - Optional - Maximum buffer per-client.
- **burst** (int) - Optional - Initial burst of data sent to the client.
- **chunk** (int) - Optional - Send data to clients using chunks of at least this length.
- **dumpfile** (string?) - Optional - Dump stream to file for debugging.
- **encoding** (string) - Optional - Encoding used to send metadata.
- **fallible** (bool) - Optional - Allow the child source to fail.
- **format** (string) - Optional - Format, e.g., "audio/ogg".
- **headers** ([string * string]) - Optional - Additional headers.
- **metaint** (int) - Optional - Interval used to send ICY metadata.
- **mount** (string) - Required - The mount point for the stream.
- **on_connect** ((headers : [string * string], uri : string, protocol : string, string) -> unit) - Optional - Callback executed when connection is established.
- **on_disconnect** ((string) -> unit) - Optional - Callback executed when connection stops.
- **on_start** (() -> unit) - Optional - Callback executed when output starts.
- **on_stop** (() -> unit) - Optional - Callback executed when output stops.
- **password** (string?) - Optional - Password for client connection.
- **port** (int) - Optional - Port for the server.
- **register_telnet** (bool) - Optional - Register telnet commands for this output.
- **start** (bool) - Optional - Start output as soon as it is available.
- **timeout** (float) - Optional - Timeout for network operations.
- **transport** (http_transport) - Optional - Http transport configuration.
- **url** (string?) - Optional - URL for the stream.
- **user** (string?) - Optional - User for client connection.
```

--------------------------------

### Configure FFmpeg Hardware Acceleration

Source: https://www.liquidsoap.info/doc-2.3.3/ffmpeg_encoder.html

Example configuration for the %ffmpeg encoder using device-based hardware acceleration.

```liquidsoap
enc = %ffmpeg(
  format="mpegts",
  %video(
    hwaccel="device",
    hwaccel_devic="/dev/...",
    ...
  )
)
```

--------------------------------

### output.harbor.hls

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Configures and starts an HLS output stream served via an internal HTTP harbor server.

```APIDOC
## output.harbor.hls

### Description
Creates an HLS output stream that serves segments and playlists over HTTP. This function handles segment generation, playlist updates, and provides a telnet interface for control.

### Parameters
- **id** (string?) - Optional - Force the value of the source ID.
- **dir_perm** (int) - Optional - Permission of the directories if some have to be created, up to umask. Default: 511.
- **extra_tags** ([string]) - Optional - Extra tags to insert into the main playlist. Default: [].
- **fallible** (bool) - Optional - Allow the child source to fail. Default: false.
- **on_file_change** ((state : string, string) -> unit) - Optional - Callback executed when a file changes.
- **on_start** (() -> unit) - Optional - Callback executed when output starts.
- **on_stop** (() -> unit) - Optional - Callback executed when output stops.
- **perm** (int) - Optional - Permission of the created files, up to umask. Default: 438.
- **persist_at** (string?) - Optional - Location of the configuration file used to restart the output.
- **playlist** (string) - Optional - Playlist name. Default: "stream.m3u8".
- **prefix** (string) - Optional - Prefix for each files in playlists.
- **register_telnet** (bool) - Optional - Register telnet commands for this output. Default: true.
- **segment_duration** (float) - Optional - Segment duration (in seconds). Default: 10.0.
- **segments** (int) - Optional - Number of segments per playlist. Default: 10.
- **segments_overhead** (int?) - Optional - Number of segments to keep after they have been featured in the live playlist. Default: 5.
- **start** (bool) - Optional - Start output as soon as it is available. Default: true.
- **strict_persist** (bool) - Optional - Fail if an invalid saved state exists. Default: false.
- **temp_dir** (string?) - Optional - Temporary directory used for writing files.
- **main_playlist_writer** (function) - Optional - Main playlist writer function.
- **segment_name** (function) - Optional - Function to generate segment names.
- **headers** ([string * string]) - Optional - Default response headers. Default: [("Access-Control-Allow-Origin", "*")].
- **port** (int) - Optional - Port for incoming harbor (http) connections. Default: 8000.
- **path** (string) - Optional - Base path for hls URIs. Default: "/".
- **tmpdir** (string?) - Optional - Directory for generated files.
- **transport** (http_transport) - Optional - Http transport configuration.
```

--------------------------------

### Startup log with cached standard library

Source: https://www.liquidsoap.info/doc-2.3.3/language.html

Example log output showing the effect of having a pre-cached standard library when running a new script.

```text
2024/07/03 14:33:27 [startup:3] main script hash computation: 0.02s
2024/07/03 14:33:27 [startup:3] main script cache retrieval: 0.02s
2024/07/03 14:33:27 [startup:3] stdlib hash computation: 0.03s
2024/07/03 14:33:27 [startup:3] Loading stdlib from cache!
2024/07/03 14:33:27 [startup:3] stdlib cache retrieval: 0.10s
2024/07/03 14:33:27 [startup:3] Typechecking main script: 0.00s
```

--------------------------------

### Configure a basic harbor input

Source: https://www.liquidsoap.info/doc-2.3.3/cookbook.html

Sets up a harbor server to accept incoming Icecast-compatible streams and integrates them into a fallback radio structure.

```liquidsoap
# Serveur settings
settings.harbor.bind_addrs := ["0.0.0.0"]

# An emergency file
emergency = single("/path/to/emergency/single.ogg")

# A playlist
playlist = playlist("/path/to/playlist")

# A live source
live = input.harbor("live",port=8080,password="hackme")

# fallback
radio = fallback(track_sensitive=false, [live, playlist, emergency])

# output it
output.icecast(
  %vorbis,
  mount="test",
  host="host",
  radio)
```

--------------------------------

### Create a playlist source

Source: https://www.liquidsoap.info/doc-2.3.3/cookbook.html

Demonstrates various playlist configurations including shuffling, normal playback, and remote reloading.

```liquidsoap
# Shuffle, play every URI, start over.
s1 = playlist("/my/playlist.txt")

# Do not randomize
s2 = playlist(mode="normal", "/my/pl.m3u")

# The playlist can come from any URI, can be reloaded every 10 minutes.
s3 = playlist(reload=600, "http://my/playlist.txt")
```

--------------------------------

### Implement a server seek function

Source: https://www.liquidsoap.info/doc-2.3.3/seek.html

Example of registering a telnet server command to perform relative seeking on a playlist source.

```liquidsoap
# A playlist source
s = playlist("/path/to/music")

# The server seeking function
def seek(t) =
  t = float_of_string(default=0., t)
  log(
    "Seeking #{t} sec"
  )
  ret = source.seek(s, t)
  "Seeked #{ret} seconds."
end

# Register the function
server.register(
  namespace=source.id(s),
  description=
    "Seek to a relative position in source #{source.id(s)}",
  usage=
    "seek <duration>",
  "seek",
  seek
)
```

--------------------------------

### video.board Constructor

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Initializes a new video.board instance with optional dimensions and ID.

```APIDOC
## video.board

### Description
Creates a plane where one can draw.

### Signature
(?id : string?, ?height : int?, ?width : int?) -> source('a)

### Parameters
- **id** (string?) - Optional - Force the value of the source ID.
- **height** (int?) - Optional - Initial height of the video.
- **width** (int?) - Optional - Initial width of the video.
```

--------------------------------

### List ALSA hardware devices

Source: https://www.liquidsoap.info/doc-2.3.3/faq.html

Example output from the aplay command used to identify sound card hardware.

```text
**** List of PLAYBACK Hardware Devices ****
card 0: Intel [HDA Intel], device 0: STAC92xx Analog [STAC92xx Analog]
  Subdevices: 1/1
  Subdevice #0: subdevice #0
```

--------------------------------

### Example type error for source lists

Source: https://www.liquidsoap.info/doc-2.3.3/migrating.html

An example of the type error message generated when source methods are inconsistent across a list.

```text
At script.liq, line xxx, char yyy-zzz:
Error 5: this value has type
  _ * source(audio=?A, video=?B, midi=?C)
  .{
    time : () -> float,
    shutdown : () -> unit,
    fallible : bool,
    skip : () -> unit,
    seek : (float) -> float,
    is_active : () -> bool,
    is_up : () -> bool,
    log :
    {level : (() -> int?).{set : ((int) -> unit)}
    },
    self_sync : () -> bool,
    duration : () -> float,
    elapsed : () -> float,
    remaining : () -> float,
    on_track : ((([string * string]) -> unit)) -> unit,
    on_leave : ((() -> unit)) -> unit,
    on_shutdown : ((() -> unit)) -> unit,
    on_metadata : ((([string * string]) -> unit)) -> unit,
    is_ready : () -> bool,
    id : () -> string,
    selected : (() -> source(audio=?D, video=?E, midi=?F)?)
  }
but it should be a subtype of the type of the value at radio.liq, line 122, char 2-21
  _ * _.{reload : _}
```

--------------------------------

### Configure initialization settings

Source: https://www.liquidsoap.info/doc-2.3.3/settings.html

Manage process-level settings including root access, exception handling, and daemon mode.

```liquidsoap
settings.init.allow_root := false
```

```liquidsoap
settings.init.catch_exn := true
```

```liquidsoap
settings.init.daemon := false
```

```liquidsoap
settings.init.daemon.change_user := false
```

```liquidsoap
settings.init.daemon.change_user.group := "daemon"
```

```liquidsoap
settings.init.daemon.change_user.user := "daemon"
```

```liquidsoap
settings.init.daemon.pidfile := true
```

```liquidsoap
settings.init.daemon.pidfile.path := "<sysrundir>/<script>.pid"
```

```liquidsoap
settings.init.daemon.pidfile.perms := 416
```

```liquidsoap
settings.init.force_start := false
```

```liquidsoap
settings.init.trace := false
```

```liquidsoap
settings.init.compact_before_start := false
```

--------------------------------

### Simple radio station script

Source: https://www.liquidsoap.info/doc-2.3.3/quick_start.html

A complete example of a radio station script using playlists, jingles, and Icecast output.

```liquidsoap
#!/usr/bin/liquidsoap
# Log dir
log.file.path.set("/tmp/basic-radio.log")

# Music
myplaylist = playlist("~/radio/music.m3u")

# Some jingles
jingles = playlist("~/radio/jingles.m3u")

# If something goes wrong, we'll play this
security = single("~/radio/sounds/default.ogg")

# Start building the feed with music
radio = myplaylist

# Now add some jingles
radio = random(weights=[1, 4], [jingles, radio])

# And finally the security
radio = fallback(track_sensitive=false, [radio, security])

# Stream it out
output.icecast(
  %vorbis,
  host="localhost",
  port=8000,
  password="hackme",
  mount="basic-radio.ogg",
  radio
)
```

--------------------------------

### HTTP GET Streaming Request Signature

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Defines the type signature for performing an HTTP GET request with a streaming body callback.

```Liquidsoap
(?headers : [string * string], ?http_version : string?, ?redirect : bool,
 ?timeout : float?, ?normalize_url : bool?, string,
 on_body_data : ((string?) -> unit)) -> unit
```

--------------------------------

### Create a Beets source with ReplayGain and blank removal

Source: https://www.liquidsoap.info/doc-2.3.3/beets.html

Enhanced source creation function that applies ReplayGain amplification and automatically trims silence using blank.eat.

```liquidsoap
def beets(id, query) =
  beets_src =
    blank.eat(
      id="#{id}_",
      start_blank=true,
      max_blank=1.0,
      threshold=-45.0,
      amplify(
        override="replaygain_track_gain",
        1.0,
        request.dynamic(
          id=id,
          retry_delay=1.,
          {
            request.create(
              string.trim(
                process.read(
                  "#{BEET} random -f '$path' #{query}"
                )
              )
            )
          }
        )
      )
    )
  (beets_src : source)
end
```

--------------------------------

### getter.get

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Get the value of a getter.

```APIDOC
## getter.get

### Description
Get the value of a getter.

### Signature
({'a}) -> 'a

### Arguments
- **(unlabeled)** ({'a}) - Required
```

--------------------------------

### request.metadata

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Get the metadata associated to a request.

```APIDOC
## request.metadata

### Description
Get the metadata associated to a request.

### Signature
(request) -> [string * string]
```

--------------------------------

### file.mtime

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Get the last modification time of a file.

```APIDOC
## file.mtime

### Description
Last modification time.

### Parameters
- **(unlabeled)** (string) - Required - The file path.

### Returns
- float - The modification time.
```

--------------------------------

### input.jack

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Initializes a source that captures audio from a JACK server.

```APIDOC
## input.jack

### Description
Creates a source that streams audio from a JACK server.

### Parameters
- **id** (string?) - Optional - Force the value of the source ID.
- **fallible** (bool) - Optional - Allow the source to fail.
- **on_start** (() -> unit) - Optional - Callback executed when input starts.
- **on_stop** (() -> unit) - Optional - Callback executed when input stops.
- **self_sync** (bool) - Optional - Mark the source as being synchronized by the jack server.
- **server** (string) - Optional - Jack server to connect to.
- **start** (bool) - Optional - Start input as soon as it is available.
```

--------------------------------

### file.mkdir

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Create a directory.

```APIDOC
## file.mkdir

### Description
Create a directory.

### Parameters
- **parents** (bool) - Optional - Also create parent directories if they do not exist (defaults to false).
- **perms** (int) - Optional - Default file rights if created (defaults to 0o755).
- **(unlabeled)** (string) - Required - The path to create.
```

--------------------------------

### file.mime

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Get a file's mime type.

```APIDOC
## file.mime

### Description
Get a file’s mime type. Uses libmagic if enabled, otherwise try to get the value using the file binary. Returns null() if no value can be found.

### Parameters
- **(unlabeled)** (string) - Required - The file to test

### Returns
- string? - The MIME type or null.
```

--------------------------------

### Get first component

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Extracts the first component of a pair.

```liquidsoap
(('a * 'b)) -> 'a
```

--------------------------------

### Get request metadata

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Retrieves the metadata associated with a request.

```liquidsoap
(request) -> [string * string]
```

--------------------------------

### Get request ID

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Retrieves the unique identifier for a request.

```liquidsoap
(request) -> int
```

--------------------------------

### Use shorthand settings

Source: https://www.liquidsoap.info/doc-2.3.3/migrating.html

Convenience shortcuts for common configuration settings.

```liquidsoap
log.level.set(4)
log.file.set(true)
log.stdout.set(true)
init.daemon.set(true)
audio.samplerate.set(48000)
audio.channels.set(2)
video.frame.width.set(720)
video.frame.height.set(1280)
```

--------------------------------

### output.dummy

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Creates a dummy output that consumes a source stream. It supports configuration for start/stop callbacks, telnet registration, and fallibility.

```APIDOC
## output.dummy

### Description
Computes the stream without actually using it. Useful for testing or processing sources without outputting audio/data.

### Signature
(id : string?, fallible : bool, on_start : (() -> unit), on_stop : (() -> unit), register_telnet : bool, start : bool, source('a)) -> unit

### Arguments
- **id** (string?) - Optional - Force the value of the source ID.
- **fallible** (bool) - Optional - Allow the child source to fail.
- **on_start** (() -> unit) - Optional - Callback executed when output starts.
- **on_stop** (() -> unit) - Optional - Callback executed when output stops.
- **register_telnet** (bool) - Optional - Register telnet commands for this output.
- **start** (bool) - Optional - Start output as soon as it is available.
- **(unlabeled)** (source('a)) - Required - The source to consume.
```

--------------------------------

### Get file size

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Returns the size of a file in bytes.

```liquidsoap
(string) -> int
```

--------------------------------

### Get ReplayGain

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Retrieves the ReplayGain value for a file in dB.

```liquidsoap
(?id : string?, ?compute : bool, ?ratio : float, string) -> float?
```

--------------------------------

### Combining Patterns

Source: https://www.liquidsoap.info/doc-2.3.3/language.html

Examples of complex pattern matching syntax in Liquidsoap.

```liquidsoap
let [{foo}, {gni}, ..., {baz}] = l

let (_.{ bla = [..., z] }, t, _, u) = x
```

--------------------------------

### list.make

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Create a list with given length, filled with given element.

```APIDOC
## list.make

### Description
Create a list with given length, filled with given element.

### Signature
(int, 'a) -> ['a]
```

--------------------------------

### Prometheus latency metrics output

Source: https://www.liquidsoap.info/doc-2.3.3/prometheus.html

Example of exported latency metrics.

```text
# Input metrics:
liquidsoap_input_latency{...} <value>
liquidsoap_input_max_latency{...} <value>
liquidsoap_input_peak_latency{...} <value>

# Output metrics:
liquidsoap_outputput_latency{...} <value>
liquidsoap_output_max_latency{...} <value>
liquidsoap_output_peak_latency{...} <value>

# Overall metrics:
liquidsoap_overall_latency{...} <value>
liquidsoap_overall_max_latency{...} <value>
liquidsoap_overall_peak_latency{...} <value>
```

--------------------------------

### Initialize SQLite database

Source: https://www.liquidsoap.info/doc-2.3.3/database.html

Opens or creates a database file and returns an object for database operations.

```liquidsoap
db = sqlite("/tmp/database.sql")

```

--------------------------------

### input.srt

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Configures and initializes an SRT input source.

```APIDOC
## input.srt

### Description
Creates an SRT input source that can operate in either listener or caller mode to receive or send media streams.

### Parameters
- **id** (string?) - Optional - Force the value of the source ID.
- **bind_address** (string) - Optional - Address to bind on the local machine (listener mode).
- **connection_timeout** (float?) - Optional - Timeout in seconds for initial connection operations (caller mode).
- **content_type** (string) - Optional - Mime type used to find a decoder.
- **dump** (string) - Optional - File path to dump received data for debugging.
- **enforced_encryption** (bool?) - Optional - Enforces passphrase matching.
- **host** (string) - Optional - Address to connect to (caller mode).
- **ipv6only** (bool?) - Optional - Restrict to IPv6 in listener mode.
- **listen_callback** (function) - Optional - Callback to accept incoming connections.
- **max** (float) - Optional - Maximum duration of buffered data.
- **messageapi** (bool) - Optional - Use message api.
- **mode** (string) - Optional - Operation mode: "listener" or "caller".
- **on_connect** (function) - Optional - Executed when connected.
- **on_disconnect** (function) - Optional - Executed when disconnected.
- **on_socket** (function) - Optional - Callback for socket creation events.
- **on_start** (function) - Optional - Executed when input starts.
- **on_stop** (function) - Optional - Executed when input stops.
- **passphrase** (string?) - Optional - Encryption passphrase.
- **payload_size** (int) - Optional - Payload size.
- **pbkeylen** (int?) - Optional - Encryption key length.
- **polling_delay** (float) - Optional - Delay between connection attempts (caller mode).
- **port** (int) - Optional - Port to bind or connect to.
- **prefer_address** (string?) - Optional - Preferred address type (system, ipv4, ipv6).
- **read_timeout** (float?) - Optional - Timeout for read operations.
- **self_sync** (bool) - Optional - Whether the source controls its own latency.
- **start** (bool) - Optional - Start input immediately.
- **streamid** (string?) - Optional - Set streamid (caller mode).
- **write_timeout** (float?) - Optional - Timeout for write operations.
```

--------------------------------

### Verify frame size configuration

Source: https://www.liquidsoap.info/doc-2.3.3/cookbook.html

Log output confirming that the audio frame size has been successfully applied.

```text
Targeting 'frame.audio.size': 2048 audio samples = 2048 ticks.
```

--------------------------------

### ffmpeg.filter.guided

Source: https://www.liquidsoap.info/doc-2.3.3/reference-extras.html

Applies a Guided filter with dynamic audio and video inputs.

```APIDOC
## ffmpeg.filter.guided

### Description
Apply Guided filter. This filter has dynamic inputs: last two arguments are lists of audio and video inputs. Total number of inputs is determined at runtime.

### Arguments
- **radius** (int?) - Optional - Set the box radius (default: 3)
- **eps** (float?) - Optional - Set the regularization parameter (default: 0.01)
- **mode** (int?) - Optional - Set filtering mode (0: basic, 1: fast) (default: 0)
- **sub** (int?) - Optional - Subsampling ratio for fast mode (default: 4)
- **guidance** (int?) - Optional - Set guidance mode (0: off, 1: on) (default: 0)
- **planes** (int?) - Optional - Set planes to filter (default: 1)
- **graph** (ffmpeg.filter.graph) - Required
- **audio_inputs** ([ffmpeg.filter.audio]) - Required
- **video_inputs** ([ffmpeg.filter.video]) - Required
```

--------------------------------

### Get second pair component

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Retrieves the second component of a pair.

```liquidsoap
(('a * 'b)) -> 'b
```

--------------------------------

### Manage file logging

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Gets or sets the file logging configuration.

```liquidsoap
() -> bool
```

--------------------------------

### Get encoder content-type

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Returns the mime type of an encoder if it is known.

```liquidsoap
(format('a)) -> string
```

--------------------------------

### video.slideshow

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Initializes a new video slideshow source.

```APIDOC
## video.slideshow

### Description
Creates a source that displays a slideshow of pictures.

### Parameters
- **id** (string?) - Optional - Identifier for the source.
- **cyclic** (bool) - Optional - If true, loops back to the first picture after the last one. Defaults to true.
- **advance** (float) - Optional - Time in seconds to wait before skipping to the next file. Defaults to -1.0 (never).
- **files** ([string]) - Optional - List of files to display.
```

--------------------------------

### file.umask

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Gets or sets the process file mode creation mask.

```APIDOC
## file.umask

### Description
Get the process’s file mode creation mask.

## file.umask.set

### Description
Set process’s file mode creation mask.

### Parameters
- **(unlabeled)** (int) - Required - Mask value.
```

--------------------------------

### Check asplit filter help

Source: https://www.liquidsoap.info/doc-2.3.3/ffmpeg_filters.html

Displays the help documentation for the asplit filter, showing its dynamic output capabilities.

```liquidsoap
% liquidsoap -h ffmpeg.filter.asplit

Ffmpeg filter: Pass on the audio input to N audio outputs. This filter has
dynamic outputs: returned value is a tuple of audio and video outputs. Total
number of outputs is determined at runtime.

Type: (?outputs : int?, ffmpeg.filter.graph,
 ffmpeg.filter.audio) ->
[ffmpeg.filter.audio] * [ffmpeg.filter.video]

Category: Liquidsoap
Flag: extra

Parameters:

 * outputs : int? (default: null)
     set number of outputs. (default: 2)

 * (unlabeled) : ffmpeg.filter.graph (default: None)

 * (unlabeled) : ffmpeg.filter.audio (default: None)
```

--------------------------------

### file.download

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Downloads a file from a URL using an HTTP GET request.

```APIDOC
## file.download

### Description
Download file using a regular http.get request. Returns true on success.

### Parameters
- **filename** (string) - Required - Downloaded filename.
- **timeout** (float) - Optional (default: 5.0) - Timeout in seconds.
- **url** (string) - Required - The URL to download from.
```

--------------------------------

### Initialize a single source

Source: https://www.liquidsoap.info/doc-2.3.3/multitrack.html

Create a source from a file with multiple tracks using the single operator.

```liquidsoap
s = single("/path/to/movie.mkv")
```

--------------------------------

### Logging File Errors

Source: https://www.liquidsoap.info/doc-2.3.3/language.html

Example of catching and logging errors during file operations.

```liquidsoap
data = "bla"
try
  file.write(data=data, "/non/existent/path")
catch err do
  log.important("Could not write to file: #{error.message(err)}")
end
```

--------------------------------

### Configure aptx codec

Source: https://www.liquidsoap.info/doc-2.3.3/settings.html

Set the preferred decoder and view available options for aptx.

```liquidsoap
settings.decoder.ffmpeg.codecs.aptx := <value>
```

```liquidsoap
settings.decoder.ffmpeg.codecs.aptx.available := ["aptx"]
```

--------------------------------

### Pinning a local git repository with opam

Source: https://www.liquidsoap.info/doc-2.3.3/build.html

Use these commands to clone a repository and pin it locally for development.

```bash
git clone https://github.com/savonet/ocaml-metadata.git
cd ocaml-metadata
opam pin -ny .
```

--------------------------------

### Basic Amplify Usage

Source: https://www.liquidsoap.info/doc-2.3.3/language.html

Example of using the amplify operator with a microphone input.

```liquidsoap
mic   = input.alsa()
radio = amplify(1.2, mic)
```

--------------------------------

### playlist.list

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Creates a playlist source with configurable playback behavior, including looping, shuffling, and error handling.

```APIDOC
## playlist.list

### Description
Creates a playlist source that can play files in normal, random, or randomized order. It supports advanced features like prefetching, custom filtering, and lifecycle callbacks.

### Arguments
- **id** (string?) - Optional - Force the value of the source ID.
- **check_next** ((request) -> bool?) - Optional - Function used to filter next tracks.
- **prefetch** (int?) - Optional - How many requests should be queued in advance.
- **loop** (bool) - Optional - Loop on the playlist (default: true).
- **mode** (string) - Optional - Playback mode: "normal", "randomize", or "random" (default: "normal").
- **native** (bool) - Optional - Use native implementation (default: false).
- **on_loop** (() -> unit) - Optional - Function executed when the playlist is about to loop.
- **on_done** (() -> unit) - Optional - Function executed when the playlist is finished.
- **max_fail** (int) - Optional - Number of failed requests before the playlist is considered failed (default: 10).
- **on_fail** (() -> [string]?) - Optional - Function executed when too many requests failed.
- **timeout** (float?) - Optional - Timeout in seconds to resolve the request.
- **cue_in_metadata** (string?) - Optional - Metadata for cue in points (default: "liq_cue_in").
- **cue_out_metadata** (string?) - Optional - Metadata for cue out points (default: "liq_cue_out").
- **(unlabeled)** ([string]) - Required - The list of files or URIs in the playlist.
```

--------------------------------

### Get string length

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Returns the length of a string using a specified encoding.

```liquidsoap
(?encoding : string?, string) -> int
```

--------------------------------

### Get nullable value

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Retrieves the value of a nullable, optionally providing a default.

```liquidsoap
(?default : 'a?, 'a?) -> 'a
```

--------------------------------

### Configure simbiosis_imx codec settings

Source: https://www.liquidsoap.info/doc-2.3.3/settings.html

Set the preferred codec and view available options for simbiosis_imx decoding.

```liquidsoap
settings.decoder.ffmpeg.codecs.simbiosis_imx := <value>
```

```liquidsoap
settings.decoder.ffmpeg.codecs.simbiosis_imx.available := ["simbiosis_imx"]
```

--------------------------------

### sqlite(path)

Source: https://www.liquidsoap.info/doc-2.3.3/database.html

Initializes a connection to a SQLite database file.

```APIDOC
## sqlite(path)

### Description
Creates or opens a SQLite database at the specified file path.

### Parameters
- **path** (string) - Required - The file path where the database is stored.

### Returns
- **db** (object) - A database object with methods for table and row manipulation.
```

--------------------------------

### request.resolve

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Resolve a request, i.e. attempt to get a valid local file.

```APIDOC
## request.resolve

### Description
Resolve a request, i.e. attempt to get a valid local file. The operation can take some time. Return true if the resolving was successful, false otherwise (timeout or invalid URI).

### Parameters
- **timeout** (float?) - Optional - Limit in seconds to the duration of the request resolution.
- **content_type** (source('a)?) - Optional - Check that the request can decode content suitable for the given source.
- **request** (request) - Required
```

--------------------------------

### list.slice

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Return the sublist of length length starting with the element at index offset.

```APIDOC
## list.slice

### Description
Return the sublist of length length starting with the element at index offset.

### Signature
(?offset : int, ?length : int?, ['a]) -> ['a]
```

--------------------------------

### list.prefix

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Compute the beginning of a list.

```APIDOC
## list.prefix

### Description
Compute the beginning of a list.

### Signature
(int, ['a]) -> ['a]
```

--------------------------------

### Slice list

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Extracts a sublist starting at a specific offset with a defined length.

```liquidsoap
(?offset : int, ?length : int?, ['a]) -> ['a]
```

--------------------------------

### Configure qoi codec

Source: https://www.liquidsoap.info/doc-2.3.3/settings.html

Set the preferred codec and view available options for qoi.

```liquidsoap
settings.decoder.ffmpeg.codecs.qoi := <value>
```

```liquidsoap
settings.decoder.ffmpeg.codecs.qoi.available := ["qoi"]
```

--------------------------------

### Type Mismatch Error

Source: https://www.liquidsoap.info/doc-2.3.3/language.html

Example of a type error when branches return different types.

```liquidsoap
x = if 1 == 2 then "A" else 5 end
```

```text
At line 1, char 19-21:
Error 5: this value has type string
but it should be a subtype of int
```

--------------------------------

### medialib

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Initializes a media library to store and query file metadata.

```APIDOC
## medialib

### Description
A library to store the metadata of files in given folders and query them. This is useful to generate playlists based on metadata.

### Parameters
- **id** (string?) - Optional - Library identifier.
- **persistency** (string?) - Optional - File path to store the database.
- **refresh** (float?) - Optional - Scan interval in seconds.
- **standardize** (function) - Optional - Function to map metadata fields.
- **initial_progress** (bool) - Optional - Show indexing progress (default: true).
- **directories** ([string]) - Optional - List of directories to index.

### Methods
- **add_directory(string)**: Add a new directory to be scanned.
- **clear()**: Remove all known metadata.
- **find(...)**: Find files based on metadata conditions (artist, album, genre, year, bpm, etc.).
- **refresh()**: Update metadata and scan for new files.
```

--------------------------------

### JSON parsing return value

Source: https://www.liquidsoap.info/doc-2.3.3/json.html

The resulting structure after parsing the complex JSON example.

```text
  - x : {
    foo = 34.24,
    gni_gno = true,
    nested = {
      tuple = (null, 3.14),
      list = [44., 55., 66.12],
      nullable_list = [null, 23, null],
      object_as_list = [("foo", 123.), ("gni", 456.0), ("gno", 3.14)],
      arbitrary_object_key = true,
      not_present = null
    }
  }
```

--------------------------------

### Configure qdmc codec

Source: https://www.liquidsoap.info/doc-2.3.3/settings.html

Set the preferred codec and view available options for qdmc.

```liquidsoap
settings.decoder.ffmpeg.codecs.qdmc := <value>
```

```liquidsoap
settings.decoder.ffmpeg.codecs.qdmc.available := ["qdmc"]
```

--------------------------------

### Identify ALSA error

Source: https://www.liquidsoap.info/doc-2.3.3/faq.html

Example of an error message caused by Pulseaudio interference with ALSA.

```text
Alsa.Unknown_error(1073697252)!
```

--------------------------------

### Implement dynamic volume control with FFmpeg filters

Source: https://www.liquidsoap.info/doc-2.3.3/ffmpeg_filters.html

Shows how to use the filter command API to adjust filter parameters at runtime by returning a control function alongside the processed source.

```liquidsoap
def dynamic_volume(s) =
  def mkfilter(graph) =
    filter = ffmpeg.filter.volume.create(graph)

    def set_volume(v) =
      ignore(filter.process_command("volume", "#{v}"))
    end

    let {audio = audio_track} = source.tracks(s)

    audio_track = ffmpeg.filter.audio.input(graph, audio_track)
    filter.set_input(audio_track)
    audio_track = filter.output
    audio_track = ffmpeg.filter.audio.output(graph, audio_track)

    s =
      source(
        {
          audio=audio_track,
          metadata=track.metadata(audio_track),
          track_marks=track.track_marks(audio_track)
        }
      )

    (s, set_volume)
  end

  ffmpeg.filter.create(mkfilter)
end

s = playlist("my_playlist")

let (s, set_volume) = dynamic_volume(s)
```

--------------------------------

### Identify crash logs

Source: https://www.liquidsoap.info/doc-2.3.3/faq.html

Example of log messages indicating an internal Liquidsoap crash.

```text
... [threads:1] Thread "XXX" aborts with exception YYY!
... [stderr:3] Thread 2 killed on uncaught exception YYY.
... [stderr:3] Raised at file ..., line ..., etc.
```

--------------------------------

### Create reference from functions

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Creates a reference using custom get and set functions.

```liquidsoap
((() -> 'a), (('a) -> unit)) -> () -> 'a
```

--------------------------------

### http.get

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Performs a full HTTP GET request and returns the response body as a string.

```APIDOC
## http.get

### Description
Perform a full http GET request.

### Parameters
- **headers** ([string * string]) - Optional - Additional headers. Defaults to [].
- **http_version** (string?) - Optional - Http request version. Defaults to null.
- **redirect** (bool) - Optional - Perform redirections if needed. Defaults to true.
- **timeout** (float?) - Optional - Timeout for network operations in seconds. Defaults to 10.0.
- **normalize_url** (bool?) - Optional - Normalize url, replacing spaces with %20 and more. Defaults to settings.http.normalize_url.
- **url** (string) - Required - Requested URL, e.g. "http://www.liquidsoap.info/".
```

--------------------------------

### Generating CUE files

Source: https://www.liquidsoap.info/doc-2.3.3/cookbook.html

Creates a CUE file alongside an audio backup to track metadata and timing.

```liquidsoap
radio =
  source.cue(
    title=
      "My stream",
    file="backup.mp3",
    "/tmp/backup.cue",
    radio
  )
output.file(%mp3, "/tmp/backup.mp3", radio)
```

```text
TITLE "My stream"
PERFORMER "The performer"
FILE "backup.mp3" MP3
  TRACK 01 AUDIO
    TITLE "Title 1"
    PERFORMER "Artist 1"
    INDEX 01 00:00:00
  TRACK 02 AUDIO
    TITLE "Title 2"
    PERFORMER "Artist 2"
    INDEX 01 01:12:67
```

--------------------------------

### input.portaudio

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Constructor for a PortAudio input source.

```APIDOC
## input.portaudio

### Description
Creates a source that streams audio from a PortAudio input device.

### Parameters
- **id** (string?) - Optional - Force the value of the source ID.
- **buflen** (int) - Optional - Length of a buffer in samples (default: 256).
- **device_id** (int?) - Optional - Device ID. Uses default device if null.
- **fallible** (bool) - Optional - Allow the source to fail (default: false).
- **latency** (float?) - Optional - Device latency. Only used when specifying device ID.
- **on_start** (() -> unit) - Optional - Callback executed when input starts.
- **on_stop** (() -> unit) - Optional - Callback executed when input stops.
- **self_sync** (bool) - Optional - Mark the source as being synchronized by the portaudio driver (default: true).
- **start** (bool) - Optional - Start input as soon as it is available (default: true).
```

--------------------------------

### Get getter value

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Defines the type signature for retrieving the current value of a getter.

```liquidsoap
({'a}) -> 'a
```

--------------------------------

### Serve static files with harbor.http.static

Source: https://www.liquidsoap.info/doc-2.3.3/reference.html

Configures a static file server on the harbor. Use transport options like ssl to enable HTTPS.

```liquidsoap
(?transport : http_transport
 .{default_port : int, name : string, protocol : string}, ?port : int,
 ?path : string, ?browse : bool, ?content_type : ((string) -> string?),
 ?headers : [string * string], string) -> unit
```

--------------------------------

### https.get function signature

Source: https://www.liquidsoap.info/doc-2.3.3/reference-deprecated.html

Deprecated HTTPS get method; use http.get instead.

```liquidsoap
(?headers : [string * string], ?http_version : string?, ?redirect : bool,
 ?timeout : float?, ?normalize_url : bool?, string) -> string
```
Tokens:
Raw