Source / Liquidsoap

buffer

Create a buffer between two different clocks.

Type:

(?id : string?, ?add_track_mark : bool, ?buffer : float, ?fallible : bool,
 ?max : float, ?register_telnet : bool, ?replay_metadata : bool,
 ?start : bool, source('a)) -> source('a)

Arguments:

• id (of type string?, which defaults to null): Force the value of the source ID.
• add_track_mark (of type bool, which defaults to false): Insert a track mark when the buffer becomes available again.
• buffer (of type float, which defaults to 1.0): Amount of data to pre-buffer, in seconds.
• fallible (of type bool, which defaults to true): Allow the child source to fail.
• max (of type float, which defaults to 10.0): Maximum amount of buffered data, in seconds.
• register_telnet (of type bool, which defaults to true): Register telnet commands for this output.
• replay_metadata (of type bool, which defaults to false): Replay the last metadata when the buffer becomes available again.
• start (of type bool, which defaults to true): Start output as soon as it is available.
• (unlabeled) (of type source('a))

Methods:

• buffer_length (of type () -> int): Buffer length, in main ticks
• buffered (of type () -> [string * float]): Length of buffered data.
• clock (of type clock): The source's clock
• duration (of type () -> float): Estimation of the duration of the current track.
• elapsed (of type () -> float): Elapsed time in the current track.
• fallible (of type bool): Indicate if a source may fail, i.e. may not be ready to stream.
• generate_frame (of type () -> unit): Generate a frame from the source without consuming it. This can be useful in advanced cases where generating a frame is required to trigger some side effect like calculating some metadata before making a decision. You should make sure that the source is available before calling this function and it should only be called inside synchronous streaming loop callback such as on_frame!
• id (of type () -> string): Identifier of the source.
• insert_metadata (of type (?new_track : bool, [string * string]) -> unit): Dynamically insert metadata in a stream. Inserts a new track with the given metadata if new_track is true.
• is_active (of type () -> 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 (of type () -> 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 (of type () -> 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.
• last_metadata (of type () -> [string * string]?): Return the last metadata from the source.
• log (of type {level : (() -> int).{set : (int) -> unit}}): Get or set the source's log level, from 1 to 5.
• register_command (of type (?usage : string?, description : string, string, ((string) -> string)) -> unit): 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.
• remaining (of type () -> float): Estimation of remaining time in the current track.
• reset_last_metadata_on_track (of type (() -> bool).{set : (bool) -> unit}): If true, the source's last_metadata is reset on each new track. If a metadata is present along with the track mark, then it becomes the new last_metadata, otherwise, last_metadata becomes null`.
• seek (of type (float) -> float): Seek forward, in seconds (returns the amount of time effectively seeked).
• self_sync (of type () -> bool): Is the source currently controlling its own real-time loop.
• self_sync_description (of type () -> string)
• skip (of type () -> unit): Skip to the next track.
• time (of type () -> float): Get a source's time, based on its assigned clock.

Callbacks:

• on_frame (of type (?before : bool, synchronous : bool, (() -> unit)) -> unit): Call a given handler on frame. When before is true, callback is executed before computing the frame and after otherwise
• on_frame_checksum (of type (?before : ((string?) -> unit)?, synchronous : bool, ((cache : string?, string) -> unit)) -> unit): Call a given handler Register callbacks to compute frame checksums for debugging purposes. This is useful to track frame content changes through the streaming pipeline. The before callback is called before computing the frame with the checksum of the cached frame (if any, null otherwise). The main callback is called after computing the frame with the checksum of the generated frame and the remaining cache (if any).
• on_metadata (of type (synchronous : bool, (([string * string]) -> unit)) -> unit): Call a given handler to execute on each metadata
• on_position (of type (position : {float}, ?remaining : bool, ?allow_partial : bool, synchronous : bool, ((float, [string * string]) -> unit)) -> unit): Call a given handler on track position. If remaining is false, callback is executed when position in track is more or equal to position. If remaining is true, callback is executed when remaining time in the current track is less or equal to position. Keep in mind that elapsed time is exact while remaining time is always estimated. Remaining time is usually more accurate for file-based sources. When allow_partial is true, if the current track ends before the offset position is reached, callback is still executed
• on_shutdown (of type (synchronous : bool, (() -> unit)) -> unit): Call a given handler to be called when source shuts down
• on_track (of type (synchronous : bool, (([string * string]) -> unit)) -> unit): Call a given handler on track marks
• on_wake_up (of type (synchronous : bool, (() -> unit)) -> unit): Call a given handler to be called after the source is asked to get ready

buffer.adaptative

Create a buffer between two different clocks. The speed of the output is adapted so that no buffer underrun or overrun occurs. This wonderful behavior has a cost: the pitch of the sound might be changed a little.

Type:

(?id : string?, ?averaging : float, ?buffer : float, ?fallible : bool,
 ?limit : float, ?max : float, ?register_telnet : bool, ?resample : bool,
 ?reset : bool, ?start : bool, source(audio=pcm('a), 'b)) ->
source(audio=pcm('a), 'b)

Arguments:

• id (of type string?, which defaults to null): Force the value of the source ID.
• averaging (of type float, which defaults to 30.0): Length of the buffer averaging, in seconds (the time constant of the smoothing to be precise). The greater this is, the less reactive to local variations we are.
• buffer (of type float, which defaults to 1.0): Amount of data to prebuffer, in seconds.
• fallible (of type bool, which defaults to false): Allow the child source to fail, in which case the output will be stopped until the source is available again.
• limit (of type float, which defaults to 1.25): Maximum acceleration or deceleration factor, ie how fast or slow we can be compared to realtime.
• max (of type float, which defaults to 10.0): Maximum amount of buffered data, in seconds.
• register_telnet (of type bool, which defaults to true): Register telnet commands for this output.
• resample (of type bool, which defaults to true): Use proper resampling instead of simply duplicating samples.
• reset (of type bool, which defaults to false): Reset speed estimation to 1 when the source becomes available again (resuming from a buffer underflow).
• start (of type bool, which defaults to true): Start output as soon as it is available.
• (unlabeled) (of type source(audio=pcm('a), 'b))

Methods:

• buffered (of type () -> [string * float]): Length of buffered data.
• clock (of type clock): The source's clock
• duration (of type () -> float): Current buffer duration, in seconds.
• elapsed (of type () -> float): Elapsed time in the current track.
• estimated (of type () -> float): Current smoothed buffer duration, in seconds.
• fallible (of type bool): Indicate if a source may fail, i.e. may not be ready to stream.
• generate_frame (of type () -> unit): Generate a frame from the source without consuming it. This can be useful in advanced cases where generating a frame is required to trigger some side effect like calculating some metadata before making a decision. You should make sure that the source is available before calling this function and it should only be called inside synchronous streaming loop callback such as on_frame!
• id (of type () -> string): Identifier of the source.
• insert_metadata (of type (?new_track : bool, [string * string]) -> unit): Dynamically insert metadata in a stream. Inserts a new track with the given metadata if new_track is true.
• is_active (of type () -> 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 (of type () -> 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 (of type () -> 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.
• last_metadata (of type () -> [string * string]?): Return the last metadata from the source.
• log (of type {level : (() -> int).{set : (int) -> unit}}): Get or set the source's log level, from 1 to 5.
• ratio (of type () -> float): Get the current scaling ratio.
• register_command (of type (?usage : string?, description : string, string, ((string) -> string)) -> unit): 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.
• remaining (of type () -> float): Estimation of remaining time in the current track.
• reset_last_metadata_on_track (of type (() -> bool).{set : (bool) -> unit}): If true, the source's last_metadata is reset on each new track. If a metadata is present along with the track mark, then it becomes the new last_metadata, otherwise, last_metadata becomes null`.
• seek (of type (float) -> float): Seek forward, in seconds (returns the amount of time effectively seeked).
• self_sync (of type () -> bool): Is the source currently controlling its own real-time loop.
• self_sync_description (of type () -> string)
• skip (of type () -> unit): Skip to the next track.
• time (of type () -> float): Get a source's time, based on its assigned clock.

Callbacks:

• on_frame (of type (?before : bool, synchronous : bool, (() -> unit)) -> unit): Call a given handler on frame. When before is true, callback is executed before computing the frame and after otherwise
• on_frame_checksum (of type (?before : ((string?) -> unit)?, synchronous : bool, ((cache : string?, string) -> unit)) -> unit): Call a given handler Register callbacks to compute frame checksums for debugging purposes. This is useful to track frame content changes through the streaming pipeline. The before callback is called before computing the frame with the checksum of the cached frame (if any, null otherwise). The main callback is called after computing the frame with the checksum of the generated frame and the remaining cache (if any).
• on_metadata (of type (synchronous : bool, (([string * string]) -> unit)) -> unit): Call a given handler to execute on each metadata
• on_position (of type (position : {float}, ?remaining : bool, ?allow_partial : bool, synchronous : bool, ((float, [string * string]) -> unit)) -> unit): Call a given handler on track position. If remaining is false, callback is executed when position in track is more or equal to position. If remaining is true, callback is executed when remaining time in the current track is less or equal to position. Keep in mind that elapsed time is exact while remaining time is always estimated. Remaining time is usually more accurate for file-based sources. When allow_partial is true, if the current track ends before the offset position is reached, callback is still executed
• on_shutdown (of type (synchronous : bool, (() -> unit)) -> unit): Call a given handler to be called when source shuts down
• on_track (of type (synchronous : bool, (([string * string]) -> unit)) -> unit): Call a given handler on track marks
• on_wake_up (of type (synchronous : bool, (() -> unit)) -> unit): Call a given handler to be called after the source is asked to get ready

This function is experimental.

request.dump

Immediately encode the whole contents of a request into a file.

Type:

(format('a), string, request, ?ratio : float, ?timeout : float,
 ?sleep_latency : float) -> unit

Arguments:

• (unlabeled) (of type format('a)): Encoding format.
• (unlabeled) (of type string): Name of the file.
• (unlabeled) (of type request): Request to encode.
• ratio (of type float, which defaults to 50.0): Time ratio. A value of 50 means process data at 50x real rate, when possible.
• timeout (of type float, which defaults to 1.0): Stop processing the source if it has not started after the given timeout.
• sleep_latency (of type float, which defaults to 0.1): How much time ahead, in seconds, should we should be before pausing the processing.

This function is experimental.

request.process

Given a request and an optional function to process this request, animate the source as fast as possible until the request is fully processed.

Type:

(request, ?process : ((source('a)) -> source('b)), ?ratio : float,
 ?timeout : float, ?sleep_latency : float) -> unit

Arguments:

• (unlabeled) (of type request): Request to process
• process (of type (source('a)) -> source('b), which defaults to <fun>): Callback to create the source to animate.
• ratio (of type float, which defaults to 50.0): Time ratio. A value of 50 means process data at 50x real rate, when possible.
• timeout (of type float, which defaults to 1.0): Stop processing the source if it has not started after the given timeout.
• sleep_latency (of type float, which defaults to 0.1): How much time ahead, in seconds, should we should be before pausing the processing.

source.duration

Estimation of the duration in the current track.

Type:

(source('a)) -> float

Arguments:

• (unlabeled) (of type source('a))

source.effective

Returns the effective source for the given source that is the source effectively being animated during the current streaming cycle. For instance, this return the currently active source in a switch and etc. The operator is recursive so it is applied through the whole streaming graph until it finds a leaf source.

Type:

(source('a)) -> source('a)

Arguments:

• (unlabeled) (of type source('a))

source.elapsed

Elapsed time in the current track.

Type:

(source('a)) -> float

Arguments:

• (unlabeled) (of type source('a))

source.fallible

Indicate if a source may fail, i.e. may not be ready to stream.

Type:

(source('a)) -> bool

Arguments:

• (unlabeled) (of type source('a))

source.id

Get the identifier of a source.

Type:

(source('a)) -> string

Arguments:

• (unlabeled) (of type source('a))

source.is_ready

Indicate if a source is ready to stream (we also say that it is available), or currently streaming.

Type:

(source('a)) -> bool

Arguments:

• (unlabeled) (of type source('a))

source.methods

Returns the given source decorated with all its methods.

Type:

(source('a)) -> source('a)

Arguments:

• (unlabeled) (of type source('a))

Methods:

• buffered (of type () -> [string * float]): Length of buffered data.
• clock (of type clock): The source's clock
• duration (of type () -> float): Estimation of the duration of the current track.
• elapsed (of type () -> float): Elapsed time in the current track.
• fallible (of type bool): Indicate if a source may fail, i.e. may not be ready to stream.
• generate_frame (of type () -> unit): Generate a frame from the source without consuming it. This can be useful in advanced cases where generating a frame is required to trigger some side effect like calculating some metadata before making a decision. You should make sure that the source is available before calling this function and it should only be called inside synchronous streaming loop callback such as on_frame!
• id (of type () -> string): Identifier of the source.
• insert_metadata (of type (?new_track : bool, [string * string]) -> unit): Dynamically insert metadata in a stream. Inserts a new track with the given metadata if new_track is true.
• is_active (of type () -> 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 (of type () -> 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 (of type () -> 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.
• last_metadata (of type () -> [string * string]?): Return the last metadata from the source.
• log (of type {level : (() -> int).{set : (int) -> unit}}): Get or set the source's log level, from 1 to 5.
• register_command (of type (?usage : string?, description : string, string, ((string) -> string)) -> unit): 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.
• remaining (of type () -> float): Estimation of remaining time in the current track.
• reset_last_metadata_on_track (of type (() -> bool).{set : (bool) -> unit}): If true, the source's last_metadata is reset on each new track. If a metadata is present along with the track mark, then it becomes the new last_metadata, otherwise, last_metadata becomes null`.
• seek (of type (float) -> float): Seek forward, in seconds (returns the amount of time effectively seeked).
• self_sync (of type () -> bool): Is the source currently controlling its own real-time loop.
• self_sync_description (of type () -> string)
• skip (of type () -> unit): Skip to the next track.
• time (of type () -> float): Get a source's time, based on its assigned clock.

Callbacks:

• on_frame (of type (?before : bool, synchronous : bool, (() -> unit)) -> unit): Call a given handler on frame. When before is true, callback is executed before computing the frame and after otherwise
• on_frame_checksum (of type (?before : ((string?) -> unit)?, synchronous : bool, ((cache : string?, string) -> unit)) -> unit): Call a given handler Register callbacks to compute frame checksums for debugging purposes. This is useful to track frame content changes through the streaming pipeline. The before callback is called before computing the frame with the checksum of the cached frame (if any, null otherwise). The main callback is called after computing the frame with the checksum of the generated frame and the remaining cache (if any).
• on_metadata (of type (synchronous : bool, (([string * string]) -> unit)) -> unit): Call a given handler to execute on each metadata
• on_position (of type (position : {float}, ?remaining : bool, ?allow_partial : bool, synchronous : bool, ((float, [string * string]) -> unit)) -> unit): Call a given handler on track position. If remaining is false, callback is executed when position in track is more or equal to position. If remaining is true, callback is executed when remaining time in the current track is less or equal to position. Keep in mind that elapsed time is exact while remaining time is always estimated. Remaining time is usually more accurate for file-based sources. When allow_partial is true, if the current track ends before the offset position is reached, callback is still executed
• on_shutdown (of type (synchronous : bool, (() -> unit)) -> unit): Call a given handler to be called when source shuts down
• on_track (of type (synchronous : bool, (([string * string]) -> unit)) -> unit): Call a given handler on track marks
• on_wake_up (of type (synchronous : bool, (() -> unit)) -> unit): Call a given handler to be called after the source is asked to get ready

source.on_shutdown

Register a function to be called when source is not used anymore by another source.

Type:

(source('a), (() -> unit)) -> unit

Arguments:

• (unlabeled) (of type source('a))
• (unlabeled) (of type () -> unit)

source.remaining

Estimation of remaining time in the current track.

Type:

(source('a)) -> float

Arguments:

• (unlabeled) (of type source('a))

source.seek

Seek forward, in seconds. Returns the amount of time effectively seeked.

Type:

(source('a), float) -> float

Arguments:

• (unlabeled) (of type source('a))
• (unlabeled) (of type float)

source.set_id

Set the id of an operator.

Type:

(source('a), string) -> unit

Arguments:

• (unlabeled) (of type source('a))
• (unlabeled) (of type string)

source.skip

Skip to the next track.

Type:

(source('a)) -> unit

Arguments:

• (unlabeled) (of type source('a))

source.time

Get a source's time, based on its assigned clock

Type:

(source('a)) -> float

Arguments:

• (unlabeled) (of type source('a))