Struct rusty_link::SessionState

pub struct SessionState { /* private fields */ }

The representation of the current local state of a client in a Link Session.

A session state represents a timeline and the start/stop state. The timeline is a representation of a mapping between time and beats for varying quanta. The start/stop state represents the user intention to start or stop transport at a specific time. Start stop synchronization is an optional feature that allows to share the user request to start or stop transport between a subgroup of peers in a Link session. When observing a change of start/stop state, audio playback of a peer should be started or stopped the same way it would have happened if the user had requested that change at the according time locally. The start/stop state can only be changed by the user. This means that the current local start/stop state persists when joining or leaving a Link session. After joining a Link session start/stop change requests will be communicated to all connected peers.

Implementations

impl SessionState

pub fn new() -> SessionState

Create a new session_state instance.

Thread-safe: yes

Realtime-safe: no

The session_state is to be used with the abl_link_capture… and abl_link_commit… functions to capture snapshots of the current link state and pass changes to the link session.

pub fn tempo(&self) -> f64

The tempo of the timeline, in Beats Per Minute.

This is a stable value that is appropriate for display to the user. Beat time progress will not necessarily match this tempo exactly because of clock drift compensation.

pub fn set_tempo(&mut self, bpm: f64, at_time: i64)

Set the timeline tempo to the given bpm value, taking effect at the given time.

pub fn beat_at_time(&self, time: i64, quantum: f64) -> f64

Get the beat value corresponding to the given time for the given quantum.

The magnitude of the resulting beat value is unique to this Link client, but its phase with respect to the provided quantum is shared among all session peers. For non-negative beat values, the following property holds: fmod(beatAtTime(t, q), q) == phaseAtTime(t, q)

pub fn phase_at_time(&self, time: i64, quantum: f64) -> f64

Get the session phase at the given time for the given quantum.

The result is in the interval [0, quantum]. The result is equivalent to fmod(beatAtTime(t, q), q) for non-negative beat values. This function is convenient if the client application is only interested in the phase and not the beat magnitude. Also, unlike fmod, it handles negative beat values correctly.

pub fn time_at_beat(&self, beat: f64, quantum: f64) -> i64

Get the time at which the given beat occurs for the given quantum.

The inverse of beatAtTime, assuming a constant tempo. beatAtTime(timeAtBeat(b, q), q) === b

pub fn request_beat_at_time(&mut self, beat: f64, time: i64, quantum: f64)

Attempt to map the given beat to the given time in the context of the given quantum.

This function behaves differently depending on the state of the session. If no other peers are connected, then this abl_link instance is in a session by itself and is free to re-map the beat/time relationship whenever it pleases. In this case, beatAtTime(time, quantum) == beat after this funtion has been called.

If there are other peers in the session, this abl_link instance should not abruptly re-map the beat/time relationship in the session because that would lead to beat discontinuities among the other peers. In this case, the given beat will be mapped to the next time value greater than the given time with the same phase as the given beat.

This function is specifically designed to enable the concept of “quantized launch” in client applications. If there are no other peers in the session, then an event (such as starting transport) happens immediately when it is requested. If there are other peers, however, we wait until the next time at which the session phase matches the phase of the event, thereby executing the event in-phase with the other peers in the session. The client application only needs to invoke this function to achieve this behavior and should not need to explicitly check the number of peers.

pub fn force_beat_at_time(&mut self, beat: f64, time: u64, quantum: f64)

Rudely re-map the beat/time relationship for all peers in a session.

DANGER: This function should only be needed in certain special circumstances. Most applications should not use it. It is very similar to requestBeatAtTime except that it does not fall back to the quantizing behavior when it is in a session with other peers. Calling this function will unconditionally map the given beat to the given time and broadcast the result to the session. This is very anti-social behavior and should be avoided.

One of the few legitimate uses of this function is to synchronize a Link session with an external clock source. By periodically forcing the beat/time mapping according to an external clock source, a peer can effectively bridge that clock into a Link session. Much care must be taken at the application layer when implementing such a feature so that users do not accidentally disrupt Link sessions that they may join.

pub fn set_is_playing(&mut self, is_playing: bool, time: u64)

Set if transport should be playing or stopped, taking effect at the given time.

pub fn is_playing(&self) -> bool

Is transport playing?

pub fn time_for_is_playing(&self) -> u64

Get the time at which a transport start/stop occurs

pub fn request_beat_at_start_playing_time(&mut self, beat: f64, quantum: f64)

Convenience function to attempt to map the given beat to the time when transport is starting to play in context of the given quantum. This function evaluates to a no-op if abl_link_is_playing equals false.

pub fn set_is_playing_and_request_beat_at_time(
    &mut self,
    is_playing: bool,
    time: u64,
    beat: f64,
    quantum: f64
)

Convenience function to start or stop transport at a given time and attempt to map the given beat to this time in context of the given quantum.

Trait Implementations

impl Drop for SessionState

fn drop(&mut self)

Executes the destructor for this type.

impl Send for SessionState

impl Sync for SessionState