Liquidsoap

https://www.liquidsoap.info/doc-2.4.0
Admin
Liquidsoap is a powerful open-source tool for building complex audio and video stream generators for...
Tokens:970,811
Snippets:6,471
Trust Score:8.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### start

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

Starts the source or output.

```APIDOC
## start

### Description
Initiates the operation of the source or output.

### Method
N/A (Method call on an object)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (200)
- **status** (unit) - Indicates successful start.
```

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

### on_start

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

Registers a callback to be executed when the output starts.

```APIDOC
## on_start

### Description
Call a given handler when output starts.

### Signature
`(synchronous : bool, (() -> unit)) -> unit`

### Parameters
* `synchronous` (bool): If true, the callback is executed synchronously.
* `handler` (function): A function that takes no arguments.
```

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

### Install Liquidsoap with FFmpeg

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

Install Liquidsoap along with the FFmpeg package for full functionality. OPAM handles external dependencies.

```bash
opam install ffmpeg liquidsoap
```

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

### on_start

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

Calls a given handler when the output starts.

```APIDOC
## on_start

### Description
Calls a given handler when output starts.

### Signature
`on_start(synchronous : bool, handler : (() -> unit)) -> unit`

### Parameters
* `synchronous` (bool) - Required - Indicates if the callback is synchronous.
* `handler` (function) - Required - The function to call on start.
```

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

### On Position Callback Example

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

Shows how to set up a callback that executes when a specific position within the current track is reached. This example triggers when 50% of the track has elapsed.

```liquidsoap
on_position(position=0.5, synchronous=true, (pos, meta) -> print("Reached 50% of track"))
```

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

### is_started

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

Checks if the source or output has started.

```APIDOC
## is_started

### Description
Checks if the source or output has been started.

### Method
N/A (Method call on an object)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
- **is_started** (bool) - `true` if the source or output is started, `false` otherwise.
```

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

### Starting the Web Interface for Telnet Emulation

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

Starts a web interface that emulates a Telnet connection to the Liquidsoap server. This interface is accessible via a web browser.

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

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

### Server Seek Function Example

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

This example demonstrates how to implement a server-based seek function for a playlist source. It registers a 'seek' command that accepts a duration in seconds.

```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
)
```

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

### Insert Metadata Example

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

Demonstrates how to dynamically insert metadata into a stream using the `insert_metadata` method. This example shows inserting a new track with specific metadata.

```liquidsoap
insert_metadata(new_track=true, ["artist", "The Beatles", "title", "Here Comes the Sun"])
```

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

### Liquidsoap Function Documentation Example (sine)

Source: https://www.liquidsoap.info/doc-2.4.0/help.html

This is an example of the detailed documentation output for the `sine` function, showing its description, type signature, parameters, and available methods. This output is generated by `liquidsoap -h sine`.

```text
Generate a sine wave.

Type: (?id : string?, ?amplitude : {float}, ?duration : float,
 ?{float}) -> source(audio=internal('a),
video=internal('b),
midi=internal('c))

Category: Source / Input

Parameters:

 * id : string? (default: null)
     Force the value of the source ID.

 * amplitude : {float} (default: 1.)
     Maximal value of the waveform.

 * duration : float (default: -1.)
     Duration in seconds (negative means infinite).

 * (unlabeled) : {float} (default: 440.)
     Frequency of the sine.

Methods:

 * fallible : bool
     Indicate if a source may fail, i.e. may not be ready to stream.

 * id : () -> string
     Identifier of the source.

 * is_active : () -> bool
     `true` if the source is active, i.e. it is continuously animated by its
     own clock whenever it is ready. Typically, `true` for outputs and
     sources such as `input.http`.

 * is_ready : () -> bool
     Indicate if a source is ready to stream. This does not mean that the
     source is currently streaming, just that its resources are all properly
     initialized.

 * is_up : () -> bool
     Indicate that the source can be asked to produce some data at any time.
     This is `true` when the source is currently being used or if it could be
     used at any time, typically inside a `switch` or `fallback`.

 * on_leave : ((() -> unit)) -> unit
     Register a function to be called when source is not used anymore by
     another source.

 * on_metadata : ((([string * string]) -> unit)) -> unit
     Call a given handler on metadata packets.

 * on_shutdown : ((() -> unit)) -> unit
     Register a function to be called when source shuts down.

 * on_track : ((([string * string]) -> unit)) -> unit
     Call a given handler on new tracks.

 * remaining : () -> float
     Estimation of remaining time in the current track.

 * seek : (float) -> float
     Seek forward, in seconds (returns the amount of time effectively
     seeked).

 * self_sync : () -> bool
     Is the source currently controlling its own real-time loop.

 * skip : () -> unit
     Skip to the next track.

 * time : () -> float
     Get a source's time, based on its assigned clock.
```

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

