Link a note to its source

Click a Timeline note to see where it was written and what transformed it. It also shows where else the same written note sounds, and lets you change it in one step that you can undo.

Select a note#

Click any note in the Timeline's Cycles lanes, or a note glyph in the Map once you have zoomed in far enough to see atoms. The note is now linked. Clicking a note never seeks, auditions or edits anything. A click on empty lane space still seeks, and it also clears the link.

A lane draws two kinds of note. Its pattern preview shows what the pattern will play. While the song runs, it also draws the notes the scheduler actually played (the bright ones under and behind the play-head). Clicking a played note links that one occurrence, and the card says when it played (played at bar 5 beat 2.50) instead of which pass it belongs to. This is how you select a note from a chooser while it runs, because a running chooser draws only what it played. An occurrence belongs to the program that played it. After a Run, the link keeps the written atom and drops the occurrence. The occurrence itself is not lost: the workbench still attributes it to the program that played it, its own atom in that program's own text (see Old runs below).

Hover before you click. With the pointer over a note, its atom and chain show faintly in Source (outlines only, no fill), and its echoes get a faint outline in the lanes. Nothing is selected, and the keyboard stays where it was. Hovering the linked note's own atom adds nothing.

A linked note lights up in several places at once, all in its track's colour:

• Source. Its written atom (c4) gets a filled, underlined band. Each level of its transformation chain gets a bracket: the literal it is written in, then |> fast 2, then |> every 2 rev. Brackets get quieter as they move outward, and they unfold from the atom outward when you select. If the atom is written in an imported module, that module's tab opens. The chain levels written in the song stay lit in the song's own buffer. The editor scrolls the atom into view, but your caret and keyboard stay where they were.
• The same written atom, wherever it sounds. A fast 2 or a shared pattern plays one written atom as several notes. Every one of them is outlined in its own track's colour: in Cycles (a left-to-right sweep) and in the Map. The rest of the song dims.
• The shared pattern inspection. The Wheel, the roll's Result view and the pattern inspector show the same atom selected (Pattern rolls and phrase editing § Shared inspection).
• The Bench notebook. A decl cell shows the same atom and chain brackets. A cell you are typing in shows none until it syncs with the song.

When you first select, a short connector draws from the note to its atom in Source. Reduce motion turns off the connector, the ring and the sweep. The colour highlights still appear.

The card#

A card floats over the Timeline's bottom edge so the lanes never move. It shows:

• the note, its track and its pass;
• how many notes the one written atom produces in each loop of the track (this atom plays 6× per loop);
• the module it is written in, when that isn't the song;
• the chain as breadcrumbs. Hover a step to light that level alone. Click a step to put the caret on it.

Which steps acted on this note. Some steps act on some passes and not others: every 2 rev reverses the phrase on the first of every two passes and leaves it alone on the second. On the card such a step says what it did to the note you picked:

• every 2 rev ✓ means it acted. The tooltip names the pass ("pass 1 of the step's 2-cycle period").
• every 2 rev · skipped means it left the phrase as written for this note. The chip is faded, and the level's bracket in Source is faint and dashed.

every, firstOf, lastOf and a seeded someCyclesBy all report this. The compiler decides each of them when it builds the events, so the answer is exact. A step that never varies by pass (fast 2, rev alone) has nothing to report. A step decided afresh each cycle while the song plays (someCyclesBy without randomCycles, sometimes, degradeBy) is not marked either, because only the running scheduler knows its answer.

The card takes the keyboard when you select:

Drag it. With a note linked, pick it up in the Cycles lanes and drag. While you hold it, the workbench lists every edit the written atom can take:

• respelled up to an octave either way;
• swapped with each neighbouring step of its sequence;
• swapped with one of the four nearest steps and respelled up to a fifth either way, so a diagonal drag moves the note in time and pitch at once (c4 → d4, swaps with e4), still as one edit.

