API Reference

ABLLink.h

Copyright 2018, Ableton AG, Berlin. All rights reserved.

Introduction

Cross-device shared tempo and quantized beat grid API for iOS.

Provides zero configuration peer discovery on a local wired or wifi network between multiple instances running on multiple devices. When peers are connected in a Link session, they share a common tempo and quantized beat grid. Optionally, start/stop commands can be shared among a subgroup of peers.

Each instance of the library has its own session state describing a beat timeline and a start/stop state. The timeline starts when the library is initialized and runs until the library instance is destroyed. Clients can reset the beat timeline in order to align it with an app’s beat position when starting playback. The start/stop state does not stop the timeline from progressing but rather describes the users intent to be playing.

The library provides one session state capture/commit function pair for use in the audio thread and one for the main application thread. In general, modifying the Link session state should be done in the audio thread for the most accurate timing results. The ability to modify the Link session state from application threads should only be used in cases where an application’s audio thread is not actively running or if it doesn’t generate audio at all. Modifying the Link session state from both the audio thread and an application thread concurrently is not advised and will potentially lead to unexpected behavior.

Typedefs

ABLLinkRef
Reference to an instance of the library.

ABLLinkSessionStateRef
A reference to a representation of the current Session State.

ABLLinkSessionTempoCallback
Called if Session Tempo changes.

ABLLinkIsEnabledCallback
Called if isEnabled state changes.

ABLLinkIsStartStopSyncEnabledCallback
Called if the user enables or disables Start Stop Sync.

ABLLinkIsConnectedCallback
Called if isConnected state changes.

Functions

ABLLinkNew
Initialize the library, providing an initial tempo.

ABLLinkDelete
Destroy the library instance and cleanup its associated resources.

ABLLinkSetActive
Set whether Link should be active or not.

ABLLinkIsEnabled
Is Link currently enabled by the user?

ABLLinkIsConnected
Is Link currently connected to other peers?

ABLLinkIsStartStopSyncEnabled
Is Start Stop Sync enabled by the user? To allow the user to enable Start Stop Sync a Boolean entry YES under the key ABLLinkStartStopSyncSupported must be added to Info.plist.

ABLLinkSetSessionTempoCallback
Invoked on the main thread when the tempo of the Link session changes.

ABLLinkSetStartStopCallback
Invoked on the main thread when the start/stop state changes.

ABLLinkSetIsEnabledCallback
Invoked on the main thread when the user changes the enabled state of the library via the Link settings view.

ABLLinkSetIsStartStopSyncEnabledCallback
Invoked on the main thread when the user changes the Start Stop Sync enabled state of the library via the Link settings view. To allow the user to enable Start Stop Sync a Boolean entry YES under the key ABLLinkStartStopSyncSupported must be added to Info.plist.

ABLLinkSetIsConnectedCallback
Invoked on the main thread when the isConnected state of the library changes.

ABLLinkCaptureAudioSessionState
Capture the current Link session state from the audio thread.

ABLLinkCommitAudioSessionState
Commit the given session state to the Link session from the audio thread.

ABLLinkCaptureAppSessionState
Capture the current Link session state from the main application thread.

ABLLinkCommitAppSessionState
Commit the given session state to the Link session from the main application thread.

ABLLinkGetTempo
The tempo of the given session state, in Beats Per Minute.

ABLLinkSetTempo
Set the session state tempo to the given bpm value, taking effect at the given host time.

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

ABLLinkTimeAtBeat
Get the host time at which the sound corresponding to the given beat time and quantum reaches the device’s audio output.

ABLLinkPhaseAtTime
Get the phase for a given beat time value on the shared beat grid with respect to the given quantum.

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

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

ABLLinkSetIsPlaying
Set if transport should be playing or stopped.

ABLLinkIsPlaying
Is transport playing?

ABLLinkRequestBeatAtStartPlayingTime
Attempt to map the given beat time to the time transport was started.

ABLLinkSetIsPlayingAndRequestBeatAtTime
Attempt to start playing at the given beat time and host time.

ABLLinkRef

Reference to an instance of the library.

typedef struct ABLLink* ABLLinkRef;

ABLLinkSessionStateRef

