API Reference

ABLLink.h

Copyright 2016, 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.

Each instance of the library has its own beat timeline that 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 library provides one timeline capture/commit function pair for use in the audio thread and one for the main application thread. In general, modifying the Link timeline should be done in the audio thread for the most accurate timing results. The ability to modify the Link timeline 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 timeline 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.

ABLLinkTimelineRef
A reference to a representation of a mapping between time and beats for varying quanta.

ABLLinkSessionTempoCallback
Called if Session Tempo changes.

ABLLinkIsEnabledCallback
Called if isEnabled state changes.

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?

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

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

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

ABLLinkCaptureAudioTimeline
Capture the current Link timeline from the audio thread.

ABLLinkCommitAudioTimeline
Commit the given timeline to the Link session from the audio thread.

ABLLinkCaptureAppTimeline
Capture the current Link timeline from the main application thread.

ABLLinkCommitAppTimeline
Commit the given timeline to the Link session from the main application thread.

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

ABLLinkSetTempo
Set the timeline 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.

ABLLinkRef

Reference to an instance of the library.

typedef struct ABLLink* ABLLinkRef;

ABLLinkTimelineRef

A reference to a representation of a mapping between time and beats for varying quanta.

typedef struct ABLLinkTimeline* ABLLinkTimelineRef;

ABLLinkSessionTempoCallback

Called if Session Tempo changes.

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

Parameters:

ABLLinkIsEnabledCallback

Called if isEnabled state changes.

typedef void ( *ABLLinkIsEnabledCallback)( 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);

ABLLinkSetSessionTempoCallback

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

void ABLLinkSetSessionTempoCallback( ABLLinkRef, ABLLinkSessionTempoCallback 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);

ABLLinkSetIsConnectedCallback

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

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

ABLLinkCaptureAudioTimeline

Capture the current Link timeline from the audio thread.

ABLLinkTimelineRef ABLLinkCaptureAudioTimeline( 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 Link state, so it should be captured and used in a local scope. Storing the Timeline for later use in a different context is not advised because it will provide an outdated view on the Link state.

ABLLinkCommitAudioTimeline

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

void ABLLinkCommitAudioTimeline( ABLLinkRef, ABLLinkTimelineRef);

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

ABLLinkCaptureAppTimeline

Capture the current Link timeline from the main application thread.

ABLLinkTimelineRef ABLLinkCaptureAppTimeline( ABLLinkRef);

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

ABLLinkCommitAppTimeline

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

void ABLLinkCommitAppTimeline( ABLLinkRef, ABLLinkTimelineRef);

This function should ONLY be called in the main thread. The given timeline will replace the current Link timeline. Modifications to the session based on the new timeline 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.

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