### On Shutdown Callback Example

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

Provides an example of registering a callback function to be executed when the source is shutting down. This is useful for cleanup operations.

```liquidsoap
on_shutdown(synchronous=true, () -> print("Source is shutting down."))
```

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

### Install FFmpeg Package with Opam

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

Use this command to install the FFmpeg package via opam, which includes the necessary ocaml-ffmpeg bindings for Liquidsoap.

```bash
% opam install ffmpeg
```

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

### on_start

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

Registers a function to be called immediately after Liquidsoap has started.

```APIDOC
## on_start

### Description
Register a function to be called when Liquidsoap starts.

### Type
```
((() -> unit)) -> unit
```

### Arguments
* `(unlabeled)` (function returning unit)
```

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

### Start Live Show Relay with Liquidsoap

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

This command starts a live show relay using Liquidsoap. It configures an Icecast output for Vorbis format and captures audio input from the ALSA soundcard.

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

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

### server.harbor

Source: https://www.liquidsoap.info/doc-2.4.0/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, ?port : int, ?uri : string) -> unit

### Arguments
- **transport** (http_transport) - Optional - Http transport. Use http.transport.ssl or http.transport.secure_transport to enable HTTPS output. Defaults to <unix_transport>.
- **port** (int) - Optional - Port of the server. Defaults to 8000.
- **uri** (string) - Optional - URI of the server. Defaults to "/telnet".
```

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

### on_wake_up

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

Register a callback to be executed after the source is asked to get ready.

```APIDOC
## on_wake_up

### Description
Registers a handler to be called after the source has been instructed to become ready.

### Method
POST (or equivalent for the specific interface)

### Endpoint
`/sources/{id}/callbacks/on_wake_up` (hypothetical)

### Parameters
#### Request Body
- **synchronous** (bool, required): If `true`, the callback is executed synchronously.
- **handler** (function, required): The function to execute after wake up.

### Request Example
(The `handler` parameter is a function, not directly representable in a typical JSON request body for an HTTP API. This suggests an SDK or internal API usage.)

### Response
#### Success Response (200)
- **status** (string): Indicates success or failure of the callback registration.

### Response Example
```json
{
  "status": "callback_registered"
}
```
```

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

### On Wake Up Callback Example

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

Demonstrates registering a callback that runs after the source has been signaled to become ready. This is useful for actions that should occur once the source is initialized.

```liquidsoap
on_wake_up(synchronous=true, () -> print("Source is ready."))
```

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

### Get Uptime in Seconds

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

Returns the current time in seconds since the Liquidsoap script started execution.

```liquidsoap
time.up()
```

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

### Get setting value using record syntax

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

Retrieve the current value of a setting using the new record syntax, for example, `settings.decoder.decoders()`.

```liquidsoap
current_decoders = settings.decoder.decoders()
```

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

### Get metadata

Source: https://www.liquidsoap.info/doc-2.4.0/harbor_http.html

This example shows how to set up an HTTP endpoint to retrieve the current metadata of a source. It registers a handler that returns the metadata in JSON format.

```APIDOC
## GET /getmeta

### Description
Retrieves the current metadata of a source and returns it as a JSON object. This endpoint is registered on port 7000.

### Method
GET

### Endpoint
/getmeta

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
GET /getmeta HTTP/1.1
Host: server:7000

```

### Response
#### Success Response (200 OK)
- **genre** (string) - The genre of the current track.
- **album** (string) - The album of the current track.
- **artist** (string) - The artist of the current track.
- **title** (string) - The title of the current track.

#### Response Example
```json
{
  "genre": "Soul",
  "album": "The Complete Stax-Volt Singles: 1959-1968 (Disc 8)",
  "artist": "Astors",
  "title": "Daddy Didn't Tell Me"
}
```
```

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

### Set metadata

Source: https://www.liquidsoap.info/doc-2.4.0/harbor_http.html

