Struct rusty_link::SessionState
source · pub struct SessionState { /* private fields */ }
Expand description
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§
source§impl SessionState
impl SessionState
sourcepub fn new() -> SessionState
pub fn new() -> SessionState
Create a new SessionState 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.
sourcepub fn tempo(&self) -> f64
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.
sourcepub fn set_tempo(&mut self, bpm: f64, at_time: i64)
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.
sourcepub fn beat_at_time(&self, time: i64, quantum: f64) -> f64
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)
sourcepub fn phase_at_time(&self, time: i64, quantum: f64) -> f64
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.
sourcepub fn time_at_beat(&self, beat: f64, quantum: f64) -> i64
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
sourcepub fn request_beat_at_time(&mut self, beat: f64, time: i64, quantum: f64)
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.
sourcepub fn force_beat_at_time(&mut self, beat: f64, time: u64, quantum: f64)
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.
sourcepub fn set_is_playing(&mut self, is_playing: bool, time: u64)
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.
sourcepub fn is_playing(&self) -> bool
pub fn is_playing(&self) -> bool
Is transport playing?
sourcepub fn time_for_is_playing(&self) -> u64
pub fn time_for_is_playing(&self) -> u64
Get the time at which a transport start/stop occurs
sourcepub fn request_beat_at_start_playing_time(&mut self, beat: f64, quantum: f64)
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.