Create dedicated documentation for Timeline synchronisation

Author: ideoforms

docs/timelines/index.md

@@ -1,11 +1,13 @@
 # Timelines
 
+## About timelines
+
 A `Timeline` schedules and executes events following a clock.
 
 By default, a Timeline creates its own internal clock at a specified tempo:
 
 ```python
-timeline = iso.Timeline(120)
+timeline = Timeline(120)
 timeline.run()
 ```
 
@@ -17,27 +19,7 @@ You can set and query the tempo using the `tempo` property:
 140
 ```
 
-## Sync from clock in
-
-A Timeline can be synchronised from an external MIDI clock:
-
-```python
-midi_in = MidiInputDevice()
-timeline = iso.Timeline(clock_source=midi_in)
-timeline.run()
-```
-
-MIDI `start` and `stop` events will be followed. Querying the timeline's `tempo` will give an estimate of the current bpm based on a moving average.
-
-## Sync to clock out
-
-You can also drive external MIDI clocks from a Timeline, by specifying the `send_clock` argument when creating the output device.
-
-```python
-output_device = iso.MidiOutputDevice(send_clock=True)
-timeline = iso.Timeline(120, output_device=output_device)
-timeline.run()
-```
+To synchronise the timeline with an external device, see [Synchronisation](synchronisation.md).
 
 ## Scheduling events
 
@@ -48,11 +30,11 @@ Scheduling events is done by passing a dict to the `Timeline.schedule()` method,
 # Play a series of 5 notes with random velocities.
 # Delay by 1 beat before playback.
 #--------------------------------------------------------------------------------
-timeline = iso.Timeline(120)
+timeline = Timeline(120)
 timeline.schedule({
-    "note": iso.PSequence([ 60, 67, 72, 77, 84 ], 1),
+    "note": PSequence([ 60, 67, 72, 77, 84 ], 1),
     "duration": 0.5,
-    "amplitude": iso.PWhite(0, 128)
+    "amplitude": PWhite(0, 128)
 }, delay=1)
 timeline.run()
 ```
@@ -66,7 +48,7 @@ To limit the number of iterations of an event, pass the `count` property:
 
 ```
 timeline.schedule({
-    "note": iso.PSeries(0, 1) + 60
+    "note": PSeries(0, 1) + 60
 }, count=4)
 ```
 
@@ -78,5 +60,4 @@ High-precision scheduling in Python is inherently limited by Python's global int
 
 ## Nonlinear time
 
-Time warping and nonlinear time is a work in progress.
-
+Time warping and nonlinear time is a work in progress.

docs/timelines/synchronisation.md

@@ -0,0 +1,54 @@
+# Timelines: Synchronisation with external clocks
+
+isobar can synchronise with external clocks in a few different ways.
+
+- MIDI: [Sync from MIDI clock in](#sync-from-midi-clock-in)
+- MIDI: [Sync to MIDI clock out](#sync-to-midi-clock-out)
+- [Ableton Link Clock](#ableton-link-clock)
+
+## Sync from MIDI clock in
+
+A Timeline can be synchronised from an external MIDI clock:
+
+```python
+midi_in = MidiInputDevice()
+timeline = Timeline(clock_source=midi_in)
+timeline.run()
+```
+
+MIDI transport events will be obeyed:
+
+- `start` starts the timeline playback from time = 0
+- `stop` stops the timeline
+- `continue` resumes playback from wherever it was stopped
+
+When synchronised to an external MIDI clock, querying the timeline's `tempo` will give an estimate of the current bpm based on a moving average.
+
+## Sync to MIDI clock out
+
+You can also drive external MIDI clocks from a Timeline, by specifying the `send_clock` argument when creating the output device.
+
+```python
+output_device = MidiOutputDevice(send_clock=True)
+timeline = Timeline(120, output_device=output_device)
+try:
+    timeline.run()
+except KeyboardInterrupt:
+    # When ctrl-c is pressed, stop the timeline, which sends a MIDI `stop`
+    # transport message to the external device.
+    timeline.stop()
+```
+
+## Ableton Link clock
+
+Playback can be synchronised with Ableton Live or other devices that support [Ableton Link](https://www.ableton.com/en/link/) clocking. Other Link processes on the same computer, or on the local network, are automatically detected.
+
+Ensure that Ableton Live is running on the network with `Link` enabled. Run the below example, and you should hear that it is synchronised with Live's playback.
+
+```
+timeline = Timeline(clock_source="link")
+timeline.schedule({
+    "note": 60
+}, quantize=1)
+timeline.run()
+```