This example illustrates how to create an HTTP endpoint to update the metadata of a source. It registers a GET handler that accepts metadata as query parameters and updates the source accordingly.

```APIDOC
## GET /setmeta

### Description
Updates the metadata of a source. Metadata is provided as query parameters in the request URL. The handler filters unusual metadata and then calls the source's `insert_metadata` method.

### Method
GET

### Endpoint
/setmeta

### Parameters
#### Path Parameters
None

#### Query Parameters
- **title** (string) - Optional - The title to set for the metadata.
- **artist** (string) - Optional - The artist to set for the metadata.
- **album** (string) - Optional - The album to set for the metadata.
- **genre** (string) - Optional - The genre to set for the metadata.

#### Request Body
None

### Request Example
```
GET /setmeta?title=foo&artist=bar HTTP/1.1
Host: server:7000

```

### Response
#### Success Response (200 OK)
- **body** (string) - A simple HTML message indicating the result of the operation (e.g., "OK!" or "No metadata to add!").

#### Response Example
```html
<html><body><b>OK!</b></body></html>
```
```

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

### On Frame Callback Example

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

Illustrates setting up a callback function to be executed on each video frame. The `before=true` argument ensures the callback runs before frame processing.

```liquidsoap
on_frame(before=true, synchronous=true, (frame) -> print("Processing frame..."))
```

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

### Custom Crossfade Transition for Radio Automation

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

This example demonstrates how to create a custom crossfade transition in Liquidsoap for a radio automation scenario. It tags music and jingle sources and applies a crossfade only when transitioning between music tracks, otherwise using a simple sequence. This setup is useful for managing transitions between different types of audio content.

```liquidsoap
# A function to add a source_tag metadata to a source:
def source_tag(s, tag) =
  def f(_) =
    [("source_tag", (tag : string))]
  end
  metadata.map(id=tag, insert_missing=true, f, s)
end

# Tag our sources
music = source_tag(music, "music")
jingles = source_tag(jingles, "jingles")

# Combine them with one jingle every 3 music tracks
radio = rotate(weights=[1, 3], [jingles, music])

# Now a custom crossfade transition:
def transition(a, b) =
  # If old or new source is not music, no fade
  if
    a.metadata["source_tag"] != "music" or a.metadata["source_tag"] != "music"
  then
    sequence([a.source, b.source])
  else
    # Else, apply the standard transition
    cross.simple(a.source, b.source)
  end
end

# Apply it!
radio = cross(duration=5., transition, radio)


```

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

### Building a Radio Stream with Icecast and Random Fallback

Source: https://www.liquidsoap.info/doc-2.4.0/sources.html

This example demonstrates how to construct a radio stream using an Icecast output, a random source selector, and a fallback mechanism for playlists. It shows a typical pipeline for combining different audio sources.

```liquidsoap
radio = output.icecast(
    %vorbis, mount="test.ogg",
    random([
      jingle,
      fallback([playlist1, playlist2, playlist3])
    ])
  )
```

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

### OSS Output with Delayed Start

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

Prevent the OSS output from starting automatically when it becomes available. Set `start` to false to manually control the startup.

```liquidsoap
output.oss(start=false)
```

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

### on_start

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

Registers a handler to be executed when the source starts. The handler is a synchronous function that takes no arguments and returns unit.

```APIDOC
## on_start

### Description
Call a given handler when source starts.

### Method
Callback registration

### Parameters
#### Callback Parameters
- **synchronous** (bool) - Required - Indicates if the callback is synchronous.
- **handler** (() -> unit) - Required - The function to execute upon starting.

### Callback Example
```lua
source.on_start(false, function() print('Source started.') end)
```
```

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

### FFmpeg guided filter signature

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

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

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

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

### input.oss Configuration and Methods

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

This snippet outlines the configurable arguments and available methods for the input.oss source. It covers how to set up the source, manage its state, and retrieve information.

