# Tempo, Link and quantization

## Where tempo comes from

| Source | Range | Notes |
|---|---|---|
| Manual entry | 20 … 300 BPM | Also sets the detector hint |
| Manual while Link is on | 20 … 999 BPM | |
| Tap tempo | 20 … 300 BPM | At least 4 taps |
| Audio input detection | 40 … 240 BPM | Needs input enabled |
| File BPM detection | 40 … 240 BPM | First 120 s of the file |
| Auto BPM | adopts ≥ 0.65 confidence | Must be enabled |
| **Ableton Link** | **20 … 999 BPM** | **Overrides everything** |

Default tempo is **120 BPM**.

**Precedence is simple: Link wins absolutely.** While Link is enabled it overwrites BPM, beat position and
beat phase every tick. Manual tempo edits propose changes to the Link session; Auto BPM
adoption is suppressed while Link is enabled.
Disabling Link leaves your local clock continuous — nothing snaps.

Auto BPM **yields entirely while Link is on**.

## Tap tempo

Available from the header **`Tap`**, the footer **`Tap`**, and **Performance → Tap tempo** (shortcut **T**).

- **Minimum 4 taps** to produce anything; the window keeps up to 8 taps.
- A **3-second gap** resets the series; intervals shorter than 0.12 s are ignored.
- At least **3 intervals must fall within 12%** of the upper median **and** make up **at least 70%** of
  the recent series.
- Fewer than 4 taps does nothing — there is no partial estimate and no error message.

## Meters (time signature)

The header menu offers exactly **4/4, 3/4, 6/8, 7/8 and 5/4**. Default **4/4**.

Numerators may be 1…16 and denominators are restricted to 2, 4, 8 and 16 (only the five above are offered
in the UI). Its help text: *"Time signature. Bar quantization follows this meter."*

## Quantization

The performance bar offers **Off, 1/4 beat, 1 beat, 4 beats, 1 bar**. Default **Off**.

- `1 bar` resolves to `numerator × 4 ÷ denominator`, so it follows the selected meter.
- **Only trigger and restart requests are quantized.** Pause, Resume, Stop and cue jumps are always
  immediate — a surprising but useful property when you are trying to stop something fast.
- A quantized request is deferred to an **absolute target beat**. Because the target is a beat count
  rather than a duration, **a later tempo change keeps the beat count** — your request still lands on
  the right beat, just sooner or later in wall-clock terms.
- Changing quantization or the meter **rebases pending requests** to the new next boundary instead of
  dropping them.
- Whole-column quantized triggers apply to every populated layer at one shared boundary.
- Releasing a held note or key early **cancels** its pending quantized press.

## Resync beat clock

Footer **`Resync`** or **Performance → Resync beat clock** (shortcut **R**) zeroes beat phase and beat
position to the downbeat, rebases beat-unit autopilot deadlines so remaining beat counts survive, and
rebases pending quantized triggers.

It is a **no-op while Link owns the downbeat** — status reads *"Beat grid follows Ableton Link."*
otherwise *"Beat clock resynced."*

## Ableton Link

Enable it at **Settings → Ableton Link → Enable Ableton Link**. It is **off at launch**; the session is
only constructed when you enable it.

**What it syncs: tempo and bar phase.** Nothing else. Specifically **not** implemented: transport
start/stop, play state, or any start/stop beat command — the bridge exposes only session creation,
enable/disable, tempo and capture.

- Peers join automatically; the UI shows peer count and phase.
- The quantum passed to the Link SDK is the composition's beats per bar, so it follows your meter.
- Local BPM edits propose session tempo rather than fighting the session.

## Crossfader

Master scope, **A / B crossfader** slider spanning **−1 … 1**, default 0, plus a **Crossfader curve** picker:
**Linear, Gentle, Fast, Cut**. `Cut` switches hard either side of centre.

Layers then pick their **Crossfader bus**: `None`, `A` or `B`.

- Bus A is multiplied by `1 − weight`, bus B by `weight`.
- **`None` layers are unaffected** by the crossfader at all — this is the common reason a crossfade appears
  to do nothing.
- A layer reaching zero opacity is skipped in rendering.

Note that this **Cut** curve is unrelated to layer transition styles.

## Autopilot

Per layer, from the layer menu's **Autopilot** picker: **Off, Next, Previous, First, Last, Random, Bag**, with an
**Interval** (default 2, minimum 0.1 through the UI) and a **Unit** of **Seconds**, **Beats**, or **Loop count**. Default is **Off**. Loop count changes the numeric label to **Loop count** and rounds entered values upward to a whole number from 1 through 1,000,000. The field displays the committed normalized number.

- Each step triggers one clip in the **active bank**, among non-empty columns. Next and Previous step to
  the next occupied column. First and Last choose the lowest or highest occupied column number in the selected bank, regardless of the currently playing column. Random uses a per-step seeded generator; Bag draws without repeats from a shuffled list that refills when empty. An empty selected bank leaves an already-playing clip intact; a refused target does not silently substitute another clip. Existing clip trigger and restart/resume behavior still applies, including when the endpoint is already active.
- The bag is cleared when you change bank or clear the layer.
- Changing bank does **not** stop other banks' playback.
- The footer's **Previous clip** / **Next clip** buttons force a manual step in an explicit direction
  regardless of the layer's mode.
- The layer's own help text: *"Advance through this layer's clips automatically. Off keeps manual
  triggering."*

Loop count follows the active clip’s transport, including its committed In/Out range. Forward and reverse Loop modes count wraps. Bounce counts two travelled spans from its current baseline, a full out-and-back distance. Once Hold and Once Clear each contribute one completion per activation; a count above one cannot advance within that activation. Static or generated sources with a finite authored timeline count logical transport cycles. Invalid timelines are rejected by normal editing/loading validation.

Pause and waiting for a first source frame contribute no cycles. Seeking, retriggering, replacement, trim/timebase/mode/reverse edits, configuration changes and bank selection reset the relevant count baseline. Speed and BPM changes preserve completed counts; future counts follow the changed actual transport. GPU frame invalidation preserves cycle progress. Only the current active clip counts, not its outgoing transition partner.

After a bank change, an already-playing clip may continue in its original bank; new completed cycles choose the next action in the selected bank. At most one action runs per layer per tick, with no excess cycles carried into a new activation. A refused launch retries after another full count of cycles. Saved sets restore the unit and count, with fresh runtime cycle progress. These loop-count rules do not qualify every broader Autopilot behavior. First/Last use the same selected unit and count; the footer’s explicit Previous/Next directions override them.

Autopilot does not read the crossfader.

## Not verified

- Whether MIDI clock or USB-device tempo sync exists anywhere: no implementation was found, and only
  Link feeds the external tempo clock. A negative was established by reading the MIDI receive path, not by
  exhaustive build-level proof.
- Cross-device Wi-Fi/Ethernet Link behaviour and physical-output phase alignment are outside the
  project's own test scope.
- Real Link transport behaviour with third-party peers.