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.

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.

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.

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.

ABLLinkSetIsConnectedCallback

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.

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.

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.

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

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.

ABLLinkIsPlaying

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.

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.