```APIDOC
## input.oss

### Description
Provides an interface for inputting audio data using the OSS (Open Sound System) device.

### Arguments
* `id` (string?, defaults to `null`): Force the value of the source ID.
* `device` (string, defaults to `"/dev/dsp"`): OSS device to use.
* `fallible` (bool, defaults to `false`): Allow the source to fail. If set to `false`, `start` must be `true` and `stop` method raises an error.
* `self_sync` (bool, defaults to `true`): Mark the source as being synchronized by the OSS driver.
* `start` (bool, defaults to `true`): Start input as soon as it is available.

### Methods
* `buffered` (returns `[string * float]`): Length of buffered data.
* `clock` (returns `clock`): The source’s clock.
* `duration` (returns `float`): Estimation of the duration of the current track.
* `elapsed` (returns `float`): Elapsed time in the current track.
* `fallible` (returns `bool`): Indicate if a source may fail.
* `id` (returns `string`): Identifier of the source.
* `insert_metadata` (takes `(?new_track : bool, [string * string])`, returns `unit`): Dynamically insert metadata in a stream.
* `is_active` (returns `bool`): `true` if the source is active.
* `is_ready` (returns `bool`): Indicate if a source is ready to stream.
* `is_started` (returns `bool`): `true` if the output or source is started.
* `is_up` (returns `bool`): Indicate that the source can be asked to produce some data at any time.
* `last_metadata` (returns `[string * string]?`): Return the last metadata from the source.
* `log` (takes `{level : (() -> int).{set : (int) -> unit}}`): Get or set the source’s log level, from `1` to `5`.
* `register_command` (takes `(?usage : string?, description : string, string, ((string) -> string))`, returns `unit`): Register a server command for this source.
* `remaining` (returns `float`): Estimation of remaining time in the current track.
* `reset_last_metadata_on_track` (takes `(() -> bool).{set : (bool) -> unit}`): If `true`, the source’s `last_metadata` is reset on each new track.
* `seek` (takes `float`, returns `float`): Seek forward, in seconds.
* `self_sync` (returns `bool`): Is the source currently controlling its own real-time loop.
* `skip` (returns `unit`): Skip to the next track.
* `start` (returns `unit`): Ask the source or output to start.
* `stop` (returns `unit`): Ask the source or output to stop.
* `time` (returns `float`): Get a source’s time, based on its assigned clock.
```

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

### Guided FFmpeg Filter Type Signature

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

Type signature for creating a guided filter instance independently of its inputs.

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

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

### Outputting First Audio and Video Track with FFmpeg Copy

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

This example demonstrates how to output a media file using FFmpeg's copy codec for both audio and video, effectively copying the first detected audio and video tracks from the source.

```liquidsoap
output.file(%ffmpeg(%audio.copy, %video.copy), "/path/to/copy.mkv", s)
```

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

### Basic Protocol Usage Example

Source: https://www.liquidsoap.info/doc-2.4.0/requests.html

Demonstrates a simple protocol chain where `annotate` adds metadata and `http` fetches the resource.

```liquidsoap
annotate:title="My Song":http://example.com/song.mp3
```

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

### Install Opus Encoding/Decoding

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

Add optional Opus encoding and decoding support by installing the Opus package. This will recompile Liquidsoap.

```bash
opam install opus
```

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

### Generating CUE Files with Liquidsoap

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

This example demonstrates how to generate CUE files alongside audio backups. The `source.cue` operator is used to record track timings and metadata, which can later be used to split the audio file.

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

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

### Configure Harbor Input and Define Source

Source: https://www.liquidsoap.info/doc-2.4.0/harbor.html

Set Harbor bind addresses and define a live Harbor input source with a specific mount point, port, and password. This source becomes available when a client connects.

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

# Some code...

# This defines a source waiting on mount point /test-harbor
live = input.harbor("test-harbor", port=8080, password="xxx")

files = playlist("the-playlist")

