2.8 Composing with scores

A score turns the instrument into a composition: written, repeatable, refinable. It is a plain text file in data/, one .txt file per score; TAB chooses which one plays. Because the flocking is deterministic, the same score with the same seed gives exactly the same performance every time: change one line, and only that changes. Change the seed for another performance of the same composition.

duration  <s>          # length; the video ends here
fadeout   <s>          # fade over the last seconds
seed      <n>          # same seed = same performance (the take)
title     <title>      # optional; default from the file name
number    <n>          # optional; catalogue number, default from the file name
boids     <n>          # 5 – 400
size      <w> <h>      # video / stage resolution
fps       <n>          # 60, 30, 20 … (the flock always runs at 60 steps/s)
grid      <px>         # beat grid spacing: 40 60 80 120 240; smaller = faster beat
theme     <name>       # visual theme at the start (default: the edition's main theme)
edition   club         # the club edition (2.5); default: classic
bpm       <n>          # club edition: the tempo, 60 – 150 (default 124)
engine    3            # the engine it was written for (3 = current)

# time  what          value      ramp
<t>     <parameter>   <v>        [<s> [linear]]   # glide there over <s> seconds; no ramp = jump
<t>     scatter                                   # throw all boids apart
<t>     beat          on | off                    # the beat layer
<t>     grid          <px>                        # change the beat grid
<t>     boids         <n>                         # add or remove boids to reach this number
<t>     octave        <-2 … +2>                   # move the whole register (0 = as designed)
<t>     pause         on | off                    # freeze the swarm / let it fly on
<t>     theme         <name>                      # visual theme by name
<t>     edition       classic | club              # switch the edition
<t>     bpm           <n>                         # club edition: the tempo
<t>     beat_volume   <%>                         # the volumes of fader 7, 5, 6 (50 = as designed)
<t>     drone_volume  <%>
<t>     note_volume   <%>

Parameters: separation, alignment, cohesion, separation_weight, alignment_weight, cohesion_weight, speed, force. Ramps are eased (gentle start and arrival); linear after the ramp glides at an even rate (recorded takes use it); without a ramp the value jumps.
Not a cue: mute is for listening only. A score always starts from the designed volumes (50 %), whatever free play left.
Engine: every score plays on the current engine. The engine line records what a score was written for; a score written for a newer engine than the sketch gets a warning. Scores follow the instrument as it develops rather than keeping old engines.
Workflow: edit the score file → TAB to choose it → P to listen in real time → edit again → V to render. A new score is a copy of an existing file with a new name; numbering the names (score-01-…, score-02-…) keeps them in order and gives the catalogue number. Or play it: write free play down with Shift+R (2.8.2) and edit that score.

2.8.1 Rendering

Offline and exact: frames are piped straight into ffmpeg (H.264, CRF 16, yuv420p), the audio is written to WAV and joined as AAC 256 kbit/s; +faststart for the web.
Naming: a render is called Swarm Synth V - SSV <number> <title> - Take <seed>.mp4, in either edition (a piece may switch between them): catalogue number (SSV and the number, without leading zeros: SSV 1), title, take. Number and title come from the file name (score-SSV-<nnn>-<title>.txt, three digits there so the files sort) or from number / title lines; the take is the seed, so a piece and take always name exactly one performance. An existing file is never overwritten: “(2)”, “(3)” are added. The HUD shows SSV <number> <title> · Take <seed> during a score.
Speed: 120 s at Full HD / 60 fps renders in about 90 s. Video and audio are both exactly the score's duration.
Determinism: all randomness, the boids' starting directions included, goes through the seeded random(), so the same score and seed give exactly the same performance.
Needs ffmpeg.

2.8.2 Writing a score by playing (Shift+R)

Shift+R in free play starts writing, Shift+R again stops and saves data/rec-<date>-<time>.txt (leaving free play — TAB, P, V, F, Shift+A, Shift+B — also saves it first). The new score is chosen at once: P plays it, V renders it. Score keys: P plays, V renders, Shift+R writes. (Plain r resets the parameters.)

A take starts fresh: the swarm is spawned again from a new seed (the take number), with the settings it had — radii, weights, speed, force, number of boids, beat, grid, octave, the edition, the tempo and the volumes — just as the score will start.
While playing, every change is noted at the simulation step it happened: slider drags and arrow keys, x scatter, + / - boids, k beat, , / . grid, SPACE pause, themes, the octave, 0 the edition, the tempo, the volumes, and the MIDI controller's faders, knobs and buttons (2.7.1). Mute and the view are not noted.
The score is simplified for reading and editing: each parameter's movement is smoothed over 1/4 s (the hand's tremor; never across a jump) and reduced to linear ramps and jumps within a tolerance (2 px for radii, 0.1 for weights and speed, 0.02 for force); actions keep their times. Repeated taps on an arrow key become one ramp; single taps seconds apart stay single short steps; a held, accelerating key becomes a few ramps along its curve.
It replays the gestures, not the exact performance: the swarm is chaotic, so the smallest difference in a value leads to a different flight after a while. That is intended — a score is the composition, P and V are its performances, and the rough hand-played movement comes out smoothed.
To make a catalogue piece: rename it (score-<n>-<title>.txt) and delete its title and number lines; add a fadeout.