A session state represents a timeline and a 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.

typedef struct ABLLinkSessionState* ABLLinkSessionStateRef;

ABLLinkSessionTempoCallback

Called if Session Tempo changes.

typedef void ( *ABLLinkSessionTempoCallback)( double sessionTempo, void *context);

Parameters:

ABLLinkStartStopCallback

Called if Session transport start/stop state changes.

typedef void ( *ABLLinkStartStopCallback)(bool isPlaying, void *context);

Parameters

ABLLinkIsEnabledCallback

Called if isEnabled state changes.

typedef void ( *ABLLinkIsEnabledCallback)( bool isEnabled, void *context);

Parameters:

ABLLinkIsStartStopSyncEnabledCallback

Called if IsStartStopSyncEnabled state changes.

typedef void(*ABLLinkIsStartStopSyncEnabledCallback)( bool isEnabled, void *context);

Parameters:

ABLLinkIsConnectedCallback

Called if isConnected state changes.

typedef void ( *ABLLinkIsConnectedCallback)( bool isConnected, void *context);

Parameters:

ABLLinkNew

Initialize the library, providing an initial tempo.

ABLLinkRef ABLLinkNew( double initialBpm);

ABLLinkDelete

Destroy the library instance and cleanup its associated resources.

void ABLLinkDelete( ABLLinkRef);

ABLLinkSetActive

Set whether Link should be active or not.

void ABLLinkSetActive( ABLLinkRef, bool active);

When Link is active, it advertises itself on the local network and initiates connections with other peers. It is active by default after init.

ABLLinkIsEnabled

Is Link currently enabled by the user?

bool ABLLinkIsEnabled( ABLLinkRef);

The enabled status is only controllable by the user via the Link settings dialog and is not controllable programmatically.

ABLLinkIsConnected

Is Link currently connected to other peers?

bool ABLLinkIsConnected( ABLLinkRef);

ABLLinkIsStartStopSyncEnabled

Is Start Stop Sync currently enabled by the user?

bool ABLLinkIsStartStopSyncEnabled(ABLLinkRef);

ABLLinkSetSessionTempoCallback

Invoked on the main thread when the tempo of the Link session changes.

void ABLLinkSetSessionTempoCallback( ABLLinkRef, ABLLinkSessionTempoCallback callback, void *context);

ABLLinkSetStartStopCallback

Invoked on the main thread when the start/stop state of the Link session changes.

void ABLLinkSetStartStopCallback( ABLLinkRef, ABLLinkStartStopCallback callback, void *context);

ABLLinkSetIsEnabledCallback

Invoked on the main thread when the user changes the enabled state of the library via the Link settings view.

void ABLLinkSetIsEnabledCallback( ABLLinkRef, ABLLinkIsEnabledCallback callback, void *context);

ABLLinkSetIsStartStopSyncEnabledCallback

Invoked on the main thread when the user changes the Start Stop Sync enabled state via the Link settings view.

voidABLLinkSetIsStartStopSyncEnabledCallback( ABLLinkRef, ABLLinkIsStartStopSyncEnabledCallback callback, void *context);

ABLLinkSetIsConnectedCallback

Invoked on the main thread when isConnected state of the library changes.

void ABLLinkSetIsConnectedCallback( ABLLinkRef, ABLLinkIsConnectedCallback callback, void *context);

ABLLinkCaptureAudioSessionState

Capture the current Link session state from the audio thread.

ABLLinkSessionStateRef ABLLinkCaptureAudioSessionState( ABLLinkRef);

This function is lockfree and should ONLY be called in the audio thread. It must not be accessed from any other threads. The returned reference refers to a snapshot of the current session state, so it should be captured and used in a local scope. Storing the session state for later use in a different context is not advised because it will provide an outdated view on the Link state.

ABLLinkCommitAudioSessionState

Commit the given session state to the Link session from the audio thread.

void ABLLinkCommitAudioSessionState( ABLLinkRef, ABLLinkSessionStateRef);

This function is lockfree and should ONLY be called in the audio thread. The given session state will replace the current Link session state. Modifications to the session based on the new session state will be communicated to other peers in the session.

ABLLinkCaptureAppSessionState