# This is the final stream.  Uses the live source as soon as available, and
# don't wait for an end of track, since we don't want to cut the beginning of
# the live stream.
#
# You may insert a jingle transition here...
radio = fallback(track_sensitive=false, [live, files])
```

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

### Prepare a Source for Later Use

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

The `prepare` method takes a source and prepares it to be returned later. This is useful for pre-loading or initializing resources.

```liquidsoap
prepare (source(video=canvas('B), 'A)) -> unit
```

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

### Force Start Without Active Source

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

Allows Liquidsoap to start even if there are no active sources. Reserved for advanced dynamic uses.

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

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

### Process URI with Input and Output

Source: https://www.liquidsoap.info/doc-2.4.0/protocols-presentation.html

Shows how to use `process.uri` with input and output placeholders for file processing.

```plaintext
$(input)

```

```plaintext
$(output)

```

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

### On Track Callback Example

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

Illustrates setting up a callback function that is invoked when a new track begins. The callback receives the metadata associated with the new track.

```liquidsoap
on_track(synchronous=true, (metadata) -> print("New track started with metadata: " + metadata))
```

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

### On Metadata Callback Example

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

Demonstrates how to register a callback function that is triggered whenever new metadata is available for the source. The callback receives the metadata as a list of key-value pairs.

```liquidsoap
on_metadata(synchronous=true, (metadata) -> print("New metadata: " + metadata))
```

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

### Get Video Source Time

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

Get the current time of the video source, based on its assigned clock. Returns a float value representing the time in seconds.

```liquidsoap
video.still_frame(source=canvas('a)).time()
```

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

### Playlist with Cue Points

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

This example shows how to configure a playlist source to use cue-in and cue-out points. The cue points are specified as absolute positions in seconds using the 'annotate' protocol.

```liquidsoap
s = playlist(prefix="annotate:liq_cue_in=\"10.\",liq_cue_out=\"45\":",
             "/path/to/music")
```

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

### Start Web Interface for Interactive Variables

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

Starts a web server accessible at http://localhost:8000/interactive to manage interactive variables through a web browser. This should be called after defining all interactive variables.

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

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

### Create a Playlist Source

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

Configure a source to play a list of URIs from a file, with options for shuffling and 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")
```

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

### Custom Authentication Function Example

Source: https://www.liquidsoap.info/doc-2.4.0/harbor.html

An example of a custom authentication function for harbor sources. This function calls an external script to validate user credentials and returns a boolean indicating access.

```liquidsoap
def auth(args) =
  # Call an external process to check the credentials: The script will return
  # the string "true" of "false".
  #
  # First call the script. Make sure to apply proper escaping of the arguments
  # to prevent command injection!
  ret =
    process.read.lines(
      "/path/to/script --user=#{args.user} --password=#{args.password}"
    )

  # Then get the first line of its output.
  ret = list.hd(default="", ret)

  # Finally returns the boolean represented by the output (bool_of_string can
  # also be used).
  if ret == "true" then true else false end
end
```

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

### Use shortcut settings for common configurations

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

Utilize convenient shortcut operators for frequently used settings like log level, file output, daemon initialization, and audio/video parameters.

```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)
```

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

### Custom Protocol Definition Example

Source: https://www.liquidsoap.info/doc-2.4.0/requests.html

Illustrates how to define a custom protocol, such as `media:`, to look up database records and return file paths.

```liquidsoap
media:123
```

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

### start_duration

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

Returns the start duration.

```APIDOC
## start_duration

### Description
Returns the start duration.

### Signature
`start_duration() -> float`
```

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

### Inline Encoding with Shared FFmpeg Encoders

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

This example demonstrates setting up audio and video sources, muxing them, and then encoding the combined stream using FFmpeg. It shows how to define encoders for FLV and MPEG-TS formats and send them to different outputs.

```liquidsoap
audio_source = single(audio_url)
video_source = single(image)

stream = source.mux.video(video=video_source, audio_source)

stream = ffmpeg.encode.audio_video(
    %ffmpeg(
        %audio(codec="aac", b="128k"),
        %video(codec="libx264", b="4000k")
    ),
    stream
)

flv = %ffmpeg(
    format="flv",
    %audio.copy,
    %video.copy,
)

# Send to one youtube output:
output.youtube.live.rtmp(
    encoder = flv,
    stream,
    ...
)

mpegts = %ffmpeg(
    format="mpegts",
    %audio.copy,
    %video.copy,
)

# And to a hls one:
output.file.hls(
  ["mpegts", mpegts],
  stream,
  ...
)
```

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

### HLS Output with Stream Specifications

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

This example shows how to specify details for each stream being outputted, including bandwidth and codecs. This is crucial for adaptive bitrate streaming. Ensure the specified formats are compatible with HLS clients.

```liquidsoap
output.file.hls(
  directory="/var/www/hls",
  "video", format("libx264", bandwidth=2000000, codecs="avc1.42e01e"),
  "audio", format("aac", bandwidth=128000, codecs="mp4a.40.2")
)
```

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

### rotate.id

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

Gets the identifier of the source.

```APIDOC
## rotate.id

### Description
Gets the identifier of the source.

### Method
`id`

### Parameters
None

### Response
- **return value** (string) - The identifier of the source.
```

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

### source.id

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

Get the identifier of a source.

```APIDOC
## source.id

### Description
Get the identifier of a source.

### Signature
`source.id(source: source('a)) -> string`

### Parameters
* `source` (source('a)) - The source to get the identifier from.

```

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

### Log with Cached Standard Library

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

Example log output when running a new script with a pre-cached standard library, demonstrating faster stdlib retrieval.

```log
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
```

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

### id

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

Get the identifier of the source.

```APIDOC
## id

### Description
Retrieves the unique identifier of the source.

### Method
GET (or equivalent for the specific interface)

### Endpoint
`/sources/{id}/id` (hypothetical)

### Parameters
None

### Response
#### Success Response (200)
- **source_id** (string): The identifier of the source.

### Request Example
(No explicit request example provided in source)

### Response Example
```json
{
  "source_id": "my_audio_source_123"
}
```
```

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

### Full Example: Applying LUFS Loudness Correction

Source: https://www.liquidsoap.info/doc-2.4.0/loudness_normalization.html

A complete example demonstrating the EU R128 standard for loudness normalization. It sets the target LUFS, enables metadata computation, and applies the normalization to a playlist source.

```liquidsoap
settings.lufs.track_gain_target := -23.

# Enable LUFS track gain metadata computation.
enable_lufs_track_gain_metadata()

# Initial source
s = playlist("~/playlist")

# Apply pre-track gain normalization.
s = normalize_track_gain(s)
```

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

### on_start Callback

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

Registers a handler to be executed when the source starts. The handler is a function that takes a boolean indicating synchronicity and returns a unit.

```APIDOC
## on_start Callback

### Description
Call a given handler when source starts.

### Signature
`on_start(synchronous : bool, (() -> unit)) -> unit`

### Parameters
* `synchronous` (bool) - Required - Indicates if the callback should be synchronous.
* `handler` (() -> unit) - Required - The function to execute upon starting.
```

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

### Compact Memory Before Start

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

Triggers the OCaml memory compaction algorithm before script startup. Useful for freeing memory but increases startup time.

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

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

### rotate.time

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

Gets the source's time.

```APIDOC
## rotate.time

### Description
Gets a source's time, based on its assigned clock.

### Method
`time`

### Parameters
None

### Response
- **return value** (float) - The source's current time in seconds.
```

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

### rotate.selected

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

Gets the currently selected source.

```APIDOC
## rotate.selected

### Description
Gets the currently selected source.

### Method
`selected`

### Parameters
None

### Response
- **return value** (source?) - The currently selected source, or `null` if none is selected.
```

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

### Scheduler Example

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

Implements a content scheduler that switches between different sources based on the time of day. Assumes 'night' and 'day' sources are defined.

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

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

### path.dirname

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

Get the directory name of a path.

```APIDOC
## path.dirname

### Description
Get the directory name of a path.

### Type
```
(string) -> string
```

### Arguments
* `(unlabeled)` (of type `string`)
```

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

### Set Source Metadata via HTTP GET Request

Source: https://www.liquidsoap.info/doc-2.4.0/harbor_http.html

Register a GET handler to update a source's metadata using query parameters. This allows external clients to modify source metadata through a simple HTTP request.

```liquidsoap
# s = some source

# The handler
def set_meta(request, response) =
  # Filter out unusual metadata
  meta = metadata.export(request.query)

  # Grab the returned message
  ret =
    if
      meta != []
    then
      s.insert_metadata(meta)
      "OK!"
    else
      "No metadata to add!"
    end

  response.html("<html><body><b>#{ret}</b></body></html>")
end

# Register handler on port 700
harbor.http.register(port=7000, method="GET", "/setmeta", set_meta)
```

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

### Run a Process with Options

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

The `process.run` function executes a shell command. It allows configuration of environment variables, standard input, sandboxing directories, network access, and timeouts. The output and status are accessible via methods.

```liquidsoap
process.run ~stdin:"input data" ~rwdirs:["/tmp"] "my_command"
```

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

### Perform HTTP GET Request

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

Use `http.get` to perform a full HTTP GET request and retrieve the entire response body as a string. It supports custom headers, HTTP version specification, redirection handling, timeouts, and URL normalization.

```liquidsoap
http.get("http://www.liquidsoap.info/")
http.get(~headers=[["User-Agent", "MyClient"]], ~timeout=5.0, "http://www.liquidsoap.info/")
```

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

### Run a Liquidsoap Recipe

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

Use the `output(..)` operator to test short Liquidsoap recipes directly from the command line.

```bash
liquidsoap -v 'output(recipe)'
```

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

### Generate Playlist from Media Library (Basic)

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

Indexes music files in a directory, shuffles them, and outputs a playlist. Uses persistency to avoid re-indexing.

```liquidsoap
m = medialib(persistency="/tmp/medialib.json", "~/music/")
l = m.find(artist_contains="Brassens")
l = list.shuffle(l)
output(playlist.list(l))
```

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

### List Available Codecs for TQI

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

Specify the available codecs for decoding TQI media. This example shows 'eatqi' as an available codec.

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

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

### rotate.elapsed

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

Gets the elapsed time in the current track.

```APIDOC
## rotate.elapsed

### Description
Gets the elapsed time in the current track.

### Method
`elapsed`

### Parameters
None

### Response
- **return value** (float) - The elapsed time in the current track in seconds.
```

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

### Log with Caching

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

Example log output showing reduced typechecking time and loading from cache when caching is enabled.

```log
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
```

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

### peak

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

Get the current value for the peak volume.

```APIDOC
## peak

### Description
Retrieves the current value for the peak volume of the source.

### Method
GET (or equivalent for the specific interface)

### Endpoint
`/sources/{id}/peak` (hypothetical)

### Parameters
None

### Response
#### Success Response (200)
- **peak_volume** (float): The current peak volume, between 0.0 and 1.0.

### Request Example
(No explicit request example provided in source)

### Response Example
```json
{
  "peak_volume": 0.92
}
```
```

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

### elapsed

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

Get the elapsed time in the current track.

```APIDOC
## elapsed

### Description
Returns the elapsed time in the current track.

### Method
GET (or equivalent for the specific interface)

### Endpoint
`/sources/{id}/elapsed` (hypothetical)

### Parameters
None

### Response
#### Success Response (200)
- **elapsed_time** (float): Elapsed time in the current track in seconds.

### Request Example
(No explicit request example provided in source)

### Response Example
```json
{
  "elapsed_time": 60.2
}
```
```

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

### Query Specific Dependency Information

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

Get detailed information about a specific dependency, such as 'soundtouch'. This helps in understanding the functionality provided by optional dependencies.

```bash
opam info soundtouch
```

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

### duration

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

Get an estimation of the duration of the current track.

```APIDOC
## duration

### Description
Provides an estimation of the duration of the current track.

### Method
GET (or equivalent for the specific interface)

### Endpoint
`/sources/{id}/duration` (hypothetical)

### Parameters
None

### Response
#### Success Response (200)
- **track_duration** (float): Estimated duration of the current track in seconds.

### Request Example
(No explicit request example provided in source)

### Response Example
```json
{
  "track_duration": 180.5
}
```
```

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

### output.preferred

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

Configures an audio output source with specified parameters. This function allows for setting an ID, fallibility, and start behavior, and requires a source of audio data.

```APIDOC
## `output.preferred`

### Description

Configures an audio output source with specified parameters. This function allows for setting an ID, fallibility, and start behavior, and requires a source of audio data.

### Arguments

* `id` (string?, optional, defaults to `null`): An identifier for the output source.
* `fallible` (bool, optional, defaults to `false`): Indicates if the source may fail or not be ready to stream.
* `start` (bool, optional, defaults to `true`): Determines if the output should start automatically.
* `source(audio=pcm('A))`: The audio source to be used for the output.

### Methods

* `buffered` (): Returns the length of buffered data.
* `clock`: Accesses the source's clock.
* `duration` (): Estimates the duration of the current track.
* `elapsed` (): Returns the elapsed time in the current track.
* `fallible` (bool): Indicates if a source may fail.
* `id` (): Returns the identifier of the source.
* `insert_metadata` (?new_track : bool, [string * string]): Dynamically inserts metadata into a stream. If `new_track` is true, a new track with the given metadata is inserted.
* `is_active` (): Returns `true` if the source is active.
* `is_ready` (): Indicates if the source is ready to stream.
* `is_started` (): Returns `true` if the output or source is started.
* `is_up` (): Indicates that the source can be asked to produce data at any time.
* `last_metadata` (): Returns the last metadata from the source.
* `log` ({level : (() -> int).{set : (int) -> unit}}): Gets or sets the source's log level (1-5).
* `register_command` (?usage : string?, description : string, string, ((string) -> string)): Registers a server command for this source.
* `remaining` (): Estimates the remaining time in the current track.
* `reset_last_metadata_on_track` ((): bool.{set : (bool) -> unit}): If `true`, resets the source's `last_metadata` on each new track.
* `seek` (float): Seeks forward in seconds.
* `self_sync` (): Checks if the source is controlling its own real-time loop.
* `shutdown` (): Shuts down the output.
* `skip` (): Skips to the next track.
* `start` (): Starts the source or output.
* `stop` (): Stops the source or output.
* `time` (): Gets the source's time based on its assigned clock.

### Callbacks

* `on_frame` (?before : bool, synchronous : bool, (() -> unit)): Calls a handler on frame. If `before` is `true`, the callback is executed before computing the frame.
* `on_metadata` (synchronous : bool, (([string * string]) -> unit)): Calls a handler for each metadata.
* `on_position` (position : {float}, ?remaining : bool, ?allow_partial : bool, synchronous : bool, ((float, [string * string]) -> unit)): Calls a handler on track position. Behavior depends on `remaining` and `allow_partial` flags.
* `on_shutdown` (synchronous : bool, (() -> unit)): Calls a handler when the source shuts down.
* `on_start` (synchronous : bool, (() -> unit)): Calls a handler when the output starts.
* `on_stop` (synchronous : bool, (() -> unit)): Calls a handler when the output stops.
* `on_track` (synchronous : bool, (([string * string]) -> unit)): Calls a handler on track marks.
* `on_wake_up` (synchronous : bool, (() -> unit)): Calls a handler after the source is asked to get ready.
```

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

### buffered

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

Get the length of buffered data for the source.

```APIDOC
## buffered

### Description
Returns the length of buffered data for the source.

### Method
GET (or equivalent for the specific interface)

### Endpoint
`/sources/{id}/buffered` (hypothetical)

### Parameters
None

### Response
#### Success Response (200)
- **buffered_data** (array of [string, float]): Information about the buffered data.

### Request Example
(No explicit request example provided in source)

### Response Example
```json
{
  "buffered_data": [["track1", 1024.5], ["track2", 512.0]]
}
```
```

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

### Displaying Text with video.text.sdl

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

This snippet demonstrates the basic usage of the video.text.sdl source to display text. It shows how to set the text content and optionally customize its appearance.

```liquidsoap
video.text.sdl("Hello, Liquidsoap!")

```

```liquidsoap
video.text.sdl(color=0xff0000, size=24, "Important Message")

```

```liquidsoap
video.text.sdl(font="/path/to/custom.ttf", duration=5.0, "Fading Text")

```

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

### Get error kind

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

Retrieve the kind of an error.

```liquidsoap
error.kind(err)
```

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

### Customizing Font and Size for Text Display

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

This example shows how to customize the font and size of the displayed text using the `font` and `size` arguments of `video.text.native`. Ensure the specified font file exists and is accessible.

```liquidsoap
video.text.native("Custom Font", font="/path/to/your/font.ttf", size=24)
```

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

### Create RTMP Server with FFmpeg

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

Sets up a simple RTMP server using FFmpeg without re-encoding. Ensure FFmpeg is installed and accessible.

```liquidsoap
s = playlist("my_playlist")

enc = %ffmpeg(format = "flv", listen = 1, %audio.copy, %video.copy)

output.url(url="rtmp://host/app/instance", enc, s)
```

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

### profiler.enable

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

Enables the profiler to start recording profiling statistics.

```APIDOC
## profiler.enable

### Description
Record profiling statistics.

### Returns
unit
```

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

### CUE File Format Example

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

This snippet illustrates the standard format of a CUE file generated by Liquidsoap, detailing track information, titles, performers, and timings.

```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
```

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

### rotate.log

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

Gets or sets the source's log level.

```APIDOC
## rotate.log

### Description
Gets or sets the source's log level, from `1` to `5`.

### Method
`log`

### Parameters
None

### Response
- **return value** ({level : (() -> int).{set : (int) -> unit}}) - An object to get or set the log level.
```
Tokens:
Raw