Struct ableton_link::SessionState

pub struct SessionState { /* fields omitted */ }

Representation of a timeline and the start/stop state

A SessionState object is intended for use in a local scope within a single thread - none of its methods are thread-safe. All of its methods are non-blocking, so it is safe to use from a realtime thread. It provides functions to observe and manipulate the timeline and 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.

Methods

impl SessionState

pub fn tempo(&self) -> f64

The tempo of the timeline, in bpm.

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 instance, 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 method is convenient if the client 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 method behaves differently depending on the state of the session. If no other peers are connected, then this 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 method has been called.

If there are other peers in the session, this 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 method 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 only needs to invoke this method 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: i64, quantum: f64)

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

DANGER: This method 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 method 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 method 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: i64)

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

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 isPlaying() equals false.

pub fn set_is_playing_and_request_beat_at_time(
    &mut self,
    is_playing: bool,
    time: i64,
    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.