Capture the current Link session state from the main application thread.

ABLLinkSessionStateRef ABLLinkCaptureAppSessionState( ABLLinkRef);

This function provides the ability to query the Link session state from the main application thread and should only be used from that thread. The returned session state stores a snapshot of the current Link state, so it should be captured and used in a local scope. Storing the session state for later use in a different context is not advised because it will provide an outdated view on the Link state.

ABLLinkCommitAppSessionState

Commit the session state to the Link session from the main application thread.

void ABLLinkCommitAppSessionState( ABLLinkRef, ABLLinkSessionStateRef);

This function should ONLY be called in the main thread. The given session state will replace the current Link session state. Modifications to the session based on the new session state will be communicated to other peers in the session.

ABLLinkGetTempo

The tempo of the given timeline, in Beats Per Minute.

double ABLLinkGetTempo( ABLLinkTimelineRef);

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.

ABLLinkSetTempo

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

void ABLLinkSetTempo( ABLLinkTimelineRef, double bpm, uint64_t hostTimeAtOutput);

ABLLinkBeatAtTime

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

double ABLLinkBeatAtTime( ABLLinkTimelineRef, uint64_t hostTimeAtOutput, double quantum);

ABLLinkTimeAtBeat

Get the host time at which the sound corresponding to the given beat time and quantum reaches the device’s audio output.

uint64_t ABLLinkTimeAtBeat( ABLLinkTimelineRef, double beatTime, double quantum);

The inverse of ABLLinkBeatAtTime, assuming a constant tempo.
ABLLinkBeatAtTime(tl, ABLLinkTimeAtBeat(tl, b, q), q) == b.

ABLLinkPhaseAtTime

Get the phase for a given beat time value on the shared beat grid with respect to the given quantum.

double ABLLinkPhaseAtTime( ABLLinkTimelineRef, uint64_t hostTimeAtOutput, double quantum);

This function allows access to the phase of a host time as described above with respect to a quantum. The returned value will be in the range [0, quantum].

ABLLinkRequestBeatAtTime

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

void ABLLinkRequestBeatAtTime( ABLLinkTimelineRef, double beatTime, uint64_t hostTimeAtOutput, double quantum);

This function 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.

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 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 only needs to invoke this method to achieve this behavior and should not need to explicitly check the number of peers.

ABLLinkForceBeatAtTime

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

void ABLLinkForceBeatAtTime( ABLLinkTimelineRef, double beatTime, uint64_t hostTimeAtOutput, double quantum);

DANGER: This function should only be needed in certain special circumstances. Most applications should not use it. It is very similar to ABLLinkRequestBeatAtTime 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 time to the given host 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.

ABLLinkSetIsPlaying

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

void ABLLinkSetIsPlaying( ABLLinkSessionStateRef, bool isPlaying, uint64_t hostTimeAtOutput);

ABLLinkIsPlaying

Is transport playing?

boolABLLinkIsPlaying(ABLLinkSessionStateRef); </code>

ABLLinkTimeForIsPlaying

Get the time at which a transport start/stop occurs

uint64_t ABLLinkTimeForIsPlaying(ABLLinkSessionStateRef);

ABLLinkRequestBeatAtStartPlayingTime

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

void ABLLinkRequestBeatAtStartPlayingTime( ABLLinkSessionStateRef, double beatTime, double quantum);

ABLLinkSetIsPlayingAndRequestBeatAtTime

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.

void ABLLinkSetIsPlayingAndRequestBeatAtTime( ABLLinkSessionStateRef, bool isPlaying, uint64_t hostTimeAtOutput, double beatTime, double quantum);

ABLLinkSettingsViewController.h

Copyright 2016, Ableton AG, Berlin. All rights reserved.

ABLLinkSettingsViewController : UIViewController

Settings view controller that provides users with the ability to view Link status and modify Link-related settings. Clients can integrate this view controller into their GUI as they see fit, but it is recommended that it be presented as a popover.

+instance:

Class method that provides an instance of the view controller given an ABLLink instance.

+ (id)instance:(ABLLinkRef)ablLink;

Clients must ensure that the ABLLink instance is not destroyed before the view controller.


Last Updated: Tuesday, August 3, 2016