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

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

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

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

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

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

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

### on_start Callback

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

Registers a handler to be called when the source starts.

```APIDOC
## on_start Callback

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

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

### Parameters
* `synchronous` (bool): Indicates if the callback is synchronous.
* `handler` (() -> `unit`): The function to call upon start.
```

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

### on_start

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

Registers a handler to be called when the output stream starts.

```APIDOC
## on_start

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

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

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

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

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

### 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."))
```

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

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

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

### 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())'
```

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

### 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"
}
```
```

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

### Basic VU Meter Usage

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

Integrate the vumeter into your Liquidsoap stream to display audio volume. This example shows a basic setup with default parameters.

```liquidsoap
vumeter(source)
```

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

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

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

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

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

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


```

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

### 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..."))
```

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

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

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

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

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

### register_command

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

Register a server command for this source. Command is registered under the source’s id namespace when it gets up and de-registered when it gets down.

```APIDOC
## register_command

### Description
Register a server command for this source. Command is registered under the source’s id namespace when it gets up and de-registered when it gets down.

### Signature
`register_command(?usage : string?, description : string, string, (() -> string)) -> unit`
```

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

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

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

### Register Server Command Example

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

Shows how to register a custom server command for a source. This allows external control or interaction with the source via its registered command.

```liquidsoap
register_command(description="Print hello world", "hello", (s) -> "Hello world!")
```

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

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

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

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

```

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

### Get Output from FFmpeg Audio Filters

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

Retrieves the audio output from an FFmpeg filter. This method is used to get the processed audio stream from the filter.

```liquidsoap
filter.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))
```

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

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

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

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

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

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

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

### Get Video Source Elapsed Time

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

Get the elapsed time in the current track for a video source. This returns a float value representing the time in seconds.

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

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

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

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

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

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

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

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

### Create ffmpeg.filter.asubboost Instance

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

Initiates an asubboost filter instance independently. Use this to send commands to the filter. Configure parameters like dry/wet gain, boost level, decay, feedback, cutoff, slope, delay, and channels. Requires ffmpeg.filter.graph input.

```liquidsoap
ffmpeg.filter.asubboost.create(?dry=1., ?wet=1., ?boost=2., ?decay=0., ?feedback=0.9, ?cutoff=100., ?slope=0.5, ?delay=20., ?channels="all", graph)
```

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

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

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

### Create FFmpeg Guided Filter

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

Initiates an FFmpeg guided filter independently of its inputs. Use this to send commands to the filter instance. Dynamic inputs are handled by the last two arguments.

```liquidsoap
ffmpeg.filter.guided.create(?radius=3, ?eps=0.01, ?mode=0, ?sub=4, ?guidance=0, ?planes=1, ffmpeg.filter.graph)
```

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

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

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

### Get or Set Source Log Level

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

Control the verbosity of source logging by getting or setting its log level using the `log` method. Levels range from 1 (most verbose) to 5 (least verbose).

```liquidsoap
my_source.log.level.set(3)
```

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

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

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

### Apply Guided FFmpeg Filter

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

Applies the Guided filter to audio and video inputs. This filter supports dynamic inputs and various configuration options for radius, epsilon, mode, subsampling, guidance, and planes.

```ocaml
ffmpeg.filter.guided(~radius=3, ~eps=0.01, ~mode=0, ~sub=4, ~guidance=0, ~planes=1, graph, audio_inputs, video_inputs)
```

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

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

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

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

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

### Configure showcqt Filter with Custom Parameters

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

Demonstrates creating a showcqt filter instance with specific video size, frame rate, and visual parameters for the sonogram and bargraph.

```liquidsoap
ffmpeg.filter.showcqt.create(
    size="1280x720",
    fps="30",
    sono_h=200,
    bar_h=100,
    sono_v="20",
    bar_v="20"
)
```

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

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

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

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

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

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

```

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

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

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

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

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

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

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

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

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

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

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

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

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

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