It compiles each edit and finds where it would put this note. Every such place shows as a faint dot. The places are magnified about the note so neighbouring pitches sit at least 6 points apart, however short the lane. The note floats under the pointer, and the place nearest it lights. A label names that edit (c4 → d#4, c4 swaps with e4). When the program plays another pitch than the one written, it says so: under fitScale, e4 → d#4 · plays d4. The whole lane is outlined as it would then play.

Release to write that edit: one Undo step, compiled before it is written, installed or drafted as described under The edit. The note eases into its place (it jumps under Reduce motion). Nothing is written if you release on the note itself, release away from every place, or press Esc.

Because each place comes from compiling the edit, the places follow the chain:

• Under every 2 rev the step written after c4 plays before it, so dragging c4 left lands on swapping it with e4.
• Under fitScale the note reaches only the pitches the scale plays.
• An edit that doesn't compile has no place to land.

Hear it before you drop it. Hold Alt while dragging. The track's pass is rendered as the edit under the pointer would make it, soloed and looped. Move to another place and that one plays; let go of Alt and it stops. Without Alt a drag is silent. The label ends Alt to hear, or hearing while it plays.

A swap moves the whole step, with its @ weight or ! repeat, and the link stays on the moved note. Places appear as they finish compiling. While you wait, the label counts them (leave it · 12/37 edits placed). On a typical song this takes well under a second; a very large song is slower. A note written in an imported module doesn't drag; use the card's keys.

Without a pointer. Tab to a track's name in the Cycles lanes and press L to link its first note; the card then takes the keyboard. On the card, L (or the ≡ chip) opens the same relationships as a list of buttons:

• Written: the atom and its line and column, then each level of the chain with what it did to this note ("every 2 rev — applied (pass 1 of 2)").
• Echoes: every note from the same written atom, with its place in the loop.
• Accepted: the recent occurrences, with their time, velocity, bar and beat.

Tab moves through the rows. ⏎ or a click links that row's note or puts the caret on that level, and Esc returns to the card. A screen reader hears the whole card as one sentence: the note, its track, when it played, where it is written, the chain with each step's decision, and its counts.

On a narrow pane (a phone), the card stacks the edit buttons under the chain instead of beside it.

The +12 / +1 / −1 / −12 and ↩ buttons do the same things. A sample atom (bd) has nothing to transpose, and the card says so.

Edit a step instead of the note. Click a chain chip (fast 2) or press Tab until it lights. That level also lights in Source. The edit keys then change the step's first number instead of the atom:

• ↑/↓ add or subtract one in its last written place (2 → 3, 0.25 → 0.26).
• ⇧↑/⇧↓ double or halve it (fast 2 → fast 4). An odd whole number won't halve, and the card says so.
• A unit is kept (120bpm → 121bpm).
• A step with no number (rev), or whose argument is a pattern (fast !"<1 2>"), refuses. Edit a pattern argument in Source.
• A step written in the song is edited in the song even when the note's atom lives in an imported module.

The same rules apply to every edit: one Undo step, compiled before it is written, and installed or drafted as described below.

How dense would it be?#

Before you change a step's number, you can see what each nearby value would do to the track. Target a step (click its chip, or press Tab until it lights), then press D or the ▮▮ chip.

A list opens above the card with one row per value: three steps down, the value written now, and three steps up, using the same stepping as ↑/↓. Each row says how many notes the track would play per bar with that value:

fast 1 · 3 per bar
fast 2 · 6 per bar · written now
fast 3 · 9 per bar

• The numbers are counted from the code, not heard. For each row the workbench compiles your song with that one number changed and counts the track's notes. It counts one row per frame, so a long song fills the list in over a moment (counting 3 more…).
• The counts read your draft. If you have edits you haven't run, the heading says counted from the draft.
• A value that doesn't compile says so (fast 0 · does not compile) and has no count.
• Click a row, or focus it and press ⏎, to point at it. Pointing changes nothing.
• The button under the list (write fast 3) is the only thing that edits. It makes the same edit as the ↑/↓ keys: checked by the compiler first, one Undo step, and installed or drafted as described under The edit.
• Esc closes the list and gives the keyboard back to the card.

The list never picks a value for you, and it doesn't rank them.

A family is counted only for a step written in the song. A step written in an imported module says so.

When it sounded#

The card has a third row: the last 16 seconds of the linked atom's accepted occurrences. There is one tick per note the scheduler accepted from that written atom, on any track that plays it. Taller ticks are louder, and the newest tick flashes. The card's edge also flashes each time the atom sounds. The row's label counts the occurrences the workbench still holds (4 accepted).

• Click a tick to link that exact occurrence. The card then says where the scheduler placed it (played at bar 7 beat 3.00), from the beat each accepted record carries. A record without a beat shows engine time instead (accepted at 0:14.28), never a guessed bar.
• A dashed break means the transport jumped (a seek or a stop) between two ticks.
• An alert dot means records were lost there. The workbench reads the engine's stream once a frame; if a stall let the engine's 4,096-record ring lap, the count becomes a lower bound (≥12 accepted) rather than a wrong number.
• After a Run, only notes from the new program count. Every record the engine writes names the install run it was scheduled under and the program it came from (the key of that program's semantic index), so counting starts with the first record that names the new program. Until then the row says waiting for the running program…. Older notes never match the new program's sources.

"Accepted" means scheduled, not heard. A muted track, a stolen voice or a silent envelope can still intervene.

In the browser the engine runs in an AudioWorklet, so the history arrives inside the visual bridge's messages. The page polls them only while a note is linked or hovered, or while the Visuals panel is open. Its history therefore starts when you link a note, not when the song started.

Old runs#

The workbench keeps the last 8 programs you ran beside the note history. Each accepted record from one of them stays attributable to that program: its written atom, where it was written, and that program's own text, even after later Runs moved or changed it. Records from a program older than that are reported as unavailable, never read against the program running now. The history holds 16,384 records; records lost to a slow poll or to that cap are kept as marked gaps.

The card draws them. After a Run, the row keeps the occurrences the same written atom had under the programs before, beside the running program's:

• They are hollow ticks; the running program's are filled.
• The label counts them apart: 3 accepted · 6 earlier.
• Hover one to read what the atom read in that run (this atom read c4 then). The list (L) has them under Earlier runs, with the run number.
• They are history. You can't select one as a note of the running program; clicking a list row shows the atom as it is written now.

An earlier program's atom counts as the same written atom only when its position carries exactly onto the linked atom, the same rule a Run uses to keep a link. If you rewrote the phrase between the runs, nothing carries and the card claims nothing from before.

The source lights and the Timeline's played notes follow the same rule around a Run: a frame from the engine names the program it came from, and it lights only that program's text.

The edit#

A transposition rewrites the written atom and nothing else. It keeps the atom's affixes: chord quality, slide, voice tag and velocity. It is one guarded splice, and one Undo step in the buffer that owns the atom. An atom in an imported module is edited in that module's buffer. Editing it changes every note that atom produces: all its echoes, on every track that plays it.

What happens next depends on whether the buffers match what is playing:

• They match. The edit is installed straight away, as if you had pressed ⌘↵, so you hear it. Undo from the card installs the undo the same way.
• You have un-run edits. The edit is written as a draft and nothing installs. The card reads draft · still playing c4 — ⌘↵ to hear, because running now would also install your other edits.

Before a song-buffer edit is written, the whole candidate is compiled. An edit that adds a compile error is refused, and nothing changes. For example, a key constraint can refuse an out-of-scale note.

When the source has moved on#

A link is made against the program that is running, but you can keep editing. Every lit span follows your edits:

• Reformatting or re-indenting maps each span token by token.
• An edit elsewhere shifts the spans around it.
• A chain level that contains an edit keeps its identity and changes size.

The atom is stricter. It survives only if it still reads as the atom this link knows: its running text, or a text the card itself wrote. Undo and Redo qualify. If you type over the atom by hand, or merge it into a neighbour, the link goes stale. Nothing lights, the edit is refused, and the card says changed by hand since it ran — Run to relink. It never lights whatever now sits at the old offsets.

After a Run, the link finds its atom again in the new program. It first looks for the same event on the same track and branch, then for the same track, then for the one other track that plays it. It keeps the link only on an exact match. If the atom is gone, the link clears with a notice. If there is more than one place it could have gone, see the next section.

When a Run finds more than one place#

Sometimes the note can't be placed exactly after a Run, but it hasn't simply gone. Then the link becomes ambiguous. It never guesses. This happens in two cases:

• The track split. The written atom is still there, but its track no longer plays it, and two or more other tracks do. For example, you renamed lead and duplicated it into lead2 and lead3.
• An edit swallowed its position. You rewrote or pasted over the phrase around the atom, so its position is lost. The new phrase has atoms that read the same (c4) in the same declaration. Typing over the atom itself is different: that still goes stale, as described above.

The card turns its alert colour. It lists the candidates as numbered chips (1 · c4 · lead · 7:24, its line and column), Source outlines each one, and Cycles and the Map light their notes. Every edit is refused until you pick one, and the refusal says why: c4 maps onto 2 places in the running song — pick one. To pick, click a chip, press 1–9, or press ←/→ then ⏎. The pick becomes an ordinary linked note, and the edits and the next Run behave exactly as above. If you Run again before picking, the ambiguous link clears with a notice.

Link a region's contents#

Instead of one note, you can link everything written in a region. There are three ways to choose the region:

• A passage of the Timeline. Shift-drag the ruler to select some bars, then press Link contents next to Play selection.
• A source range. Select text in Source (the song or an import tab), then press link selection in the editor's footer.
• A pattern view's range. Drag across the roll's Result view, then press LINK RANGE.

The link holds every written atom in the region and every event that comes from one. Source lights each atom in its track's colour. A source range is also bracketed. Cycles and the Map outline the member notes wherever they sound, including content placed by written-timeline regions. The pattern inspector reports linked region · 6 of these events. Then the card shows:

• the count, for example 8 notes · bars 1–2 · 5 written atoms · 2 tracks;
• the accepted occurrences of every member;
• ← / → to point at a member, and ⏎ (or a click) to link that one note instead.

A passage means its bars. A Timeline passage is a stretch of song time, so it holds what sounds inside it. The lanes and the Map light a member only in the passes that fall in the selected bars, and the card counts only the occurrences the scheduler placed there (2 accepted in these bars). A source range and a pattern range are not tied to song time: their members light in every pass.

Count a passage bar by bar. With a Timeline passage linked, press D or the per bar chip. The list shows each bar of the passage and how many of its notes fall in it. Point at a bar, then press link bar 2 to make that one bar the linked passage. A passage longer than 64 bars is cut at 64, and the list says so. A source range or a pattern range has no bars to count.

A region is read-only. An edit key is refused, with the reason. After a Run, the region asks the new program the same question. A source range asks from wherever the range now sits in your draft. A source range that crosses edits you haven't run yet is refused. Run first.

Large regions are cut, and say so. A region holds at most 256 distinct written atoms, 4,096 events, and 65,536 index records scanned. Past a limit, the region keeps the members in source order up to the limit, never a sample. The card then says cut at the atom cap: 256 of 300.

Track colours for playing steps#

A playing-step light remembers the track that struck it, so Source, the notebook's cells and import tabs all paint a sounding atom in that track's lane colour. The colours come from timeline::lane_color, the same as the Timeline and the Map. A pattern that two tracks share takes the colour of whichever track struck it last.

The Display ▸ Track colour setting (Off / While playing / Always) is described in See a signal on its control.

Limits#

• A single note of region content in a written-timeline song (region/timeline) can't be clicked on its own yet. Link the passage instead, or link a note elsewhere that was written as the same atom.
• A source range or a pattern range is matched by written events, not by played occurrences: a member lights in every pass it sounds in. Only a Timeline passage is limited to its bars.
• A chooser's branches that are not latched are not drawn, so they can't be selected until they play. Then you can pick the played note.
• A generated note (from run, rwalk or a spliced literal) has no written atom. The card shows its chain and offers no edit.
• Echoes follow the compiler's provenance, so they report scheduling, not audibility. A muted, stolen or silent voice still counts.
• Earlier-run occurrences are drawn but can't be selected, and they only appear for a single note, not for a region.
• A step decided while the song plays (sometimes, degradeBy) is not marked on the card as applied or skipped.
• A region can't be edited as a set.
• A note drag reaches the four nearest steps respelled, and farther steps only as written. Two edits that would put the note in the same place resolve to the smaller one.
• The density list counts written notes per bar. It does not render sound, and it does not follow a step that is decided while the song plays (sometimes, degradeBy): those count as written.
• Measured sweeps of a kernel's parameters are the kernel lab's (Measure a kernel case by case).