Introduction

Ferrous Lineup is an open source program, written in Rust, for playing songs with a backing band. Type the chords of a song bar by bar, pick a style, and a band (bass, drums and piano, with a guitar, strings, horns or an organ when the style has them) plays it in any key and tempo. Every part the band plays lands on a track of its own, where you can open it in the piano roll, change it by hand, or leave it out and play it yourself.

It is also a way to learn harmony while you play. It names every chord you hear, with its numeral in the key and what it does there, and it knows the other ways music names harmony too: pitch-class sets, twelve-tone rows and Kröpfl’s micromodes.

This book is about the inside: how the code is organized, how it is designed and why, and how the music theory the app knows is written in Rust. It explains the Rust each part uses as it goes, pointing at the real files, so it is also a Rust course built around a real program. You do not need to know Rust before reading; if you know another programming language, you can follow along. To use the app, read the user manual instead: it has no code at all.

How the book is organized

The chapters follow the code, from the program’s shape to how it ships. Each says what a part of the app does, with a link to the manual page on using it; how it is designed and why; the Rust it uses; the files it lives in; and the tests that guard it. Exercises close each part.

At the back are the project file format, a Rust glossary, a music glossary and ideas for what comes next.

Where to start

• To learn Rust: read the parts in order, with the Rust glossary open, and try the exercises at the end of each part. Building it from source gets the code running first.
• To learn how the music theory is programmed: start with Part III, and keep the music glossary close. The theory itself, without code, is taught in the manual.
• To change something: find the part of the app in the contents, read its chapter, and run its tests before and after your change.

How to read it

1. Online, at https://naelolaiz.github.io/ferrous-lineup/.
2. As one PDF, to read offline or print: ferrous-lineup-book.pdf. It has page numbers, the contents at the front, an index of words at the back, and bookmarks for every chapter.
3. As Markdown files, in the repository’s book/src folder, or as a website on your computer with mdbook serve --open in book/.

The book is also in Spanish, at https://naelolaiz.github.io/ferrous-lineup/es/. How the books are built tells how the websites and PDFs are made.

Code links point at the main branch, and the snippets in the chapters are copied from it. Where a snippet leaves lines out, it says so with // ....

Name and license

“Ferrous” means “made of iron”, and rust is iron oxide; a lineup is the players of a band, the band that plays your songs.

Ferrous Lineup is free software, released under the GNU General Public License, version 3 or later.

Building it from source

To use Ferrous Lineup, the ready-made downloads are enough (see the manual’s Installing it). To read its code with this book, change it and run its tests, build it yourself. It takes a few commands on Linux, macOS or Windows.

1. Install Rust

Rust is installed with rustup, a small tool that downloads the compiler (rustc) and the build tool (cargo) and keeps them up to date:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

On Windows, download and run rustup-init.exe from https://rustup.rs instead. Restart the terminal afterwards and check that it worked:

cargo --version
rustc --version

Ferrous Lineup needs Rust 1.95 or newer, as rust-version in the root Cargo.toml says: it uses the 2024 edition of the language (see Editions), if let chains, which arrived in Rust 1.88, and file locks, which arrived in 1.89, and egui and eframe, which draw the window, need 1.95. If your Rust is older, rustup update fixes it.

2. Install the system’s build tools

Rust downloads its own libraries, the crates, by itself, but it needs a linker from your system, and on Linux a few crates talk to libraries that come with the system: ALSA for sound, and X11 or Wayland for windows.

Debian or Ubuntu:

sudo apt install build-essential pkg-config libasound2-dev \
    libxkbcommon-dev libxkbcommon-x11-0 libwayland-dev

Fedora:

sudo dnf install gcc pkgconf-pkg-config alsa-lib-devel \
    libxkbcommon-devel libxkbcommon-x11 wayland-devel

File dialogs use the desktop’s portal, which GNOME and KDE already have; on a bare window manager, install xdg-desktop-portal-gtk. MIDI goes through the ALSA sequencer, which desktop systems load already; if the app’s MIDI menu says MIDI is unavailable, load it with sudo modprobe snd-seq.

macOS: Apple’s command line tools bring the linker and the system libraries:

xcode-select --install

Windows: when rustup-init.exe asks, let it install the Visual Studio Build Tools; Rust uses their linker. Then use the commands below in PowerShell or the Command Prompt.

3. Get the code and run it

Clone the repository (Git comes with the build tools on macOS and Linux; on Windows, install it from https://git-scm.com) and build:

git clone https://github.com/naelolaiz/ferrous-lineup
cd ferrous-lineup
cargo run --release

The first build takes a few minutes, because Cargo compiles every dependency; later builds compile only what changed. --release turns on the optimizations, which audio code needs to keep up. While you work on the code, cargo run alone builds faster, and keeps the console where messages and panics show.

The first time, a window over it offers real instrument sounds; SoundFonts and General MIDI says what it does.

The manual’s The main window says what each part of it does.

4. From the command line

The program takes a few arguments of its own. After cargo run, -- says that what follows is for the program, not for Cargo:

cargo run --release -- my-song.lineup                       # open a project
cargo run --release -- --demos                              # list the demos
cargo run --release -- --trace "Frère Jacques" --out round.tsv   # play a demo headless, note by note
cargo run --release -- --help

--trace is the playback trace: it plays a project or a demo the way File > Export WAV… does, without a window or a sound card, and writes every note it starts to a table.

5. Run the tests

cargo test

runs every test of every crate of the workspace. How the code is tested says what kinds there are and how to run some of them.

6. Build the books

The books are written with mdBook, a Rust tool. Install it once, at the version the workflow uses, then build:

cargo install mdbook --version 0.5.4 --locked
cd book
mdbook serve --open

mdbook serve builds the website, opens it, and builds it again each time you save a page. book-es/, manual/ and manual-es/ work the same way. How the books are built also prints the PDF.

Useful commands

Five crates, and what each one may know

Files: Cargo.toml, the Cargo.toml of each crate in crates/, and crates/lineup-core/src/lib.rs

Ferrous Lineup is one program, ferrous-lineup, built from five Rust crates. This chapter is about how they are split and why: what Cargo is, what a crate, a workspace and a module are, a first small type and the Rust it shows, and the few rules the whole program keeps, each explained in a chapter of its own later in the book. The last section is a map of where each part of the app lives.

Cargo

Cargo is Rust’s build tool and package manager in one. It reads Cargo.toml files, downloads dependencies from crates.io, compiles everything in the right order, runs tests and much more. You will almost never call the compiler rustc directly.

Crates

A crate is Rust’s unit of compilation: one library or one program. Ferrous Lineup is five crates, each with a job it can be tested on its own:

Why five crates instead of one?

• Clear boundaries. lineup-core cannot accidentally depend on the UI, because it does not list eframe as a dependency. The compiler enforces the architecture for us.
• Faster tests. lineup-core depends only on serde and ron, so cargo test -p lineup-core compiles a small crate, not the whole GUI toolkit, the audio drivers or the video encoders.
• Heavy dependencies stay where they are needed. Only lineup-listen decodes audio formats, and only lineup-video compiles the H.264 and MP3 encoders from their C sources.
• Reuse. A command-line renderer or a plugin could be built on top of lineup-core and lineup-audio without touching the window code. The playback trace already works this way: ferrous-lineup --trace plays a song through lineup-audio without opening a window (see The playback trace).

The dependencies only point one way:

lineup-app ──▶ lineup-audio ──▶ lineup-core
    │ ├──────▶ lineup-listen ──▶ lineup-core
    │ └──────▶ lineup-video
    └────────────────────────▶ lineup-core

lineup-video does not know about songs at all: it is given pictures and sound and makes a file of them.

Package name and program name

The program is built from the package lineup-app, but the file Cargo writes is called ferrous-lineup. The two names live in different places of crates/lineup-app/Cargo.toml:

[package]
name = "lineup-app"

[[bin]]
name = "ferrous-lineup"
path = "src/main.rs"

[package] name is how Cargo and other crates refer to the package (cargo test -p lineup-app). [[bin]] describes one program the package builds; the double brackets are TOML for “one entry of a list”, because a package can build several programs. Without a [[bin]] entry, Cargo would name the program after the package, lineup-app. A crate called lineup-core is written lineup_core in use lines, because a hyphen is a minus sign in Rust and cannot be part of a name; Cargo turns the hyphens into underscores for you.

The workspace

A workspace is a group of crates that are built together and share one Cargo.lock file and one target/ output folder. Look at the top-level Cargo.toml:

[workspace]
resolver = "3"
members = [
    "crates/lineup-core",
    "crates/lineup-audio",
    "crates/lineup-listen",
    "crates/lineup-video",
    "crates/lineup-app",
]

[workspace.package]
version = "0.4.0"
edition = "2024"
license = "GPL-3.0-or-later"
repository = "https://github.com/naelolaiz/ferrous-lineup"
rust-version = "1.95"

[workspace.dependencies]
lineup-core = { path = "crates/lineup-core" }
cpal = "0.18"
...

• members lists the crates.
• [workspace.package] holds settings shared by every crate. Each crate then writes version.workspace = true to inherit them, so the version number lives in one place. rust-version is the oldest Rust compiler that can build the code; an older one stops with a clear message instead of a confusing error.
• [workspace.dependencies] pins each dependency version once. A crate says cpal.workspace = true to use it. This keeps all crates on the same version of every library.

A version like "0.18" means “0.18.0 or any newer 0.18.x”. The exact versions Cargo picked are recorded in Cargo.lock, which is committed to the repository so everyone builds exactly the same code.

Editions

edition = "2024" picks the edition of the Rust language. Editions let Rust make small breaking changes every few years without breaking old code: each crate declares which edition it is written in, and crates of different editions work together fine.

Modules

Inside a crate, code is organized in modules. A module is usually one file. In crates/lineup-core/src/lib.rs:

#![allow(unused)]
fn main() {
pub mod pitch;   // loads src/pitch.rs as the module `pitch`
pub mod tempo;   // loads src/tempo.rs as the module `tempo`
// ... and about thirty more

pub use pitch::Note;   // re-export: users can write lineup_core::Note
pub use tempo::Tempo;
}

• mod pitch; tells the compiler to look for pitch.rs next to lib.rs.
• pub makes it visible outside the crate. Without pub, everything in Rust is private by default, visible only inside its own module.
• use brings a name into scope, like import in other languages. pub use also re-exports it.

A module can have modules of its own. harmony.rs declares pub mod chord;, and the compiler finds it in harmony/chord.rs: the folder has the name of the module it belongs to.

lib.rs is the crate root of a library; main.rs is the crate root of a program. Note that the crate is called lineup-core in Cargo.toml but lineup_core in code: Rust code cannot contain - in names, so Cargo replaces it with _.

Doc comments

Comments starting with /// document the item below them, and //! documents the enclosing module or crate. They are written in Markdown. Run cargo doc --open to see them rendered as a browsable website: every type and function in Ferrous Lineup shows up with its explanation.

A first type: Note

Most of lineup-core is small types with functions attached. The smallest, Note in pitch.rs, shows the pieces every later chapter uses. A note is stored as its MIDI number, 0 to 127, middle C being 60:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(from = "u8", into = "u8")]
pub struct Note(u8);
}

Note is a tuple struct: a struct whose fields have no names, read as .0, .1 and so on. With one field that gives a number a type of its own, it is a newtype, which Pitch classes, notes and spelling explains with the rest of the note’s music. The field has no pub, so code outside pitch.rs cannot write Note(200).

Methods: impl blocks

A type’s functions are written apart from its data, in an impl block:

#![allow(unused)]
fn main() {
impl Note {
    /// The lowest MIDI note.
    pub const MIN: Note = Note(0);
    /// The highest MIDI note.
    pub const MAX: Note = Note(127);
    /// Middle C.
    pub const C4: Note = Note(60);
    // ...

    /// Creates a note from a MIDI number, clamping it to 0..=127.
    pub fn new(midi: u8) -> Self {
        Note(midi.min(Self::MAX.0))
    }

    /// The MIDI note number.
    pub fn midi(self) -> u8 {
        self.0
    }
    // ...
}
}

• pub const C4 is an associated constant, written Note::C4.
• Self is the type the impl is for, here Note.
• A function whose first parameter is self is a method, called as note.midi(). One without self, like new, is an associated function, called as Note::new(60). Rust has no constructors; new is only the usual name.
• The last expression of a function, written without ;, is what it returns.
• midi takes self by value, not &self: a Note is Copy, so passing one copies a single byte.

Traits, and derive

A trait is a set of methods a type promises to have, like an interface in other languages. The standard library’s fmt::Display says how a value is written by {} in format! and by to_string():

#![allow(unused)]
fn main() {
impl fmt::Display for Note {
    /// Writes the note as a name and octave, such as `C#4`.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}{}", self.pitch_class(), self.octave())
    }
}
}

So Note::new(61).to_string() is "C#4", and every place that shows a note writes it the same way.

Many traits are the same for every type: comparing field by field, copying, printing for debugging. #[derive(...)] asks the compiler to write those for you:

Serialize and Deserialize come from serde, not from the compiler (Saving). Default is the trait for “a sensible starting value”; Tempo writes its own, 130 BPM:

#![allow(unused)]
fn main() {
impl Default for Tempo {
    fn default() -> Self {
        Tempo { bpm: 130.0 }
    }
}
}

Numbers: as

Rust never changes a number’s type by itself. as says so, as in octave:

#![allow(unused)]
fn main() {
pub fn octave(self) -> i8 {
    (self.0 / 12) as i8 - 1
}
}

self.0 / 12 is a u8, which cannot be negative, and the octave of the lowest notes is -1, so the division’s result becomes an i8 before 1 is taken away. Indexes into a list must be usize, so as usize shows up wherever a number picks an item.

Panics

When a program reaches something that must never happen, such as an index past the end of a list, Rust panics: it stops the thread and prints where and why. assert!, assert_eq!, unwrap and expect panic on purpose when their condition fails, which is how a test fails (How the code is tested). A panic means a mistake in the program, never bad input: a damaged project file is an error the app shows, and tests make sure no file can make the reader panic (Saving).

Rules the whole program keeps

A handful of decisions shape every part of the code. Each has a chapter that shows it at work:

1. The audio thread never waits. The sound card asks for samples every few milliseconds, and a late answer is a click. The audio thread never takes a lock, never allocates memory and never makes a system call; it reads commands from a queue and leaves its messages in others. See Two threads.
2. The window owns the project; the audio thread keeps its own copy of just what it needs to make sound. The two never share data, so they never need a lock.
3. One way to tell the audio thread. Every edit, and every undo and redo, compares the project before and after and sends the differences. There is one piece of code to get right, and it is tested on its own. See Telling the audio thread what changed.
4. Keep copies, not instructions. Undo keeps whole copies of the project, not a list of how to reverse each edit. A copy cannot be reversed wrongly. See Undo and redo.
5. Things that refer to each other by number change together. A clip says “pattern 2”; remove pattern 1, and the clip must now say “pattern 1”. The project owns all its lists and only lets them change through its methods. See The project.
6. A file is a contract with the future. The file format has its own types, separate from the ones the program works with, and a version number that only moves when it must. See Saving.
7. Drawing is separated from changing. A window’s drawing code returns a list of actions, and the app applies them in one place, through the same edit function. See The editors.
8. Music theory as types. Pitch classes, scales, chords and “what is playing” are small Rust types with methods, tested like any other code. See Pitch classes, notes and spelling.
9. Tools are plain functions. Every editing tool takes notes and returns new ones, knowing nothing about windows or mice. See Editing tools as plain functions.
10. Knowledge as data. Styles, rhythms and songs are written as short strings in tables that a person can read and check, in Roman numerals and steps of a bar, so the same table plays in any key and meter. See The library.
11. The band only writes patterns. Trying a style or playing a chord sheet is an ordinary edit, so undo, saving and the audio thread work without knowing the band exists. See How the band plays a chord sheet.
12. The same code, faster than real time. Exporting a WAV file, a video or a trace runs the very same code the sound card uses, on a thread of its own, as fast as the computer can go. See Exporting.

Where each part lives

Every source file starts with a //! comment that says what it is for; this map is made of their first lines. lineup-core:

lineup-audio: engine.rs (the sound card and the audio thread), instrument.rs, drums.rs, timbre.rs, sample.rs and soundfont.rs (the instruments), effects.rs and reverb.rs, levels.rs, metronome.rs, render.rs (playing without a sound card) and trace.rs.

lineup-app: app.rs and the modules in app/ (menus, files, editing, export, MIDI, settings), one module per window (channel_rack.rs, piano_roll.rs, playlist.rs, chord_sheet.rs, harmony_keys.rs, library_browser.rs, lead_sheet.rs, twelve_tone.rs, micromodes.rs, style_editor.rs, ear_training.rs), and the shared pieces: theme.rs, widgets.rs, icons.rs and i18n.rs.

Two threads: the window and the audio

Files: crates/lineup-audio/src/engine.rs, crates/lineup-audio/src/dsp.rs and crates/lineup-app/src/midi.rs

The window and the sound live on different threads. The window thread draws about sixty times a second and answers clicks and keys; the audio thread fills the sound card’s buffer every few milliseconds and must never be late. How the two talk to each other is the most important decision in the program, and it is where Rust’s ownership rules start to earn their keep.

  UI thread (lineup-app)                         Audio thread (lineup-audio)
  ─────────────────────                        ─────────────────────────
  Project (lineup-core)       commands         AudioThread
   ├─ channels       ───────────────────▶       ├─ channels: Vec<ChannelState>
   ├─ patterns                                  │    └─ Instrument + notes
   └─ playlist                                  ├─ Sequencer
                                                │
  views             ◀── playhead, position ─────┤  (atomic numbers)
                                                │
  collect_garbage() ◀── trash queue ────────────┘  old values to free

How digital audio works

Sound is a vibration. A sound card plays it by moving a speaker according to a list of numbers called samples, typically 44,100 or 48,000 per second (the sample rate). Each sample is a value between −1.0 and 1.0, the speaker position at that instant. With two channels (stereo), the samples are interleaved: left, right, left, right…

The sound card does not wait for us. It plays from a small buffer and, every few milliseconds, asks the program to refill it by calling a function we provide: the audio callback. It runs on a separate, high-priority audio thread.

The golden rule of the audio thread

If the callback is late, even once, the buffer runs empty and you hear a click or a gap (an underrun or xrun). So code on the audio thread must never do anything that can take an unpredictable amount of time:

• no locks (a Mutex held by the UI could block it),
• no memory allocation or freeing (Vec::push past its capacity, String, Box::new, or dropping the last owner of any of them),
• no file, network or console I/O (println! included),
• no waiting for other threads.

Everything else in this chapter follows from this rule.

Sending commands with a ring buffer

The UI never changes audio state directly. It sends messages, values of one enum with nearly forty variants. A few of them:

#![allow(unused)]
fn main() {
pub enum Command {
    Play,
    Seek(usize),
    Stop,
    SetTempo(Tempo),
    SetMasterVolume(f32),
    InsertChannel {
        index: usize,
        instrument: Instrument,
        notes: ChannelNotes,
        volume: f32,
        muted: bool,
    },
    RemoveChannel(usize),
    SetNotes {
        pattern: usize,
        channel: usize,
        notes: Vec<NoteEvent>,
    },
    // ...
}
}

This is a Rust enum. Unlike enums in C or Java, each variant can carry its own data: Seek carries a step number, SetNotes a whole list of notes. An enum value is exactly one of its variants.

The messages travel through a ring buffer from the rtrb crate: a fixed-size queue, allocated once, with one writer (the Producer) and one reader (the Consumer). Pushing and popping never lock and never allocate, so the audio thread can read it safely.

#![allow(unused)]
fn main() {
let (command_producer, command_consumer) = rtrb::RingBuffer::new(COMMAND_QUEUE_SIZE);
let (trash_producer, trash_consumer) = rtrb::RingBuffer::new(TRASH_QUEUE_SIZE);
let (live_producer, live_consumer) = rtrb::RingBuffer::new(LIVE_QUEUE_SIZE);
let (midi_producer, midi_consumer) = rtrb::RingBuffer::new(MIDI_OUT_QUEUE_SIZE);
}

RingBuffer::new returns a tuple of two values, which we take apart with a let (a, b) = ... pattern. There are four queues: commands from the UI, values for the UI to free (the trash, below), keys from a MIDI keyboard (MIDI), and messages for MIDI Out channels. For each, one end stays on one thread and the other end is moved to the other.

Ownership makes this safe

Here is where Rust shines. Producer can be used from one thread and Consumer from another, but there is only one of each, and Rust’s ownership rules guarantee it:

• Every value has exactly one owner. When the owner goes away, the value is dropped (freed).
• Assigning or passing a value moves it to the new owner, and the old name can no longer be used.

Once consumer is moved into the audio callback, the UI code physically cannot touch it anymore: the compiler would reject it. Data races are not “unlikely”; they are compile errors.

Commands that carry data

Command is not Copy, because an Instrument can hold an Arc<SampleData> and SetNotes holds a Vec. Moving it through the ring buffer is still fine: the value is moved into the queue’s preallocated slot and out again, with no allocation. The Vec inside was allocated on the UI thread, before it was sent.

When the queue is full

The queue holds 4096 commands, enough for a whole large project. If it is ever full, the UI got ahead of the audio thread, which empties it at the start of every block. send_wait does not drop the command: it yields and tries again, up to a thousand times.

#![allow(unused)]
fn main() {
pub fn send_wait(&mut self, mut command: Command) -> bool {
    for _ in 0..SEND_WAIT_ROUNDS {
        match self.commands.push(command) {
            Ok(()) => return true,
            Err(rtrb::PushError::Full(returned)) => command = returned,
        }
        // A stream that has reported an error will not empty the
        // queue, so waiting for room would only freeze the window.
        if self.problems.broken.load(Ordering::Relaxed) {
            return false;
        }
        std::thread::yield_now();
    }
    false
}
}

push takes the command by value. When the queue is full it gives the command back inside the error, PushError::Full(returned), so the loop can try again with it: nothing is copied and nothing is lost.

Opening the sound card

AudioEngine::start uses the cpal crate, which works on Linux (ALSA), macOS (CoreAudio) and Windows (WASAPI), so the same code runs on all three.

#![allow(unused)]
fn main() {
pub fn start() -> Result<Self, EngineError> {
    let host = cpal::default_host();
    let device = host
        .default_output_device()
        .ok_or(EngineError::NoOutputDevice)?;
    let supported = device
        .default_output_config()
        .map_err(EngineError::Config)?;
    ...
}
}

Option, Result and the ? operator

Rust has no null and no exceptions. Instead:

• Option<T> is either Some(value) or None. default_output_device() returns Option<Device> because there may be no sound card.
• Result<T, E> is either Ok(value) or Err(error). default_output_config() returns Result<SupportedStreamConfig, cpal::Error>.

Both are ordinary enums from the standard library. Because they are types, you cannot forget to handle the missing or failed case: the compiler will not let you use a Device you might not have.

• .ok_or(EngineError::NoOutputDevice) turns an Option into a Result, using our error for the None case.
• .map_err(EngineError::Config) wraps cpal’s error in our own variant. Notice that EngineError::Config is used like a function here: enum variants with data can be called as constructors.
• ? means “if this is an Err, return it from the function right now; otherwise give me the Ok value”. It replaces long chains of if error then return.

A custom error type

#![allow(unused)]
fn main() {
#[derive(Debug)]
pub enum EngineError {
    NoOutputDevice,
    Config(cpal::Error),
    UnsupportedFormat(SampleFormat),
    BuildStream(cpal::Error),
    Play(cpal::Error),
}

impl fmt::Display for EngineError { ... }
impl std::error::Error for EngineError {}
}

One enum lists every way starting the engine can fail. Implementing Display gives each a human-readable message, and the empty impl std::error::Error marks it as a proper error type that works with the rest of the Rust ecosystem. The app turns it into text with err.to_string() and keeps running without sound: every window works, and Edit > Settings… > Audio offers to try again.

Generics: one function, many sample types

Different sound cards want samples in different formats: 32-bit floats, 16-bit integers, and so on. We generate f32 internally and convert at the last moment. Instead of writing the stream code six times, we write it once as a generic function:

#![allow(unused)]
fn main() {
fn build_stream<T>(
    device: &cpal::Device,
    config: StreamConfig,
    mut audio_thread: AudioThread,
    problems: Arc<StreamProblems>,
) -> Result<cpal::Stream, EngineError>
where
    T: SizedSample + FromSample<f32>,
{ ... }
}

T is a placeholder type, and the where clause lists trait bounds: T can be any type that is a cpal sample (SizedSample) and that can be created from an f32 (FromSample<f32>). Inside, T::from_sample(x) does the conversion.

Then start picks the right version with a match:

#![allow(unused)]
fn main() {
let stream = match sample_format {
    SampleFormat::F32 => {
        build_stream::<f32>(&device, config, audio_thread, Arc::clone(&problems))
    }
    SampleFormat::I16 => {
        build_stream::<i16>(&device, config, audio_thread, Arc::clone(&problems))
    }
    ...
    other => return Err(EngineError::UnsupportedFormat(other)),
}?;
}

• match compares a value against patterns and runs the first arm that fits. The compiler checks that every possible value is covered. other is a catch-all pattern that also gives a name to the value.
• build_stream::<f32> (the “turbofish” syntax ::<>) chooses T = f32. The compiler generates a separate, fully optimized copy of the function for each type used. This is called monomorphization, and it means generics cost nothing at run time.
• audio_thread is moved into whichever arm runs. The compiler knows only one arm runs, so this is allowed.

The audio callback is a closure

Inside build_stream:

#![allow(unused)]
fn main() {
let data_callback = move |output: &mut [T], _: &cpal::OutputCallbackInfo| {
    audio_thread.process(output);
};

let error_callback = move |err: cpal::Error| {
    problems.broken.store(true, Ordering::Relaxed);
    if let Ok(mut slot) = problems.error.lock() {
        *slot = Some(err.to_string());
    }
    eprintln!("audio stream error: {err}");
};

device
    .build_output_stream(config, data_callback, error_callback, None)
    .map_err(EngineError::BuildStream)
}

|args| body is a closure: an anonymous function that can use variables from the place where it was written. The move keyword makes the closure take ownership of audio_thread, and with it of the command consumer and everything else the audio thread works with. That is necessary because the closure will run on another thread, long after build_stream has returned, so it cannot just borrow local variables.

cpal’s signature requires the callback to be FnMut(&mut [T], &OutputCallbackInfo) + Send + 'static:

If we tried to share something unsafe, such as a plain reference into the UI’s data, the program would not compile. This is how Rust turns the golden rule of audio into checks the compiler does for you.

&mut [T] is a mutable slice: a borrowed view into the sound card’s buffer, which we fill but do not own.

The error callback is the one place that may lock and print: cpal calls it outside the audio callback, when something goes wrong while the stream runs, such as an unplugged interface. It keeps the newest problem for the window to show.

AudioThread::process

The audio callback hands each buffer to one method. Its outline:

#![allow(unused)]
fn main() {
pub(crate) fn process<T>(&mut self, output: &mut [T])
where
    T: SizedSample + FromSample<f32>,
{
    self.flush_trash();
    self.flush_midi_backlog();
    while let Ok(command) = self.commands.pop() {
        self.apply(command);
    }
    while let Some(message) = self.live_input.as_mut().and_then(|keys| keys.pop().ok()) {
        self.play_live(message);
    }

    for frame in output.chunks_mut(self.output_channels) {
        if self.playing
            && let Some(step) = self.sequencer.tick()
        {
            self.playhead.store(step, Ordering::Relaxed);
            self.start_notes(step);
        }
        // ... mix the channels, the reverb and the metronome ...
    }
    self.send_midi();
}
}

• while let Ok(command) = ... keeps looping as long as the pattern matches, so it drains every waiting command and stops when the queue is empty.
• as_mut turns &mut Option<Consumer> into Option<&mut Consumer>, and and_then asks it for a key only if there is a consumer.
• chunks_mut(channels) splits the buffer into frames, one sample per output channel.
• if a && let Some(x) = b { ... } is a let chain: a condition and a pattern match combined in one if.

The audio thread’s state lives in a struct, AudioThread, instead of loose variables inside the closure. That lets the tests run it with a plain Vec instead of a sound card, and lets the renderer play a song into a file with the same code.

Mixing a frame

For each frame, every channel’s instrument makes one sample. The sample goes through the channel’s effects and volume, and then to the left and right sides as its pan says, and to the reverb as much as its send says (The mixer):

#![allow(unused)]
fn main() {
for channel in &mut self.channels {
    let volume = channel.volume.next_value();
    let sample = channel.effects.process(channel.instrument.next_sample()) * volume;
    ...
    dry[0] += kept * gains[0];
    dry[1] += kept * gains[1];
    send += sample * amount;
}
...
// `tanh` gently rounds off peaks above 1.0 instead of clipping them hard.
let stereo = stereo.map(f32::tanh);
}

• for channel in &mut self.channels iterates over mutable references, so each instrument can advance its own state.
• Mixing is just adding: sounds in the air add up, and so do samples.
• Several loud drums at once can add up past 1.0, which a sound card would clip harshly. tanh (the hyperbolic tangent) passes small values almost unchanged and bends large ones smoothly toward ±1.0, a gentle soft clipper.
• volume.next_value() is a Smoothed value. A volume that jumps makes the speaker jump, which you hear as a click, so it glides toward its target instead: every sample it covers a small fraction of the remaining distance. This is a one-pole smoother, settling in a few milliseconds, too fast to hear as a fade but enough to remove the click.

Room reserved in advance

#![allow(unused)]
fn main() {
channels: Vec::with_capacity(MAX_CHANNELS),
}

A Vec has a length (how many items it holds) and a capacity (how many fit in the memory it has). push allocates only when the length would exceed the capacity. Reserving room for MAX_CHANNELS at startup, on the UI thread, means push on the audio thread never allocates. The UI refuses to add more channels than that, so the limit is never hit. The list of notes waiting to start late, the pattern lengths and the trash backlog are reserved the same way.

Vec::remove(index) shifts the following items down, which never allocates either. That is how RemoveChannel keeps the audio thread’s channel numbers matching the UI’s list.

Freeing memory somewhere else: the trash queue

When a channel is removed or its notes replaced, the old value may hold the last Arc to a sample, or a Vec of notes. Dropping it would free that memory, and freeing can take a lock inside the memory allocator. So the audio thread does not drop it. It sends it back:

#![allow(unused)]
fn main() {
fn set_instrument(&mut self, channel: usize, instrument: Instrument) {
    match self.channels.get_mut(channel) {
        Some(state) => {
            let mut old = std::mem::replace(&mut state.instrument, instrument);
            silence(&mut old, &mut self.midi_out, &mut self.midi_backlog);
            ...
            self.throw_away(Garbage::Instrument(old));
        }
        None => self.throw_away(Garbage::Instrument(instrument)),
    }
}
}

std::mem::replace(&mut place, new) puts new into place and returns what was there. It is how you take a value out of a struct field you only have a &mut to, since Rust never lets a field be left empty. (silence sends the note-offs the old instrument still owes a MIDI Out synth.)

throw_away pushes the value into a second ring buffer, going the other way. Garbage is an enum with a variant for each kind of thing the audio thread gives back: instruments, note lists, channels, songs, tempo lists, phrases, delay lines. The UI thread empties the queue once per frame:

#![allow(unused)]
fn main() {
pub fn collect_garbage(&mut self) {
    while let Ok(garbage) = self.trash.pop() {
        // Dropping a value frees its memory. Here, on the UI thread,
        // that is allowed to take as long as it needs.
        match garbage {
            Garbage::Instrument(instrument) => drop(instrument),
            Garbage::Notes(notes) => drop(notes),
            ...
        }
    }
}
}

drop(value) is a plain function from the prelude that takes ownership and lets the value go out of scope. Writing it explicitly documents the intent: this is where the memory is freed.

A burst of changes between two frames could fill the trash queue. Then throw_away keeps the value in a backlog reserved in advance, and flush_trash moves it into the queue at the start of the next block. Only if the backlog fills too, which means the UI has not collected for a long time, is the value freed on the audio thread, as a last resort.

The playhead: an atomic integer

The UI wants to highlight the step being played. The audio thread knows it. Sharing it through a Mutex would mean the audio thread could wait for the lock, so we use an atomic:

#![allow(unused)]
fn main() {
let playhead = Arc::new(AtomicUsize::new(NO_STEP));
// audio thread:
self.playhead.store(step, Ordering::Relaxed);
// UI thread:
match self.playhead.load(Ordering::Relaxed) { NO_STEP => None, step => Some(step) }
}

An AtomicUsize is a number that the processor can read and write in one indivisible operation, so two threads can use it without a lock and without ever seeing a half-written value. Both threads hold an Arc to the same one (Arc::clone(&playhead) makes the second handle).

Ordering::Relaxed says we only care about this one value, not about the order of other memory writes around it. It is the cheapest ordering and enough for a display. Stricter orderings (Acquire, Release, SeqCst) are for when one value guards access to others.

Rust has no “null” step, so usize::MAX stands for “stopped”, and playhead() turns it into an honest Option<usize> right away so no other code ever sees the magic number.

The position to a fraction of a step, which recording and the views need, is an f64, and there is no atomic float. So it is kept as the bits of the f64 in an AtomicU64: position.to_bits() on the audio thread, f64::from_bits(bits) on the other side. Two numbers that must always be read together, such as the pattern played over the song and its step, share one AtomicU64: one in the high 32 bits, the other in the low ones.

Keeping the stream alive: Drop

#![allow(unused)]
fn main() {
pub struct AudioEngine {
    // The stream is never read, but it must be kept: dropping it stops audio.
    _stream: cpal::Stream,
    commands: rtrb::Producer<Command>,
    trash: rtrb::Consumer<Garbage>,
    playhead: Arc<AtomicUsize>,
    position: Arc<AtomicU64>,
    ...
}
}

The cpal::Stream is never used after it starts, but it must be kept: when a value is dropped, Rust runs its cleanup code (its Drop implementation), and dropping a Stream closes the sound card. Storing it in the engine ties the sound’s lifetime to the engine’s. The leading underscore tells the compiler “I know this field is never read”.

This pattern, where owning a value means owning a resource and dropping it releases the resource, is called RAII. Rust uses it everywhere: files close, locks unlock and memory frees itself when its owner goes away.

When the sound card goes away

An unplugged interface, a changed default device or a sound server that restarted makes the stream report an error. Edit > Settings… > Audio then offers Try again (and Restart audio while the stream runs), which opens the system’s default output device again. The project stays: the whole of it is sent to the fresh audio thread, the MIDI ports are reconnected to the new engine, and a song that was playing seeks back to the same position and plays on.

The old engine is dropped before the new one starts, because a device being reopened cannot still be held by the dead stream.

Two things need care when an audio thread goes away:

Notes sounding on an external synth. A note sent over MIDI Out gets its note-off from the audio thread that played it; when that thread is gone, the note-offs it still owed go with it. The messages go out through a small thread, midi-out, that empties the audio thread’s queue every millisecond. When its queue is abandoned, its loop ends, and before it finishes it sends All Notes Off (controller 123) on all sixteen channels:

#![allow(unused)]
fn main() {
let sender = move || {
    while !messages.is_abandoned() {
        // ... send what the audio thread queued ...
    }
    // The engine is gone, and with it the note offs of notes still
    // sounding on the synth.
    if let Some(connection) = lock(&output).as_mut() {
        for channel in 0..16 {
            let _ = connection.send(&all_notes_off(channel));
        }
    }
};
}

The new engine’s sending thread must not start before the old one has sent its All Notes Off, or that message could cut off the new engine’s first notes. So reconnect_audio waits for the old thread, polling JoinHandle::is_finished for at most 100 ms (in practice about a millisecond, since the old engine is already gone). It does not call join(), which could wait for ever on a MIDI port that hangs: the window must never freeze over a port.

Messages that must arrive. A dropped note-off leaves a note sounding for ever on an external synth, so MIDI Out never drops one. Messages that find the output queue full wait in a reserved backlog and go out at the start of the next block. Removing a channel or replacing an instrument sends its note-offs the same way, and disconnecting a port sends All Notes Off on all sixteen channels before the connection closes.

The playback trace is the opposite case: it records every note for a report, not for the sound, so if its queue fills, the audio thread counts the lost events and carries on. Waiting there would put the trace before the music. When the audio restarts, the trace goes on in the same file: what the old thread left is written, and a new queue is sent to the new thread.

Testing without a sound card

The tests at the bottom of engine.rs build an AudioThread with ring buffers, push commands, render into a Vec<f32> and check the result: a hit at frame 0 and another 6000 frames later at 120 BPM, silence when muted, edits taking effect while playing, and old instruments arriving in the trash. A small Harness struct holds the pieces so each test stays short.

The project: patterns, channels, tracks, clips and markers

Files: crates/lineup-core/src/pattern.rs, crates/lineup-core/src/project.rs, crates/lineup-core/src/playlist.rs and crates/lineup-core/src/arrangement.rs

Everything the user works on is one value of type Project: the channels of the channel rack, the patterns of notes they play, the playlist that arranges the patterns into a song, and the markers along it (sections, tempo, time signature, key and chords). It is also exactly what a project file saves. This chapter is about its shape and the rules it keeps. The windows that edit it are in The editors; how to use them is in the user manual’s Patterns and the playlist.

Notes, steps and patterns

A pattern is a short stretch of music, often one bar, with a row of notes for every channel. A note is a pitch, a start, a length and a velocity, all counted in steps (a sixteenth note each in 4/4):

#![allow(unused)]
fn main() {
pub struct NoteEvent {
    pub pitch: Note,
    /// The step the note starts on, counted from 0.
    pub start: usize,
    /// How many steps the note is held for, at least 1.
    pub length: usize,
    /// How hard the note is played, from 1 to 127 (as in MIDI).
    pub velocity: u8,
    /// How many ticks after the start of its first step the note really
    /// starts, from 0 to [`TICKS_PER_STEP`] - 1.
    pub nudge: u8,
    /// How many ticks before the end of its last step the note really
    /// ends.
    pub trim: u8,
}
}

The channel rack’s step buttons and the piano roll edit the same notes. A step that is “on” is just a note one step long at the default pitch, so is_on asks whether any note starts there:

#![allow(unused)]
fn main() {
pub fn is_on(&self, channel: usize, step: usize) -> bool {
    self.notes(channel).iter().any(|note| note.start == step)
}
}

One kind of data with two views is how pattern-based studios work, and it means the audio thread has a single kind of thing to play. nudge and trim place a note between steps, for music played by a person or imported from a MIDI file; notes on the grid leave them at 0.

Channels: enums with data

#![allow(unused)]
fn main() {
pub enum SampleSource {
    /// One of the drums built into Ferrous Lineup.
    Builtin(Drum),
    /// A WAV file on disk.
    File(PathBuf),
}

pub enum ChannelKind {
    /// Plays a recorded or built-in sound from start to end for each
    /// note, faster for higher notes and slower for lower ones.
    Sampler(SampleSource),
    /// The built-in "Lineup Osc" synthesizer, which can play chords.
    Synth,
    /// Makes no sound itself: sends its notes out through MIDI, on
    /// MIDI channel `channel` (0 to 15, shown as 1 to 16).
    MidiOut { channel: u8 },
}
}

A channel has a name, a volume, a mute switch, a General MIDI instrument number, and a kind. Enums nest: a channel is a sampler, the Lineup Osc or a MIDI Out channel, and a sampler’s sound is either a built-in drum or a file. Each fact is stored once and every combination makes sense. MidiOut { channel: u8 } shows that a variant can also have named fields, like a struct.

PathBuf is the standard type for an owned file path. It is not a String, because file names on some systems are not valid UTF-8 text; path.display() turns one into something printable.

Drum::ALL is an associated constant holding every variant, so menus can loop over the drums instead of listing them by hand.

The shape of a project

A project has a list of patterns, and a playlist that says where each one plays:

#![allow(unused)]
fn main() {
pub struct Project {
    pub mixer: crate::Mixer,
    pub tempo: Tempo,
    pub scale: Scale,
    pub time_signature: TimeSignature,
    pub loose_timing: u8,
    pub swing: u8,
    pub(crate) channels: Vec<Channel>,
    pub(crate) patterns: Vec<Pattern>,
    pub(crate) playlist: Playlist,
    pub(crate) band: Option<Band>,
    // ...where each part came from, and the locked channels
}
}

Every pattern has one row of notes per channel. Pattern-based studios work this way: a pattern is “what every instrument plays during these bars”, so the drums pattern simply has empty rows for the synth.

The playlist is two lists:

#![allow(unused)]
fn main() {
pub struct Track {
    pub name: String,
    pub muted: bool,
    // ...a display height, which older files leave out
}

pub struct Clip {
    pub pattern: usize,
    pub track: usize,
    pub start: usize,
    /// How many times the pattern plays, one after the other.
    pub repeats: usize,
}

pub struct Playlist {
    pub(crate) tracks: Vec<Track>,
    pub(crate) clips: Vec<Clip>,
    // ...sections, a loop region, and time, tempo, key and chord markers
}
}

A clip is three numbers and a repeat count: which pattern, on which track, starting at which step of the song, and how many times the pattern plays. Notice what is not there: the clip’s length. It is the pattern’s length times the number of repeats, so it is worked out when needed:

#![allow(unused)]
fn main() {
pub fn clip_length(&self, clip: &Clip) -> usize {
    self.patterns.get(clip.pattern).map_or(0, Pattern::length) * clip.repeats
}

impl Clip {
    /// A clip that plays its pattern once.
    pub fn new(pattern: usize, track: usize, start: usize) -> Self {
        Clip { pattern, track, start, repeats: 1 }
    }
}
}

Storing the length too would mean two places that must agree. Make the pattern longer and every clip’s stored length would be wrong. A value that can be computed from others is usually better computed than stored. The same goes for the end of a repeated clip: it is start + clip_length, not another field.

Project::playback_arrangement unrolls the repeats into Plays before the song reaches the audio thread (see Sections, repeats and loops below); the clip is the thing you draw, and its repeats is the little “×2” on it.

map_or(0, Pattern::length) says “if there is a pattern, call Pattern::length on it; otherwise use 0”. A method can be passed by name, like a function, when its only argument is self.

Four rules, one gatekeeper

The comment on Project lists the rules it keeps:

• every clip in the playlist refers to a pattern and a track that exist;
• sections are sorted and never overlap, and repeats stay in range.

Most of these rules are about two lists at once, so no single list can keep them. The Project owns all of them, keeps the fields private to lineup-core, and changes them only in methods that keep every rule. Adding a channel adds a row to every pattern:

#![allow(unused)]
fn main() {
pub fn add_channel(&mut self, channel: Channel) -> Option<usize> {
    if self.channels.len() >= MAX_CHANNELS {
        return None;
    }
    self.channels.push(channel);
    for pattern in &mut self.patterns {
        pattern.push_row();
    }
    Some(self.channels.len() - 1)
}
}

Removing a pattern is the interesting one. Clips refer to patterns by their position in the list, so when pattern 1 goes, the clips of pattern 1 must go too, and the clips of patterns 2, 3, 4… must each move down by one so they keep playing the same music:

#![allow(unused)]
fn main() {
pub fn remove_pattern(&mut self, index: usize) -> Option<Pattern> {
    if index >= self.patterns.len() || self.patterns.len() == 1 {
        return None;
    }
    self.playlist.clips.retain(|clip| clip.pattern != index);
    for clip in &mut self.playlist.clips {
        if clip.pattern > index {
            clip.pattern -= 1;
        }
    }
    Some(self.patterns.remove(index))
}
}

• retain keeps the items for which the closure returns true, and drops the others, in one pass.
• for clip in &mut self.playlist.clips gives a mutable reference to each clip in turn, so clip.pattern -= 1 changes the clip in the list.
• The method returns the removed pattern, wrapped in Some. The caller can ignore it, keep it, or check that the removal happened at all.

The test removing_a_pattern_renumbers_its_followers checks the whole story: after removing “Beat”, the five Beat clips are gone, “Chords” is pattern 0, and the fill still plays at bar 8.

For a list of at most 999 patterns (usually far fewer), positions plus one careful method are the simpler choice. It is the kind of trade-off with no single right answer; one of the exercises of this part asks you to think about it.

Handing out &mut Pattern safely

The app needs to change notes in a pattern. Project could copy every Pattern method (toggle, add_note, replace_note…) as a method of its own. Instead it hands out the pattern itself:

#![allow(unused)]
fn main() {
pub fn pattern_mut(&mut self, index: usize) -> Option<&mut Pattern> {
    self.patterns.get_mut(index)
}
}

Is that safe? With &mut Pattern, could the app add a row and break the “one row per channel” rule? No, because of how the row methods are declared in pattern.rs:

#![allow(unused)]
fn main() {
pub(crate) fn push_row(&mut self) { ... }
pub(crate) fn remove_row(&mut self, channel: usize) { ... }
}

pub(crate) means “public inside this crate only”. project.rs can call them, because it is in lineup-core; lineup-app cannot, even with a &mut Pattern in its hands. Every method lineup-app can call keeps the row count as it is. Privacy in Rust is about modules and crates, not about who holds a reference, and that lets one type give out a reference to another without giving away its rules.

On the app side, every pattern edit goes through one small helper:

#![allow(unused)]
fn main() {
fn edit_pattern(&mut self, label: &'static str, change: impl FnOnce(&mut Pattern)) {
    let index = self.pattern;
    self.edit(label, |project| {
        if let Some(pattern) = project.pattern_mut(index) {
            change(pattern);
        }
    });
}

// For example:
RackAction::ToggleStep { channel, step } => {
    self.edit_pattern("change steps", |pattern| {
        pattern.toggle(channel, step);
    });
}
}

• impl FnOnce(&mut Pattern) accepts any closure that takes a pattern. FnOnce is the most accepting of the three closure traits: the closure only has to be callable once, so it may even move values it captured.
• self.edit(label, ...) is the one function every change to the project goes through. It keeps the change for undo and tells the audio thread what changed (Undo and redo, Telling the audio thread what changed). label is what Edit > Undo will say.

Names, and impl Into<String>

Patterns have names. The constructor takes the name first:

#![allow(unused)]
fn main() {
pub fn new(name: impl Into<String>, channels: usize, length: usize) -> Self {
    Pattern {
        name: name.into(),
        color: 0,
        time: None,
        player: None,
        length: length.clamp(1, MAX_STEPS),
        rows: vec![Vec::new(); channels],
    }
}
}

impl Into<String> accepts anything that can be turned into a String: Pattern::new("Beat", 5, 16) with a &str, or Pattern::new(format!("Pattern {n}"), 5, 16) with a String, without the caller writing .to_string(). Inside, name.into() does the conversion (for a String, it just moves it).

name is a public field while length and rows are private. Mixing is fine in Rust: name has no rule to keep, so there is no reason to hide it behind methods. color, time and player say which colour the pattern is drawn in, the time signature it was written in, and which of the band’s players wrote it, if one did.

Cloning a pattern uses Pattern’s Clone derive:

#![allow(unused)]
fn main() {
pub fn clone_pattern(&mut self, index: usize) -> Option<usize> {
    let mut copy = self.patterns.get(index)?.clone();
    copy.name = format!("{} copy", copy.name);
    // A copy is yours, not the band's.
    copy.player = None;
    self.push_pattern(copy)
}
}

.clone() copies the whole pattern, every row and every note, so the copy and the original never share anything; the test cloned_patterns_are_independent checks that changing one leaves the other alone. The ? after get(index) returns None from the function straight away if there is no such pattern.

No two notes in the same place

add_note refuses to add a note in the same place as another. replace_note, used when dragging, must refuse too, or one note could be dragged exactly on top of another, so it checks every note except the one being replaced:

#![allow(unused)]
fn main() {
let duplicate = row
    .iter()
    .enumerate()
    .any(|(other_index, other)| other_index != index && other.same_place(&note));
}

So “no two notes of the same pitch start at the same moment” is true for every pattern, and loading a file can insist on it. same_place compares the pitch, the step and the nudge, so two notes that start a few ticks apart are still two notes.

How long is the song?

The song ends where its last clip ends, rounded up to a whole bar:

#![allow(unused)]
fn main() {
pub fn song_length(&self) -> usize {
    let clips = self
        .playlist
        .clips
        .iter()
        .map(|clip| clip.start + self.clip_length(clip));
    let sections = self.playlist.sections.iter().map(Section::end);
    let end = clips.chain(sections).max().unwrap_or(0);
    self.meter().round_up_to_bar(end)
}
}

max returns an Option, because an empty list has no maximum; unwrap_or(0) turns “no clips” into a length of 0. chain joins the two iterators, because a song can end with a clip or with a section that has no clip at its very end. self.meter() knows the time signature, and its round_up_to_bar is division that rounds up: in 4/4, 17 steps is 17.div_ceil(16) = 2 bars.

Where is a pattern, while the song plays?

In song mode the audio thread reports a step of the song. The channel rack and the piano roll show one pattern, so they need to know which step of that pattern is playing, if any:

#![allow(unused)]
fn main() {
pub fn pattern_step_in_song(&self, pattern: usize, song_step: usize) -> Option<usize> {
    self.playlist
        .audible_clips()
        .filter(|clip| clip.pattern == pattern)
        .find_map(|clip| self.step_in_clip(&clip, song_step))
}

/// The step of its pattern the clip plays on song step `step`.
fn step_in_clip(&self, clip: &Clip, step: usize) -> Option<usize> {
    let pattern_length = self.patterns.get(clip.pattern).map_or(0, Pattern::length);
    let end = clip.start + pattern_length * clip.repeats;
    (clip.start..end)
        .contains(&step)
        .then(|| (step - clip.start) % pattern_length)
}
}

Read it as a sentence: of the clips that can be heard, take those of this pattern, find the first one that covers this song step, and tell me how far into the clip that step is. The % pattern_length is what makes a repeated clip start its pattern again each time round: a 16-step clip that repeats at song step 16 is on pattern step 0 there. audible_clips skips clips on muted tracks:

#![allow(unused)]
fn main() {
pub fn audible_clips(&self) -> impl Iterator<Item = Clip> + '_ {
    self.clips
        .iter()
        .copied()
        .filter(|clip| self.tracks.get(clip.track).is_some_and(|track| !track.muted))
}
}

.copied() turns an iterator of &Clip into one of Clip. That works because Clip is Copy (three numbers), and it means callers get plain values instead of references into the playlist.

The starting song

Project::demo builds an eight-bar song, which many tests play, with the same methods the app uses:

#![allow(unused)]
fn main() {
for bar in [0, 2, 4, 6] {
    project.add_clip(Clip::new(chords, chord_track, bar * 16));
}
for bar in 2..7 {
    project.add_clip(Clip::new(beat, drum_track, bar * 16));
}
project.add_clip(Clip::new(fill, drum_track, 7 * 16));
}

2..7 is a range from 2 up to, but not including, 7: bars 3 to 7 when counting from 1, as the ruler does. The fill takes the place of the beat in bar 8. File > New beat starts from Project::template instead: the drum kit and a Lineup Osc, with no notes and one track. File > New starts from Project::with_band, an empty chord sheet with a band (How the band plays a chord sheet).

Sections, repeats and loops

A song has more shape than its clips: an intro, a verse, a chorus heard twice, a beat that loops for eight bars. The playlist keeps three more things for it:

• Sections: named stretches of the song (Intro, Verse, Chorus…) in a strip above the bar numbers. A section can be played several times in a row: it is drawn once and marked “×2”.
• Clip repeats: a clip can play its pattern again and again, like stretching a pattern clip in other pattern-based studios.
• A loop region: song mode can loop just one part of the song.

Sections do not own clips. A section is only a name and a range of steps: whatever clips lie under it are part of it. Deleting a section leaves the clips alone.

Two kinds of step

Here is the one idea that makes everything else simple. Once a section can repeat, the playlist as drawn and the song as played are no longer the same length:

timeline:   | Intro | Chorus ×2 | Outro |
song:       | Intro | Chorus | Chorus | Outro |

So the code talks about two kinds of step:

• a timeline step is a place in the playlist, as drawn;
• a song step is a moment in the song, as heard.

Project::song_length is the length of the timeline. Arrangement is the song as heard:

#![allow(unused)]
fn main() {
pub struct Arrangement {
    /// The pieces of patterns to play, in song steps.
    pub plays: Vec<Play>,
    /// The stretches of the timeline, in the order they play.
    pub passes: Vec<Pass>,
    /// How long the song is, in song steps.
    pub length: usize,
}

pub struct Play {
    pub pattern: usize,
    pub start: usize,  // the song step it starts on
    pub skip: usize,   // how far into the clip it starts
    pub length: usize, // how many steps it lasts
}
}

A Pass says “timeline steps 32 to 63 play at song steps 64 to 95, and this is round 2 of 2 of section 1”. A Play says “play pattern 3 from song step 64 for 32 steps, starting 0 steps into it”. The pattern loops for as long as the Play lasts, so a clip repeated three times is one Play three patterns long. skip is not zero when a section or the loop region starts halfway through a clip.

Project::arrangement() builds it for the whole song (the exports use it), and Project::playback_arrangement() for what song mode plays: the loop region if there is one, the whole song if not.

Building the arrangement

arrange in arrangement.rs cuts the timeline into pieces at section edges. Sections play repeats times; the gaps between them play once:

#![allow(unused)]
fn main() {
fn pieces(project: &Project, from: usize, to: usize)
    -> Vec<(usize, usize, Option<usize>, usize)>
{
    let mut pieces = Vec::new();
    let mut cursor = from;
    for (index, section) in project.playlist().sections().iter().enumerate() {
        if section.end() <= cursor || section.start >= to {
            continue;
        }
        if section.start > cursor {
            pieces.push((cursor, section.start, None, 1)); // a gap
        }
        let start = section.start.max(cursor);
        let end = section.end().min(to);
        pieces.push((start, end, Some(index), section.repeats));
        cursor = end;
    }
    if cursor < to {
        pieces.push((cursor, to, None, 1));
    }
    pieces
}
}

This only works because sections are kept sorted and never overlapping. That is a rule, so, as with clips, the list is private and only Project’s methods change it. add_section and set_section check the rule and refuse a section that would break it; insert_section keeps the order with partition_point, a binary search that returns the first place where the condition stops being true:

#![allow(unused)]
fn main() {
let index = sections.partition_point(|other| other.start < section.start);
sections.insert(index, section);
}

Then, for each piece and each time round, every clip that overlaps the piece adds a Play for the part of it inside the piece. max and min clamp the clip to the piece:

#![allow(unused)]
fn main() {
let begin = clip.start.max(piece_from);
let end = clip_end.min(piece_to);
if begin < end {
    arrangement.plays.push(Play {
        pattern: clip.pattern,
        start: start + (begin - piece_from),
        skip: begin - clip.start,
        length: end - begin,
    });
}
}

The audio thread knows nothing of sections

Command::SetSong carries the arrangement’s plays, and all the audio thread does with them is a remainder:

#![allow(unused)]
fn main() {
pub fn pattern_step(&self, step: usize, pattern_length: usize) -> Option<usize> {
    if pattern_length == 0 || !(self.start..self.end()).contains(&step) {
        return None;
    }
    Some((self.skip + step - self.start) % pattern_length)
}
}

% wraps the step around the pattern, which is all that “repeat” means. Everything about names, rounds and loops stays in lineup-core, where it can be tested without a sound card. The audio thread stays small, and it allocates nothing: the Vec<Play> is built on the UI thread, and the old one is sent back to be freed there.

The WAV export and the MIDI export use the same Arrangement, so all three agree on what the song is. The MIDI writer needs the opposite question: on which song steps does a note at pattern step 2 play? That is Play::song_steps_of, which uses an iterator with step_by:

#![allow(unused)]
fn main() {
(first..self.length)
    .step_by(pattern_length.max(1))
    .map(move |offset| self.start + offset)
}

Back from the song to the playlist

The audio thread counts song steps, so the playhead it reports is a song step. To draw it, the app turns it back into a timeline step with the arrangement’s passes:

#![allow(unused)]
fn main() {
fn song_position(&self) -> Option<(usize, Pass)> {
    if self.mode != PlayMode::Song {
        return None;
    }
    let step = self.playhead()?;
    let song = self.project.playback_arrangement();
    let pass = *song.pass_at(step)?;
    Some((pass.from + (step - pass.start), pass))
}
}

The Pass travels with it to the playlist, which is how a section knows to show “▶ 2 of 2”. The channel rack, the piano roll and the harmony keys get the timeline step, so they show the right step of the right clip during a repeat too.

Saving: format 4

Clip and Section both have a repeats field, and most of the time it is 1. serde can leave a field out of the file when it has its usual value, and fill it back in when reading a file that does not have it:

#![allow(unused)]
fn main() {
#[serde(default = "once", skip_serializing_if = "is_once")]
pub repeats: usize,
}

default names a function that returns the value to use, and skip_serializing_if a function that says when to leave the field out. The lists in the file (sections, loop_region) use the plain #[serde(default)] with Vec::is_empty and Option::is_none. So a project that uses none of this is written byte for byte as before, and an older Ferrous Lineup opens it.

An older version would also open a project that does use repeats: it skips fields it does not know. But it would play every repeat once, which is a song that sounds wrong without a word of warning. So format_for returns 4 for any project with sections, a loop region or a repeated clip, and older versions refuse it with a clear message (Saving).

Drawing it: a module inside a module

The strips are drawn in a file of their own. A file module can have children: mod sections; inside playlist.rs loads playlist/sections.rs. A child module can see its parent’s private items, so sections.rs uses Layout, Snap and PlaylistAction from playlist.rs with use super::{Layout, PlaylistAction, Snap}; without making them public to the rest of the app.

Each section is its own clickable area, made with ui.interact over a rectangle we choose, which returns a Response like any widget:

#![allow(unused)]
fn main() {
let response = ui.interact(rect, ui.scope_id().with(("section", index)),
                           Sense::click_and_drag());
}

The id must be different for each section and the same from one frame to the next, so it is built from the section’s number. The menu is an egui::Popup attached to that response, opened on a click and closed only by a click outside, because it holds a text field you type into.

Dragging a section does not change the project on every frame, the way dragging a clip does. Only an outline is drawn, and the project changes once, when the button comes up. A section moves inside a sorted list: if one frame’s move jumped it past a neighbour, its number would change in the middle of the drag, and the next frame would move the wrong section.

Writing out the repeats

Write out the repeats in a section’s menu turns “Chorus ×3” into Chorus, Chorus 2 and Chorus 3, one after the other, each played once, so you can change the third chorus without changing the others. The song sounds the same before and after; a test checks it by comparing the two arrangements.

It shares its code with Duplicate: make_room moves everything after the section later, then the clips that start inside the section are copied into the gap. One thing to watch: clips are copied whole. The fill in the picture starts inside the chorus and runs past its end, so the original and its copy overlap. Ferrous Lineup cannot cut a clip in two (a clip has no “start this far into the pattern”); one of the exercises of this part adds it.

Telling the audio thread what changed

Files: crates/lineup-core/src/diff.rs, crates/lineup-app/src/app/edit.rs, crates/lineup-audio/src/engine.rs and crates/lineup-audio/src/sample.rs

One way in for every change

The audio thread keeps its own copy of everything it plays: each channel’s instrument, volume, pan and notes, the pattern lengths, the song (see Two threads). The window must keep that copy up to date, and a change can touch anything. A click on a step changes one list of notes. Deleting a pattern renumbers every clip after it. Typing a chord makes the band write new patterns. Undo replaces the whole project with an older one, which can differ in anything at all.

There are three ways to tell the audio thread about a change:

1. Send the whole project again: every pattern and channel, as when a file is opened. Simple, but every instrument would be built again, cutting off every note that is ringing, and a sample file would be read again for a one-step undo.
2. Write, for each kind of edit, the commands it needs, and for undo, the commands that reverse it. That is a hand-written pair for every edit, and every pair is a chance to get the reverse wrong (the next chapter says more about this choice).
3. Compare the project before and after, and send only what differs.

Ferrous Lineup does the third, for every change, not only for undo. No edit sends its own commands. Every change goes through one method, edit:

#![allow(unused)]
fn main() {
pub(super) fn edit<R>(
    &mut self,
    label: &'static str,
    change: impl FnOnce(&mut Project) -> R,
) -> R {
    if self.history.is_open() {
        // A drag or a typing session is under way, and its first change
        // made the undo step. Keep changing the project without copying
        // the whole of it every frame; the audio catches up steadily
        // from the last state it was given.
        let (patterns, channels) =
            (self.project.patterns().len(), self.project.channels().len());
        let result = change(&mut self.project);
        self.project.follow_chord_sheet();
        self.file.project_edited();
        self.recovery.project_changed();
        self.step_unsynced = true;
        if self.project.patterns().len() != patterns
            || self.project.channels().len() != channels
        {
            // A pattern or channel came or went: the views and the
            // audio thread's rows have to move now, not in 50 ms.
            self.sync_step();
        } else {
            self.sync_step_if_due();
        }
        return result;
    }
    // A step left open by a direct history call: send it before the
    // audio's state is assumed to be this project.
    self.finish_step_sync();
    let before = self.project.clone();
    let result = change(&mut self.project);
    // The band plays what the chord sheet says now, in the same step.
    self.project.follow_chord_sheet();
    if self.project != before {
        self.sync_audio(&before);
        self.synced = self.project.clone();
        self.step_unsynced = false;
        self.last_sync = Instant::now();
        self.file.project_reverted();
        self.recovery.project_changed();
        // `before` is moved into the history here, after its last use.
        self.history.record(label, before);
    }
    result
}
}

Read the second half first, the ordinary case. edit keeps a copy of the project, lets the closure change it, and if anything changed, it does four things in one place:

• sync_audio(&before) tells the audio thread what differs. The rest of this chapter is about it.
• follow_chord_sheet lets the band write its patterns again if the chord sheet, the key or the bars changed, as part of the same step (see How the band plays a chord sheet).
• file and recovery hear that the project changed: the title bar gets its unsaved-changes star, and a recovery copy will be written (see Saving). project_reverted works the star out again from scratch, because a change made in one go can put back exactly what was saved, as a step clicked on and off again does.
• history.record keeps before as the undo step called label (see Undo and redo).

Having one path pays off twice. There is only one piece of code that turns project changes into commands, so it can be tested thoroughly on its own. And it runs on every click, so if it had a mistake you would hear it while editing, not only in the rare moment you undo something unusual.

A drag is one step, not one per frame

The first half, the is_open branch, is the important performance detail. A drag changes notes on every frame, sixty times a second, but only its first frame needs the copy for undo and the full comparison. While the step is open, the project is changed directly, and synced holds the last state the audio thread was given. sync_step_if_due compares the project with that state and sends the differences at most every 50 ms:

#![allow(unused)]
fn main() {
/// How often, at most, a drag's changes reach the audio thread. The
/// window still draws every frame; only the sound waits this long, and
/// the whole project is copied only when this comes round.
const SYNC_INTERVAL: Duration = Duration::from_millis(50);

fn sync_step_if_due(&mut self) {
    if self.last_sync.elapsed() >= SYNC_INTERVAL {
        self.sync_step();
    }
}

fn sync_step(&mut self) {
    let before = std::mem::replace(&mut self.synced, Project::empty());
    self.sync_audio(&before);
    self.synced = self.project.clone();
    self.step_unsynced = false;
    self.last_sync = Instant::now();
}
}

std::mem::replace takes the old synced out of the struct and leaves an empty project in its place, so sync_audio can borrow it as before without a copy (it could not borrow self.synced while also borrowing self mutably). When a pattern or a channel comes or goes in the middle of a step, waiting is not good enough: the views count rows that the audio thread does not have yet, so sync_step runs at once.

When the mouse is released, finish_step_sync sends the last missing changes, and the step closes. One drag is one undo step, one copy and a handful of messages.

Undo and redo replace the whole project, so they always do the full comparison:

#![allow(unused)]
fn main() {
pub(super) fn undo(&mut self) {
    self.finish_step_sync();
    let before = self.project.clone();
    if self.history.undo(&mut self.project).is_some() {
        self.sync_audio(&before);
        self.synced = self.project.clone();
        self.step_unsynced = false;
        self.last_sync = Instant::now();
        self.file.project_reverted();
        self.recovery.project_changed();
        self.restore_song_library();
        self.keep_place_in_song(&before);
    }
}
}

The last two lines are for the window, not the sound: the library shows the style and rhythm this version of the project plays, and if undo changed the time signature, playback stays on the same bar.

Reading edit

edit takes a closure that changes the project, and the closure gets the project as its argument:

#![allow(unused)]
fn main() {
self.edit("move clip", |project| project.move_clip(index, track, start));
}

Why not let the closure reach self.project itself? Because edit already holds &mut self, and a closure that borrowed self too would be a second borrow of the same value while the first is still in use. The borrow checker refuses that. Handing the closure &mut self.project as an argument lends it exactly the part it needs, for exactly as long as the call lasts.

The closure’s type is impl FnOnce(&mut Project) -> R. FnOnce is the closure trait for closures called exactly once: it lets the closure move a value into the project, such as a new channel, because nothing will call it a second time. (Fn closures may be called many times and only read what they capture; FnMut ones may change it.)

R is whatever the closure returns, and edit passes it back to the caller. Many Project methods return something: add_clip returns the new clip’s index as an Option<usize>, remove_pattern the pattern it removed, insert_bars whether there was room. Because R can be any type, a closure can simply be the method call, |project| project.add_clip(clip), and the caller gets the answer. If edit asked for impl FnOnce(&mut Project), which must return (), each of those would need braces and a semicolon to throw the value away.

edit_pattern is a small wrapper for the most common case, a change to the selected pattern:

#![allow(unused)]
fn main() {
fn edit_pattern(&mut self, label: &'static str, change: impl FnOnce(&mut Pattern)) {
    let index = self.pattern;
    self.edit(label, |project| {
        if let Some(pattern) = project.pattern_mut(index) {
            change(pattern);
        }
    });
}
}

self.project != before compares the two projects completely: the derived PartialEq compares every field, every list, every note. If nothing changed, such as a clip dragged back onto the same cell or a note deleted where there was none, nothing is sent and no undo step is recorded.

diff: the list of changes

The comparison lives in lineup-core, which knows projects but nothing about the audio thread. It describes differences in the project’s own words:

#![allow(unused)]
fn main() {
pub enum Change {
    RemovePattern(usize),
    InsertPattern(usize),
    RemoveChannel(usize),
    InsertChannel(usize),
    Instrument(usize),
    Volume(usize),
    Muted(usize),
    Pan(usize),
    ReverbSend(usize),
    Effects(usize),
    PatternLength(usize),
    Notes { pattern: usize, channel: usize },
    Tempo,
    LooseTiming,
    Mixer,
    Song,
}

pub fn diff(before: &Project, after: &Project) -> Vec<Change>
}

The changes are steps to follow in order, and each number is a position at the moment its change is applied. After RemovePattern(0), the pattern that used to be number 1 is number 0, and any later change calls it 0. Values (a volume, a list of notes) are not in the Change: they are read from the newer project when the change is turned into a command. That keeps Change small and Copy.

Only what makes a sound is compared. Pattern names, channel names, track names, section names and the key give no change at all, because the audio thread never sees them. Muting a track does give one: it takes that track’s clips out of the song, so the clips the audio thread plays change.

The mixer is audible too. Moving a channel between the speakers gives Pan, changing how much of it goes to the reverb gives ReverbSend, changing its EQ, compressor or delay gives Effects, and changing the master volume or the reverb itself gives Mixer. Soloing a channel is a mixer change and changes which channels are heard, so diff also reports Muted for every channel whose effective mute changed. Loose timing gives LooseTiming: it decides how far off the grid a note may start.

Lining up two lists

The hard part is the lists. Say the patterns were [Beat, Chords, Fill] and now are [Beat, Fill]. Comparing item by item would say pattern 1 changed from Chords to Fill and pattern 2 disappeared, which is true but clumsy: it would send all of Fill’s notes again. What really happened is “pattern 1 was removed”.

Alignment finds that. It counts how many items are the same at the start of both lists, and how many at the end. What is left in the middle was removed from the old list and inserted in the new one:

  before:  Beat │ Chords │ Fill        start = 1 (Beat is the same)
  after:   Beat │        │ Fill        end   = 1 (Fill is the same)
                                       removed = 3 - 1 - 1 = 1
                                       inserted = 2 - 1 - 1 = 0

#![allow(unused)]
fn main() {
fn new<T>(before: &[T], after: &[T], same: impl Fn(&T, &T) -> bool) -> Self {
    if before.len() == after.len() {
        return Alignment { start: 0, removed: 0, inserted: 0 };
    }
    // The same at the start...
    let start = before
        .iter()
        .zip(after)
        .take_while(|(old, new)| same(old, new))
        .count();
    // ...and the same at the end, without counting an item twice.
    let room = before.len().min(after.len()) - start;
    let end = before[start..]
        .iter()
        .rev()
        .zip(after[start..].iter().rev())
        .take_while(|(old, new)| same(old, new))
        .count()
        .min(room);
    Alignment {
        start,
        removed: before.len() - start - end,
        inserted: after.len() - start - end,
    }
}
}

The iterator chain reads well once you know the pieces: zip walks two lists side by side, giving pairs; take_while keeps pairs while they are equal and stops at the first that is not; count says how many were kept. rev walks the lists backwards, for the end.

.min(room) is easy to miss and important. With [A, A] becoming [A], the start finds one equal item, and so does the end, the same A. Both counts together would say two items are kept out of a list of one, and after.len() - start - end would be 1 - 1 - 1, which for a usize is not -1 but a panic (“attempt to subtract with overflow”). Limiting the end to what is left after the start keeps the arithmetic honest.

When both lists are as long, nothing was added or removed, so items are simply compared position by position. That covers the most common edits: a click on a step changes one pattern, in place.

Alignment works for any T, because the caller says what “the same” means with the same closure. For channels that is full equality: |old, new| old == new. For patterns it is not, and that is the subtle part. A pattern’s rows change when channels come and go: when the band joins, every pattern gets a row for each of its channels, so comparing whole patterns would say every pattern changed. The alignment would then send every pattern’s notes again, and the app would select a pattern that only looks new.

So patterns are lined up by the things that identify them, not by their contents:

#![allow(unused)]
fn main() {
/// Whether two patterns are the same pattern, perhaps with other notes.
fn same_pattern(old: &Pattern, new: &Pattern) -> bool {
    old.name == new.name && old.color == new.color && old.player == new.player
}
}

The notes and the length are what the aligner lets change in place. Name, colour and player say which pattern it is; the notes that differ are sent afterwards as Notes and PatternLength changes anyway.

fn pointers: enum variants are functions

Once two lists are lined up, the changes are: remove the middle of the old list, then insert the middle of the new one.

#![allow(unused)]
fn main() {
fn changes(
    self,
    remove: fn(usize) -> Change,
    insert: fn(usize) -> Change,
) -> impl Iterator<Item = Change> {
    let removals = (self.start..self.start + self.removed).rev().map(remove);
    let insertions = (self.start..self.start + self.inserted).map(insert);
    removals.chain(insertions)
}
}

and it is called like this:

#![allow(unused)]
fn main() {
patterns.changes(Change::RemovePattern, Change::InsertPattern)
}

Change::RemovePattern is not a value here, it is a function. Every enum variant that holds data in parentheses is also a function that builds it: Change::RemovePattern has the type fn(usize) -> Change. The lowercase fn(usize) -> Change is a function pointer type: the address of a plain function, with no captured variables. A closure that captures nothing can be one too. map(remove) calls it for every number, building RemovePattern(2), RemovePattern(1) and so on.

Removals go from the last one backwards. Removing pattern 2 first leaves patterns 0 and 1 where they were, so RemovePattern(1) still means the right pattern. Going forwards, removing pattern 1 first would move pattern 2 down to 1, and the second removal would hit the wrong one. Insertions go forwards for the same reason: once position 1 is filled, position 2 is right after it.

chain joins two iterators into one: first all of removals, then all of insertions. The function returns impl Iterator<Item = Change>, “some iterator of changes”, without naming its long real type (Chain<Map<Rev<Range<usize>>, fn(usize) -> Change>, ...>).

The order of everything

#![allow(unused)]
fn main() {
pub fn diff(before: &Project, after: &Project) -> Vec<Change> {
    let patterns = Alignment::new(before.patterns(), after.patterns(), same_pattern);
    let channels = Alignment::new(before.channels(), after.channels(), |old, new| old == new);

    let mut changes: Vec<Change> = patterns
        .changes(Change::RemovePattern, Change::InsertPattern)
        .chain(channels.changes(Change::RemoveChannel, Change::InsertChannel))
        .collect();
    ...
}

Patterns come first, then channels, then everything inside them. The order matters because of what the audio thread does with each change:

• An inserted pattern arrives in the audio thread with no notes in any channel; its notes follow as Notes changes.
• An inserted channel arrives complete: its instrument, volume, and its notes in every pattern. So the patterns must already be right when it comes, or it would bring notes for the wrong number of patterns.

Then, for every channel that existed before (old_index says where it was, or None if it is new), the instrument and mix are compared:

#![allow(unused)]
fn main() {
for (index, channel) in after.channels().iter().enumerate() {
    let Some(old_index) = channels.old_index(index) else {
        continue; // a new channel arrives complete
    };
    let old = &before.channels()[old_index];
    if old.kind != channel.kind
        || old.program != channel.program
        || old.sent_on != channel.sent_on
    {
        changes.push(Change::Instrument(index));
    }
    if old.volume != channel.volume {
        changes.push(Change::Volume(index));
    }
    if old.pan != channel.pan {
        changes.push(Change::Pan(index));
    }
    if old.reverb_send != channel.reverb_send {
        changes.push(Change::ReverbSend(index));
    }
    if old.effects != channel.effects {
        changes.push(Change::Effects(index));
    }
    if before.channel_muted(old_index) != after.channel_muted(index) {
        changes.push(Change::Muted(index));
    }
}
}

The instrument is built from three fields: the kind (drum, sample file, Lineup Osc, MIDI Out), the General MIDI program, and sent_on, the MIDI port a drum is sent to instead of playing here. channel_muted is not simply the channel’s mute button: it also takes the mixer’s solo into account. That is why a solo change shows up as a Muted change on the other channels, as well as a Mixer change.

let ... else either takes the value out of the Some, or runs the else block, which must leave: here continue jumps to the next channel.

Then the notes, for every pattern and every old channel:

#![allow(unused)]
fn main() {
for (index, pattern) in after.patterns().iter().enumerate() {
    let old_index = patterns.old_index(index);
    let old_pattern = old_index.map(|old| &before.patterns()[old]);
    if let Some(old) = old_pattern
        && old.length() != pattern.length()
    {
        changes.push(Change::PatternLength(index));
    }
    for channel in 0..after.channels().len() {
        let Some(old_channel) = channels.old_index(channel) else {
            continue; // a new channel brought its notes with it
        };
        // The notes as they are played, with the song's swing: a
        // new amount, or a pattern now in a time signature that does
        // not swing, plays other notes. A new pattern starts with no
        // notes in the audio thread.
        let old_notes = match old_index {
            Some(old) => before.played_notes(old, old_channel),
            None => Cow::Borrowed(&[][..]),
        };
        if old_notes != after.played_notes(index, channel) {
            changes.push(Change::Notes { pattern: index, channel });
        }
    }
}
}

The if let ... && ... is a let chain: the block runs only if the pattern is old and its length changed.

The notes compared are played_notes, not the written ones. Swing moves the offbeat notes later without changing what is written (see Tempo, meter, swing and feel), and the audio thread must be sent what is heard. So turning the swing up changes no written note, but gives a Notes change for every list it moves. played_notes returns a Cow (“clone on write”): a Cow::Borrowed when the written notes are played as they are, which costs nothing, and a Cow::Owned with a changed copy only when swing moves them. Two Cows compare by their contents, whichever kind they are.

&[][..] is an empty slice: [] is an empty array, and [..] takes all of it as a slice. A new pattern is compared with “no notes”, which is exactly what the audio thread has for it, so a Notes change is sent only for the channels that have notes in it.

Last come the tempo, the looseness, the mixer and the song. The song is compared through the arrangement that song mode actually plays:

#![allow(unused)]
fn main() {
let (old_song, new_song) = (before.playback_arrangement(), after.playback_arrangement());
if old_song.plays != new_song.plays
    || old_song.length != new_song.length
    || before.played_tempos(&old_song) != after.played_tempos(&new_song)
{
    changes.push(Change::Song);
}
}

An Arrangement is the clips with their repeats and the sections’ repeats already unrolled, cut to the loop region if there is one (see The project). Comparing it catches a moved clip, a mute, a repeat count, a changed loop and a tempo marker in one Song change. Tempo markers are part of the song because the length of a step changes partway through it.

When the story is ambiguous

Say there are three Lineup Osc channels with the same settings but different notes, and you delete the middle one. Comparing the channels alone (name, instrument, volume, mute), the old list is [Osc, Osc, Osc] and the new one [Osc, Osc], and the alignment cannot tell which one went: it finds two equal at the start and says the last was removed.

That is fine. The notes of the second channel now differ (it holds what used to be the third channel’s notes), so a Notes change follows, and the audio thread ends up with exactly the right channels and notes. The diff does not need to guess what you really did. It needs a list of steps that ends in the same place, and a short one where it can.

Testing with a model

How do you test a function like diff? Checking its exact output for every case would be brittle, and would not prove the output is right. What we really want to know is: if the audio thread follows these changes, does it end up with the new project?

So the tests build a small model of what the audio thread knows: the pattern lengths, each channel’s instrument, mix, effects and notes per pattern, the tempo, and the song. It is simple enough to trust at a glance:

#![allow(unused)]
fn main() {
struct ModelChannel {
    kind: ChannelKind,
    program: Option<u8>,
    volume: f32,
    muted: bool,
    pan: f32,
    reverb_send: f32,
    effects: crate::Effects,
    /// One list per pattern.
    notes: Vec<Vec<NoteEvent>>,
}

struct Model {
    lengths: Vec<usize>,
    channels: Vec<ModelChannel>,
    tempo: Tempo,
    loose_timing: u8,
    plays: Vec<Play>,
    song_length: usize,
    tempos: Vec<Tempo>,
}
}

Model::apply does to the model what the audio thread does for each change, and check puts it together:

#![allow(unused)]
fn main() {
/// Diffs two projects, checks that following the changes turns the
/// first into the second, and returns the changes.
fn check(before: &Project, after: &Project) -> Vec<Change> {
    let changes = diff(before, after);
    let mut model = Model::of(before);
    for &change in &changes {
        model.apply(change, after);
    }
    assert_eq!(model, Model::of(after), "changes: {changes:?}");
    changes
}

/// Checks both directions, as undo and then redo would.
fn check_both_ways(before: &Project, after: &Project) -> Vec<Change> {
    check(after, before);
    check(before, after)
}
}

Every test checks this property first, and only then, where it matters, the exact changes: that a step click gives a single Notes, that names and the key give nothing, that undoing a deleted pattern starts with InsertPattern(0), that swing changes the notes played. The last test makes a mess on purpose, removing a pattern, adding a channel, toggling a step, changing a volume and the tempo all at once, and also diffs an empty project against the demo song, as opening a file would.

This kind of test is called property-based: it checks a rule that must hold for any input, rather than one answer for one input. One of the exercises takes it further, with projects changed at random.

The app’s side: sync_audio

sync_audio turns each Change into a command, reading values from the current project:

#![allow(unused)]
fn main() {
fn sync_audio(&mut self, before: &Project) {
    let sample_rate = self.sample_rate();
    let mut patterns_moved = false;
    let mut channels_changed = false;
    for change in diff(before, &self.project) {
        match change {
            Change::RemovePattern(index) => {
                self.send(Command::RemovePattern(index));
                // Keep the same pattern selected. If it was the one
                // removed, the next one takes its place.
                if index < self.pattern {
                    self.pattern -= 1;
                }
                patterns_moved = true;
            }
            Change::InsertPattern(index) => {
                let pattern = &self.project.patterns()[index];
                let (length, bands) = (pattern.length(), pattern.player.is_some());
                self.send(Command::InsertPattern { index, length });
                if bands {
                    // A part the band wrote, as you typed a chord:
                    // the pattern you had stays selected.
                    if index <= self.pattern {
                        self.pattern += 1;
                    }
                } else {
                    // A new pattern (added, cloned, or brought back
                    // by undo) is the one you want to see, from its
                    // start.
                    self.pattern = index;
                    self.rewind_for_new_pattern();
                }
                patterns_moved = true;
            }
            Change::Notes { pattern, channel } => {
                let notes = self.project.played_notes(pattern, channel).into_owned();
                self.send(Command::SetNotes { pattern, channel, notes });
            }
            ...
        }
    }
    ...
}
}

The other arms are just as direct. InsertChannel builds the channel’s instrument and sends it with its notes for every pattern. Instrument builds a new instrument and sends SetInstrument. Volume, Pan, ReverbSend and Effects send their one value, Muted sends the channel’s effective mute, LooseTiming sends the new amount, Mixer sends the master volume and the reverb settings, and Song sends the three commands that replace the song, its tempos and its metronome clicks. Tempo sends the tempo at the practice speed, if you slowed the song down to practise (see Practice tools).

into_owned turns the Cow from played_notes into a Vec the command can carry: it clones a borrowed list, and simply hands over an owned one.

sync_audio also keeps the window’s own numbers pointing at the right things. The selected pattern is a position, so it moves down when a pattern before it goes, and up when the band inserts one before it. The piano roll remembers which channel it shows, so it is told when channels come and go (channel_removed and channel_inserted). Because these updates are here, adding, cloning and deleting patterns select the right pattern whether you did them or undo did.

The audio thread inserts in place

Undoing “delete pattern 0” must put a pattern back at position 0, not at the end. So the audio thread’s commands take a position:

#![allow(unused)]
fn main() {
/// Add an empty pattern at position `index`; the patterns from there
/// on move up one place. An index past the end adds it at the end.
InsertPattern { index: usize, length: usize },

/// Add a channel at position `index`, with its notes in every pattern.
/// The channels from there on move down one row. An index past the
/// end adds it at the bottom.
InsertChannel {
    index: usize,
    instrument: Instrument,
    notes: ChannelNotes,
    volume: f32,
    muted: bool,
},
}

Vec::insert(index, value) moves every item from index on one place up, and puts value in the gap. Would that allocate on the audio thread? Only if the Vec were full. Room for MAX_CHANNELS channels and MAX_PATTERNS patterns is reserved when the audio thread is made (see Room reserved in advance), and both commands check the limit first, so insert always fits in memory that is already there. Moving items along is just copying, which is allowed in real time:

#![allow(unused)]
fn main() {
fn insert_pattern(&mut self, index: usize, length: usize) {
    if self.pattern_lengths.len() < MAX_PATTERNS {
        let index = index.min(self.pattern_lengths.len());
        self.pattern_lengths.insert(index, length);
        for channel in &mut self.channels {
            channel.notes.insert_empty(index);
        }
        ...
    }
}
}

An index past the end is clamped (index.min(len)) rather than refused. The audio thread must never panic, and “insert after the last one” is the most sensible reading of a too-big number.

InsertChannel is one of the biggest commands. Every slot of the command queue is as big as the biggest command, so a test keeps commands at 80 bytes at most. An instrument’s voices are behind a Box, so a command carries a pointer to them, never all of them.

Instruments come back from a cache

Undoing “load sample” gives a channel its old instrument back, and that might be a sample file. Reading a file on the window’s thread for an undo would make the window stutter, and the file might even be gone by now.

So the app keeps a SampleCache: every sample file read so far, by path.

#![allow(unused)]
fn main() {
pub struct SampleCache {
    loaded: HashMap<PathBuf, Arc<SampleData>>,
}

impl SampleCache {
    pub fn get(&mut self, path: &Path) -> Result<Arc<SampleData>, SampleError> {
        // A `HashMap<PathBuf, _>` can be searched with a `&Path`, because
        // `PathBuf` implements `Borrow<Path>`: no `PathBuf` is built here.
        if let Some(sample) = self.loaded.get(path) {
            return Ok(Arc::clone(sample));
        }
        self.reload(path)
    }

    pub fn reload(&mut self, path: &Path) -> Result<Arc<SampleData>, SampleError> {
        let sample = Arc::new(SampleData::load_wav(path)?);
        self.loaded.insert(path.to_path_buf(), Arc::clone(&sample));
        Ok(sample)
    }
}
}

A HashMap finds a value by its key in about the same time however many entries it holds. Its keys are owned PathBufs, but get takes a borrowed &Path. That works because of the Borrow trait: PathBuf implements Borrow<Path>, a promise that a PathBuf and the Path it holds hash and compare the same way. So the map can look up a &Path directly, without building a PathBuf just to search. (HashMap<String, _> can be searched with a &str for the same reason.)

The cache hands out Arc clones, so the cache and every sampler using the sound share one copy of it in memory. A test checks this with Arc::ptr_eq, which asks whether two Arcs point at the very same memory, not merely at equal values:

#![allow(unused)]
fn main() {
assert!(Arc::ptr_eq(&first, &second), "the second get shares the first");
assert!(!Arc::ptr_eq(&first, &reloaded), "reload reads the file again");
}

Dropping a file on the rack calls reload, not get: you may have changed the file in an audio editor since, and dropping it again should pick that up. A file that cannot be read is not remembered, so the next attempt reads it again. Opening another project clears the cache.

Instrument::for_channel takes the cache as an argument (&mut SampleCache) instead of reading files itself. Exporting builds every instrument again (see Exporting), and thanks to the cache it reads no files either.

Undo and redo

Files: crates/lineup-core/src/history.rs and crates/lineup-app/src/app/edit.rs

Every change to a song can be undone with Ctrl+Z and redone with Ctrl+Shift+Z or Ctrl+Y, and the Edit menu names the step it would undo (“Undo move clip”). This chapter is about how the history is kept, and when one step ends and the next begins.

Two ways to undo

There are two classic ways to build undo.

The command pattern records every change as an instruction that knows how to reverse itself: “add note C4 at step 3” is undone by “remove note C4 at step 3”. The history is a list of instructions. It uses very little memory, but every kind of change needs its own reverse, written by hand, and each one is a new place to make a mistake. Think of what undoing “delete pattern” would need: put the pattern back at its old position, with its name and length and the notes of every channel, put back every clip that used it, and renumber the clips of the patterns after it again. If one detail is forgotten, undo quietly gives back a slightly different song.

Snapshots keep a whole copy of the project from before each undoable step. Undo puts the copy back. There is nothing to reverse, so there is nothing to reverse wrongly: whatever the change did, the copy is exactly what was there before. The cost is memory, and the time to make a copy.

Ferrous Lineup uses snapshots. A NoteEvent takes 24 bytes, and a song has a few hundred or a few thousand of them, so a copy of a whole project is some kilobytes. Even a big project with 10,000 notes holds about 240 KB of notes, and making one copy takes far less than a millisecond. The app keeps at most 256 MiB of snapshots: a small song gets the full 100 steps, while a very large one still gets at least 10 (which can go over the budget). That is a fair price for undo that is correct by construction. (One of the exercises shows how to make the copies much cheaper, if a project ever gets big enough to need it.)

History<T>

The history lives in lineup-core, and it does not know about projects at all:

#![allow(unused)]
fn main() {
struct Step<T> {
    label: &'static str,
    state: T,
}

pub struct History<T> {
    /// The oldest step is at the front, the newest at the back. A
    /// `VecDeque` can drop the oldest step from the front cheaply.
    undo: VecDeque<Step<T>>,
    redo: Vec<Step<T>>,
    limit: usize,
    /// Whether the newest undo step still takes in new changes.
    open: bool,
}

impl<T> History<T> {
    pub fn new(limit: usize) -> Self { ... }
    pub fn record(&mut self, label: &'static str, before: T) { ... }
    pub fn is_open(&self) -> bool { ... }
    pub fn close(&mut self) { ... }
    pub fn reopen(&mut self, label: &'static str) -> bool { ... }
    pub fn undo(&mut self, current: &mut T) -> Option<&'static str> { ... }
    pub fn redo(&mut self, current: &mut T) -> Option<&'static str> { ... }
    pub fn undo_label(&self) -> Option<&'static str> { ... }
    pub fn redo_label(&self) -> Option<&'static str> { ... }
    pub fn clear(&mut self) { ... }
}
}

History<T> is generic: T is whatever is being remembered. The app uses a History<Project>; the tests use a History<i32>, which makes them short and easy to read:

#![allow(unused)]
fn main() {
#[test]
fn changes_join_the_open_step() {
    let mut history = History::default();
    let mut value = 0;
    // A drag: three changes before the mouse button is released.
    for new in [1, 2, 3] {
        history.record("drag", value);
        value = new;
    }
    history.close();
    history.undo(&mut value);
    assert_eq!(value, 0, "one undo goes back to before the drag");
}
}

Look at the impl line: impl<T> History<T>, with no trait bound on T. Not even Clone. The history never copies a T; it only moves the values it is given from one list to another. The caller makes the copy (self.project.clone()) and hands it over. If a method of History ever called .clone() on a state, the compiler would refuse with “no method named clone found for type parameter T”, and we would have to write impl<T: Clone>. A generic type with no bounds is a strong promise: the code cannot do anything with a T except store it, move it and drop it.

The compiler makes a separate copy of the code for each T it is used with (this is monomorphization), so a History<Project> is as fast as if it had been written for Project by hand.

&'static str labels

Each step has a label, such as "move clip", for the Edit menu. Its type is &'static str: a reference to text that lives for the whole program. Every string literal written in the code has this type, because the text is stored inside the program file itself. So a label costs nothing: no String is built, nothing is allocated, and the history holds no borrow that could end too soon. The price is that a label cannot be made at run time (“rename pattern Beat”), since that text would not exist until the program builds it.

The labels are written in English, and the Edit menu translates them when it shows them, so the history does not need to know the app’s language (see Two languages).

VecDeque: a list with two cheap ends

When there are already limit steps, recording one more forgets the oldest. In a Vec, removing the first item (remove(0)) moves every other item one place down. A VecDeque (“double-ended queue”, said “vec deck”) is a ring buffer, like the queues between the threads (see Two threads): it keeps track of where its front is, so push_back and pop_front are both cheap.

The limit is not a constant in the app. History::new takes it, and undo_limit_for works it out from the project’s size:

#![allow(unused)]
fn main() {
const UNDO_BYTES: usize = 256 * 1024 * 1024;
const MIN_UNDO_STEPS: usize = 10;

pub(super) fn undo_limit_for(project: &Project) -> usize {
    limit_for_bytes(project.heap_bytes())
}

fn limit_for_bytes(bytes: usize) -> usize {
    (UNDO_BYTES / bytes.max(1)).clamp(MIN_UNDO_STEPS, DEFAULT_LIMIT)
}
}

heap_bytes counts the notes, clips, markers and names, the things whose number grows with the song. A small project divides 256 MiB by a few kilobytes and gets more than DEFAULT_LIMIT, so it is clamped to 100. A huge project gets fewer, but never fewer than 10, so undo does not vanish just because the song is long. Opening a file builds a fresh History with the limit for that project. History::default() means 100, which is what the little tests use.

#![allow(unused)]
fn main() {
pub fn record(&mut self, label: &'static str, before: T) {
    self.redo.clear();
    if self.open {
        return;
    }
    self.undo.push_back(Step { label, state: before });
    if self.undo.len() > self.limit {
        self.undo.pop_front();
    }
    self.open = true;
}
}

Every new change clears the redo list. After you undo three steps and then change something, those three steps belong to a future that no longer exists. (A few programs keep a whole tree of histories, so no branch is ever lost; most simply drop the old future, as this one does.)

The redo list is a plain Vec, because steps are only added and taken at its end.

mem::swap: undo without copying

#![allow(unused)]
fn main() {
pub fn undo(&mut self, current: &mut T) -> Option<&'static str> {
    let mut step = self.undo.pop_back()?;
    // Now `current` holds the old state and `step` the newer one.
    std::mem::swap(current, &mut step.state);
    let label = step.label;
    self.redo.push(step);
    self.open = false;
    Some(label)
}
}

pop_back() gives an Option, and the ? operator works on Option in a function that returns an Option: if there is nothing to undo, undo returns None at once and changes nothing.

std::mem::swap exchanges the values behind two &mut references. After it, current (the app’s project) holds the older version, and the step holds the version we just left, ready for redo. Nothing is copied or allocated: a Project is mostly Vecs, and a Vec is a pointer, a length and a capacity, so swapping two projects swaps a few of those small values, whatever the size of the song. The borrow checker is what makes this simple: swap needs two &mut references, and two &mut references can never point at the same value, so swap can exchange the two values’ bytes without checking anything.

redo is the mirror image, popping from redo and pushing onto undo.

When does one step end?

Dragging a clip across the playlist moves it a little on many frames, and each move is an edit. If each one were its own step, undoing the drag would take as many presses of Ctrl+Z as there were frames. So the history keeps the newest step open, and record does nothing while it is: the step already holds the project from before the drag started, which is exactly where undo should go back to.

The app decides when a step ends, because only it knows what the mouse is doing. It calls the history at the start and at the end of every frame:

#![allow(unused)]
fn main() {
/// Called at the start of each frame. A press of a mouse button
/// always begins a new undo step.
pub(super) fn start_frame_for_undo(&mut self, ctx: &egui::Context) {
    if ctx.input(|input| input.pointer.any_pressed()) {
        self.close_step();
    }
}

/// Called at the end of each frame. While a mouse button is held (a
/// drag), a text field has the keyboard (typing a name) or a take is
/// being recorded, changes join one undo step; once all of them are
/// over, the step ends.
pub(super) fn end_frame_for_undo(&mut self, ctx: &egui::Context) {
    let holding = ctx.input(|input| input.pointer.any_down());
    if !holding && !ctx.text_edit_focused() && !self.is_recording() {
        self.close_step();
    } else if self.step_unsynced {
        // The step goes on, but its last change may still be waiting
        // for its turn: a drag held still, or the last key typed, has
        // no next edit to carry it to the audio thread. Send it when
        // it is due, and make sure a frame comes then.
        self.sync_step_if_due();
        if self.step_unsynced {
            ctx.request_repaint_after(SYNC_INTERVAL.saturating_sub(self.last_sync.elapsed()));
        }
    }
}
}

Follow a few gestures through these two functions:

• A click on a step. egui reports a click on the frame the button is let go. That frame’s edit opens a step, and the end of the same frame closes it, since no button is down any more: one change, one step.
• A drag. The press closes whatever was open. Every frame of the drag edits the project while the button is down, so the edits join one step. The frame where the button is let go closes it.
• Typing a pattern name. While the text field has the keyboard focus, every letter joins the same step. Clicking elsewhere takes the focus away and closes it, so undo puts back the whole old name at once.
• Typing a tempo. Clicking the BPM box turns it into a text field, so the same rule applies: everything typed there is one step, which ends when you leave the box.
• Recording a take. Every note played while recording joins one step, so one undo takes the whole take away.

start_frame_for_undo matters for one case: a click that starts while a text field still has the focus. The press closes the typing step, so the click’s change does not join it.

The else if branch is about sound, not undo. While a step is open, changes reach the audio thread at most every 50 ms, carried by the next edit (see Telling the audio thread what changed). A drag held still makes no next edit, so the frame sends what is still waiting once it is due, and request_repaint_after asks egui for a frame at that moment even if nothing moves.

Closing a step is close_step:

#![allow(unused)]
fn main() {
fn close_step(&mut self) {
    self.finish_step_sync();
    if self.history.is_open() {
        self.file.project_reverted();
    }
    self.history.close();
}
}

It sends whatever the audio thread is still missing, and works out the unsaved-changes star again (a note dragged away and back leaves the song as it was saved). Then the history stops taking changes into the step.

Several clicks, one step

Some changes come one click at a time but belong together. Tapping a tempo is a click per beat; nudging the master volume or the number of choruses is a click or a drag per nudge. Undo should take all of them back at once. reopen lets the app open the newest step again:

#![allow(unused)]
fn main() {
/// Opens the newest step again, if it is called `label` and nothing
/// was undone since, so the next change joins it: taps of a tempo,
/// each a click of its own, make one step. Returns whether it did.
pub fn reopen(&mut self, label: &'static str) -> bool {
    if self.redo.is_empty() && self.undo_label() == Some(label) {
        self.open = true;
    }
    self.open
}
}

and the app calls it just before the edit:

#![allow(unused)]
fn main() {
pub(super) fn set_master_volume(&mut self, master: f32) {
    const STEP: &str = "master volume";
    self.history.reopen(STEP);
    self.edit(STEP, |project| project.mixer.master = master);
}
}

If the last step was another change, or something was undone since, the label does not match and a new step starts as usual.

Everything goes through edit

The pattern name field shows how strict the rule “every change goes through edit” is. egui’s text field wants a &mut String to change. Giving it the project’s own name would change the project directly, behind the history’s back: no undo step, and no message to the audio thread either. So the field edits a copy, and the copy goes through edit when it changed:

#![allow(unused)]
fn main() {
// The field edits a copy, so the change can go through `edit`.
let mut name = self.project.patterns()[self.pattern].name.clone();
if ui.text_edit_singleline(&mut name).changed() {
    self.edit_pattern("rename pattern", |pattern| pattern.name = name);
}
}

The Project type helps here: its lists are private, and only its methods can change them (see The project). Anything that changes a project needs a &mut Project, and in the app the only place that hands one out is edit.

Keyboard shortcuts

#![allow(unused)]
fn main() {
const UNDO: KeyboardShortcut = KeyboardShortcut::new(Modifiers::COMMAND, Key::Z);
const REDO: KeyboardShortcut =
    KeyboardShortcut::new(Modifiers::COMMAND.plus(Modifiers::SHIFT), Key::Z);
/// The other common shortcut for redo, used on Windows.
const REDO_Y: KeyboardShortcut = KeyboardShortcut::new(Modifiers::COMMAND, Key::Y);

pub(super) fn edit_shortcuts(&mut self, ctx: &egui::Context) {
    let pressed = |shortcut| ctx.input_mut(|input| input.consume_shortcut(&shortcut));
    // Ctrl+Z would also match Ctrl+Shift+Z, so redo is checked first.
    if pressed(REDO) || pressed(REDO_Y) {
        self.redo();
    } else if pressed(UNDO) {
        self.undo();
    }
}
}

Modifiers::COMMAND is Ctrl on Linux and Windows and ⌘ on a Mac. egui’s consume_shortcut is forgiving about extra keys: a shortcut without Shift also matches when Shift is held. That is usually what you want (on many keyboards + needs Shift, and Ctrl++ should still work), but here it means Ctrl+Shift+Z would count as Ctrl+Z too. Checking redo first, and using else if, settles it.

|| stops at the first true, so if Ctrl+Shift+Z was pressed, Ctrl+Y is not even looked at. “Consume” means the key press is taken out of egui’s input, so nothing else in the same frame reacts to it.

These shortcuts are skipped while a text field has the keyboard. egui’s text fields have their own undo for typing, and Ctrl+Z there should undo the last letters, not the last change to the song.

The Edit menu shows the same shortcuts, written the way the system writes them (“Ctrl+Z” on Linux, “⌘Z” on a Mac), and puts the translated label in the item, “Undo move clip”.

Undo and the unsaved-changes star

The window title shows a star when the project differs from the saved file. It does not compare the two projects on every frame: an edit sets a flag, and the comparison happens when the title is next worked out. Undo and redo set the flag too, so they can make the star go away when the project is equal to the saved one again. A plain dirty: bool set on every edit would have kept the star after the undo. Saving shows the rest of this.

Opening a file, or File > New, replaces the whole project and clears the history. Undoing into a different song would be surprising, and the “Save changes?” question already protects what you leave behind.

Saving: the .lineup file, recovery and damaged files

Files: crates/lineup-core/src/file.rs, crates/lineup-app/src/app/files.rs, crates/lineup-app/src/app/recovery.rs, crates/lineup-app/src/app/recent.rs and crates/lineup-core/tests/damaged_files.rs

A song is saved as a .lineup file. This chapter is about what is in that file and why it is shaped that way, how a file from an older or a newer version is read, how saving avoids ever leaving a half-written file, and how the app keeps a copy of unsaved work in case it crashes. The numbered list of format versions is in the reference page Project file format.

What a project file looks like

A .lineup file is plain text. To see one, open a demo under File > Demos, use File > Save As…, and open the saved file in a text editor. File > New beat starts a song with an empty pattern and a drum kit; this is the whole file it saves:

(
    format: 1,
    tempo: 130.0,
    scale: (
        root: C,
        kind: Major,
    ),
    channels: [
        (
            name: "Kick",
            kind: Sampler(Builtin(Kick)),
            volume: 0.8,
            muted: false,
        ),
        (
            name: "Clap",
            kind: Sampler(Builtin(Clap)),
            volume: 0.8,
            muted: false,
        ),
        ...
        (
            name: "Lineup Osc",
            kind: Synth,
            volume: 0.6,
            muted: false,
        ),
    ],
    patterns: [
        (
            name: "Pattern 1",
            length: 16,
            notes: [
                [],
                [],
                [],
                [],
                [],
            ],
        ),
    ],
    tracks: [
        (
            name: "Track 1",
            muted: false,
        ),
    ],
    clips: [],
)

Other songs carry more. The starting song’s synth channel plays a General MIDI piano, so it carries program: Some(0) and its file says format: 9. Its chords read as notes, one per line:

                    (pitch: 48, start: 0, length: 8, velocity: 100),
                    (pitch: 60, start: 0, length: 8, velocity: 100),
                    (pitch: 64, start: 0, length: 8, velocity: 100),
                    (pitch: 67, start: 0, length: 8, velocity: 100),

File > New, an empty chord sheet with a band, saves format: 17 and ends with the band: band: Some((style: "Pop beat", ...)).

The format is RON, “Rusty Object Notation”. It looks like Rust: a struct is ( field: value, ... ), a list is [ ... ], and enum variants are written by name, Sampler(Builtin(Kick)), just as in the code. JSON would work too, but JSON has no enums, so the same channel would read {"Sampler": {"Builtin": "Kick"}}. RON is easier to read and to fix by hand, which matters for a program you learn from: you can open a song in a text editor and see your own data structures.

serde: describe the data once

Rust’s standard way to turn values into text (or bytes) and back is the serde crate, short for serialize and deserialize. serde does not know any format itself. It defines two traits, Serialize and Deserialize, and format crates such as ron or serde_json use them.

You almost never write those traits by hand. A derive macro writes them for you:

#![allow(unused)]
fn main() {
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Channel {
    pub name: String,
    pub kind: ChannelKind,
    pub volume: f32,
    pub muted: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub program: Option<u8>,
    #[serde(default, skip_serializing_if = "is_centred")]
    pub pan: f32,
    // ...the reverb send, the MIDI channel a drum is sent on, and the
    // channel's effects, each left out at its default.
}
}

The macro reads the struct definition at compile time and generates code that writes each field by name, and reads them back. For this to work, every field’s type must be Serialize too, so ChannelKind, SampleSource, Drum, NoteEvent, Scale, PitchClass, Track, Clip and the rest derive it as well. String, numbers, bool, Vec, Option and PathBuf come with serde.

The derive is turned on by asking for serde’s derive feature in Cargo.toml. Features are optional parts of a crate that you switch on when you need them:

serde = { version = "1", features = ["derive"] }

The #[serde(default, skip_serializing_if = ...)] lines are how the file format grows quietly. A field that is at its default is not written at all, and a field missing from an older file is filled in with its default. That is why the drum kit above, which uses nothing beyond the first layout, is written exactly as the first version of the format wrote it: a channel in the middle with all of it in the reverb says nothing about pan or reverb send.

Keeping the rules while reading: from and into

A Tempo cannot be made outside 10 to 522 BPM, because its field is private and Tempo::new clamps it. A derived Deserialize would set the field directly from the file, so a file saying tempo: 9000.0 would create a tempo the rest of the program promises can never exist.

The fix is to tell serde to go through a type we control:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd, Serialize, Deserialize)]
#[serde(from = "f32", into = "f32")]
pub struct Tempo {
    bpm: f32,
}

impl From<f32> for Tempo {
    fn from(bpm: f32) -> Self {
        Tempo::new(bpm)
    }
}

impl From<Tempo> for f32 {
    fn from(tempo: Tempo) -> Self {
        tempo.bpm
    }
}
}

#[serde(from = "f32")] means “read an f32, then convert it with From<f32>”. That conversion is Tempo::new, which clamps. The test values_out_of_range_are_clamped edits a saved file to say 9000 BPM and checks that it loads as 522. into = "f32" does the reverse when saving, which also makes the file say tempo: 130.0 instead of tempo: (bpm: 130.0). Note does the same with its MIDI number.

Always in letters and English

The app can show note names in letters (C, D, E) or in solfège (Do, Re, Mi), and its texts in English or Spanish (see Two languages). A file must not depend on either: a song saved by someone who reads solfège must open for someone who reads letters. So to_text and from_text set both for as long as they run:

#![allow(unused)]
fn main() {
let file = Language::English.with(|| NoteNaming::Letters.with(|| ProjectFile::from(project)));
let mut text = NoteNaming::Letters.with(|| ron::ser::to_string_pretty(&file, style))?;
}

with sets the naming for the thread, runs the closure, and puts the old naming back, so the window draws in solfège again on its next frame.

A separate type for the file

Project itself does not derive serde. Its fields are private because they must agree with each other (one row per channel, clips that point at real patterns), and a derived Deserialize would fill them straight from the file, agreeing or not. So the file has its own struct:

#![allow(unused)]
fn main() {
#[derive(Debug, Serialize, Deserialize)]
struct ProjectFile {
    format: u32,
    #[serde(default, skip_serializing_if = "crate::Mixer::is_default")]
    mixer: crate::Mixer,
    tempo: Tempo,
    scale: Scale,
    #[serde(default, skip_serializing_if = "TimeSignature::is_common")]
    time_signature: TimeSignature,
    channels: Vec<Channel>,
    patterns: Vec<PatternFile>,
    tracks: Vec<Track>,
    clips: Vec<Clip>,
    // ...sections, the loop region, time, tempo and key markers, loose
    // timing, swing, the chord sheet, the band, where each part came
    // from, and the locked channels: each left out when it is empty.
}

#[derive(Debug, Serialize, Deserialize)]
struct PatternFile {
    name: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    color: Option<usize>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    time: Option<TimeSignature>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    player: Option<Player>,
    length: usize,
    /// One list of notes per channel, in the order of `channels`.
    notes: Vec<Vec<NoteEvent>>,
}
}

A ProjectFile accepts anything shaped right. Turning it into a Project is where the checking happens, and it is written as a TryFrom implementation, the standard trait for “a conversion that can fail”:

#![allow(unused)]
fn main() {
impl TryFrom<ProjectFile> for Project {
    type Error = FileError;

    fn try_from(file: ProjectFile) -> Result<Self, Self::Error> {
        let mut project = Project::empty();
        // ...checks on the mixer, the time signature and each channel's
        // mix, effects and MIDI channel...
        for channel in file.channels {
            project.add_channel(channel);
        }
        for (index, saved) in file.patterns.into_iter().enumerate() {
            // `Project::empty` already has one pattern; add the others.
            if index > 0 {
                project.add_pattern();
            }
            let Some(pattern) = project.pattern_mut(index) else { ... };
            pattern.set_length(saved.length);
            for (channel, notes) in saved.notes.into_iter().enumerate() {
                for note in notes {
                    if pattern.add_note(channel, note).is_none() {
                        return invalid(/* where, and what is wrong */);
                    }
                }
            }
        }
        // ...tracks, clips, sections, markers, the chord sheet and the band...
        Ok(project)
    }
}
}

The project is rebuilt through its front door: add_channel, add_pattern, add_note, add_clip, the same methods the app calls when you click. Those methods already keep every rule (see The project), so a file can never create a project that the window could not have created. When a method refuses (a note that does not fit, a clip that plays a pattern that is not there), the error says where, so a person editing the file by hand can fix it: “the project file is damaged: clip 1 (pattern 99, track 1) does not fit in the playlist”.

type Error = FileError; is an associated type: part of the trait that each implementation chooses. With TryFrom in place, the standard library also provides the matching try_into, so let project: Project = file.try_into()?; would work too.

Saving goes the other way with From<&Project> for ProjectFile, which copies the data out with to_vec() and map. It cannot fail, so it is a From, not a TryFrom.

The version number

#![allow(unused)]
fn main() {
pub const FORMAT_VERSION: u32 = 29;
}

FORMAT_VERSION is the newest layout this program can read. A file does not always use it: format_for writes the lowest format that can hold the project. A project that uses nothing new stays format 1, so an older Ferrous Lineup can still open it. The starting song needs format 9, because its synth channel plays a General MIDI program; a song with a chord sheet needs at least format 12; one with a horn section or a channel effect needs 28, and a band playing another style’s drums 29. The long comment above FORMAT_VERSION says, for every number, what it added and what an older program would get wrong without it; Project file format has the same list as a table.

A file from a newer version must be refused with a clear message, not read wrongly. The obvious way is to read a tiny struct first:

#![allow(unused)]
fn main() {
#[derive(Deserialize)]
struct Header {
    format: u32,
}
}

By default, serde skips fields that a struct does not list, so a Header can be read from the whole file. But to skip the rest of the file, RON has to look ahead through all of it, number by number. On a long song such as Boléro, that took over a minute, even in a release build. So the whole file is read first, and only if that fails does format_number read the number from the first few bytes:

#![allow(unused)]
fn main() {
pub fn from_text(text: &str) -> Result<Project, FileError> {
    // A text editor may start the file with a byte-order mark, which is
    // not part of the RON text or of the format number.
    let text = text.strip_prefix('\u{feff}').unwrap_or(text);
    let file: ProjectFile = match NoteNaming::Letters.with(|| ron::from_str(text)) {
        Ok(file) => file,
        Err(err) => {
            return Err(match format_number(text) {
                Some(format) if format > FORMAT_VERSION => FileError::NewerFormat(format),
                _ => err.into(),
            });
        }
    };
    if file.format > FORMAT_VERSION {
        return Err(FileError::NewerFormat(file.format));
    }
    NoteNaming::Letters.with(|| Project::try_from(file))
}

/// The format number at the start of a project file, `(format: 25, ...`,
/// read without the RON reader.
fn format_number(text: &str) -> Option<u32> {
    let rest = text.trim_start().strip_prefix('(')?.trim_start();
    let rest = rest.strip_prefix("format")?.trim_start();
    let rest = rest.strip_prefix(':')?.trim_start();
    let digits = rest
        .find(|c: char| !c.is_ascii_digit())
        .unwrap_or(rest.len());
    rest[..digits].parse().ok()
}
}

to_text always writes format first, so this looks only where the number must be. A newer file often fails to read at all, because of fields or names this version does not know; then the format number alone says why. If the file is so broken that even the number cannot be read, the original RON error is the one reported. And if the file parses but still says a newer format, it is refused too, because the same text may mean something else in that format. A byte-order mark at the start (some text editors add one) is stripped first, so it cannot hide the (.

The test files_from_the_future_are_refused reads a file one format newer than this version, (format: 30, sparkles: true) today, and expects NewerFormat(30), and the message “this file uses format 30, made by a newer version of Ferrous Lineup (this one reads up to format 29)”.

Errors as an enum

#![allow(unused)]
fn main() {
#[derive(Debug)]
pub enum FileError {
    /// The file could not be read or written: missing, no permission, disk full...
    Io(io::Error),
    /// The text is not a valid project file. The error says where.
    Parse(ron::error::SpannedError),
    /// The project could not be turned into text (should never happen).
    Write(ron::Error),
    /// The file was saved by a newer version of Ferrous Lineup.
    NewerFormat(u32),
    /// The file is shaped right, but what it says does not make sense.
    Invalid(String),
}
}

This is the same pattern as EngineError (see A custom error type) and SampleError: one variant per kind of problem, a Display implementation with a message for people (in the app’s language), and std::error::Error so it works with any Rust error handling. Two more things make it pleasant to use.

From for ?. Inside a function that returns Result<_, FileError>, the ? operator can only pass an error on if it knows how to turn it into a FileError. These implementations teach it:

#![allow(unused)]
fn main() {
impl From<io::Error> for FileError {
    fn from(err: io::Error) -> Self {
        FileError::Io(err)
    }
}
}

With one for io::Error, one for ron’s parse error and one for its write error, a function can mix calls from both libraries and use ? on all of them:

#![allow(unused)]
fn main() {
pub fn load(path: &Path) -> Result<Project, FileError> {
    let text = fs::read_to_string(path)?; // io::Error -> FileError::Io
    from_text(&text)
}
}

source. The Error trait has an optional method that returns the lower-level error a value wraps. Error-reporting tools follow it to print a chain like “could not load: no such file”. FileError::Io returns its io::Error; Invalid has nothing underneath and returns None.

#![allow(unused)]
fn main() {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
    match self {
        FileError::Io(err) => Some(err),
        FileError::Parse(err) => Some(err),
        FileError::Write(err) => Some(err),
        FileError::NewerFormat(_) | FileError::Invalid(_) => None,
    }
}
}

&(dyn Error + 'static) is a trait object: a reference to some value that implements Error, without saying which type. That lets one method return an io::Error in one case and a ron error in another.

Saving without losing the old file

#![allow(unused)]
fn main() {
pub fn save(project: &Project, path: &Path) -> Result<(), FileError> {
    let text = to_text(project)?;
    let temporary = path.with_extension(format!("{EXTENSION}.tmp"));
    if let Err(err) = fs::write(&temporary, text) {
        let _ = fs::remove_file(&temporary);
        return Err(err.into());
    }
    if let Err(err) = fs::rename(&temporary, path) {
        let _ = fs::remove_file(&temporary);
        return Err(err.into());
    }
    Ok(())
}
}

Writing straight over song.lineup has a nasty failure: if the program crashes or the disk fills up halfway, the file is half old, half new, and neither version can be loaded. Writing to song.lineup.tmp first and then renaming it over the original avoids that, because the operating system replaces a file by renaming in a single step. Either the rename happened and the new file is complete, or it did not and the old file is untouched. On Windows, Rust’s fs::rename also replaces an existing file, so the same code works everywhere. The WAV and video exports and the recovery copy are written the same way.

to_text always ends lines with \n (RON would use \r\n on Windows), so a song is the same file on every system, and a project saved on one computer shows no difference in version control when saved on another.

The tests save to std::env::temp_dir(), the system’s folder for temporary files (/tmp on Linux, something under your user folder on Windows), with the process id in the name so two test runs at once do not collide, and delete the file afterwards.

Damaged files never crash the app

A project file can be cut short by a full disk, edited by hand, or be something else under a .lineup name. MIDI files come from every program there is. Reading a file must end in a project or in an error message, never in a crash. The test file damaged_files.rs checks this the way a fuzzer does: it damages good files in many small ways and reads each result.

The damage comes from a tiny random number generator, xorshift, written in the test:

#![allow(unused)]
fn main() {
struct Damage(u64);

impl Damage {
    fn next(&mut self) -> u64 {
        self.0 ^= self.0 << 13;
        self.0 ^= self.0 >> 7;
        self.0 ^= self.0 << 17;
        self.0
    }
}
}

It starts from a fixed seed, so every run damages the files the same way, and a failure shows up again on the next run. It needs no new dependency. For project files and chord sheets, it replaces numbers with extreme ones (-1, 65535, 18446744073709551615, NaN), cuts pieces out, and repeats pieces. For MIDI files, it changes, cuts and repeats bytes. Each test reads 600 damaged copies. A project that reads must also save and read back.

The test catches a panic with std::panic::catch_unwind, so a failure prints the damaged file that caused it, up to its first 4,000 characters:

#![allow(unused)]
fn main() {
fn must_not_panic<T: std::fmt::Debug>(input: T, read: impl FnOnce(&T)) {
    if panic::catch_unwind(AssertUnwindSafe(|| read(&input))).is_err() {
        let shown = format!("{input:?}");
        let shown: String = shown.chars().take(4000).collect();
        panic!("reading this damaged file panicked:\n{shown}");
    }
}
}

Overflow is the kind of mistake it catches. A file whose key change sat at step 18446744073709551615, the largest usize, fails validation as it should, but writing the error message computed marker.start + 1 to say “step …”, and that overflowed. Rust treats overflow differently in the two build profiles. In a debug build, + panics on overflow (“attempt to add with overflow”). In a release build it wraps around to 0, silently. So a run in release mode over 15,000 damaged files saw nothing, and the same files in debug mode crashed. The messages use saturating_add(1), which stops at the largest number instead of overflowing, and CI runs the tests in debug mode (see How the code is tested).

In the app: the File menu

The app side is in crates/lineup-app/src/app/files.rs. Its first lines explain an unusual layout:

#![allow(unused)]
fn main() {
//! This is a child module of `app` (its file is `app/files.rs`), so it can
//! use the private fields of [`LineupApp`]: in Rust, private means "visible
//! in this module and the modules inside it".
}

app.rs declares mod files;, and Rust looks for that module in app/files.rs. The file holds another impl LineupApp block. A type can have any number of impl blocks, in any modules of its crate, so a big type can be split by topic. Being a child of app, files sees the private fields self.project, self.audio and so on, which a sibling module like playlist could not.

Choosing a file

File dialogs come from the rfd crate (“Rusty File Dialog”), which shows the system’s own dialog: GTK or KDE on Linux (through the desktop portal, or the zenity program), the Finder’s panel on macOS, the Explorer dialog on Windows.

#![allow(unused)]
fn main() {
fn project_dialog() -> rfd::FileDialog {
    rfd::FileDialog::new().add_filter(tr("Ferrous Lineup project"), &[file::EXTENSION])
}

if let Some(path) = project_dialog().pick_file() {
    self.open_now(path);
}
}

pick_file waits until the user picks a file or cancels, and returns an Option<PathBuf>. The window does not redraw while the dialog is open, but the music keeps playing, because it runs on the audio thread. On a Linux system with neither a portal nor zenity, pick_file returns None straight away; the dialog simply does not appear.

Save As gives the file a .lineup extension even if you type another one, so song.txt is saved as song.lineup, not as something that another importer would try to open.

“Save changes?”

How does the app know there are unsaved changes? It keeps a copy of the project as it was last opened or saved, and compares. But Project derives PartialEq, so != walks every channel, note and clip. That is cheap once, but a drag edits the project on every frame, and comparing the whole song every frame is wasted work. FileState therefore caches the answer:

#![allow(unused)]
fn main() {
/// Whether the project differs from `saved`, as last worked out.
dirty: bool,
/// Set when the project may differ from `saved`; `dirty` is worked
/// out again the next time it is asked for.
check_dirty: bool,
}

An edit sets check_dirty, but only if the project was not already dirty. While it is dirty, more frames of a drag do not ask for the whole comparison again:

#![allow(unused)]
fn main() {
pub(super) fn project_edited(&mut self) {
    if !self.dirty {
        self.check_dirty = true;
    }
}
}

A change made in one go (a click), an undo, a redo, and the end of a drag can all make the project match the saved copy again, so they always ask for a new comparison with project_reverted (see Telling the audio thread what changed). The cached answer is read every frame for the title, but the comparison itself runs only when the flag is set:

#![allow(unused)]
fn main() {
pub(super) fn has_unsaved_changes(&mut self) -> bool {
    if self.file.check_dirty {
        self.file.dirty = match &self.file.saved {
            Some(saved) => self.project != *saved,
            None => true, // recovered work has never been saved
        };
        self.file.check_dirty = false;
    }
    self.file.dirty
}
}

So a step clicked on and then off again clears the star, and so does a note dragged away and back, once you let go.

Anything that would throw the project away waits for an answer first:

#![allow(unused)]
fn main() {
pub(super) enum Pending {
    /// A chord sheet with a band.
    New,
    /// An empty pattern and a drum kit.
    NewBeat,
    Open,
    OpenPath(PathBuf),
    Demo(Demo),
    Import,
    ImportMidi,
    ImportChordSheet,
    Quit,
}

pub(super) fn request(&mut self, ctx: &egui::Context, action: Pending) {
    // ...a quit during an export asks about the export first...
    if self.has_unsaved_changes() || ... {
        self.file.pending = Some(action);
    } else {
        self.perform(ctx, action);
    }
}
}

While pending holds something, unsaved_changes_dialog shows an egui::Modal, a window that dims everything behind it and takes all the clicks:

Save saves and then carries out the waiting action, unless saving failed or the user cancelled the Save As dialog; Don’t save carries it out straight away; Cancel, Escape or a click outside forgets it. The pending value is the whole state machine: None means “nothing waiting”, Some(Pending::Open) means “the user wants to open a file, once they decide about the changes”.

pub(super) makes the enum visible to the parent module (app), which needs it for FileState, but no further.

The style editor has its own unsaved draft. Quitting with an edited draft asks Save style changes? as well, so saving the song never silently throws the style away.

Closing the window

Clicking the window’s × asks the operating system to close it. egui reports the request, and the app can say no:

#![allow(unused)]
fn main() {
let close_requested = ctx.input(|input| input.viewport().close_requested());
if close_requested
    && !self.file.quitting
    && (self.has_unsaved_changes() || self.style_editor.has_unsaved_changes())
{
    ctx.send_viewport_cmd(egui::ViewportCommand::CancelClose);
    self.file.pending = Some(Pending::Quit);
}
}

When the user then picks Save or Don’t save, perform(Pending::Quit) sets quitting and sends ViewportCommand::Close, which is let through this time.

Quitting while a WAV or video export is still running asks An export is still running, with Stop it and quit and Keep exporting. Stopping waits until the export has stopped and removed its unfinished file, and then closes, so a half-written file is never left behind looking finished.

Shortcuts

#![allow(unused)]
fn main() {
const SAVE: KeyboardShortcut = KeyboardShortcut::new(Modifiers::COMMAND, Key::S);
const SAVE_AS: KeyboardShortcut =
    KeyboardShortcut::new(Modifiers::COMMAND.plus(Modifiers::SHIFT), Key::S);

let pressed = |shortcut| ctx.input_mut(|input| input.consume_shortcut(&shortcut));
if pressed(SAVE_AS) {
    self.save_as();
} else if pressed(SAVE) {
    self.save();
}
}

• Modifiers::COMMAND is Ctrl on Linux and Windows and ⌘ on macOS, so each system gets the shortcut its users expect. The File menu shows the right one, too: “Ctrl+S” or “⌘S”.
• consume_shortcut checks the keys and removes them from the input, so a text field does not also see them.
• Ctrl+S would also match Ctrl+Shift+S (the extra Shift is ignored), so the longer shortcut is checked first.

These const values call KeyboardShortcut::new while compiling. That is allowed because egui marked it as a const fn, a function simple enough to run at compile time.

The title bar

The window title shows the song’s name and a star for unsaved changes, “song.lineup* · Ferrous Lineup”. A demo shows its own name and says it is read-only, “Für Elise (demo, read-only) · Ferrous Lineup”: demos are built into the app, so Save asks for a new file, as Save As does. The app sends a ViewportCommand::Title only when the text changes, not on every frame.

Opening a file from outside

#![allow(unused)]
fn main() {
let mut args = std::env::args_os().skip(1);
let first = args.next();
}

ferrous-lineup song.lineup starts with the song open, which is also what a file manager does when you double-click a file associated with the app. (The same first argument can instead be --trace, --demos or --help, which do their job without opening a window; see The playback trace.) args_os returns the arguments as OsStrings, exactly as the system gave them. std::env::args would panic on a file name that is not valid UTF-8, which Linux allows. skip(1) skips the first argument, which is the program’s own name.

A .lineup file dropped on the window is opened too, after the same “Save changes?” question, and a MIDI file, a chord sheet or a recording is imported. Other dropped WAV files go to the channel rack (see Importing recordings for which WAV is which).

File > Open recent

File > Open recent lists the last ten projects opened or saved, most recent first. The list is kept in egui’s stored data, so it survives a restart. Each item shows the file’s name, with the full path in its tooltip. Opening a file that no longer loads removes it from the list instead of leaving a dead entry.

The list holds paths, not copies of projects. If a project is moved or renamed outside the app, the old path stays until an attempt to open it fails.

A copy of unsaved work

The app writes a recovery copy of the project while it has unsaved changes. The first change writes one at once, so the first edit of a session is not the one a crash loses; after that it writes every thirty seconds:

#![allow(unused)]
fn main() {
/// How often unsaved work is written while it keeps changing.
const INTERVAL: Duration = Duration::from_secs(30);
}

A window left alone draws no frames, and so would never get round to writing. So when a copy is due, autosave asks egui for a frame at that moment with request_repaint_after: the copy catches up within about half a minute of a change, even if nobody touches the app.

The files are in a recovery folder inside the app’s data folder, the one eframe::storage_dir(APP_NAME) gives it. On Linux that is usually ~/.local/share/ferrouslineup/recovery. Each run of the app names its files after itself, such as 4211-1793047912612-0.lineup and 4211-1793047912612-0.info: the process number, the time it started in milliseconds, and a count. Why each run needs its own is in Two windows at once below. The copy is not written next to the project, because a project may be on a read-only medium, and an autosave file in a folder of songs would surprise anyone looking at it. The small .info file carries the project’s path and name, so a recovered song comes back as itself, not as “Untitled”.

The copy is written by file::save, which writes a temporary file and renames it. A crash in the middle leaves the previous copy whole; the info file is written after the project, so a crash between them loses the name rather than giving the project the wrong one.

At startup, if a copy is there, a modal asks Recover unsaved work? and names the song:

• Recover it puts the project back, with its path and name, and removes the copy. It also loads the file on disk, if it still exists, as the “saved” version, so the recovered work correctly shows the unsaved star; undoing back to the file clears it. If the file is gone, the recovered project is simply unsaved.
• Discard it removes the copy and leaves the project the app would otherwise have opened.

A clean exit removes the copy, because there is nothing to recover. The copy that remains is the sign of a crash, a kill, or a power cut. A copy whose project will not load is removed at startup rather than offered. A single recovery.lineup straight in the data folder, as older versions wrote it, is offered too.

Two windows at once

Nothing stops you from starting Ferrous Lineup twice. If every run wrote the same copy, the second window would find the first one’s copy at startup and offer it as if the first had crashed, while it was still open; and each window’s autosave would replace the other’s copy.

So each run writes its own copy, and next to it a third file, <run>.lock, which it locks before the first copy is written and holds while it runs. A file lock is a promise kept by the operating system: only one open file can hold it, and when the program that holds it ends, the system lets go of it, even in a crash or a power cut. That makes it the right question to ask at startup: “is the run that wrote this copy still going?” If its lock can be taken, it is not, and the copy is offered; if not, the copy belongs to a window that is still open and is left alone.

The standard library has had file locks since Rust 1.89 (File::lock, File::try_lock and friends). try_lock does not wait: it says at once whether it got the lock, and its error tells “someone else holds it” apart from “this system cannot lock files”:

#![allow(unused)]
fn main() {
fn take_lock(path: &Path) -> Lock {
    // A copy whose lock file is gone was left by a run that closed with
    // work unsaved: the file is made again, to be taken.
    let Ok(file) = OpenOptions::new()
        .create(true)
        .truncate(false)
        .write(true)
        .open(path)
    else {
        return Lock::Unknown;
    };
    match file.try_lock() {
        Ok(()) => Lock::Taken(file),
        Err(TryLockError::WouldBlock) => Lock::Held,
        Err(TryLockError::Error(_)) => Lock::Unknown,
    }
}
}

The lock lasts as long as the File value: dropping it lets go. So a window that finds a copy keeps the File in the Recovered value until you answer the question; a third window opened meanwhile cannot take the lock and does not offer the same copy twice. When the app closes, the Drop of Recovery removes its lock file; a copy of unsaved work stays, without its lock, to be offered next time. A system that cannot lock files (Lock::Unknown) offers the copy anyway: offering it twice loses nothing, never offering it would.

If two runs crashed, there are two copies. The newest is offered first, and the next waits until the work recovered before it is saved or let go, so recovering one never replaces another.

Drawing the windows with egui: layout, zoom, themes, icons

Files: crates/lineup-app/src/main.rs, crates/lineup-app/src/app.rs, crates/lineup-app/src/theme.rs, crates/lineup-app/src/widgets.rs, crates/lineup-app/src/icons.rs, crates/lineup-app/src/app/view.rs, crates/lineup-app/src/app/shortcuts.rs and crates/lineup-app/src/app/about.rs

The window is drawn with egui, a GUI library written in Rust, and eframe, egui’s framework for running it as a native app on Linux, macOS and Windows. This chapter is about how the main window is put together each frame, the look, how rows of controls fit any window size, the zooms, the windows that float over the playlist, and the Help menu. The editors themselves, the channel rack, the piano roll and the playlist, have the next chapter.

Immediate mode

Most GUI toolkits are retained mode: you create button objects once, keep them in a tree and attach callbacks to them. egui is immediate mode: on every frame, you call a function that describes the whole UI from your own data, and the library draws it and tells you what was clicked.

#![allow(unused)]
fn main() {
if ui.button("▶ Play").clicked() {
    self.set_playing(true);
}
}

That line both draws the button and checks whether it was clicked. There are no button objects to keep in sync with your state. The state is just the fields of your struct, and the UI is always a picture of it. This fits Rust nicely, because there are no callbacks holding references to your data.

The price is that a frame cannot go back. Something drawn early in the frame cannot know what is drawn later in it. Several pieces of this chapter (the hint bar, wrapping groups, zoom) solve that the same way: they use what the previous frame found, a sixtieth of a second old.

main.rs

fn main() -> eframe::Result {
    // The first command-line argument, if there is one, is a file to open,
    // or what to do instead of opening the window.
    let mut args = std::env::args_os().skip(1);
    let first = args.next();
    match first.as_ref().and_then(|arg| arg.to_str()) {
        Some("--trace") => std::process::exit(trace(args)),
        Some("--demos") => { /* print the demos' names */ return Ok(()); }
        Some("--help" | "-h") => { /* print how to use it */ return Ok(()); }
        _ => {}
    }
    let path = first.map(PathBuf::from);

    let mut viewport = eframe::egui::ViewportBuilder::default()
        .with_title(app::APP_NAME)
        .with_inner_size([1280.0, 800.0])
        .with_min_inner_size([800.0, 520.0])
        .with_icon(window_icon());
    // ...inside a Flatpak, the window takes the sandbox's app id...

    let options = eframe::NativeOptions {
        viewport,
        ..Default::default()
    };

    eframe::run_native(
        app::APP_NAME,
        options,
        Box::new(|cc| Ok(Box::new(app::LineupApp::new(cc, path)))),
    )
}

• main returns a Result. If it returns Err, Rust prints the error and exits with a failure code.
• ViewportBuilder::default().with_title(...) is the builder pattern: each method takes the builder and returns it modified, so calls chain.
• ..Default::default() is struct update syntax: “every field I did not list takes its default value”.
• Box::new(|cc| ...) passes a closure that eframe calls once to create our app. Box puts a value on the heap. It is needed here because eframe accepts any type implementing its App trait, and to store a value whose exact type it does not know, it needs a pointer to it: Box<dyn App>. The dyn keyword means “some type implementing this trait, decided at run time” (a trait object).
• "--help" | "-h" is an or-pattern: the arm matches either string.

LineupApp: the state

LineupApp holds everything the window needs: the project, the undo history, the open windows and their own state, the file, the settings, and the connection to the audio thread. That connection is an enum:

#![allow(unused)]
fn main() {
enum Audio {
    /// Boxed: the engine is much bigger than a `String`, and every
    /// `Audio` would otherwise take as much room as the biggest variant.
    Running(Box<AudioEngine>),
    Unavailable(String),
}
}

It captures a real situation: either there is a running engine, or there is the reason there is not. You cannot have both, and you cannot have neither, so the type cannot represent an impossible state. Compare that with the usual alternative, an Option<AudioEngine> plus an Option<String>, which allows four combinations of which two make no sense.

An enum is as big as its biggest variant, plus room to say which one it is. Box keeps the big engine on the heap, so Audio is the size of a pointer or a String, whichever is bigger. Clippy points this out with its large_enum_variant lint.

Using it:

#![allow(unused)]
fn main() {
fn send(&mut self, command: Command) {
    if let Audio::Running(engine) = &mut self.audio {
        engine.send(command);
    }
}
}

if let is a one-arm match: if self.audio is Running, bind the engine inside to engine and run the block. Matching on &mut self.audio borrows the engine mutably instead of moving it out of the struct.

If the computer has no working sound card, the app still opens and the status bar says why in orange: “Audio unavailable: …”. A failure becomes data we display, rather than a crash.

One frame

eframe calls ui every time the window needs repainting:

#![allow(unused)]
fn main() {
impl eframe::App for LineupApp {
    fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) {
        if let Audio::Running(engine) = &mut self.audio {
            engine.collect_garbage();
        }
        self.check_trace();
        let ctx = ui.ctx().clone();
        self.before_drawing(&ctx);
        self.panels(ui, &ctx);
        let playing = self.song_position().filter(|_| self.playing);
        let area = self.main_area(ui, &ctx, playing);

        // The channel rack and the piano roll float on top of the playlist.
        let playhead = self.pattern_playhead();
        self.bring_window_to_front(&ctx);
        self.rack_window(&ctx, area, playhead);
        self.piano_roll_window(&ctx, area, playhead);
        // The chord sheet is drawn last, so it opens over the others.
        self.chord_sheet_window(&ctx, area, playing);
        // ...ear training, the lead sheet, the mixer, the shortcuts,
        // About, the style editor, Settings and the dialogs...
        self.unsaved_changes_dialog(&ctx);
        self.update_title(&ctx);
        self.end_frame_for_undo(&ctx);
    }

    fn on_exit(&mut self) {
        self.forget_recovery();
    }
}
}

The order is the design:

1. collect_garbage frees what the audio thread sent back (see The trash queue).
2. before_drawing does everything that must happen before anything is drawn: it notes whether a click is closing a menu, sets the language and the note names for the frame, closes an undo step on a mouse press, writes the recovery copy when due, reads the keyboard shortcuts and the zoom keys, reads MIDI input, and checks on exports and imports running in the background. While playing it asks egui for another frame at once (ctx.request_repaint()), so the playhead moves; otherwise egui draws only when something happens.
3. panels draws the bars along the edges: the menus with the hint bar, the toolbar, the status bar, and the harmony keys. Panels must come before the central area, which takes whatever space is left.
4. main_area draws the playlist (or the chord sheet, when it fills the main window) and returns the rectangle it took.
5. The windows float over that rectangle. Windows drawn later are on top, so the chord sheet comes last of the three editors.
6. end_frame_for_undo decides whether the undo step ends (see Undo and redo).

on_exit runs once when the app closes cleanly: there is no unsaved work to recover, so this run’s recovery copy goes.

The many self.something(ui) methods keep ui short. Each closure passed to a panel can borrow self mutably, because each one runs and finishes before the next starts, which the borrow checker can see.

A theme is one function

egui draws every widget from a Style: colours in style.visuals, sizes and gaps in style.spacing. Nothing is painted with a hard-coded colour unless the code asks for one. So the whole look is one function, theme::apply, called once when the app starts:

#![allow(unused)]
fn main() {
pub fn apply(ctx: &egui::Context) {
    ctx.set_theme(egui::Theme::Dark);
    ctx.style_mut_of(egui::Theme::Dark, |style| {
        let visuals = &mut style.visuals;
        visuals.panel_fill = PANEL;
        visuals.window_fill = WINDOW;
        visuals.selection.bg_fill = ACCENT; // selected and switched-on things
        visuals.selection.stroke = Stroke::new(1.0, ON_ACCENT);
        // ...shadows, corners, warning and error colours...
        let widgets = &mut visuals.widgets;
        for (state, fill) in [
            (&mut widgets.inactive, BUTTON),
            (&mut widgets.hovered, BUTTON_HOVER),
            (&mut widgets.active, BUTTON_PRESSED),
            (&mut widgets.open, BUTTON_HOVER),
        ] {
            state.bg_fill = fill;
            state.weak_bg_fill = fill;
            state.bg_stroke = Stroke::new(1.0, OUTLINE);
            // ...
        }
        // ...spacing...
    });
}
}

The look borrows from pattern-based studios: dark blue-grey panels, raised grey buttons, an orange light for whatever is selected or switched on, and black “LCD” displays for numbers such as the tempo. Three things to notice in the code:

• style_mut_of(Theme::Dark, ...) changes the dark style only. egui keeps one style for dark and one for light, and the app always uses dark.
• The for loop walks an array of pairs of mutable references. Each &mut widgets.inactive borrows a different field, so Rust allows several of them at once: the borrow checker tracks fields of a struct separately.
• The colours are const items: Color32::from_rgb is a const fn, so it runs at compile time and costs nothing when the app runs.

Views still have their own constants for the things only they draw (the playlist’s rows, the piano roll’s keys, the step buttons), with values that match the theme.

Changing the style for a few widgets

The tempo display is a DragValue, egui’s number you drag or type, but drawn black with green-blue digits. Its style is changed only inside its frame:

#![allow(unused)]
fn main() {
pub fn lcd_frame(
    ui: &mut Ui,
    label: &str,
    width: f32,
    add: impl FnOnce(&mut Ui) -> Response,
) -> Response {
    wrapping(ui, |ui| {
        egui::Frame::new()
            .fill(LCD)
            // ...
            .show(ui, |ui| {
                // ...the label above, written smaller if it is long...
                ui.vertical(|ui| {
                    ui.label(label);
                    let visuals = &mut ui.visuals_mut().widgets;
                    for state in [&mut visuals.inactive, &mut visuals.hovered, &mut visuals.active] {
                        state.bg_fill = LCD;
                        state.fg_stroke.color = LCD_TEXT;
                        // ...
                    }
                    ui.style_mut().override_font_id = Some(FontId::monospace(16.0));
                    add(ui)
                })
                .inner
            })
    })
    .inner
}
}

Every Ui has its own copy of the style (an Arc<Style>; style_mut makes a private copy the first time it is changed). The frame’s contents get a child Ui, so the change stays inside the frame and the rest of the toolbar is untouched. add is a closure that returns the widget’s Response, so the caller can still ask changed() outside:

#![allow(unused)]
fn main() {
let tempo = theme::lcd_frame(ui, tr("TEMPO"), 62.0, |ui| {
    ui.add(egui::DragValue::new(&mut bpm).range(Tempo::MIN..=Tempo::MAX))
});
}

Tempo’s field is private, so the value is copied into a local bpm, the widget edits that, and a new Tempo is built if it changed. The Tempo stays valid whatever is typed. Tempo::MIN..=Tempo::MAX is an inclusive range: a..b leaves b out, a..=b keeps it.

A label longer than the display, as some are in Spanish, is written a little smaller to fit, so the toolbar keeps its width in every language.

The hint bar: a message from the future

Next to the menus, a line says what the control under the mouse does. That line is drawn first, at the top of the window, but the widgets that know what the mouse is on are drawn later in the same frame. In immediate mode there is no going back to repaint the bar.

So the bar shows what was found on the previous frame. Widgets leave their hint in egui’s memory, ctx.data, which is a map from an Id to a value of any type:

#![allow(unused)]
fn main() {
pub fn hint(response: Response, text: impl Into<String>) -> Response {
    let text = text.into();
    if response.hovered() {
        response
            .ctx
            .data_mut(|data| data.insert_temp(hint_id(), text.clone()));
    }
    response.on_hover_text(text)
}
}

At the start of the next frame, the bar takes it out, so it does not linger once the mouse moves away:

#![allow(unused)]
fn main() {
pub fn start_frame(&mut self, ctx: &egui::Context) {
    let text = ctx.data_mut(|data| data.remove_temp::<String>(hint_id()));
    if text != self.text {
        // The mouse moved onto or off a widget: draw once more, so the
        // bar does not lag a frame behind until the next event.
        ctx.request_repaint();
    }
    self.text = text;
}
}

remove_temp::<String> uses the turbofish ::<String> to say which type to take out: the map can hold values of many types under the same Id. The request_repaint is the subtle part. egui only draws a frame when something happens. When the mouse moves onto a button, that frame records the hint, but the bar still shows the old one. Asking for one more frame shows the new hint straight away, instead of whenever the mouse next moves.

Rows that fit any window

The toolbar holds the play mode, the transport, the tempo and position displays, the pattern selector, the five window buttons, the count-in, the metronome and the master volume. In a window 1280 points wide it fits on one row; a test, the_toolbar_fits_on_one_row_at_1280_points, checks that it stays so. A narrower or zoomed window must still reach every control.

egui lays widgets out one after another. ui.horizontal puts them in a row and keeps going past the edge if they do not fit: whatever is past the edge is still there, just not drawn. ui.horizontal_wrapped is the same row, except that a widget that would not fit starts a new row. The toolbar and the harmony keys bar are wrapping rows, so on a narrow window the second part of them moves down.

Groups that wrap: last frame’s width

The toolbar’s buttons are in groups, each inside a dark frame. A wrapping row decides to wrap by asking a widget how big it wants to be before placing it. A frame cannot answer that: Frame::show draws its contents into whatever room is left, and only knows its size afterwards. So theme::wrapping uses the frame before. egui redraws the window many times a second, so last time’s width is a very good guess:

#![allow(unused)]
fn main() {
let id = ui.next_auto_id().with("wrapping");
let last_width = ui.ctx().data(|data| data.get_temp::<f32>(id)).or(guess);
let row_started = ui.cursor().min.x > ui.max_rect().min.x;
if let Some(width) = last_width
    && ui.layout().main_wrap
    && row_started
    && width > ui.available_size_before_wrap().x
{
    ui.end_row();
}
let response = add(ui);
let width = response.response.rect.width();
ui.ctx().data_mut(|data| data.insert_temp(id, width));
}

• ui.next_auto_id() is the id egui would give the next widget. It depends on how many widgets came before in this Ui, so it is the same every frame as long as the toolbar is drawn in the same order. That makes it a key for remembering something about one group.
• get_temp::<f32> asks egui’s memory for an f32; the turbofish tells Rust which type to look for, because nothing else in the line says so.
• The if let ... && ... chain (a “let chain”) only runs end_row when there is a width from last time, the layout wraps, the row already has something in it, and the group does not fit. The very first frame has no width yet, so the group may stick out for one frame, which nobody sees.

theme::group and lcd_frame wrap their frames in it, and keep_together offers the same to any group of widgets, with a guess for the very first frame. That first frame matters inside a window: egui windows grow to fit their contents, and a single frame of contents that is too wide is enough to widen a window for good. The piano roll’s toolbar keeps its groups together this way, so a long scale name (F# major’s “F# G# A# B C# D# E#”) moves its group to a second row instead of widening the window.

Text that gets shorter, and right to left

Wrapping suits buttons. For a long line of text, like a status message, it is often better to cut it short. Every text in egui has a wrap mode: Wrap breaks it onto more lines, Truncate cuts it with “…”, and Extend lets it run on. A whole area can set it for all its text through its style:

#![allow(unused)]
fn main() {
ui.style_mut().wrap_mode = Some(egui::TextWrapMode::Truncate);
}

A truncated label shows the whole text when you point at it, so nothing is lost.

The status bar has two parts: messages on the left, and the playlist’s zoom controls on the right. If the messages were drawn first, a long one (“Audio unavailable: could not read the device settings…”) would take all the room and push the zoom out. So the bar is laid out right to left: the zoom goes in first, from the right edge, and the messages get whatever is left:

#![allow(unused)]
fn main() {
fn status_bar(&self, ui: &mut egui::Ui) {
    ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
        view::zoom_control(ui);
        ui.separator();
        ui.with_layout(egui::Layout::left_to_right(egui::Align::Center), |ui| {
            ui.style_mut().wrap_mode = Some(egui::TextWrapMode::Truncate);
            self.status_messages(ui);
        });
    });
}
}

In a right-to-left layout the first widget is the rightmost one, which is why zoom_control adds its + button before the percentage and the − button.

Zoom

There are two kinds of zoom.

The interface size makes everything bigger or smaller: text, buttons, menus. egui draws in points, not pixels. How many pixels a point takes is pixels_per_point: the screen’s own scale (1.0, 1.5 or 2.0 on most screens) times egui’s zoom factor. ctx.set_zoom_factor changes the second.

The areas zoom what they draw without changing the text. As in most music programs, the playlist and the piano roll zoom their two directions separately: horizontal zoom makes bars and steps wider (less time on screen, in more detail), vertical zoom makes tracks and piano keys taller. The channel rack’s steps are square buttons, so it has one zoom for both.

What is under the pointer?

The keys and the wheel zoom what the pointer is over. In Rust, “one of these kinds” is an enum, and a variant can carry a value:

#![allow(unused)]
fn main() {
pub(crate) enum Target {
    Area(Area), // Area::Main (the playlist), Area::Rack, Area::PianoRoll
    Interface,
}
}

Target::at finds it. egui keeps a stack of layers: the background where the panels are drawn, then each window above it, then menus and tooltips. ctx.layer_id_at(pos) says which layer is on top at a point:

#![allow(unused)]
fn main() {
fn at(ctx: &egui::Context, pos: egui::Pos2, playlist: egui::Rect) -> Target {
    match ctx.layer_id_at(pos) {
        Some(layer) if layer.id == super::rack_id() => Target::Area(Area::Rack),
        Some(layer) if layer.id == PianoRoll::id() => Target::Area(Area::PianoRoll),
        Some(layer) if layer.order == egui::Order::Background && playlist.contains(pos) => {
            Target::Area(Area::Main)
        }
        _ => Target::Interface,
    }
}
}

Each arm has a match guard, the if after the pattern. The pattern Some(layer) matches any layer, and the arm is only taken if the guard is true too; otherwise match tries the next arm. The last arm, _, catches everything left.

The toolbars, the harmony keys and the playlist are all drawn on the same background layer, so the layer alone cannot tell them apart. The playlist therefore remembers where it was drawn, and the guard checks playlist.contains(pos). The zoom keys are read at the start of a frame, before anything is drawn, so this is the rectangle from the previous frame. If the pointer is outside the window, the keys zoom what was clicked last.

The chord sheet is text, so it follows the interface size, in its own window or in the playlist’s place. In the playlist’s place it covers the playlist, and the playlist’s last rectangle would be a lie, so zoom_shortcuts passes an empty one instead:

#![allow(unused)]
fn main() {
let playlist = match self.chord_sheet.fills_window() {
    true => egui::Rect::NOTHING,
    false => self.playlist.area(),
};
}

Rect::NOTHING contains no point, so the guard is never true, and the keys fall through to Target::Interface.

Every way of zooming (keys, wheel, touchpad pinch) calls the same few methods on Target, and only they look at which kind it is:

#![allow(unused)]
fn main() {
fn step(self, ctx: &egui::Context, axis: Axis, bigger: bool) {
    match self {
        Target::Area(area) => area.step_zoom(ctx, axis, bigger),
        Target::Interface => {
            ctx.set_zoom_factor(interface_step(ctx.zoom_factor(), bigger));
        }
    }
}
}

Target::Area(area) both checks the variant and takes the Area out of it into the variable area. The interface has a single size, so axis is not used there: Ctrl and Alt do the same.

A zoom per area and per axis

Each area keeps one number per direction, in egui’s memory, under a key made of both:

#![allow(unused)]
fn main() {
fn key(self, axis: Axis) -> egui::Id {
    let axis = if self.two_way() { axis } else { Axis::Horizontal };
    egui::Id::unique(("zoom-2", self, axis))
}
}

The rack is not two_way, so both its axes share the horizontal key: zooming it “vertically” zooms it both ways. The values are stored with insert_persisted, so egui saves them with the window positions and they are the same the next time the app starts. The "zoom-2" name is there because an older meaning of “zoom” (a scale for everything in the window, text included) was saved under "zoom": a new name means old values are simply not found, instead of being read the wrong way.

Every way of zooming in steps goes through step_zoom, which walks a ladder of sizes:

#![allow(unused)]
fn main() {
const STEPS: [f32; 19] = [
    0.25, 0.33, 0.4, 0.5, 0.6, 0.75, 0.9, 1.0, 1.1, 1.25, 1.5, 1.75, 2.0, 2.5, 3.0, 4.0, 5.0, 6.0,
    8.0,
];
}

Each step is roughly a fifth bigger than the one before, so it takes as many steps to go from 100% to 200% as from 400% to 800%. That is how zoom feels natural: our eyes compare sizes by ratio, not by difference. Each area and axis has its own range within the ladder (tracks and keys can only get so short before their names no longer fit), and the buttons are greyed out at the ends. The interface sizes are a shorter list of their own, 50% to 250%, the same ones Settings > Appearance offers.

Reading the wheel ourselves

egui gives a single zoom_delta() for Ctrl+wheel, with no idea of direction. So the app reads the frame’s raw wheel events and sorts them by the modifier keys held:

#![allow(unused)]
fn main() {
for event in &input.raw.events {
    if let egui::Event::MouseWheel { unit, delta, modifiers, .. } = event {
        // Up or right zooms in. Shift turns a wheel sideways.
        let amount = if delta.y != 0.0 { delta.y } else { delta.x };
        if modifiers.alt {
            tall.add(*unit, amount);
        } else if modifiers.command {
            wide.add(*unit, amount);
        }
    }
}
}

if let with a pattern is how Rust picks one variant out of an enum and names its fields at the same time; .. ignores the fields we do not need.

On Linux (X11), one notch of the wheel sometimes arrives as two events, and zooming two steps per notch feels jumpy. So the notches are added up and zoom at most one step per frame:

#![allow(unused)]
fn main() {
fn apply(self, target: Target, ctx: &egui::Context, axis: Axis) {
    if self.notches != 0.0 {
        target.step(ctx, axis, self.notches > 0.0);
    }
    if self.smooth != 1.0 {
        target.scale(ctx, axis, self.smooth);
    }
}
}

A frame lasts a few milliseconds, so turning the wheel quickly still zooms step by step. A touchpad sends many tiny movements instead of notches (MouseWheelUnit::Point); those multiply the zoom smoothly.

Zooming into what you point at

When the zoom changes, the step and the note under the pointer must stay under the pointer. The grid is inside a scroll area, so this means choosing a new scroll offset. The thing under the pointer is at from + anchor in the contents, where from is how far the view is scrolled and anchor is where the pointer is in the view. Zooming by ratio moves it to (from + anchor) * ratio. For it to stay under the pointer, the new scroll must be that minus anchor. In the piano roll:

#![allow(unused)]
fn main() {
let x = KEY_WIDTH + (from.x + anchor.x - KEY_WIDTH) * ratio.x - anchor.x;
let y = (from.y + anchor.y) * ratio.y - anchor.y;
self.scroll_to = Some(vec2(x.max(0.0), y.max(0.0)));
}

The KEY_WIDTH terms are there because the piano keyboard at the left does not stretch: only what is right of it grows.

One more thing had to be turned off. egui’s scroll areas have a rubber band: scroll past the end, and the view springs back. On the frame of a zoom, the scroll area still knows the old size of the contents, so the new offset looks like scrolling past the end, and the view would slide back after each zoom. widgets::no_rubber_band turns it off for the grids:

#![allow(unused)]
fn main() {
pub fn no_rubber_band(ui: &mut egui::Ui) {
    ui.spacing_mut().scroll.kinetic.rubber_band = false;
}
}

The channel rack is drawn with ordinary egui widgets, which have no zoom of their own. widgets::zoom_contents makes them bigger by multiplying the text sizes and the spacing of the window’s style, as lcd_frame changes its colours: only inside the rack.

Windows over the playlist

The channel rack, the piano roll, the chord sheet, the mixer and the others are egui::Windows, which float over everything. They are kept inside the playlist’s rectangle with Window::constrain_to(area), so a window never hides the toolbar, the harmony keys or the status bar:

#![allow(unused)]
fn main() {
let playlist = egui::CentralPanel::default_margins().show(ui, |ui| { /* ... */ });
let area = playlist.response.rect;
}

Every show in egui returns an InnerResponse: .inner is what the closure returned (here the playlist’s actions) and .response tells where it was drawn.

Which windows a song opens on

What you study in a song is its bars and chords; what you edit in a beat is the steps of a pattern. So the app decides what to show by what was opened:

#![allow(unused)]
fn main() {
/// What a song opens on: the chord sheet in front, since its bars and
/// chords are what you study and write in a song, and the rack out of
/// the way (F6 brings it back).
fn show_chord_sheet(&mut self) {
    self.chord_sheet.open = true;
    self.rack_open = false;
    self.bring_to_front = Some(chord_sheet::window_id());
}

/// What a beat opens on: the rack in front, and no chord sheet.
fn show_beat(&mut self) {
    self.chord_sheet.open = false;
    self.show_rack();
}
}

Song demos, File > New and an imported chord sheet call show_chord_sheet; File > New beat calls show_beat. Opening a saved file leaves the windows as they are, since you chose them yourself. A demo is a song or a style, an enum, and only the songs open on the sheet:

#![allow(unused)]
fn main() {
if let Demo::Song(_) = demo {
    self.show_chord_sheet();
}
}

The app itself opens on the windows that were open when it was last closed. app/windows.rs keeps them as one small struct of bools, one for each window of the View menu:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub(super) struct OpenWindows {
    chord_sheet: bool,
    lead_sheet: bool,
    rack: bool,
    piano_roll: bool,
    harmony_keys: bool,
    /// The Patterns and Library panel.
    browser: bool,
    mixer: bool,
    ear_training: bool,
}
}

Its Default is the first time: the chord sheet, the harmony keys and the Library over the playlist, with no rack. #[serde(default)] on the struct fills a window added to the list later with its value in Default, so an older save still reads. The style editor and the dialogs are left out: each opens for something, a style or a question, that the next run does not have.

App::save, which eframe calls every 30 seconds and when the window closes, writes the struct among the preferences kept by name (see Kept by name, not by type), and LineupApp::new reads it back:

#![allow(unused)]
fn main() {
fn save(&mut self, storage: &mut dyn eframe::Storage) {
    self.preferences.put(windows::NAME, &self.open_windows());
    self.preferences.save(storage);
}
}

#![allow(unused)]
fn main() {
let windows: OpenWindows = preferences::get(ctx, NAME).unwrap_or_default();
}

Writing them only on save, rather than at every click on a window button, keeps the many places that open and close windows free of that chore. the_app_first_opens_on_the_chord_sheet_then_with_the_windows_left_open checks both runs: the first opens on the sheet, and after closing it with F5 and opening the mixer with F9, the next start finds the mixer open and the sheet closed.

Windows the size of what they show

egui remembers each window’s size, and saves it with the rest of its memory when the app closes. That is right for a window you work in, like the piano roll: you made it big because you wanted it big. It is wrong for a window that is as big as what it shows: drag the mixer wide once, and it would open across the whole playlist ever after, with its channels in one corner. So there are two kinds of window:

#![allow(unused)]
fn main() {
pub enum Opening {
    /// Each time it opens: a window as big as what it shows.
    EveryTime,
    /// The first time it opens after the app starts: a window to work
    /// in, which keeps the size you give it while the app runs.
    FirstTime,
}
}

The mixer, the shortcuts list, ear training, the twelve-tone row, the pitch-class sets and the micromodes open every time at the size of their contents, up to the height of the playlist, and scroll past that. The piano roll, the chord sheet, the lead sheet and Settings open at their own size the first time after the app starts, and keep a size you give them while it runs.

widgets::open_at does it. It finds out whether the window is opening now (it was not drawn in the last frame), and if so gives it a fixed size for that one frame:

#![allow(unused)]
fn main() {
let first = ctx.data_mut(|data| {
    !std::mem::replace(data.get_temp_mut_or(id.with("has-opened"), false), true)
});
if opens(ctx, id) && (first || opening == Opening::EveryTime) {
    ctx.request_discard("a window opens at its own size");
    window.fixed_size(size)
} else {
    window
}
}

Three things in it are worth a look:

• std::mem::replace(place, new) puts new in place and returns what was there. Here it reads “had this window opened before?” and marks it as opened, in one step. The flag is stored with get_temp_mut_or, which egui does not save, so it is false again each time the app starts.
• egui lays a window out as it draws it, so on its first frame the window is drawn before anything knows how big its contents are. request_discard asks egui to throw that frame away and draw it again; you only see the second one, already at the right size.
• The “size” given is a narrow width and the greatest height. egui grows a window to fit wider contents but never makes it taller than they are, so the window ends up exactly as big as what it shows. For that to work, nothing in it may fill all the room it is given, such as a scroll area that does not shrink to its contents.

A window whose contents change while it is open, like the mixer when a channel is added or the rack when another pattern has fewer channels, is fitted again with fit_when_changed. It hashes a summary of the contents (each channel’s name and instrument, say) and fits the window again when the hash changes.

Clicks that do what you meant

Two helpers in widgets.rs make the grids react to the click you meant.

A quick tap. On a touchpad, a tap can press and release the button within one frame. egui’s press_origin() is forgotten as soon as the button is up, so on that frame it is None. press_pos reads the press from the frame’s list of events instead, which also says where the button went down, not where the pointer is at the end of the frame:

#![allow(unused)]
fn main() {
pub fn press_pos(
    input: &egui::InputState,
    only: Option<egui::PointerButton>,
) -> Option<egui::Pos2> {
    input.events.iter().find_map(|event| match *event {
        egui::Event::PointerButton { pos, button, pressed: true, .. }
            if only.is_none_or(|only| only == button) => Some(pos),
        _ => None,
    })
}
}

find_map walks the events until the closure returns Some, and returns that. Option::is_none_or reads well here: “no button was asked for, or it is this one”.

A click that closes a menu. Open a drop-down list, then click on the grid to close it: egui closes the menu, but the click also reaches the grid, which would draw a note, place a clip or turn on a step. In most programs that click only closes the menu. So at the start of each frame, before anything is drawn and while a menu that will close is still open, the app remembers whether the button now down went down while a menu was open:

#![allow(unused)]
fn main() {
pub fn track_dismissing(ctx: &egui::Context) {
    let id = dismissing_id();
    let (pressed, down, released) = ctx.input(|input| {
        (
            press_pos(input, None).is_some(),
            input.pointer.any_down(),
            input.pointer.any_released(),
        )
    });
    let open = egui::Popup::is_any_open(ctx);
    ctx.data_mut(|data| {
        let dismissing = data.get_temp_mut_or(id, false);
        if pressed {
            *dismissing = open;
        } else if !down && !released {
            *dismissing = false;
        }
    });
}
}

The grids ask dismissing(ctx) and ignore the press, the drag and the release that belong to it. The value lives in egui’s temporary memory, a handy place for a little state shared between widgets that do not know each other.

Remembering between runs

egui keeps some state of its own between frames in its memory: the zoom factor, where each window is, how wide a resizable panel is. eframe can save that memory when the app closes and load it when it starts. It does so only with its persistence feature, which is off by default because it brings in serde and ron. Turning it on is one line in the workspace’s Cargo.toml:

eframe = { version = "0.37", features = ["persistence"] }

With it, eframe also remembers the size and position of the main window. It writes a file called app.ron in the place each system keeps app data (on Linux, ~/.local/share/ferrouslineup/), every 30 seconds and when the window closes.

The app keeps most of its own lasting choices in the same memory, with insert_persisted instead of insert_temp: the area zooms, the settings, the recent files, the library’s filters. Each module stores its own under an Id of its own, and eframe saves them all together. Anything kept with insert_temp is forgotten when the app closes.

Kept by name, not by type

egui finds a value in its memory by two things: the Id it was stored under and its Rust type, through the type’s TypeId. A TypeId is a number the compiler works out from the type’s path, its fields and the crate it is in, and the crate’s part changes with the crate’s version and with the version of the compiler. So after an update of the app, or a build with a newer Rust, or a field added to the type, get_persisted looks under a new number and finds nothing: the setting is back to its default, and the old value sits unread in app.ron. The SoundFont showed it: with the same app.ron, version 0.4.0 played from GeneralUser GS and a build numbered 0.4.1 had it off.

eframe has a storage of its own, the same app.ron, which finds values by a name: a &str that stays the same whatever the version. eframe hands it to the app only twice: as cc.storage when the app starts, and to App::save, every 30 seconds and when the window closes. The module app/preferences.rs bridges the two. It keeps every preference by name, written as RON text, in one map:

#![allow(unused)]
fn main() {
/// Each preference by name, written as RON. egui's context holds one
/// handle to the map and the app another, to save it.
#[derive(Clone, Default)]
pub(super) struct Preferences(Arc<Mutex<BTreeMap<String, String>>>);
}

A handle to the map lives in egui’s temporary memory, so any code with the Context reaches it, as with any other value kept there:

#![allow(unused)]
fn main() {
/// The preference kept as `name`, if there is one and it can be read.
pub(super) fn get<T: DeserializeOwned>(ctx: &egui::Context, name: &str) -> Option<T> {
    let text = Preferences::of(ctx).map().get(name).cloned()?;
    ron::from_str(&text).ok()
}

/// Keeps `value` as the preference `name`.
pub(super) fn set<T: Serialize>(ctx: &egui::Context, name: &str, value: &T) {
    if let Ok(text) = ron::to_string(value) {
        Preferences::of(ctx).map().insert(name.to_string(), text);
    }
}
}

The app reads the map from eframe’s storage before anything else is made,

#![allow(unused)]
fn main() {
if let Some(storage) = cc.storage {
    preferences::Preferences::of(&cc.egui_ctx).load(storage);
}
}

keeps another handle to it, and gives it back to eframe to write:

#![allow(unused)]
fn main() {
fn save(&mut self, storage: &mut dyn eframe::Storage) {
    self.preferences.save(storage);
}
}

The Arc<Mutex<…>> lets both handles share one map. The lock is held only while a line is read or written, and only the window’s thread takes it. Because the values are RON text until they are asked for, a type can change its fields and still read what an older version kept, with #[serde(default)] for fields that were not there yet.

The sound settings (SoundFonts) are kept this way, as "sound-font", and so are the open windows, as "open-windows". The other choices above are still in egui’s memory, so an update can forget them; moving one over is a matter of calling preferences::get and preferences::set with a name instead of get_persisted and insert_persisted with an Id.

Cargo features

A feature is a switch a crate offers to turn on optional code. Inside eframe the code that saves memory sits behind #[cfg(feature = "persistence")], so without the feature it is not even compiled. Turning on a feature in one crate can turn on features in others: eframe’s persistence turns on egui’s, which adds serde derives to the types egui keeps in its memory. You can see what a crate offers in the [features] table of its Cargo.toml, or on its page on docs.rs.

Pictures painted, not typed

The toolbar’s five window buttons and the count-in and metronome toggles are square buttons with a picture; the name, what the window shows and its key appear when the mouse is over one. An emoji would be the easy way to draw such a picture, but an emoji is a character, drawn by a font, and some systems have no font with those characters: there the buttons would show empty boxes. So the pictures in icons.rs are painted, with lines, rectangles and polygons, the same way on every system.

Each picture is a plain function with the same signature, and Rust can name that signature as a type:

#![allow(unused)]
fn main() {
/// A picture: drawn by a function of the painter, the square it fills
/// and the colour to draw it in.
pub type Picture = fn(&Painter, Rect, Color32);
}

fn(&Painter, Rect, Color32) is a function pointer type. Any function with that signature can be stored in a variable of type Picture, put in an array, or passed to another function, without a Box or a generic.

Each picture is drawn in a square, and its points are given as fractions of the square, from 0 to 1, so the same picture can be drawn at any size:

#![allow(unused)]
fn main() {
/// The point `x`, `y` of the way across and down `rect`, each from 0 to 1.
fn at(rect: Rect, x: f32, y: f32) -> Pos2 {
    rect.min + vec2(x * rect.width(), y * rect.height())
}

/// The mixer: three faders, each at its own level.
pub fn mixer(painter: &Painter, rect: Rect, color: Color32) {
    for (x, level) in [(0.2, 0.62), (0.5, 0.3), (0.8, 0.5)] {
        line(painter, rect, (x, 0.0), (x, 1.0), color.gamma_multiply(0.6));
        let knob = Rect::from_center_size(at(rect, x, level), vec2(6.0, 3.5));
        painter.rect_filled(knob, 1.0, color);
    }
}
}

The chord sheet is a page with chord names two to a line, the rack three rows of steps with some lit, the piano roll a keyboard with three notes, the harmony keys a keyboard with two black keys, the metronome its body and arm.

The toolbar draws its five window buttons from an array. Each entry holds the name, the bool that says whether that window is open, the picture and the hint:

#![allow(unused)]
fn main() {
let windows: [(&str, &mut bool, icons::Picture, &str); 5] = [
    ("Chord sheet", &mut self.chord_sheet.open, icons::chord_sheet,
     "the song's harmony bar by bar, to read and write (F5)"),
    ("Channel rack", &mut self.rack_open, icons::rack,
     "the steps of the selected pattern (F6)"),
    // … the piano roll, the harmony keys, the mixer
];
for (name, open, picture, about) in windows {
    let button = icons::toggle(ui, name, *open, picture);
    // ...the hint, and a click opens or closes the window...
}
}

There are five &mut borrows of self in one array. The borrow checker allows it because each one borrows a different field: self.chord_sheet.open, self.rack_open, self.piano_roll.open and so on. Two &mut to the same field would not compile.

The test every_picture_stays_in_its_square paints each picture into a 16-point square and checks that no shape goes outside it, and the_window_buttons_open_and_close_their_windows clicks each of the five and checks that its window opens, that the button lights, and that a second click closes it.

Every key in a list

Help > Keyboard shortcuts, or F1, opens a window with every key the app answers to, section by section.

The list is data: a Vec of sections, each with a title, a note on when its keys work and its lines. A line’s keys are one of four kinds:

#![allow(unused)]
fn main() {
enum Keys {
    /// Any of these does it.
    Any(Vec<KeyboardShortcut>),
    /// The first does the first half of what the line says, the second the
    /// second: "Up / down".
    Pair(KeyboardShortcut, KeyboardShortcut),
    /// The mouse wheel, turned while holding these.
    Wheel(Modifiers),
    /// Keys that are not one shortcut, written out.
    Written(&'static str),
}
}

Wherever the app has a constant for a shortcut, the list uses that same constant: files::SAVE, edit::UNDO, piano_roll::OCTAVE_UP, view::MIXER. So if a key changes, the list changes with it. Turning a Keys into text uses egui’s format_shortcut, which writes “Ctrl+Shift+Z” on Linux and Windows and “⇧⌘Z” on a Mac, the way the menus write them.

Because the list is data, it can also be tested as data. no_two_global_shortcuts_share_a_key collects the keys of the sections that work anywhere and fails if any key is listed twice, since that key would do two things at once.

Help: the manual and About

Help > User manual opens the user manual’s web pages in the app’s language. The address lives in a function of about.rs, so the Help menu and the About window both ask it:

#![allow(unused)]
fn main() {
pub(super) fn manual() -> &'static str {
    match i18n::current_language() {
        Language::English => MANUAL,
        Language::Spanish => MANUAL_ES,
    }
}
}

The match has no _ arm on purpose. Add a third language, and the compiler stops here until you decide which manual its readers get. pub(super) makes manual visible to app.rs and to the modules inside it, such as shortcuts.rs, where the Help menu is, and to nothing else.

In the menu, the button asks egui to open that address in a new tab of the web browser:

#![allow(unused)]
fn main() {
if ui.button(crate::i18n::tr("User manual")).clicked() {
    ui.ctx()
        .open_url(egui::OpenUrl::new_tab(super::about::manual()));
    ui.close();
}
}

Help > About Ferrous Lineup says which version you are running, under which license, and where to find the user manual, this book (each also as a PDF), the code and the list of known problems. It is the first thing to look at before reporting one.

Everything it says about the program comes from Cargo.toml, read while the program is compiled:

#![allow(unused)]
fn main() {
const ISSUES: &str = concat!(env!("CARGO_PKG_REPOSITORY"), "/issues");

ui.label(format!("{} {}", tr("Version"), env!("CARGO_PKG_VERSION")));
ui.weak(tr(env!("CARGO_PKG_DESCRIPTION")));
}

• env!("NAME") is a macro that the compiler replaces with the value of the environment variable NAME while it compiles, as a &'static str. Cargo sets CARGO_PKG_VERSION, CARGO_PKG_DESCRIPTION, CARGO_PKG_REPOSITORY and a few more from the [package] section of Cargo.toml (the app takes its version, license and repository from the workspace’s [workspace.package]). A variable that is not set is a compile error, not a surprise for the user.
• concat! joins literals into one at compile time, so ISSUES is a constant too. format! could not be used there: it builds a String while the program runs, and a const must be known before it runs.

So when a release changes the version in Cargo.toml, the window changes with it, and nobody has to remember a second place. The release builds compare the tag with this same number.

The picture is the one the desktop shows for the app’s window: WINDOW_ICON, 256 × 256 pixels of red, green, blue and alpha bytes, built into the program with include_bytes!. egui draws pictures from textures, images kept on the graphics card, so the bytes are made into a texture the first time the window opens and kept in egui’s memory:

#![allow(unused)]
fn main() {
fn icon(ctx: &egui::Context) -> egui::TextureHandle {
    let id = egui::Id::unique("about-icon");
    if let Some(texture) = ctx.data(|data| data.get_temp(id)) {
        return texture;
    }
    let size = crate::WINDOW_ICON_SIZE as usize;
    let image = egui::ColorImage::from_rgba_unmultiplied([size, size], crate::WINDOW_ICON);
    let texture = ctx.load_texture("about-icon", image, egui::TextureOptions::LINEAR);
    ctx.data_mut(|data| data.insert_temp(id, texture.clone()));
    texture
}
}

A TextureHandle works like an Arc: a clone is cheap, and the texture stays on the graphics card while any clone of it is alive. The one kept in egui’s memory means the picture is sent to the card once, not on every frame. WINDOW_ICON is a constant of main.rs, not marked pub; about.rs can still read it as crate::WINDOW_ICON, because a private item is visible to its own module and to every module inside it.

ui.hyperlink_to(text, url) draws a link. Clicking it does not start the browser: egui adds an OutputCommand::OpenUrl to what the frame gives back, and eframe asks the system to open the address. That makes the click easy to test. help_about_shows_the_version_the_license_and_where_the_book_is opens Help > About, checks that the version line and every link are drawn, clicks The book, and checks that the frame asked for the book’s address, without any browser opening. help_user_manual_opens_the_manual_in_the_apps_language does the same for Help > User manual, in English and in Spanish.

Testing a window without a screen

All the tests named in this chapter draw the app without a screen. egui::Context::run_ui (or run_pass) takes the input of one frame, the mouse position, the keys and the clicks, and returns everything egui would hand to the graphics card, without drawing it. A test can then find a widget by its Id or its text, check where it was placed, click it in the next frame, and read the app’s state. app/ux_tests.rs holds most of them; How the code is tested has the rest of the story.

One detail of these tests is worth knowing. What run_ui returns includes the font’s texture. egui checks, only in debug builds, that such a texture is not dropped without being used, and panics if it is. So tests that keep the output clear it first:

#![allow(unused)]
fn main() {
// The font texture is not drawn anywhere here.
output.textures_delta.clear();
}

A test that passes in a release build and fails in a debug build is usually one of these checks: debug_assert! is compiled only into debug builds, and a library can have many of them. That is why CI runs the tests in a debug build.

The editors: channel rack, piano roll and playlist

Files: crates/lineup-app/src/channel_rack.rs, crates/lineup-app/src/piano_roll.rs, crates/lineup-app/src/playlist.rs, crates/lineup-app/src/widgets.rs and crates/lineup-app/src/app.rs

Three windows edit the music itself. The playlist fills the main window: patterns placed as clips on tracks, which together make the song. The channel rack (F6) shows one pattern as rows of steps, one row per channel. The piano roll (F7) shows one channel of one pattern as notes on a grid, with high notes at the top. The rack and the piano roll float over the playlist, as the previous chapter describes.

All three are built the same way, and that is the first thing this chapter is about.

Drawing returns actions

None of the editors changes the project. Each one only looks at it and returns what the user did, as a list of actions. The rack’s are an enum:

#![allow(unused)]
fn main() {
pub enum RackAction {
    PlayPattern,
    // ...
    SelectChannel(Option<usize>),
    ToggleStep { channel: usize, step: usize },
    ClearStep { channel: usize, step: usize },
    Preview(usize),
    SetVolume { channel: usize, volume: f32 },
    ToggleMute(usize),
    Remove(usize),
    OpenPianoRoll(usize),
    AddDrum(Drum),
    AddSynth,
    // ...sending over MIDI, instruments...
    LoadSample { channel: Option<usize>, path: PathBuf },
}

pub fn show(
    ui: &mut Ui,
    project: &Project,
    pattern: usize,
    selected: Option<usize>,
    playhead: Option<usize>,
    playback: Option<RackPlayback>,
    locks: bool,
) -> Vec<RackAction>
}

project: &Project is a shared borrow: the function may read the project but cannot change it, and the compiler enforces that. The app then applies the actions:

#![allow(unused)]
fn main() {
let rack_actions = rack
    .show(ctx, |ui| {
        // ...
        channel_rack::show(ui, &self.project, self.pattern, selected, playhead, /* ... */)
    })
    .and_then(|window| window.inner)
    .unwrap_or_default();
for action in rack_actions {
    self.apply(action);
}
}

Window::show returns None when the window is closed, and its inner is None when the window is folded up, so the actions are wrapped twice. .and_then(|window| window.inner) unwraps the outer Option and returns the inner one; .unwrap_or_default() turns None into an empty Vec.

This split also solves a borrowing puzzle. While the rack is drawing, it holds a shared borrow of the project, so it could not also change it (that would need a &mut at the same time, which the borrow checker forbids). Collecting actions first and applying them after the drawing is finished keeps the two borrows apart in time.

apply is one match with an arm per action. Each arm that changes the song goes through edit or edit_pattern, which keeps the undo history and tells the audio thread what changed (see Telling the audio thread what changed):

#![allow(unused)]
fn main() {
RackAction::ToggleStep { channel, step } => {
    self.edit_pattern("change steps", |pattern| {
        pattern.toggle(channel, step);
    });
}
}

The same action does the same thing wherever it comes from: a click, a key, or a menu. The piano roll returns RollActions and the playlist PlaylistActions, and the app applies them the same way.

The selected pattern

The rack and the piano roll show one pattern, the selected one. The app keeps it:

#![allow(unused)]
fn main() {
pub struct LineupApp {
    // ...
    /// The selected pattern: the one the channel rack and the piano roll
    /// show, pattern mode plays, and new playlist clips use.
    pattern: usize,
    mode: PlayMode,
    // ...
}
}

It is a field of the app, not of the project: it is where you are looking, not part of the song, so it is not saved and selecting a pattern does not count as an unsaved change. The editors take it as an argument, so they stay functions of what they are given.

The playhead they get depends on the mode. In pattern mode the audio thread’s step is a step of the selected pattern. In song mode it is a step of the song, and the app asks the project where the selected pattern is at that moment:

#![allow(unused)]
fn main() {
fn pattern_playhead(&self) -> Option<usize> {
    let step = self.playhead()?;
    match self.mode {
        PlayMode::Pattern => Some(step),
        PlayMode::Song => {
            // ...a pattern played over the song gives its own step...
            let (step, _) = self.song_position()?;
            self.project.pattern_step_in_song(self.pattern, step)
        }
    }
}
}

pattern_step_in_song looks for a clip of the pattern, on a track that is not muted, that covers the song’s step, and returns None if there is none. So while the song plays, the rack’s playhead runs whenever a clip of the selected pattern is playing, and disappears in the bars where it is not.

The channel rack

Writing your own widgets

egui has buttons and sliders, but not step buttons or knobs. Making one takes three moves: reserve space, read the mouse, paint.

#![allow(unused)]
fn main() {
pub fn step_button(ui: &mut Ui, on: bool, beat_group: usize, is_playhead: bool) -> Response {
    let (rect, response) = ui.allocate_exact_size(step_size(ui), Sense::click());

    if ui.is_rect_visible(rect) {
        let mut fill = if on {
            STEP_ON
        } else {
            STEP_OFF[beat_group % 2]
        };
        if response.hovered() {
            fill = fill.gamma_multiply(1.25);
        }
        if is_playhead {
            // The whole column that is sounding lights up, down every row.
            fill = fill.lerp_to_gamma(PLAYHEAD, if on { 0.25 } else { 0.35 });
        }
        let painter = ui.painter();
        // ...a dark edge along the bottom, the pad, a light strip on a
        // step that is on, an orange outline on the step playing...
    }
    response
}
}

• allocate_exact_size claims a rectangle in the layout and says which interactions we want (Sense::click()). It returns the rectangle and a Response describing what the mouse did there this frame. step_size(ui) is the step’s size times the rack’s zoom.
• is_rect_visible skips painting rows that are scrolled out of view.
• The Painter draws shapes. Colours are Color32 constants defined at the top of the file, so the palette lives in one place.
• lerp_to_gamma mixes some orange into the step playing, a little less on a step that is on, so a lit step stays white.
• Returning the Response lets the caller use it like any built-in widget: if response.clicked() { ... }.

Beats alternate colours, so you can count them, and start again in every bar so all bars look alike: in 3/4, dark, light, dark. The rack asks the time signature which beat each step is in (time.beat_at(step).index), so 6/8 groups its steps in threes.

The knob uses Sense::click_and_drag(), turns vertical mouse movement into a value change, and calls response.mark_changed() so callers can use .changed() as they would on a slider. Its pointer is drawn with a little trigonometry: the angle sweeps 270 degrees, and (sin, -cos) of the angle gives the direction (screen y grows downward, hence the minus).

Menus

#![allow(unused)]
fn main() {
name.context_menu(|ui| self.channel_menu(ui, index, channel, locked, actions));
}

context_menu opens a menu on a right-click; menu_button opens one on a normal click (the “Add channel” button). Both take a closure that draws the menu’s contents, and ui.close() closes the menu after a choice. add_enabled_ui(false, ...) greys out everything inside, which is how “Add channel” is disabled when the rack is full:

#![allow(unused)]
fn main() {
let rack_full = project.channels().len() >= MAX_CHANNELS;
ui.add_enabled_ui(!rack_full, |ui| {
    ui.menu_button(tr("➕ Add channel"), |ui| { /* ... */ });
});
}

Drag and drop

egui reports files being dragged over the window in input.raw.hovered_files, and files dropped in input.raw.dropped_files. While drawing, the rack keeps each row’s rectangle; afterwards it finds the row under the mouse:

#![allow(unused)]
fn main() {
let target_row = pointer.and_then(|p| row_rects.iter().position(|rect| rect.contains(p)));
}

position returns the index of the first item for which the closure is true, or None. A WAV file dropped on a row replaces that channel’s sound; a file dropped anywhere else becomes a new channel named after the file (path.file_stem() is the file name without its extension). A project, MIDI or chord sheet file, or a recording, is left for the app, which opens or imports it.

Loading happens in LineupApp::load_sample, on the window’s thread, because reading files is slow and must never happen on the audio thread. It reads the file before changing anything, so a broken file leaves the channel as it was and puts the reason in the status bar.

A row of lights over the steps

A drum machine has a row of small lights, one over each step, and the light over the step being played runs along with the music. The rack has that row too. The lights must sit exactly over the steps, but the steps start after the mute light, the knob, the lock and the channel name, and their widths change with the rack’s zoom. Rather than adding those widths up (and getting it wrong the next time a control is added to a row), the rack lets the rows tell it:

#![allow(unused)]
fn main() {
let (lights, _) = ui.allocate_exact_size(
    egui::vec2(1.0, widgets::step_lights_height(ui)),
    egui::Sense::hover(),
);
let mut steps_left = None;
for (index, channel) in project.channels().iter().enumerate() {
    let row = ui.horizontal(|ui| self.row(ui, index, channel, actions));
    steps_left.get_or_insert(row.inner);
    row_rects.push(row.response.rect);
}
if let Some(left) = steps_left {
    let marks = step_marks(self.time, self.pattern.length());
    widgets::step_lights(ui, lights, left, &marks, self.playhead);
}
}

allocate_exact_size reserves an empty strip at the top, so the rows go under it. Each row returns where its steps start (ui.cursor().left() just before the first step); get_or_insert keeps the first row’s value and ignores the others. Once the rows are done, step_lights paints into the reserved strip. egui draws everything at the end of the frame, so painting into space reserved earlier is fine.

step_lights takes a slice of StepMark, a small enum that says whether each step starts a bar, starts a beat, or neither:

#![allow(unused)]
fn main() {
pub enum StepMark {
    Bar,
    Beat,
    Plain,
}
}

The light over the first step of each bar is a little brighter than the others, and the light over the first step of each beat a little brighter than the steps in between, so the row can be counted like the steps under it. Each light is placed one step width (the button plus the gap after it) after the one before, the same arithmetic the mini piano roll uses, so lights, buttons and previews line up at any zoom.

A mini piano roll for melodies

A channel whose notes are all plain steps shows step buttons. Any other channel shows widgets::mini_roll, a tiny drawing of its notes, and clicking it opens the piano roll. The widget has to line up with the step buttons, which have a gap between them:

#![allow(unused)]
fn main() {
let gap = ui.spacing().item_spacing.x;
let step_size = step_size(ui);
let step_width = step_size.x + gap;
let size = vec2(step_width * length as f32 - gap, step_size.y);
}

The pitch range is squeezed into the row’s height, but never less than an octave, so three close notes do not fill the row from top to bottom:

#![allow(unused)]
fn main() {
let visible = || notes.iter().filter(|note| note.start < length);
let lowest = visible().map(|note| note.pitch.midi()).min().unwrap_or(0);
let highest = visible().map(|note| note.pitch.midi()).max().unwrap_or(0);
let span = (highest - lowest).max(12) as f32;
}

visible is a closure that makes a fresh iterator each time it is called, because min and max each use one up. The column that is playing is filled with a see-through orange (gamma_multiply(0.25) makes the colour a quarter as strong), as the step buttons are tinted.

Drums in another pattern, and a rack that fits

Songs often keep their drums in a pattern of their own, “A drums” next to “A”. The rack for “A” would show drum rows with nothing in them, which looks broken. So when a pattern has no drum steps and others do, drums_elsewhere says so above the rows, with a button for each of those patterns.

The rack opens as big as its rows. natural_size adds them up (the controls, the steps, the lights, the “Add channel” menu, room for a scroll bar), and the window is given that size for one frame whenever the rows change, as windows the size of what they show do. It can still be made smaller, and then it scrolls. When every row fits, the plain mouse wheel scrolls the steps sideways. egui has a style setting for exactly that, which works when the scroll area allows only one direction:

#![allow(unused)]
fn main() {
ui.style_mut().always_scroll_the_only_direction = true;
let vertical = rows_height > ui.available_height();
let scroll = egui::ScrollArea::new([true, vertical])
}

The piano roll

A window with state of its own

The channel rack is a function: everything it shows comes from the project. The piano roll needs to remember things the project does not know about, from one frame to the next: which channel it shows, what a click draws, the selected notes, a drag in progress. So it is a struct with methods:

#![allow(unused)]
fn main() {
pub struct PianoRoll {
    pub open: bool,
    channel: usize,
    stamp: ChordStamp,
    /// The length of new notes, in steps. Resizing a note changes it, so
    /// the next note drawn is as long as the last one edited.
    note_length: usize,
    drag: Option<Drag>,
    group_drag: Option<GroupDrag>,
    selection: Vec<NoteEvent>,
    ghosts: bool,
    zoom: Vec2,
    // ...
}
}

It still never changes the project itself. show returns a list of RollActions, as the rack does:

#![allow(unused)]
fn main() {
pub enum RollAction {
    /// Add one note, or the notes of a chord.
    AddNotes { channel: usize, notes: Vec<NoteEvent> },
    RemoveNote { channel: usize, index: usize },
    /// Replace a note that was moved or resized.
    ReplaceNote { channel: usize, index: usize, note: NoteEvent },
    /// Replace some notes with others, all at once: a moved selection,
    /// a tool, new velocities. `label` names the undo step.
    ReplaceNotes { channel: usize, old: Vec<NoteEvent>, new: Vec<NoteEvent>, label: &'static str },
    /// Play some notes right now, without adding them.
    Preview { channel: usize, pitches: Vec<Note> },
    SetScale(Scale),
    /// Show another pattern: one where the channel has notes.
    SelectPattern(usize),
    /// Open the channel rack, where drum steps are edited.
    OpenRack,
    // ...
}
}

So the struct holds view state, which is never saved, and the project holds document state (the notes), which is.

The window is built like this:

#![allow(unused)]
fn main() {
// `open` is a copy: the window needs `&mut open` while the closure
// below needs `&mut self`, and both cannot borrow `self` at once.
let mut open = self.open;
let window = egui::Window::new(roll_title)
    .id(id)
    .open(&mut open)
    .default_pos([150.0, 160.0])
    .constrain_to(area);
// ...the size it opens at...
window.show(ctx, |ui| {
    self.contents(ui, project, pattern_notes, playhead, held, &mut actions)
});
self.open = open;
}

• The title changes with the pattern and the channel, and egui normally identifies a window by its title. .id(...) gives it a fixed identity instead, so it keeps its position and size when you switch channels.
• .open(&mut open) adds the close button: egui sets open to false when it is clicked.
• If the window borrowed &mut self.open while the closure borrowed &mut self (to call self.contents), self.open would be borrowed mutably twice at once, which Rust forbids. Copying the bool out and back in avoids the overlap.

Pixels and music: Grid

Most of the drawing code turns steps and pitches into screen positions, or the pointer position back into a step and a pitch. That arithmetic lives in one place:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy)]
struct Grid {
    /// Where all the steps and rows are, even those scrolled out of view.
    rect: Rect,
    step_width: f32,
    /// How tall a row (one pitch) is: the vertical zoom.
    row_height: f32,
    length: usize,
    time: TimeSignature,
    /// The left edge of the keyboard. The keyboard stays at the left of
    /// the view while the grid scrolls sideways under it.
    keys_left: f32,
}

impl Grid {
    /// The x coordinate where `step` begins.
    fn x(self, step: usize) -> f32 {
        self.rect.left() + step as f32 * self.step_width
    }

    /// The y coordinate of the top of a pitch's row (high notes at the top).
    fn row_top(self, midi: u8) -> f32 {
        self.rect.top() + (HIGHEST - midi) as f32 * self.row_height
    }

    /// The step and pitch under a point. Points outside the grid give the
    /// nearest cell, so a drag can go past the edges.
    fn cell_at(self, pos: Pos2) -> (usize, Note) {
        let row = ((pos.y - self.rect.top()) / self.row_height)
            .floor()
            .clamp(0.0, (HIGHEST - LOWEST) as f32) as u8;
        (self.step_at(pos.x), Note::new(HIGHEST - row))
    }
    // ...keys, cells, step_at, note_rect, text_size
}
}

High notes are at the top, so the row counts down from HIGHEST. cell_at clamps, so a drag that leaves the grid still gets the nearest cell, and returns a tuple, (usize, Note), which the caller takes apart with let (step, pitch) = grid.cell_at(pos);. note_rect draws a note from its exact start to its exact end, including how far it is nudged off the step, so a triplet sits between two steps, as it is heard.

Because Grid is Copy and its methods take self by value, it can be passed to every drawing function without any & or lifetimes. For a struct of a few numbers, copying is as cheap as passing a reference.

At 100% the whole pattern fits across the window, so the step width is worked out on every frame from the window’s width. Zooming in makes the steps wider, and the grid scrolls sideways under the keyboard.

A keyboard that stays, lanes that follow

The grid is inside a scroll area, but two things must not scroll away with it. The piano keys are drawn at the left edge of what is visible (keys_left: visible.left()), on top of the grid, so the notes slide under them. The chord lane above the grid and the velocity lane below it are drawn outside the scroll area, so they do not know how far the grid is scrolled. A small struct carries what they need to line up:

#![allow(unused)]
fn main() {
/// What the chord and velocity lanes need to line up with the grid.
#[derive(Debug, Clone, Copy)]
struct Lanes {
    step_width: f32,
    /// How far the grid is scrolled sideways, in pixels.
    scroll_x: f32,
    length: usize,
}
}

Each lane builds its own Grid from it (Lanes::grid), moved by scroll_x, and uses the same functions as the note grid to find where a step is. One source of truth for “where is step 12?” is what keeps three strips drawn separately in line.

Mouse input as a small state machine

egui reports what the mouse is doing this frame. A drag lasts many frames, so the piano roll remembers it in an enum:

#![allow(unused)]
fn main() {
enum Drag {
    /// Moving a note. `grab` is how many steps after the note's start the
    /// pointer took hold of it, so the note does not jump under the pointer.
    Move { index: usize, grab: usize },
    /// Changing a note's length by dragging its right end.
    Resize { index: usize },
}
}

handle_input is long, but each part answers one question:

1. Was the left button just pressed on the grid? If it hit a note, start a Move, or a Resize if the press was near the note’s right end. If it hit an empty cell, add what a click draws (a note or a chord); a single new note also starts a Move, so you can place and drag in one gesture.
2. Is the right button down over a note? Delete it. Checking every frame means you can sweep across several notes to delete them all.
3. Is the left button up? Then any drag is over.
4. Is a drag in progress? Work out where the note would be now, and if that differs from where it is, send a ReplaceNote.

The fourth part uses a let chain with three conditions, and struct update syntax to change one or two fields:

#![allow(unused)]
fn main() {
if let Some(drag) = self.drag
    && let Some(pos) = pointer
    && let Some(&note) = notes.get(drag.index())
{
    let (step, pitch) = grid.cell_at(pos);
    let pitch = self.snapped(pitch, scale);
    let changed = match drag {
        Drag::Move { grab, .. } => NoteEvent {
            pitch,
            start: step.saturating_sub(grab),
            ..note
        },
        Drag::Resize { .. } => {
            let length = (step + 1).saturating_sub(note.start).max(1);
            self.note_length = length;
            // ...
            NoteEvent { length, trim, ..note }
        }
    };
    if changed != note {
        // ...play the new pitch, keep the note selected...
        actions.push(RollAction::ReplaceNote { channel, index: drag.index(), note: changed });
    }
}
}

Some(&note) in a pattern copies the note out of the &NoteEvent that get returns. Comparing changed != note (thanks to the derived PartialEq) means nothing is sent while the pointer stays inside the same cell, even though this code runs every frame. snapped moves the pitch onto the key when Snap to scale is on.

Two details make clicks land where they were meant. A quick right-click can press and release the button within a single frame, so “is the button down?” is already false by the time the frame is drawn. The code asks “was it pressed this frame, or is it down?” instead:

#![allow(unused)]
fn main() {
pointer.secondary_pressed() || pointer.secondary_down(),
}

And on the frame the left button goes down, the press is handled where the button went down, which widgets::press_pos reads from the frame’s events (see Clicks that do what you meant): a quick hand can press and move on in the same frame.

When the pointer is over an empty cell, the piano roll draws outlines of what a click would place, from the same stamp_notes the click itself uses. With “Chord in key (seventh)” chosen, you see the whole chord before you place it.

The selection holds notes, not positions

The simplest way to remember which notes are selected would be their positions in the channel’s list: selection: Vec<usize>. The single-note drag does exactly that (Drag::Move { index, .. }), and it works there because nothing else changes the list during a drag.

A selection lives much longer than a drag. While notes are selected, a tool takes them out of the list and puts new ones at the end, undo swaps in a whole older project, and deleting a note moves every note after it one place up. After any of those, position 3 may be a different note, or no note at all. A selection of positions would quietly select the wrong notes, and the next tool would change notes you never chose.

So the selection holds the notes themselves:

#![allow(unused)]
fn main() {
/// The selected notes, by value. A note that is no longer in the
/// pattern (after an undo, say) is simply not found, and so not
/// selected: the selection can never point at the wrong note.
selection: Vec<NoteEvent>,
}

This works because a channel never holds two notes in the same place: the pattern’s rule (same pitch, same start, same nudge) makes every note’s value unique, so a value names exactly one note. NoteEvent is Copy and PartialEq, so keeping copies and comparing them is cheap and easy.

At the start of every frame, notes that have gone are forgotten:

#![allow(unused)]
fn main() {
let notes = pattern.notes(self.channel);
self.selection.retain(|note| notes.contains(note));
}

And when the piano roll replaces some notes, it makes the selection follow them, so that pressing ↑ three times moves the same chord three times:

#![allow(unused)]
fn main() {
fn replace(
    &mut self,
    pattern: &Pattern,
    actions: &mut Vec<RollAction>,
    label: &'static str,
    old: Vec<NoteEvent>,
    new: Vec<NoteEvent>,
) -> Option<Vec<NoteEvent>> {
    let new = tidy_notes(new);
    if old == new || !pattern.can_replace_notes(self.channel, &old, &new) {
        return None;
    }
    let was_selected = old.iter().any(|note| self.selection.contains(note));
    self.selection.retain(|note| !old.contains(note));
    if was_selected {
        self.selection.extend(&new);
    }
    actions.push(RollAction::ReplaceNotes {
        channel: self.channel,
        old,
        new: new.clone(),
        label,
    });
    Some(new)
}
}

replace is the one door every group change goes through: the tools, the group drag and the velocity lane. It tidies the new notes the same way the pattern will, asks the pattern whether the change is allowed, and only then sends the action. Tidying here too means the selection holds exactly the notes that will be in the pattern, and checking first means a refused move does nothing at all instead of half a thing.

The comparison costs a little: contains looks through the whole list, so checking every note against the selection takes time proportional to the number of notes times the size of the selection. For a piano roll with a few hundred notes, that is far below a millisecond. If it ever mattered, a HashSet<NoteEvent> would make each check constant time (NoteEvent already derives Hash for that).

Selecting with the mouse

Ctrl+click on a note adds it to the selection, or takes it out:

#![allow(unused)]
fn main() {
if let Some(at) = self.selection.iter().position(|&n| n == note) {
    self.selection.remove(at);
} else {
    self.selection.push(note);
}
}

input.modifiers.command is “Ctrl” on Linux and Windows and “⌘” on a Mac, so the same code follows each system’s habits.

Ctrl+drag on empty space draws a box. Only the corner where it started is kept; the selection is rebuilt from scratch on every frame, from that corner and the pointer, so making the box smaller again unselects notes:

#![allow(unused)]
fn main() {
if let Some(origin) = self.selection_box
    && let Some(pos) = pointer
{
    let area = Rect::from_two_pos(origin, pos);
    self.selection = notes
        .iter()
        .filter(|note| note.start < grid.length && grid.note_rect(note).intersects(area))
        .copied()
        .collect();
}
}

Rect::from_two_pos makes a rectangle from any two corners, whichever way the box was dragged, and intersects is true when two rectangles overlap at all, so a note only needs to be touched by the box.

Moving a group

Pressing a selected note (anywhere but its right end, which still resizes) starts a group drag:

#![allow(unused)]
fn main() {
struct GroupDrag {
    /// The cell where the drag started.
    from_step: usize,
    from_pitch: Note,
    /// The notes as they were when the drag started.
    originals: Vec<NoteEvent>,
    /// The notes as they are now, after the moves so far.
    moved: Vec<NoteEvent>,
    /// Whether the notes have moved at all.
    edited: bool,
}
}

On every frame of the drag, the new position is worked out from the originals, with the whole distance from the start cell to the pointer:

#![allow(unused)]
fn main() {
let steps = step as isize - drag.from_step as isize;
let semitones = i32::from(pitch.midi()) - i32::from(drag.from_pitch.midi());
drag.edited |= steps != 0 || semitones != 0;
let snap = self.snap_to_scale && drag.edited;
let new = tools::shift(&drag.originals, steps, grid.length)
    .and_then(|shifted| tools::transpose(&shifted, semitones))
    .map(|moved| match snap {
        true => tools::snap_to_scale(&moved, scale),
        false => moved,
    })
    .filter(|moved| fits_view(moved));
}

Moving the notes a little each frame (from moved) would be the obvious way, but small errors would add up: a move refused at the edge of the pattern would be lost, and the notes would end up somewhere other than under the pointer. Starting from the originals every time means the notes are always exactly where the pointer says, and dragging back to the start puts them back exactly as they were.

The tools (see Editing tools as plain functions) are joined with Option::and_then: shift, and if that worked, transpose the result. map snaps the notes to the key when Snap to scale is on, but only once they have moved, so dragging a selection up a semitone and back down snaps it into the key. filter then refuses notes outside the rows the piano roll shows. The replacement goes from moved (what is in the pattern now) to new, and moved is updated to what replace returned.

The drag is taken out of self while it is worked on:

#![allow(unused)]
fn main() {
if let Some(mut drag) = self.group_drag.take()
    && let Some(pos) = pointer
{
    // ... self.replace(pattern, actions, "move notes", drag.moved.clone(), new) ...
    self.group_drag = Some(drag);
}
}

self.replace needs &mut self, the whole struct. If drag were a reference into self.group_drag, the borrow checker would refuse: one part of self would be borrowed while all of self is borrowed mutably. Option::take moves the drag out and leaves None, so drag is a separate value and self is free; the drag is put back at the end.

Every frame of the drag produces a ReplaceNotes, and each one goes through edit_pattern. They still make a single undo step, because a step stays open while a mouse button is held (see Undo and redo). And because the step is already open, edit does not copy the whole project again on every frame; it sends the audio thread what changed at most every 50 ms, and the rest when the button is released. Nothing in the piano roll has to know about either.

Who gets the keys

The arrow keys and Delete are useful in the piano roll, but the rack and the playlist use them too, and a key that changes notes in a window you are not looking at would be a nasty surprise. So the editor keys go to the window clicked last, and to no other:

#![allow(unused)]
fn main() {
/// Editor shortcuts belong to the last clicked window, including its title
/// and toolbar. Popup controls and text fields keep their own keyboard input.
pub fn editor_keyboard(ctx: &egui::Context, layer: egui::LayerId) -> bool {
    editor_active(ctx, layer)
        && !ctx.text_edit_focused()
        && !egui::Popup::is_any_open(ctx)
        && ctx.memory(|memory| memory.is_above_modal_layer(layer))
}
}

editor_active remembers the layer of the last press (each window is a layer, see What is under the pointer?), in egui’s memory, and answers whether it is this one. A window the app opens for you, as a double-click on a clip opens the piano roll, is given the keyboard with widgets::give_keyboard, as if it had been clicked. The playlist shares the background layer with the toolbars, so for it the place of the click matters too (editor_keyboard_in). The keys are ignored while a text field has the keyboard, so typing a pattern name never moves notes, and while a menu is open.

Space, which plays and stops, has the opposite problem: it must work everywhere, but egui lets a focused button be pressed with Space too. Click ▶ Play, then press Space, and the shortcut would stop the music while the button started it again. So the shortcuts are read before any panel is drawn, and consume_key takes the press away once it is used:

#![allow(unused)]
fn main() {
let typing = ctx.text_edit_focused() || egui::Popup::is_any_open(ctx);
// `consume_key` reports whether the key was pressed and removes the
// press, so a focused button does not also react to Space.
let pressed = |key| ctx.input_mut(|input| input.consume_key(egui::Modifiers::NONE, key));
if !typing && !controls_active && pressed(egui::Key::Space) {
    // ...play or stop the song, or the pattern in the rack or piano roll...
}
}

The order of the shortcuts

Each key is a KeyboardShortcut: a key and its modifiers.

#![allow(unused)]
fn main() {
pub(crate) const KEY_UP: KeyboardShortcut = shortcut(Modifiers::NONE, Key::ArrowUp);
pub(crate) const OCTAVE_UP: KeyboardShortcut = shortcut(Modifiers::SHIFT, Key::ArrowUp);
pub(crate) const IN_KEY_UP: KeyboardShortcut = shortcut(Modifiers::ALT, Key::ArrowUp);
}

shortcut is a const fn, a function simple enough to run while compiling, which is why its results can be consts. They are pub(crate) so that the list in Help > Keyboard shortcuts uses the same constants (see Every key in a list).

The piano roll asks egui whether each one was pressed with input.consume_shortcut(&shortcut). That returns true once, and “consumes” the key press so nothing else reacts to it. One detail of egui matters here: it matches shortcuts logically, which means extra Shift or Alt keys do not stop a match. Shift+↑ counts as a press of ↑ as well. Checked in the wrong order, Shift+↑ would be eaten by the “up a semitone” shortcut before the “up an octave” one ever saw it. So the list goes from the most specific to the least:

#![allow(unused)]
fn main() {
// egui counts Shift+↑ and Alt+↑ as ↑ too, so the longer shortcuts
// are checked first.
let keys = [
    (IN_KEY_UP, Tool::InKey(1)),
    (IN_KEY_DOWN, Tool::InKey(-1)),
    (OCTAVE_UP, Tool::Transpose(12)),
    (OCTAVE_DOWN, Tool::Transpose(-12)),
    (KEY_UP, Tool::Transpose(1)),
    // ...
];
keys.into_iter()
    .find(|&(shortcut, _)| pressed(shortcut))
    .map(|(_, tool)| tool)
}

find stops at the first shortcut pressed, so at most one tool runs per frame, and the later, shorter shortcuts are not even asked.

One enum for the menu and the keys

The Tools menu and the keys both produce a Tool:

#![allow(unused)]
fn main() {
enum Tool {
    Copy,
    Cut,
    Paste,
    Duplicate,
    Transpose(i32),
    InKey(i32),
    Shift(isize),
    Quantize,
    SnapToKey,
    Invert { up: bool },
    Arpeggiate,
    Delete,
    SelectAll,
    SelectNone,
}
}

and use_tool turns any Tool into a call to the right function in lineup_core::tools, followed by replace. A tool changes the selected notes, or every note when none is selected; Delete only ever deletes a selection. Whether a tool came from the menu or a key, it takes exactly the same path, so the two can never behave differently. The menu shows each tool’s key next to it, written the way the system writes keys, so it doubles as the list of shortcuts.

A menu that stays open

egui menus close on any click inside them, which is right for a list of commands. But the Tools menu also holds choices: the arpeggio’s order and speed. Closing the menu when you pick “up and down” would make you open it again to press “Arpeggiate chords”. So this menu is told to close only on a click outside it, and each tool closes it by hand:

#![allow(unused)]
fn main() {
let stay_open = egui::containers::menu::MenuConfig::new()
    .close_behavior(egui::PopupCloseBehavior::CloseOnClickOutside);
let menu = egui::containers::menu::MenuButton::new(tr("Tools")).config(stay_open);
menu.ui(ui, |ui| {
    // ...
    let mut item =
        |ui: &mut Ui, text: &str, tool: Tool, shortcut: Option<KeyboardShortcut>| {
            // ...
            if ui.add(button).clicked() {
                picked = Some(tool);
                ui.close();
            }
        };
    item(ui, "Up a semitone", Tool::Transpose(1), Some(KEY_UP));
    // ...
});
}

item is a closure stored in a variable and called many times. It assigns to picked, a variable outside it, so it borrows picked mutably for as long as the closure exists, and has to be declared let mut item (calling it changes what it captured: it is an FnMut). The ui is passed in as an argument on each call instead of being captured, because the code between the calls uses ui too, and a closure holding on to it would block that. Menus with a text field in them, such as the playlist’s section menu, stay open the same way, so a click into the field does not close them.

Ghost notes: hearing the other channels

A chord is often shared between instruments: the pad plays C and G, the bass plays E, and together they make C/E. Looking only at the channel being edited, the piano roll would say “C5” (a power chord) where you hear C/E.

So the piano roll can listen to the other channels as well. Not all of them: drum channels hold plain steps, and a kick drum is not part of the harmony. A channel counts if any of its notes is not a plain step:

#![allow(unused)]
fn main() {
let others: Vec<usize> = (0..pattern.rows())
    .filter(|&other| other != self.channel)
    .filter(|&other| pattern.notes(other).iter().any(|note| !note.is_step()))
    .collect();
let mut heard = vec![self.channel];
if self.ghosts {
    heard.extend(&others);
}
}

heard is the list of channels whose notes count for the harmony: this one, and the others when “Ghost notes” is ticked. The line that names the chord under the pointer, the next-chord hints and the note names all take heard, and gather its notes with a small helper:

#![allow(unused)]
fn main() {
fn sounding<'a>(
    pattern: &'a Pattern,
    channels: &'a [usize],
    step: usize,
) -> impl Iterator<Item = Note> + 'a {
    channels
        .iter()
        .flat_map(move |&channel| pattern.sounding_at(channel, step))
}
}

• flat_map calls the closure for each channel, gets an iterator of notes back each time, and joins them all into one iterator, as if the channels’ notes were one list.
• The result borrows pattern and channels, so it must not outlive them. <'a> names that borrow, and + 'a on the return type says “this iterator lives no longer than 'a”. analyze takes any iterator of notes, so it reads the notes straight from the pattern, without copying them into a Vec first.
• move makes the closure take its own copies of what it uses: step (a number) and pattern (a reference, which is copied, not the pattern). Without move, the closure would borrow the variable step, which belongs to sounding and disappears when it returns, while the iterator lives on.

The ghost notes are painted before this channel’s notes, so this channel’s notes are always on top, in grey with a thin border. They are only drawn: clicks only look at this channel’s notes, so ghost notes can never be selected, moved or deleted by accident. When no other channel plays melodies or chords, the checkbox is greyed out, and its hover text says why.

The chord lane: chunk_by, then measure

The lane above the grid names the harmony. Its first row names what this channel plays at every step; its second row, All, names what the whole song sounds like there, beat by beat, as Hearing harmony works it out. Each row joins neighbouring steps with the same harmony into one block:

#![allow(unused)]
fn main() {
// `chunk_by` splits a slice wherever two neighbours differ. A
// harmony holds its bass, so C and C/E are two blocks.
let mut start = 0;
for run in harmonies.chunk_by(|a, b| a == b) {
    let end = start + run.len();
    if let Some(label) = run[0].label_in(scale) {
        // ...a block from step `start` to step `end`, with the label...
    }
    start = end;
}
}

chunk_by splits a slice into runs wherever the closure says two neighbours do not belong together. Each run is a slice of the original vector, so nothing is copied. Comparing whole harmonies, not their labels, matters: every group of notes without a chord name is labelled “?”, and joining by label would turn several different unnamed chords in a row into one long “?” block, as if one chord were held.

Running analyze for every step on every frame sounds like a lot, but it is at most a few hundred small loops over a few notes. Measure before optimizing: here it does not show up at all.

A name must fit its block. Cut off at the edges, “E7/B” in a narrow block would show “7/”, which is not a name at all, and for someone learning harmony from the screen a wrong name is worse than none. egui draws text in two steps. First it lays it out: it picks the glyph of each character in the font, and works out where each goes and how much room the whole takes. The result is a galley (the name comes from printing: a tray of type set in lines, ready to print). Then it paints the galley. painter.text(...) does both at once; to decide before drawing, the two steps are taken apart:

#![allow(unused)]
fn main() {
let name = painter.layout_no_wrap(label, FontId::proportional(11.0), LANE_TEXT);
if name.size().x <= chord_rect.width() - 2.0 {
    // A long chord's name stays in view while it scrolls.
    let shown = chord_rect.intersect(cells);
    painter.with_clip_rect(chord_rect).galley(
        shown.center() - name.size() / 2.0,
        name,
        LANE_TEXT,
    );
}
}

layout_no_wrap lays the text out on one line, and name.size() is how wide and tall it is. If it fits in the block, with a point to spare on each side, the same galley is painted; nothing is laid out twice. galley takes the top-left corner of the text, so the centre is moved back by half the size. If it does not fit, nothing is drawn; pointing at the block still names the chord in full in the line under the toolbar.

Scale highlighting

paint_rows colours each row by asking the scale about its pitch class, with a match on a tuple of two bools:

#![allow(unused)]
fn main() {
let fill = match (is_root, in_scale) {
    (true, _) => ROOT_ROW,
    (false, true) => SCALE_ROW,
    (false, false) => OTHER_ROW,
};
}

The keys on the left get a dot for notes in the key (orange for the root), and notes outside the key are drawn red. The key is the song’s key where the pattern is played (project.pattern_key), so a pattern used after a key change is shown in the new key. Change the key and every colour follows on the next frame, because nothing is cached: immediate mode draws from the current state every time.

The velocity lane

Making room for it

The lane sits under the grid. The grid is a ScrollArea that fills the height it is given. Given all the height left in the window, it would push the lane below the window’s edge; egui windows grow to fit their contents, so the window would grow, the grid would fill the new height, the lane would be pushed out again, and the window would creep a few pixels taller on every frame. So the grid is given exactly the height that is left once the lane has its share:

#![allow(unused)]
fn main() {
// The velocity lane goes below the grid, so the grid leaves room
// for it: the lane, the gap, and egui's spacing between widgets.
// Taking even a pixel too much would make the window grow a
// little on every frame.
let below = VELOCITY_HEIGHT + 4.0 + 2.0 * ui.spacing().item_spacing.y;
let grid_height = (ui.available_height() - below).max(96.0);
}

The easy part to forget is item_spacing: egui puts a small gap after every widget, here after the scroll area and after the space. A simple way to catch a window that creeps is to take two screenshots a few seconds apart and compare them.

Setting velocities

The lane is one widget that senses clicks and drags. While the button is down on it, the pointer’s height sets the velocity, and its x position picks the step:

#![allow(unused)]
fn main() {
if response.is_pointer_button_down_on()
    && !crate::widgets::dismissing(ui.ctx())
    && let Some(pos) = response.interact_pointer_pos()
    && (cells.contains(pos) || response.dragged())
{
    let step = lane.step_at(pos.x);
    let height = (lane.rect.bottom() - pos.y) / lane.rect.height();
    let velocity = (height * 127.0).round().clamp(1.0, 127.0) as u8;
    let selected_here = notes
        .iter()
        .any(|note| note.start == step && self.selection.contains(note));
    let old: Vec<NoteEvent> = notes
        .iter()
        .filter(|note| note.start == step && note.velocity != velocity)
        .filter(|note| !selected_here || self.selection.contains(note))
        .copied()
        .collect();
    let new = old.iter().map(|&note| NoteEvent { velocity, ..note }).collect();
    self.replace(pattern, actions, "change velocity", old, new);
}
}

• The height is a fraction from 0 (bottom) to 1 (top), scaled to MIDI’s 1 to 127. clamp keeps it inside even when the pointer leaves the lane during a drag. Casting a float with as never wraps (300.0 becomes 255 and -5.0 becomes 0), but 0 would be a note you cannot hear, so the clamp makes sure the velocity is at least 1.
• A chord has several notes on the same step. All of them change, unless some of them are selected: then only the selected ones do. That is how you make the top note of a chord louder than the others, the way pianists bring out a melody.
• Notes that already have the velocity are left out of old, so holding the button still does not send the same change every frame.

Sweeping across the lane changes each step as the pointer passes over it, and the whole sweep is one undo step, like any drag.

Velocity shows in the grid too. A note’s colour is multiplied by a factor between 0.55 and 1 depending on its velocity (fill.gamma_multiply(0.55 + 0.45 * f32::from(note.velocity) / 127.0)), so soft notes are darker, but never so dark that they disappear.

Finding your notes

The piano roll shows one channel of one pattern, and that pair can be empty while the song plays plenty: the chords of a song may be in “Chords”, not in “Beat”. An empty grid with no word of explanation looks like lost notes. So the piano roll does two things.

First, it follows the notes. When it opens, or the pattern changes, and the channel shown has no notes there, it moves to the channel with the most melody or chord notes:

#![allow(unused)]
fn main() {
pub fn busiest_channel(pattern: &Pattern) -> Option<usize> {
    (0..pattern.rows())
        .map(|channel| {
            let melodic = pattern.notes(channel).iter().filter(|note| !note.is_step());
            (channel, melodic.count())
        })
        .filter(|&(_, count)| count > 0)
        .max_by_key(|&(channel, count)| (count, std::cmp::Reverse(channel)))
        .map(|(channel, _)| channel)
}
}

max_by_key returns the last of several equal maximums. Comparing the tuple (count, Reverse(channel)) breaks ties towards the lower channel number instead: std::cmp::Reverse wraps a value and flips its ordering. Drum steps are left out on purpose: in a pattern of drums alone, the piano roll does not jump to the kick drum, whose “notes” are all the same plain step. A channel you picked yourself, in the rack or the editor, is kept.

To notice the window opening, the piano roll remembers whether it was open last frame. open is a public field that the toolbar button, F7 and the View menu flip, so this is the one place that sees every way in:

#![allow(unused)]
fn main() {
let opened = self.open && !self.was_open;
// ... at the end of `show`:
self.was_open = open;
}

On opening, it also scrolls to the middle of the notes. The middle is not worked out by halving pitches: with integers, / throws away the remainder, and 41 / 2 + 67 / 2 is 53, a row off the true middle, 54. Instead it asks egui to centre the whole block of rows, from the top of the highest note to the bottom of the lowest:

#![allow(unused)]
fn main() {
let top = grid.row_top(highest.clamp(LOWEST, HIGHEST));
let bottom = grid.row_top(lowest.clamp(LOWEST, HIGHEST)) + row_height;
let target = Rect::from_min_max(pos2(rect.left(), top), pos2(rect.left() + 1.0, bottom));
ui.scroll_to_rect(target, Some(Align::Center));
}

Second, when the channel really has no notes in the pattern, it says so over the grid, with buttons to go where the notes are:

Finding the patterns where the channel plays is a filter over all of them, keeping the index (to select it) and the name (to show it):

#![allow(unused)]
fn main() {
let elsewhere: Vec<(usize, &str)> = project
    .patterns()
    .iter()
    .enumerate()
    .filter(|&(index, other)| {
        index != self.pattern && !other.notes(self.channel).is_empty()
    })
    .map(|(index, other)| (index, other.name.as_str()))
    .collect();
}

The &str in the vector borrows from project. That is fine because the vector lives only while this frame is drawn, and project outlives it. A button for another pattern cannot select it directly: the selected pattern belongs to the app. So it returns RollAction::SelectPattern, the same way every other change leaves the piano roll.

The message lies over the grid instead of taking a line above it, so the grid does not jump up when the first note is drawn and the message goes away. It is drawn after the grid, in a child Ui placed over it, and the grid remembers where it was drawn last frame (self.banner) and leaves clicks there alone: a click on one of its buttons must not also draw a note underneath.

Wiring it into the app

The app owns a PianoRoll and, while drawing the windows, calls:

#![allow(unused)]
fn main() {
let roll_actions = self.piano_roll.show(
    ctx,
    &self.project,
    self.pattern,
    playhead,
    &held,
    area,
    roll_zoom,
);
for action in roll_actions {
    self.apply_roll(action);
}
}

self.piano_roll.show(..., &self.project, ...) borrows one field mutably and another one immutably at the same time, which the borrow checker allows because they are different fields. apply_roll then changes the pattern through edit_pattern, as the rack does:

#![allow(unused)]
fn main() {
RollAction::ReplaceNotes { channel, old, new, label } => {
    self.edit_pattern(label, |pattern| {
        pattern.replace_notes(channel, &old, &new);
    });
}
}

When a channel is removed, PianoRoll::channel_removed either lets go of its channel (it is gone) or moves its channel number down by one, so it keeps showing the same channel; channel_inserted does the opposite when undo brings a channel back.

In a short window, under 420 points, the grid comes first: the hint lines under the toolbar move into the tooltip of the line that names the chord, so a small screen still shows a dozen rows of notes.

The playlist

A big grid: show_viewport

The playlist can be far bigger than the window: dozens of bars, and as many tracks as the song uses. It goes in a scroll area. But some parts must not scroll away: the track names on the left, and the bar numbers and the strips above them at the top.

ScrollArea::show_viewport makes this possible. Its closure receives the visible part of the content, as a rectangle measured from the content’s top-left corner:

#![allow(unused)]
fn main() {
let output = area.show_viewport(ui, |ui, viewport| {
    self.grid(ui, viewport, project, current, playhead, &mut actions)
});
}

grid allocates the full size of the content, then works out where the visible part is on screen:

#![allow(unused)]
fn main() {
let (rect, response) = ui.allocate_exact_size(size, Sense::click_and_drag());

// `viewport` is the visible part, measured from the top-left of the
// content. Moving it by the content's position on screen gives the
// visible part in screen coordinates, where everything is drawn.
let visible = viewport.translate(rect.min.to_vec2());
}

rect is the whole content in screen coordinates (its top-left corner moves up and left as you scroll). Adding that corner to viewport gives visible, the part of the screen where the content shows. Then:

• the tracks and clips are drawn at their place in the content, so they scroll;
• the track names are drawn at visible.left(), and the ruler and the strips at visible.top(), so they stay put while the clips slide underneath.

They are drawn after the clips, so they cover them.

The arithmetic for steps, tracks and pixels lives in a small Copy struct, as in the piano roll:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy)]
struct Layout<'a> {
    /// The top-left corner of step 0 of track 0.
    origin: Pos2,
    /// How wide a step is and how tall a track is: the zoom.
    step_width: f32,
    track_tops: &'a [f32],
    tracks: usize,
    /// Whether there is an empty row below the last track, where a clip
    /// starts a new track. There is unless the playlist is full.
    spare: bool,
}
}

Each track can have its own height, so Layout keeps where each track starts (track_tops), worked out once per frame. To find the track under the pointer, cell_at uses partition_point, a binary search on that sorted list: the number of tops above the pointer, minus one, is the track.

Real widgets in a painted area: ui.put

Everything in the grid is painted by hand, but the track names should be editable text fields and the mute lights should be the same light as in the rack. ui.put places any widget in a rectangle you choose:

#![allow(unused)]
fn main() {
let light_response = ui
    .put(light, |ui: &mut Ui| widgets::mute_light(ui, enabled))
    .on_hover_text(tr("Click to mute or unmute the track"));

let shown = tr_name(&track.name).into_owned();
let mut name = shown.clone();
let field = egui::TextEdit::singleline(&mut name)
    .frame(egui::Frame::NONE)
    .text_color(HEADER_TEXT);
let name_response = ui.put(name_rect, field);
if name_response.changed() && name != shown {
    actions.push(PlaylistAction::RenameTrack { track: index, name });
}
}

• A closure |ui: &mut Ui| -> Response counts as a widget: egui implements its Widget trait for any such closure. That is how a function-style widget like mute_light can be passed to put.
• The text field edits a copy of the name. If it changed, the copy goes into a RenameTrack action, and the app changes the project. The playlist keeps the rule that it never changes the project itself.
• Frame::NONE removes the field’s border, so it looks like a label until you click it.

Placing, moving and stretching clips

Placing, moving and deleting clips follows the piano roll’s pattern: a press decides what the drag is, and the drag follows the pointer until the button is released.

#![allow(unused)]
fn main() {
struct ClipDrag {
    index: usize,
    grab: usize,
    stretch: bool,
}
}

A press on empty space places a clip of the selected pattern and starts moving it; a press on a clip starts moving that clip and selects its pattern; a press on a clip’s right edge starts stretching it, which repeats its pattern as many times as fit up to the pointer. The press is handled where the button went down:

#![allow(unused)]
fn main() {
// A press is handled where the button went down. A quick hand can
// press and move in the same frame, and the clip or empty cell
// under the pointer *now* may not be the one that was clicked.
// A click that closes a menu does nothing else.
let dismissing = widgets::dismissing(ui.ctx());
let pressed_at = press_origin.filter(|pos| {
    primary_pressed && !dismissing && response.hovered() && cells.contains(*pos)
});
if let Some(pos) = pressed_at {
    let (track, step) = layout.cell_at(pos);
    match clip_at(project, layout, pos) {
        Some(index) => { /* start moving or stretching that clip */ }
        None => { /* add a clip of the selected pattern, and start moving it */ }
    }
}
}

Option::filter keeps the value only if the closure returns true, so pressed_at is Some only on the frame of a press, over the grid.

Positions snap to the grid you choose in the toolbar: a bar, a beat or a step. Where bars and beats fall depends on the time signature at that point of the song, so the snap asks the song’s Meter:

#![allow(unused)]
fn main() {
/// The snap point at or before `step`. Where the bars and beats are
/// depends on the time signature there: a bar of 3/4 is 12 steps, a
/// beat of 6/8 is 6.
fn floor(self, step: usize, meter: &Meter) -> usize {
    match self {
        Snap::Bar => meter.floor_to_bar(step),
        Snap::Beat => meter.floor_to_beat(step),
        Snap::Step => step,
    }
}
}

Ctrl or Shift and a click adds a clip to the selection, Ctrl and a drag on empty space draws a box around clips, and dragging one of several selected clips moves them all, kept inside the playlist.

Double-click a clip to edit it

In most music programs you double-click a clip to edit it. egui counts the clicks:

#![allow(unused)]
fn main() {
let double_clicked = ui.input(|input| {
    input
        .pointer
        .button_double_clicked(egui::PointerButton::Primary)
});
if double_clicked
    && !dismissing
    && response.hovered()
    && let Some(pos) = pointer.filter(|pos| cells.contains(*pos))
    && let Some(index) = clip_at(project, layout, pos)
{
    actions.push(PlaylistAction::EditClip(clips[index].pattern));
}
}

The app picks the editor: the piano roll, on the busiest channel, when the pattern has melodies or chords; the channel rack when it only has drums. Either way the window comes to the front, and takes the keyboard with it:

#![allow(unused)]
fn main() {
fn bring_window_to_front(&mut self, ctx: &egui::Context) {
    if let Some(id) = self.bring_to_front.take() {
        let layer = egui::LayerId::new(egui::Order::Middle, id);
        ctx.move_to_top(layer);
        // Its keys go with it: Delete after double-clicking a clip
        // deletes notes in the piano roll, not clips in the playlist.
        widgets::give_keyboard(ctx, layer);
    }
}
}

A window’s layer is named by the id the window was given, which is why the rack and the piano roll get theirs from small functions (rack_id() and PianoRoll::id()) instead of writing the same Id::unique(...) in several places.

Drawing a clip’s notes: Box<dyn Fn>

Each clip shows a sketch of its pattern. Drum patterns look best as a tiny step sequencer (one line per channel), anything with melody as a tiny piano roll (higher notes higher). The two need different ways to turn a note into a height, chosen once per clip:

#![allow(unused)]
fn main() {
// Turns a channel and a note into a height from 0.0 (bottom) to 1.0 (top).
let height: Box<dyn Fn(usize, u8) -> f32> = if steps_only {
    let used: Vec<usize> = (0..channels)
        .filter(|&channel| !pattern.notes(channel).is_empty())
        .collect();
    let count = used.len().max(1) as f32;
    Box::new(move |channel, _| {
        let row = used.iter().position(|&c| c == channel).unwrap_or(0) as f32;
        1.0 - (row + 0.5) / count
    })
} else {
    // ...the lowest and highest note, as in the rack's mini piano roll...
    Box::new(move |_, midi| ((midi - lowest) as f32 + centering) / span)
};
}

Every closure has its own, unnamed type, so the two branches of the if produce values of different types, and a variable can only have one type. Box<dyn Fn(usize, u8) -> f32> is the common type: “a closure on the heap that takes a channel and a pitch and returns a height”. dyn Fn is a trait object, like dyn App in main.rs. The move keyword makes each closure take ownership of what it uses (used, lowest…), which must outlive the if that created them.

This runs on the window’s thread, once per clip per frame, so the small allocation for the Box does not matter. On the audio thread it would.

A clip’s colour is its pattern’s. Each pattern keeps a color, a place in the playlist’s palette, saved in the project file. It does not come from the pattern’s number, because then deleting the first pattern would recolour all the others.

Only the tracks you use

A project has only the tracks down to its last clip: File > New has one track, a demo has the ones it uses. Below the last track there is a fainter spare row: place a clip on it (or drag one onto it) and it becomes a track. Its header has a ➕ New track button too.

Project::clip_fits decides whether a clip may go somewhere. One more row than the tracks is allowed, the one just below the last track, as long as the playlist is not full:

#![allow(unused)]
fn main() {
fn clip_fits(&self, clip: Clip) -> bool {
    let tracks = self.playlist.tracks.len();
    clip.pattern < self.patterns.len()
        && (clip.track < tracks || (clip.track == tracks && tracks < MAX_TRACKS))
        && clip.start < MAX_SONG_STEPS
        && (1..=MAX_REPEATS).contains(&clip.repeats)
}
}

add_clip and move_clip then call open_track, which adds a track when the clip is on that new row. Because the track and the clip are added by the same edit, one Ctrl+Z takes both away. The playlist view only has to draw one more row: Layout has its spare flag and a rows() method, and cell_at clamps to rows().

Demos are built on a playlist of sixteen tracks, because naming track 0 and track 1 is easier when they exist; at the end, remove_unused_tracks drops the empty tracks at the bottom. Files saved before tracks were trimmed need almost the same thing, with one difference: a track someone renamed or muted was kept on purpose, so loading drops only tracks that are exactly as a new track starts. Two rules, one loop, which takes the rule as a closure:

#![allow(unused)]
fn main() {
pub fn remove_unused_tracks(&mut self) {
    self.trim_tracks(|_, _| true);
}

pub(crate) fn remove_blank_tracks(&mut self) {
    self.trim_tracks(|index, track| *track == Track::numbered(index + 1));
}

fn trim_tracks(&mut self, drop: impl Fn(usize, &Track) -> bool) {
    // ...from the bottom, pop tracks with no clips while `drop` says so...
}
}

impl Fn(usize, &Track) -> bool means “any function or closure that takes a row number and a track and answers yes or no”. The compiler makes a copy of trim_tracks for each closure, so this costs nothing at run time. Comparing with Track::numbered(index + 1) works because Track derives PartialEq: a blank track is equal to a brand new one for its row.

Trimming only ever removes tracks below the last clip. An empty track in the middle stays, because removing it would move every clip under it up a row.

Inserting, moving and deleting tracks

A clip names its track by number. Insert a track at row 2, and every clip on row 2 or below must move down one, or the drums would suddenly sit on the wrong track:

#![allow(unused)]
fn main() {
pub fn insert_track(&mut self, index: usize) -> Option<usize> {
    let tracks = &mut self.playlist.tracks;
    if tracks.len() >= MAX_TRACKS {
        return None;
    }
    let index = index.min(tracks.len());
    tracks.insert(index, Track::numbered(tracks.len() + 1));
    for clip in &mut self.playlist.clips {
        if clip.track >= index {
            clip.track += 1;
        }
    }
    Some(index)
}
}

remove_track is the mirror image: drop the track’s clips with retain, then move the ones below up one. swap_tracks swaps two rows and the clips on them. Whoever changes the list fixes the numbers that point into it, which is why the fields are private and only Project’s methods change them (see The project). Each of these is one call inside edit, so undo brings a deleted track back with its clips.

The menu is egui’s context_menu on the track’s name field. A text field still opens a menu on a right-click, because typing only needs the left button. A track’s lower edge can be dragged to make it taller or shorter, and a double-click on it gives it back its usual height.

Following the playhead past the names

With Follow playhead on, the playlist scrolls to keep the playhead in view. When a song plays to its end and starts again, or a loop goes back to its start, the playhead jumps left and the view follows it. But the track names on the left are drawn over the bars, and to the scroll area they are not there at all: revealing the playhead could leave it under them. So follow_x is told how wide the fixed part is, and makes the rectangle it reveals reach that much further left:

#![allow(unused)]
fn main() {
pub fn follow_x(ui: &Ui, step: Option<usize>, x: f32, view: Rect, covered: f32) {
    // ...only when the step changed, and Follow playhead is on...
        let margin = (view.width() * 0.1).min(60.0);
        let y = view.center().y;
        ui.scroll_to_rect(
            Rect::from_min_max(
                pos2(x - margin - covered, y - 0.5),
                pos2(x + margin, y + 0.5),
            ),
            None,
        );
}
}

scroll_to_rect scrolls as little as it can so the rectangle is inside the view. Going left, that leaves the rectangle’s left edge at the view’s left edge, covered points left of the playhead, so the playhead ends up right of the names. The playlist passes HEADER_WIDTH (its names), the piano roll KEY_WIDTH (its keyboard). Going right, nothing changes. Only a new step scrolls, so you can still scroll by hand while the music plays.

Trying the windows

The tools and the project are covered by unit tests, and many of the editors’ behaviours by tests that draw the window without a screen (see Testing a window without a screen). But some problems only show when a person uses the window: a window that creeps taller on every frame, a menu that closes when you pick a choice in it, a chord that lands above the pointer instead of around it. That is a good habit for any UI code: write the logic so it can be tested without the window, and then still try the window.

Two languages: translations, and letters or solfège

Files: crates/lineup-core/src/i18n.rs, crates/lineup-core/src/i18n/es.rs, crates/lineup-app/src/i18n.rs, crates/lineup-core/src/pitch.rs, crates/lineup-core/src/harmony/symbol.rs, crates/lineup-core/src/chord_sheet.rs, crates/lineup-core/src/file.rs and crates/lineup-app/src/app/settings.rs

Two settings change how Ferrous Lineup talks to you:

• Edit > Settings… > Appearance > Language writes the menus, windows and settings in English or Español.
• Edit > Settings… > Harmony > Note naming names notes, keys and chords with letters (C, F#, Bb major, Am7) or in solfège (Do, Fa#, Sib major, Lam7).

They are separate, so you can have Spanish menus with letters, or English menus with solfège. Until you choose a note naming, though, it follows the language: Spanish menus name notes in solfège, as Spanish schools do, and English menus with letters. Once you choose one, it stays, whatever language you pick after. Both settings change only what you see. A song saved with one choice opens exactly the same for someone with the other.

Notes named Do, Re, Mi

In English and German, notes are named with letters. In Spanish, Italian, French and Portuguese, and in the countries that speak them, they are named with syllables:

letters    C    D    E    F    G    A    B
solfège    Do   Re   Mi   Fa   Sol  La   Si

Sharps and flats are written after the syllable as after the letter: F# is Fa# (Fa sostenido in Spanish) and Bb is Sib (Si bemol). A key is named the same way, so B♭ major is Sib major, or Sib mayor with Spanish menus, and D Dorian is Re dórico.

This is fixed do: Do is always C, whatever the key. Some ear-training methods use a movable do instead, where do is the tonic of the key (in G major, do is G). The app always uses fixed do, as Spanish and Italian schools do, since a note’s name must not change with the key.

Octave numbers stay as they were: middle C is C4 in letters and Do4 in solfège, the octave starting at C and going up to B. Some French and Spanish books number octaves one lower and call middle C Do3. The app keeps one numbering, so a note keeps its number whichever way it is named.

Chords in solfège

A chord symbol is a root, a quality and sometimes a bass note. In solfège only the note names change:

letters    C    Am7     G7/B     Bdim     F#m7b5    Eb+
solfège    Do   Lam7    Sol7/Si  Sidim    Fa#m7b5   Mib+

Spanish-speaking musicians call the first way cifrado americano and the second cifrado latino. Lead sheets for jazz and pop are usually in letters, even in Spanish; teachers and songbooks often use syllables. With solfège chosen, the chord sheet, the harmony keys, the piano roll, the playlist’s key changes and the examples in the hints all write notes, keys and chords the second way.

Typing a chord either way

You can type a chord either way, whichever is chosen: Am7 and Lam7 are the same chord. After Enter, the bar shows it the way the setting names notes.

A few names could be read both ways. o is one way of typing a diminished chord (Bo is B°), so Do could be C (solfège) or D° (letters), and Do7 could be C7 or D°7. The app reads such a name the way the setting names notes: with solfège chosen, Do is C. Names that only make sense one way are read that way: Faug is F augmented even with solfège chosen, because “Fa” followed by “ug” is not a chord, and Fam is F minor even with letters chosen.

The quality is written the same in both: F augmented is Faaug in solfège. It reads back correctly, but Fa+ is easier on the eye, and the app reads it too.

On the chord sheet, typing on a selected bar starts typing in it, but L is the key that switches between pattern and song. With solfège chosen, La chords start with L, so there L starts typing instead. With letters chosen, no chord starts with L, and L switches as before.

What is saved

Projects, saved styles, the chord-sheet text that Ctrl+C copies, and playback traces are always written with letters, and in English. The settings never reach them. So a song you saved while seeing Lam7 contains Am7, and opens with Am7 or Lam7 according to the settings of whoever opens it.

In the code

Two settings, kept like the numerals setting

Language and NoteNaming (both in lineup-core) are kept like the minor-key numerals setting: an enum with a #[default], a thread_local! Cell that every function can read, and a with that sets it for a while and puts it back with a Drop guard, even after a panic.

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
pub enum NoteNaming {
    #[default]
    Letters,
    Solfege,
}

thread_local! {
    static NOTE_NAMING: Cell<NoteNaming> = const { Cell::new(NoteNaming::Letters) };
}
}

A note is printed in hundreds of places, through its Display implementation ({} in format!). A per-thread value lets all of them follow the setting without passing it down through every function:

#![allow(unused)]
fn main() {
impl fmt::Display for NoteName {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.format(NoteNaming::current()))
    }
}
}

The window sets both values from the saved settings before drawing each frame:

#![allow(unused)]
fn main() {
pub fn apply_settings(ctx: &egui::Context) {
    language(ctx).set();
    note_naming(ctx).set();
}
}

A video export draws its views on a thread of its own, which starts with the defaults, so it takes the language and the naming along, as it already took the numerals setting.

Solfège until you choose

egui keeps the window’s preferences as values under an Id, and get_persisted gives None for an Id nothing was stored under. That None is what tells “never chosen” apart from a choice, so the naming falls back on the language only then:

#![allow(unused)]
fn main() {
pub fn note_naming(ctx: &egui::Context) -> NoteNaming {
    ctx.data_mut(|data| data.get_persisted(note_naming_id()))
        .unwrap_or_else(|| language_naming(language(ctx)))
}

/// How notes are named where `language` is spoken.
fn language_naming(language: Language) -> NoteNaming {
    match language {
        Language::English => NoteNaming::Letters,
        Language::Spanish => NoteNaming::Solfege,
    }
}
}

Reading never stores anything; only set_note_naming, called when you click a naming in Settings, does. So until that click, every frame asks the language again, and switching to Spanish switches the notes to solfège. The match has no _ arm on purpose: a third language would not compile until someone says how it names notes.

Translating: the English text is the key

Each piece of text the interface shows is written in English in the code and goes through tr. It lives in lineup-core, not in the app, so that the texts the core writes, the names of styles, instruments, chords and scales, are translated too:

#![allow(unused)]
fn main() {
pub fn tr(text: &'static str) -> &'static str {
    match Language::current() {
        Language::English => text,
        Language::Spanish => in_spanish(text).unwrap_or_else(|| missed(text)),
    }
}
}

The Spanish catalog is in i18n/es.rs: a big match for the menus, the main windows and the settings, and, in the files of i18n/es/, tables of pairs by area (the app, theory, instruments, the library, the songs), gathered once into a HashMap:

#![allow(unused)]
fn main() {
static TEXTS: LazyLock<HashMap<&'static str, &'static str>> =
    LazyLock::new(|| TABLES.into_iter().flatten().copied().collect());

/// `text` in Spanish, or `None` for a text with no translation yet.
pub fn translate(text: &str) -> Option<&'static str> {
    main_texts(text).or_else(|| TEXTS.get(text).copied())
}
}

LazyLock builds the map the first time it is used, on whichever thread asks first, and every thread shares it after that. flatten turns the five tables into one run of pairs, and collect builds the map from them.

Using the English text itself as the key has two advantages. The code still reads naturally (tr("Settings"), not tr(SETTINGS_TITLE)), and a text with no translation yet simply stays in English, through unwrap_or_else. The cost is that changing an English text means changing its key in the catalog too, or the Spanish one is lost; a test catches that (see below).

Both the argument and the result are &'static str: text written in the program itself, which lives as long as the program does. So tr can return either one without copying anything.

A few relatives of tr cover the other cases:

• trf("{} steps a bar", &[&12]) puts its arguments where the translated text has {}, so the Spanish can put the number among other words: “12 pasos por compás”.
• trc("clef", "Bass") is for a word whose translation depends on where it is shown: the bass clef is “Fa”, the instrument “Bajo”. The catalog has it as "clef|Bass".
• tr_name translates the names the app gives things, a channel, a track or a pattern: “Bass” is “Bajo”, “Pattern 12” is “Patrón 12” and “A drums” is “Batería de A”. A name you typed yourself stays as typed.
• A catalog text can name notes in braces, as in "{Bb} mayor"; they are named as the setting says (see Examples that follow the setting). Such a text is built once for each naming and kept, with Box::leak, which turns a String into a &'static str that is never freed. There are only so many texts and two namings, so the memory kept has a limit.

Names on screen, letters in files

Since Display follows the setting, anything that turns a note into text and saves it would save solfège. The places where data leaves the program run with letters instead, through with:

#![allow(unused)]
fn main() {
pub fn to_text(project: &Project) -> Result<String, FileError> {
    // …
    let file = Language::English.with(|| NoteNaming::Letters.with(|| ProjectFile::from(project)));
    let mut text = NoteNaming::Letters.with(|| ron::ser::to_string_pretty(&file, style))?;
    // …
}
}

A chord marker is saved as its text, through the serde attributes into = "String" and try_from = "String" (see Twelve-tone rows). Its conversions run with letters too, so a marker is saved as Am7 wherever it is saved from:

#![allow(unused)]
fn main() {
impl From<HarmonyName> for String {
    fn from(harmony: HarmonyName) -> Self {
        NoteNaming::Letters.with(|| harmony.to_string())
    }
}
}

Saved styles, the chord-sheet text and the playback trace do the same. The library’s own charts are written in letters in the source, so they are read with letters too.

Reading a name either way

NoteName::read_as reads a note at the start of a text in one naming, and gives back the name and the rest of the text. For solfège it tries each syllable:

#![allow(unused)]
fn main() {
NoteNaming::Solfege => Letter::ALL.into_iter().find_map(|letter| {
    text.strip_prefix(letter.solfege())
        .map(|rest| (letter, rest))
})?,
}

strip_prefix returns the text after the prefix if the text starts with it, and None if not. find_map returns the first Some. “Sol” and “Si” both start with S, but neither is the start of the other, so only one can match.

read_either tries both namings, the setting’s own first, and keeps the first reading whose rest fits:

#![allow(unused)]
fn main() {
pub fn read_either<'a>(
    text: &'a str,
    fits: impl Fn(&'a str) -> bool,
) -> Option<(NoteName, &'a str)> {
    NoteNaming::current()
        .reading_order()
        .into_iter()
        .filter_map(|naming| NoteName::read_as(text, naming))
        .find(|&(_, rest)| fits(rest))
}
}

What “fits” means depends on the caller, so it is a closure. A chord symbol fits when the rest is a quality and maybe a bass; a whole note name fits when nothing is left:

#![allow(unused)]
fn main() {
pub fn parse(text: &str) -> Option<NoteName> {
    NoteName::read_either(text, str::is_empty).map(|(name, _)| name)
}
}

str::is_empty is a function, and a function can be passed wherever a closure with the same arguments is expected.

The lifetime 'a says that the rest handed to fits, and returned, is a piece of text, not a copy. That is how “Faug” works with solfège chosen: “Fa” leaves “ug”, which fits rejects, so the letters reading, F with “aug”, is tried and kept.

Examples that follow the setting

The hints on the chord sheet and in the settings give example chords. They are written with the notes in braces, {A}m7 {D}7, and with_notes names each one as the setting says, so with solfège chosen the hint reads “Lam7 Re7”. Braces around anything that is not a note name, like the set {0,1,4} in the same hint, are left alone.

L for La

ChordSheet::takes_l says whether an L typed now belongs to the sheet: the sheet has the keyboard, a bar is selected, nothing is being typed yet, and notes are named in solfège. The app’s L shortcut checks it first:

#![allow(unused)]
fn main() {
let l_types = self.chord_sheet.takes_l() && !self.live.typing();
if !typing && !controls_active && !l_types && pressed(egui::Key::L) {
}

!self.live.typing() is there because with the typing keyboard on, letters play notes, and L switches pattern and song as usual.

Outside the app

The Linux desktop file has Spanish lines next to the English ones, GenericName[es]=Banda de acompañamiento for example, which a Spanish desktop shows in its menus. The AppStream file that software centres read gives each paragraph of the description a Spanish twin, <p xml:lang="es">, and appstreamcli validate checks it.

The tests

every_window_writes_in_spanish opens six demos in Spanish with every window open, then the shortcuts, About, the video export, the style editor, each page of Settings and each menu. It fails if anything asked tr for a text the catalog has no Spanish for, or if any text drawn on screen is an English text the catalog does have Spanish for, which catches text drawn without tr. In the core, every_name_and_description_the_app_shows_has_spanish does the same for every instrument, style, chord, scale and demo name the core gives the app.

solfege_changes_how_names_look_not_what_is_saved builds every demo song twice, once with letters and once with solfège, and checks that the saved file and the chord-sheet text are identical, and that every chord, written as the sheet shows it in solfège, reads back as the same chord.

names_are_read_in_letters_or_solfege reads Sib7, Fa#m, Sol and Reb, and checks that Do7 starts with D when letters are chosen and with C when solfège is. solfege_is_a_way_of_showing_names checks that Am7 shows as Lam7, G/B as Sol/Si and B♭ major as Sib mayor, and that Lam7 and Am7 are the same chord.

in_solfege_l_types_la_chords_and_in_letters_it_switches_mode selects a bar on the chord sheet, presses L with solfège chosen and types Lam7, then checks that the mode stayed and the bar holds A minor 7; with letters, L switches the mode and leaves the bar alone.

spanish_names_notes_in_solfege_until_a_naming_is_chosen switches the language back and forth with no naming chosen, and the naming follows it; then it chooses a naming and switches the language again, and the naming stays. spanish_names_notes_in_solfege_and_keeps_letters_once_chosen does it the way you would: Spanish menus, Armonía, Letras (C, D, E…), and a restart of the app, after which the notes are still letters.

Exercises: the shape of the program

These exercises practise the Rust of this part on the real code. Each one says what is already there, so you extend it rather than build it again. Some are small pieces of work with a clear end; the ones called “Think about it” are questions, with no code to write.

Try them on a branch of your own. Run cargo test after each change, and cargo fmt --all --check and cargo clippy --workspace --all-targets -- -D warnings before you call one finished: CI runs all three.

Crates and threads

1. Break it on purpose (any crate)

Learning to read compiler errors is half of learning Rust. Try each of these, read the error, then undo it:

• In AudioEngine::new (engine.rs), call build_stream::<f32>(&device, config.clone(), audio_thread, Arc::clone(&problems)) twice in a row, so the second call fails because audio_thread was moved into the first.
• Remove move from the audio callback closure in build_stream.
• Add a variant SetName(String) to Command. Why can Command not be Copy? Which variants already make that impossible, and what does the compiler say when you ask for Clone?
• Make Note’s field pub (in lineup-core/src/pitch.rs) and write Note(200) in app.rs. Why does that compile, and why is it a bad idea?

Practises: ownership, move closures, Copy and non-Copy types, privacy.

2. Think about it: the audio thread

• Why would Command::InsertChannel { instrument: Box<Instrument>, ... } be worse than sending the instrument by value? (Instrument already boxes its voice arrays; what would a second box buy?)
• What would happen if the window forgot to call collect_garbage?
• Garbage is one enum with a variant for each kind of thing thrown away. What would one trash queue per kind cost, and what would it gain?
• AudioEngine::playhead uses Ordering::Relaxed. Could the window ever see a step number that was never played?

The project

3. Delete every empty track (lineup-core and lineup-app, easy)

Deleting one track is already there: read Project::remove_track and the “Delete track” item in the track’s right-click menu. It removes the track and its clips, and moves the clips of the tracks below it up by one, just as remove_pattern does for patterns.

What is missing is a way to remove all the empty tracks at once. remove_unused_tracks only drops empty tracks at the bottom of the playlist (it calls trim_tracks). Add remove_empty_tracks, which removes a track wherever it is if it has no clips, and an item for it in the track menu. Which indices must you visit, and in which order, so that the clips keep pointing at the right tracks? What should happen if that would leave no tracks? Write a test with the demo song first, then the method.

Practises: retain, keeping rules that span two lists, testing the order of index changes.

4. Think about it: positions or ids

Clips refer to patterns by their position in the list, which is why remove_pattern has to renumber them. Imagine instead that every pattern has a permanent id (struct PatternId(u32)) that never changes.

• Which methods of Project become simpler, and which harder?
• What would change in the file, and in the audio thread’s ChannelNotes?
• Would undo be easier with ids or with positions?

Telling the audio thread what changed

5. Random edits for the diff (lineup-core, medium)

The diff tests check hand-picked cases. Write one that checks a thousand random ones: start from the demo, make a random edit (toggle a step, add or remove a pattern or a channel, change a volume, move a clip…), call check_both_ways(&before, &after), and repeat from the new project.

For randomness without any crate, a tiny “xorshift” generator is enough for tests:

#![allow(unused)]
fn main() {
struct Random(u64);

impl Random {
    fn next(&mut self, below: usize) -> usize {
        self.0 ^= self.0 << 13;
        self.0 ^= self.0 >> 7;
        self.0 ^= self.0 << 17;
        (self.0 % below as u64) as usize
    }
}
}

Start it from a fixed number (not 0, which stays 0 forever), so a failure happens again every time you run the test. If you want to go further, the proptest crate does this properly, and when it finds a failing case it shrinks it to the smallest list of edits that still fails.

Also try several random edits between two checks, as one undo step might hold. Does diff ever produce a long list where a short one would do? Is that a problem?

Practises: property-based testing, reproducible randomness.

6. Channels lined up by name (lineup-core, medium)

diff lines up the channels of two projects with |old, new| old == new, and the patterns with same_pattern. Write same_channel(old: &Channel, new: &Channel) -> bool, which says two channels are the same when they have the same name, and pass it to Alignment::new instead. Run the diff tests. Then find a case where it gives the wrong answer: what happens with two channels called “Piano”?

Practises: functions as arguments, what “the same” means.

7. Think about it: what to send

• SetNotes sends a channel’s whole list of notes for every change. At what size would that become a problem, and what would you send instead?
• The window sends the song’s length along with its pieces, instead of letting the audio thread work it out. What would it take to keep two copies of that calculation in agreement, and how would you notice if they drifted apart? The pieces are Plays made by Project::playback_arrangement. Why is unrolling repeats on the window’s side simpler than teaching the audio thread about sections?
• Undo while the song plays. When undo removes a channel, its ringing notes stop at once, because the channel goes to the trash. In the case of three identical Lineup Osc channels, the audio thread removes the last channel and gives its notes to another one. Which channel’s ringing note keeps sounding, and could you ever hear the difference?

Undo and redo

8. An undo history window (lineup-app, easy)

Add Edit > History…, a small window listing every step that can be undone or redone, newest at the top, with the current position marked. Clicking a step jumps there.

You need two methods on History: one giving the undo labels and one the redo labels, each as an iterator (self.undo.iter().map(|step| step.label)). Jumping back five steps is five calls to history.undo. Should sync_audio run after each one, or once at the end, comparing with the project from before the first? Which is cheaper, and does the audio thread end up the same either way? (Exercise 5 answers the last question.)

Practises: iterators over private fields, rev(), reusing diff.

9. Cheaper snapshots (lineup-core, harder)

Every undo step copies the whole project, every pattern included, even though a click on a step changes one pattern. (A drag copies once, when its step opens, not on every frame, but the copy is still the whole project.) Make the copies cheap by sharing what did not change: store the patterns as Vec<Arc<Pattern>>.

Cloning a Vec<Arc<Pattern>> copies only the pointers and adds one to each count; the patterns themselves are shared between the current project and every copy in the history. To change one, use Arc::make_mut, which gives a &mut Pattern and first makes a private copy only if the pattern is shared (“clone on write”). So Project::pattern_mut becomes self.patterns.get_mut(index).map(Arc::make_mut).

Then diff can skip unchanged patterns quickly: if Arc::ptr_eq says two patterns are the same memory, they are certainly equal. Make a test project with 999 patterns full of notes, and measure the time of an edit before and after with std::time::Instant. Does PartialEq for the project still work unchanged? Does the file format need to change?

Practises: Arc for sharing, clone on write, measuring before optimizing.

10. Think about it: labels and what undo covers

• Step labels are &'static str, so “rename pattern” cannot say which pattern. A String label would allow “rename pattern Beat”, but most labels are fixed text, and a String would allocate for each of them. Look up std::borrow::Cow<'static, str>: how does it let a label be either, and allocate only when it must?
• The master volume is part of the project’s mixer, so undo changes it back, and it is saved with the song. The selected pattern, the zoom and the open windows are not. Would you expect undo to change any of them? What would have to move into Project for that, and what would it mean for the saved file?

Saving

11. A new project field and its format test (lineup-core, medium)

Goal. Add one harmless field to a project, save it without breaking old files, and prove that a song which uses it is written as the next format. ProjectFile, its serde defaults and the file tests are already there; this is the smallest complete exercise in growing the format.

Files. crates/lineup-core/src/project.rs, crates/lineup-core/src/file.rs.

Steps.

1. Add pub notes: String to Project, initialized to String::new() in Project::empty.
2. Add notes: String to ProjectFile, with #[serde(default, skip_serializing_if = "String::is_empty")], and copy it in both directions.
3. Raise FORMAT_VERSION by one, to 30 (if another exercise already took 30, use the next free number). In format_for, return the new number first when !project.notes.is_empty(); leave everything else as it is.
4. Write three tests in file.rs: an empty project stays at its old format and has no notes: line; a project with notes is the new format and round-trips; and a file written before the field existed reads back with empty notes.

Run. cargo test -p lineup-core file.

Done when. Old project texts still open, the new field survives a round trip, and format_for names the new number only for a song that needs it. files_from_the_future_are_refused builds its file from FORMAT_VERSION + 1, so it keeps passing.

12. A recovery copy that is damaged (lineup-app, easy)

Goal. Make crash recovery trustworthy when the copy on disk is not. app/recovery.rs already writes a project copy, an .info file and a lock file for each window to the recovery folder in the app’s data folder, offers the copy at the next start, and removes a copy that will not load. The test a_recovery_copy_comes_back_with_its_file covers the happy path. Add the unhappy ones.

Files. crates/lineup-app/src/app/recovery.rs.

Steps.

1. See it by hand: open a demo, type a chord in the first bar, wait a moment, and force-quit the app. Do not use File > Quit. Start it again and choose Recover it. Close the recovered song without saving it.
2. Read Files, load and write, and the tests at the bottom of the file.
3. Add a test that takes Files::of_run(&folder, "test"), creates the folder, writes rubbish into its project file, puts a valid info file beside it, calls load(files.clone(), None), and checks that it returns None and that both files are gone.
4. Add a second test that writes a valid project to files.project with file::save, but leaves out the info file. Check that load still returns the project, with no path and no name, so the dialog can call it “Untitled”.
5. Remove the temporary folder at the end of each test, as the existing ones do.

Run. cargo test -p lineup-app recovery.

Done when. Both tests pass, and the first fails if the files.remove() call in load’s error branch is deleted.

13. Forget a recent project (lineup-app, medium)

File > Open recent remembers the last ten projects in egui’s persisted data, and stays right when a file has been moved or deleted (the open fails and the path is removed). Read app/recent.rs.

Extend it: a “Clear recent” item that forgets the whole list, and a small ✕ next to each entry that forgets one. The ✕ must not also open the file, so watch the order in which you check the two clicks. Why is the list stored as Vec<String> rather than Vec<PathBuf>, and what happens to a path that is not UTF-8?

Practises: egui menus, persistence, paths that are not UTF-8.

14. Reading numbers slowly (lineup-core and RON, medium)

The version number explains why the app no longer reads a file’s format through a struct with one field: skipping the rest of the file made RON look ahead, number after number, to the end of the text.

1. Say a saved song is 2 MB of text with 120,000 numbers in it. If skipping each number reads, on average, half the file, how many bytes are read in total? At about 2 GB a second, how long does that take? How long for a song twice as long?
2. Find the look-ahead in RON’s source: in the version Cargo.lock names, src/parse.rs searches self.src()[skip..] for "..". Rewrite that line so it searches only the first raw_float_len characters. (Hint: slice self.src()[skip..][..raw_float_len], and think about what happens if the slice ended in the middle of a character.) Then compare with how RON 0.12.3 does it, and read its comment on why a .. cannot straddle the end.
3. format_number returns None for (tempo: 120.0, format: 25). Why is it fine that it only reads the start of the file? (Look at the order of the fields in ProjectFile, and at to_text.)

Practises: thinking in growth rates, reading a library’s source, string slices.

15. Think about it: files

• has_unsaved_changes compares the whole project with the saved copy, but only after an edit or an undo sets check_dirty, not on every frame. Roughly how many notes would a project need before one comparison takes a noticeable part of a frame (about 16 milliseconds)? Why does project_edited set check_dirty only when dirty is already false? What would a counter that every edit increases add to this design?
• The project file has its own types (ProjectFile, PatternFile) instead of deriving Serialize on Project itself. What would go wrong the day someone renames a field of Project, if the file used it directly?
• An older Ferrous Lineup refuses to open a file with a newer format number. Could it load what it understands and ignore the rest instead? When would that be helpful, and when would it quietly lose someone’s work?
• The damaged-file test writes NaN in place of numbers. What happens when a project file says tempo: NaN? And master: NaN? Find the code that decides each, and say why they differ.

Drawing the windows

16. A double-click resets the volume (lineup-app, easy)

Make a double-click on the toolbar’s VOL slider set the master volume back to lineup_core::Mixer::default().master (0.8). A Reset button would not fit: the toolbar must stay on one row in a window 1280 points wide, in Spanish too, and the_toolbar_fits_on_one_row_at_1280_points checks it.

Call LineupApp::set_master_volume (in app/mixer.rs) rather than assigning the field, so the change is a step to undo and the diff sends the audio thread Command::SetMasterVolume. Run the app and check that the slider moves.

Practises: immediate-mode input, Response, routing a change through edit.

17. Remember the hint level (lineup-app and lineup-core, medium)

The harmony keys’ hint level goes back to Short every time the app starts. Other choices are remembered: Remembering between runs shows how, and settings.rs keeps the minor-numerals choice with get_persisted and insert_persisted under an Id of its own. Do the same for HintLevel: give it serde’s Serialize and Deserialize in lineup-core (which already depends on serde), and read and write it where HarmonyKeys keeps hints. Which other choices would you remember the same way?

Practises: serde derives across crates, egui’s persisted data.

18. Hints everywhere (lineup-app, small)

theme::hint gives a widget a line in the hint bar and the same text as a tooltip. The toolbar, the harmony keys and some playlist buttons use it; the channel rack and the piano roll still use plain on_hover_text. Change them to theme::hint, and make the hint bar show the pattern’s name when nothing is under the mouse. Why does theme::hint take the Response by value and give it back, instead of taking &Response?

Practises: ownership through a function, egui’s Response, reading someone else’s module before changing it.

19. F10 for the metronome, and its F1 line (lineup-app, easy)

Goal. The metronome is a toggle in the toolbar and in Edit > Settings… > Playback. Give it a key and add the key to the F1 list. F10 is free; do not use plain M, which plays a note when the typing keyboard is on.

Files. crates/lineup-app/src/app/practice.rs, crates/lineup-app/src/app.rs, crates/lineup-app/src/app/shortcuts.rs, crates/lineup-app/src/app/ux_tests.rs.

Steps.

1. In practice.rs, add a KeyboardShortcut constant for F10, the way view.rs keeps F5 to F8.
2. In LineupApp::keyboard_shortcuts, read it in the same guarded place as Home and End: not while a text field has the keyboard, and not while a control is in use. Call set_metronome with the opposite of practice.view().metronome.
3. Add a line to the Anywhere section in shortcuts.rs: “Metronome on or off”. Use the constant rather than writing the key twice.
4. Add a headless test in ux_tests.rs: press F10, assert practice.view().metronome; press it again, assert it is off.

Run.

cargo test -p lineup-app shortcuts
cargo test -p lineup-app metronome

Done when. F10 toggles the toolbar button, F1 lists it under “Anywhere”, and no_two_global_shortcuts_share_a_key still passes. A new line in the F1 list is English text: the test every_window_writes_in_spanish tells you it needs a Spanish one too (see Two languages).

20. A picture and a version (lineup-app, easy)

• Draw another picture for Follow playhead in icons.rs: a playhead with two arrows. Which test tells you when a line goes outside its square?
• Add a Copy version button to the About window that puts “Ferrous Lineup” and the real version on the clipboard with ctx.copy_text. Can the text be a const, built with concat! and env!?

Practises: painting with egui, compile-time strings.

21. Think about it: lists and windows

• In shortcuts.rs, the “Harmony keys” section uses Written("1 to 7"). Why not seven KeyboardShortcuts in an Any? What would the list show then?
• The lead sheet opens with Opening::FirstTime. What would change for you if it used EveryTime? Try it, and say which you prefer.

The editors

22. Clear a row (lineup-app, easy)

Right-clicking one step already clears it (RackAction::ClearStep). Add “Clear steps” to a channel’s name menu in channel_menu, with a new RackAction::ClearRow { channel }. In LineupApp::apply, call edit_pattern to switch every step of that channel off, without sending the audio thread a command by hand: the edit’s diff sends the new notes. Why is one whole-row edit better than a loop of single-step edits?

Practises: the action pattern, keeping project and audio in step.

23. Paint steps by dragging (lineup-app, medium)

In the rack you click one step at a time. Give widgets::step_button a Sense::click_and_drag() and make Rows::steps paint every step the pointer passes over. Rows is rebuilt every frame and only returns actions, so keep the first step, and whether it was being switched on or off, in LineupApp (or in egui’s memory) and pass it in.

Add RackAction::SetStep { channel, step, on } rather than reusing ToggleStep, so a step the pointer crosses twice does not flip back. Check response.hovered() together with ui.input(|i| i.pointer.primary_down()), and stop painting when the pointer leaves the row. Should the whole drag be one step to undo? See When does one step end?

Practises: immediate-mode state, egui input, the action pattern.

24. Show the scale degree on the keys (lineup-app, easy)

paint_keys in piano_roll.rs draws a dot on every key of the scale. Draw the degree number instead (1 for the root, 2, 3…), using Scale::degree_of. A twelve-tone row already numbers its notes; keep that path as it is. Musicians use these numbers all the time (“the 5 chord”, “a flat 7”).

Practises: Option in drawing code, painter.text.

25. The rack’s lights (lineup-app, easy)

1. Make the lit light green instead of orange. Where is the colour defined, and what else uses it?
2. Give the lights on the first step of each bar a colour of their own, instead of only a brighter one.
3. While the song plays a different pattern than the rack shows, the lights stay dark. Add a faint note in the rack, such as “Not playing now”, for that case. Which values in channel_rack::show tell you the song is playing?

Practises: reading drawing code, egui colours.

26. Shorter chord names (lineup-app, medium)

The piano roll’s chord lane leaves out a name that does not fit its block. Make it try a shorter name first: for a slash chord, the chord without its bass (“E7” for “E7/B”), and then the root alone (“E”). Lay out each with layout_no_wrap and draw the first one that fits. Is a chord without its bass still the right name for what plays?

Practises: measuring text before drawing it, iterators with find.

27. Alt-drag to copy a clip (lineup-app, easy)

Ctrl+D duplicates the selected clips, but dragging a copy is quicker when you want it somewhere else. Shift is taken (Shift-click adds a clip to the selection), so use Alt.

In PlaylistView::handle_input, read the modifier keys with ui.input(|input| input.modifiers.alt). The obvious plan is to add a copy on the press and drag the copy. But add_clip refuses a clip of the same pattern that already starts at the same place, so a copy cannot be added on top of the original. Instead, remember in ClipDrag that this drag copies, and add the copy only when the pointer reaches another cell. Which index does the new clip get in Project::playlist().clips(), and how does the drag learn it?

Practises: reading egui input, reusing actions you already have.

28. A pattern colour picker (lineup-app, medium)

Pattern colours are already saved. Pattern has a public color (an index into PALETTE in playlist.rs), PatternFile writes it when it is not the pattern’s place in the list, and files without it load with the pattern’s place as its colour. Read PatternFile and pattern_color.

What is missing is the picker. Add one to the ⋯ pattern menu in the toolbar, with a little square for each palette colour, that sets the pattern’s colour through edit_pattern. Then add “Reset colours”, which gives every pattern its place in the list again. Does changing a colour need a new FORMAT_VERSION? What does an older Ferrous Lineup do with a file that has one?

Practises: evolving a file format, #[serde(default)], routing a change through edit.

29. Go to a bar (lineup-app, medium)

Home, End, Page Up and Page Down already move the playhead: read the transport keys in LineupApp::keyboard_shortcuts, seek and skip_bars. Add a small “bar” box next to the position display, where typing a bar number and pressing Enter goes there. A bar’s first step depends on every meter change before it: which function already turns a step into a bar, and can it go the other way? While you type in the box, Home and End must move the text cursor, not the playhead: what keeps them from doing both?

Practises: keyboard focus, converting bars to steps.

30. Think about it: what a drag remembers

The single-note drag in the piano roll remembers a note by its index in the list (Drag::Move { index, .. }), while a selection remembers the notes themselves. What could go wrong with the index if the list were kept sorted by start time, and a note was moved while being dragged?

Two languages

31. Letters and solfège (lineup-core and the app)

1. With solfège chosen, type Do in an empty bar of the chord sheet. Then choose letters and type Do in the next bar. What does each bar hold, and why are they different?
2. Write the seven chords of Si♭ major in solfège, then check them on the harmony keys. Which chord is diminished?
3. A project is saved with letters more than once over: file::to_text does its work inside NoteNaming::Letters.with, and so does From<HarmonyName> for String. Remove every NoteNaming::Letters.with from both, keeping what is inside, and run cargo test -p lineup-core solfege. Which check fails, and what would a friend using letters find in your file? Then put back only the one in From<HarmonyName>. The tests pass again: why, and why keep the others too?
4. with_notes leaves {0,1,4} alone. Find the line in with_notes that decides this, and say what it would do with {Do}.
5. note_naming could store the language’s naming the first time it reads none, with insert_persisted, so the next read finds it. It would look tidier. What would then go wrong for someone who starts the app in English and switches it to Spanish a week later?

Practises: thread-local settings, string slices, reading tests.

The sequencer: timing to the sample

Files: crates/lineup-core/src/sequencer.rs and crates/lineup-audio/src/engine.rs

The audio thread plays a pattern or the song by counting audio frames. The counting is done by a small type in lineup-core, the sequencer, which knows nothing about sound: it only says on which frame each step starts. Everything that sounds on a step, the notes of every channel in every clip, is the audio thread’s side, in engine.rs. This chapter follows a step from the frame count to the notes it starts. How the audio thread itself runs is in Two threads; how tempo changes, meters and swing bend the steps is in Tempo, meter, swing and feel.

The arithmetic

A step is a sixteenth note, and a beat a quarter note, so a beat has four steps (STEPS_PER_BEAT). At a tempo of T beats per minute and a sample rate of R frames per second, one beat lasts R × 60 / T frames and one step a quarter of that:

frames per step = R × 60 / T / 4

120 BPM, 48 kHz:  48000 × 60 / 120 / 4 = 6000 frames      (exact)
130 BPM, 44.1 kHz: 44100 × 60 / 130 / 4 = 5088.46... frames (not whole!)

#![allow(unused)]
fn main() {
pub fn frames_per_step(tempo: Tempo, sample_rate: u32) -> f64 {
    tempo.samples_per_beat(sample_rate) / STEPS_PER_BEAT as f64
}
}

If 5088.46 were rounded to 5088, every step would be 0.46 frames short. That is about 10 microseconds, nothing you would hear once, but it adds up: after a few minutes the drums would be audibly ahead of anything else running at 130 BPM. So the sequencer keeps the fraction, in an f64.

Ticking

The audio thread calls tick once for every frame it renders:

#![allow(unused)]
fn main() {
pub fn tick(&mut self) -> Option<usize> {
    let fired = if self.frames_until_next <= 0.0 {
        let step = self.next_step;
        if self.coming_round {
            self.laps += 1;
        }
        self.next_step = (self.next_step + 1) % self.length;
        self.coming_round = self.next_step == 0;
        self.frames_until_next += self.frames_per_step;
        Some(step)
    } else {
        None
    };
    self.frames_until_next -= 1.0;
    fired
}
}

frames_until_next counts down by one each frame. When it reaches zero, the next step fires and a whole step’s length is added to the counter, not assigned. Whatever fraction was left over stays in the counter, so step boundaries land at 0, 5088.46, 10176.92… rounded to the nearest frame each time, but never drifting. % is the remainder operator: it wraps the step number back to 0 at the end of the loop.

Because a step starts on the exact frame where it begins, not at the start of the audio block that contains it, the timing does not depend on the sound card’s buffer size. This is what sample-accurate means.

What else the sequencer can tell

Other parts of the program ask the sequencer more than “which step now”:

• position gives the step with the fraction that has passed: 4.5 is halfway through step 4. Recording uses it to put a key played between two steps on the nearer one (MIDI).
• laps counts how many times the loop came round by playing on past its last step. A jump back to the start does not count. The speed trainer goes faster on each lap (Practice tools).
• due says which step starts on the next tick, without moving. The audio thread asks it before tick, so a song whose tempo changes can set the new tempo before that step starts, and the whole step lasts as long as it should.
• start_at jumps, so the given step fires on the next tick; a step past the end wraps round, as playback would.

set_tempo changes the length of the steps to come; the step already playing keeps the frames it has left. set_length wraps to step 0 if the next step is past the new end.

Why it lives in lineup-core

The sequencer has nothing to do with sound cards. It only counts. Keeping it in lineup-core means it is tested in milliseconds, without audio, and the count-in uses a second one of its own.

Testing with iterators

#![allow(unused)]
fn main() {
fn run(sequencer: &mut Sequencer, frames: usize) -> Vec<(usize, usize)> {
    (0..frames)
        .filter_map(|frame| sequencer.tick().map(|step| (frame, step)))
        .collect()
}
}

This helper ticks the sequencer frames times and lists every step that fired together with the frame it fired on:

• 0..frames is a range, which is an iterator over numbers.
• filter_map calls the closure for each frame and keeps only the Some results, unwrapped.
• Option::map turns Some(step) into Some((frame, step)), a tuple.
• collect() gathers the results into a Vec. Rust works out which collection to build from the return type.

The tests then check exact frame numbers:

#![allow(unused)]
fn main() {
assert_eq!(
    fired,
    vec![(0, 0), (6_000, 1), (12_000, 2), (18_000, 3), (24_000, 0)]
);
}

and that one minute at 130 BPM gives exactly 520 steps (130 beats × 4), the last within one frame of where 519 exact steps put it. Underscores in number literals like 6_000 are ignored by the compiler and just make big numbers easier to read.

Pattern mode and song mode

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum PlayMode {
    /// Loop the selected pattern, to work on it.
    #[default]
    Pattern,
    /// Play the playlist from the start, and loop at the end of the song.
    Song,
}
}

The sequencer is the same in both modes. It counts steps from 0 to some length and loops. Only the length changes: the selected pattern’s length in pattern mode, the song’s length in song mode.

#![allow(unused)]
fn main() {
fn update_loop_length(&mut self) {
    let length = match self.mode {
        PlayMode::Pattern => self.pattern_length(self.pattern),
        PlayMode::Song => self.song_length,
    };
    let length = if length == 0 { STEPS_PER_BAR } else { length };
    self.sequencer.set_length(length);
}
}

An empty song would have length 0, and a loop of zero steps makes no sense, so it becomes one silent bar.

The song arrives as Command::SetSong { plays, length }: the pieces of patterns to play, with every repeat already unrolled, and the length. The audio thread could work the length out, but Project already does, and two copies of one calculation can drift apart. What a Play is, and how the project builds them, is in Sections, repeats and loops.

Notes for every pattern: ChannelNotes

Each channel needs one list of notes per pattern. A Vec of Vecs does that, but there is a catch. When a pattern is added, the audio thread must add an empty list to every channel. Vec::new() itself is free: an empty Vec has no memory of its own yet. But adding it to the outer Vec allocates if the outer Vec is full. To be safe, the outer Vec must have room for every pattern there could ever be, reserved before it reaches the audio thread.

That is a rule about how the value was made, and Rust can enforce such rules with a newtype, a struct with one private field:

#![allow(unused)]
fn main() {
pub struct ChannelNotes(Vec<Vec<NoteEvent>>);

impl ChannelNotes {
    /// One list per pattern, in pattern order.
    pub fn new(lists: impl IntoIterator<Item = Vec<NoteEvent>>) -> Self {
        let mut patterns = Vec::with_capacity(MAX_PATTERNS);
        patterns.extend(lists.into_iter().take(MAX_PATTERNS));
        ChannelNotes(patterns)
    }

    /// Adds an empty list for a new pattern at position `pattern`, without
    /// allocating. The lists from there on move up one place.
    fn insert_empty(&mut self, pattern: usize) {
        if self.0.len() < self.0.capacity() {
            self.0.insert(pattern.min(self.0.len()), Vec::new());
        }
    }
}
}

Because the field is private, code outside engine.rs cannot write ChannelNotes(some_vec). The only way to make one is ChannelNotes::new, which always reserves room for MAX_PATTERNS lists. So every ChannelNotes the audio thread receives has the room, and insert_empty can never allocate. The check len < capacity makes extra sure: if it were ever full, it would rather skip the insert than allocate. .0 is how you reach the field of a tuple struct (one whose fields have no names). The test channel_notes_have_room_for_every_pattern pins the promise down.

On the window’s side, sending a channel builds one with an iterator, one list per pattern:

#![allow(unused)]
fn main() {
// The notes as they are played, with the song's swing.
let notes = ChannelNotes::new(
    (0..self.project.patterns().len())
        .map(|pattern| self.project.played_notes(pattern, index).into_owned()),
);
}

new takes impl IntoIterator<Item = Vec<NoteEvent>>, so it accepts this iterator, an array like [steps(&[0]), steps(&[2])] in the tests, or a Vec of lists. The notes are played_notes, not the written ones: with swing, the second eighth of each beat comes late (Tempo, meter, swing and feel).

Patterns come and go

RemovePattern takes the pattern’s list out of every channel. The lists after it move down one place, exactly as Project::remove_pattern renumbers the clips, so both sides keep agreeing about what “pattern 2” means. Each removed list goes to the trash queue, to be freed on the window’s thread:

#![allow(unused)]
fn main() {
fn remove_pattern(&mut self, pattern: usize) {
    if pattern < self.pattern_lengths.len() {
        self.pattern_lengths.remove(pattern);
        for index in 0..self.channels.len() {
            if let Some(notes) = self.channels[index].notes.remove(pattern) {
                self.throw_away(Garbage::Notes(notes));
            }
        }
        self.update_loop_length();
        ...
    }
}
}

The loop counts with an index instead of for channel in &mut self.channels, because the body calls self.throw_away, which needs &mut self. A for loop over &mut self.channels would hold a mutable borrow of part of self for the whole loop, and self.throw_away would need another. With an index, each self.channels[index] borrow ends on the same line.

Clear empties everything before a new project is sent, when a file is opened:

#![allow(unused)]
fn main() {
while let Some(mut channel) = self.channels.pop() {
    silence(&mut channel.instrument, &mut self.midi_out, &mut self.midi_backlog);
    self.throw_away(Garbage::Channel(channel));
}
// `clear` empties the list but keeps its memory: nothing is freed.
self.pattern_lengths.clear();
let old = std::mem::take(&mut self.plays);
self.throw_away(Garbage::Song(old));
}

• pop takes the last item out of a Vec, or returns None when it is empty, so while let Some(..) runs until nothing is left.
• silence tells an external synth to let go of the notes a MIDI Out channel is holding, since a synth only stops a note when it is told to.
• clear on a Vec<usize> sets its length to zero but keeps its memory, so nothing is freed here, and later pushes do not allocate.
• std::mem::take takes the value out and leaves the type’s default in its place, here an empty Vec (which owns no memory).

Opening a project throws away up to MAX_CHANNELS (32) channels, each with its instrument and notes, and the song, its tempos and its metronome clicks, which is why the trash queue has 1024 places.

Starting the notes of a step

When a step fires, the audio thread starts the notes that begin on it. In pattern mode that is one pattern. In song mode, a step of the song can be inside several clips at once, one per track, and each clip has its own idea of “which step”:

#![allow(unused)]
fn main() {
PlayMode::Song => {
    // `self.plays` is read while `self.channels` is changed: two
    // different fields, so the borrows do not overlap.
    for play in &self.plays {
        let length = self.pattern_lengths.get(play.pattern).copied().unwrap_or(0);
        if let Some(local_step) = play.pattern_step(step, length) {
            // Notes stop at the end of the pattern, or of the
            // piece, whichever comes first.
            let room = (length - local_step).min(play.end() - step);
            start_pattern_notes(
                &mut self.channels,
                Origin {
                    pattern: play.pattern,
                    pattern_step: local_step,
                    song_step: step,
                    over_song: false,
                },
                room,
                timing,
                &mut self.pending,
                self.trace.as_deref_mut(),
            );
        }
    }
    ...
}
}

A clip that starts on song step 32 plays its pattern’s step 2 on song step 34. If two clips overlap (a Chords clip and a Beat clip, on two tracks), both start their notes. A clip that repeats its pattern is one long Play, and pattern_step takes the song step modulo the pattern length, so the pattern comes round again and again inside it.

Borrowing only what you need

start_pattern_notes is a plain function, not a method:

#![allow(unused)]
fn main() {
fn start_pattern_notes(
    channels: &mut [ChannelState],
    origin: Origin,
    room: usize,
    timing: Timing,
    pending: &mut Vec<Pending>,
    mut trace: Option<&mut Tracer>,
) { ... }
}

If it were a method taking &mut self, calling it inside for play in &self.plays would not compile: the loop borrows self.plays to read, and the call would borrow all of self to change. As a function taking &mut self.channels, it borrows only that field, which does not overlap with self.plays. Shaping a function’s arguments so it borrows only what it needs is a common way to work with the borrow checker rather than against it.

Origin says where the notes come from: the pattern, the step of the pattern, the step of the song, and whether they come from a pattern played over the song (below). Every voice keeps the origin of the note it plays, which is how the audio thread later knows whether the song still plays it.

Timing bundles the numbers that always travel together:

#![allow(unused)]
fn main() {
/// How long a step is, the sample rate the instruments run at, how
/// loose the timing is, and the frame the step starts on.
#[derive(Debug, Clone, Copy)]
struct Timing {
    step_frames: f64,
    sample_rate: u32,
    loose_frames: f64,
    now: u64,
}
}

Without it, the function would take nine arguments, several of them plain numbers, and a call with four numbers in a row is easy to get in the wrong order. (Clippy’s too_many_arguments lint complains from eight, and readability suffers before that.)

How long a note is held

A note’s length is in steps; the instrument wants frames. The audio thread works it out when the note starts, and calls it the gate:

#![allow(unused)]
fn main() {
let tick = timing.step_frames / TICKS_PER_STEP as f64;
let held = if note.length <= room {
    note.length as f64 * timing.step_frames - f64::from(note.nudge + note.trim) * tick
} else {
    room as f64 * timing.step_frames - f64::from(note.nudge) * tick
};
let gate = held as u32;
}

A note that runs past the end of its pattern, or of the piece of the song that plays it, is cut there (room), so a pattern’s last chord does not hang over the next clip. nudge and trim are fractions of a step, in ticks: a note from a MIDI performance can start a little after its step and end a little before its last one. With loose timing, each note also starts a little late on purpose. A note that starts late waits in pending, a list reserved in advance, until its frame comes. Both are in Tempo, meter, swing and feel.

When the song changes under a playing note

The song can change while it plays: a clip is moved or deleted, a track is muted, the band writes new patterns. A note that already started would ring on to the end of its gate, even though the song no longer plays it. So when a new song arrives while playing, the audio thread lets go of the notes it no longer plays:

#![allow(unused)]
fn main() {
fn release_notes_left_out(&mut self) {
    // The fields are borrowed one by one, so the closure can read the
    // song while the channels are changed.
    let plays = &self.plays;
    let lengths = &self.pattern_lengths;
    let still_played = |origin: Origin| {
        if origin.over_song {
            return true;
        }
        let length = lengths.get(origin.pattern).copied().unwrap_or(0);
        plays.iter().any(|play| {
            play.pattern == origin.pattern
                && play.pattern_step(origin.song_step, length) == Some(origin.pattern_step)
        })
    };
    for channel in &mut self.channels {
        channel.instrument.release_unless(still_played);
    }
    ...
}
}

A note is still played if some piece of the new song plays the same step of the same pattern on the same song step. release_unless takes the test as a closure (impl Fn(Origin) -> bool), so each kind of instrument can let go in its own way: a synth voice goes to its release, a sampler fades its sound out quickly, a MIDI Out sends a note-off. Keys held on a keyboard and previews have no origin, so they are never cut. notes_stop_when_the_song_no_longer_plays_them checks it.

The closure borrows self.plays and self.pattern_lengths, and the loop borrows self.channels to change it. That is allowed because they are different fields: since the 2021 edition, a closure that uses self.plays captures only that field, not all of self, so writing self.plays inside the closure would work as well. The two local references only make plain which parts of self it reads.

Seeking, and switching mode

Command::Seek(step) moves the start position. While stopped, that is where the next Play starts. While playing, playback jumps there at once:

#![allow(unused)]
fn main() {
fn seek(&mut self, step: usize) {
    self.start = step;
    self.pending.clear();
    ...
    if self.playing {
        // Notes that were playing would otherwise hang on
        // until the end they will now never reach.
        for channel in &mut self.channels {
            channel.instrument.release_all();
        }
        ...
        self.sequencer.start_at(step);
    }
}
}

Notes waiting in pending belong to the old position, so they are dropped. Switching between pattern and song mode starts the new loop from its top, and releases held notes for the same reason. Stopping releases every note, keys held down included: each one goes into its release, so the sound rings out a moment and does not hang on.

A pattern over the song

The channel rack’s ▶ Play over the song plays the selected pattern over the song as it plays, to try it out with the rest of the band (Command::SetOverlay). It starts on the song’s next bar line, so it comes in in time, and loops for as long as it plays:

#![allow(unused)]
fn main() {
fn overlay_step(&mut self, step: usize) -> Option<(usize, usize)> {
    let bar_line = click_at(&self.song_clicks, step) == Click::Bar;
    let overlay = self.overlay.as_mut()?;
    // After a jump it waits for a bar line, to start again from its
    // top in time with the bars.
    if overlay.last.is_some_and(|last| step != last + 1)
        && let Some((pattern, _)) = overlay.playing.take()
    {
        overlay.coming.get_or_insert(pattern);
    }
    overlay.last = Some(step);
    if bar_line && let Some(pattern) = overlay.coming.take() {
        overlay.playing = Some((pattern, 0));
    }
    let (pattern, at) = overlay.playing?;
    let length = self.pattern_lengths.get(pattern).copied().unwrap_or(0);
    if length == 0 {
        return None;
    }
    let at = at % length;
    overlay.playing = Some((pattern, at + 1));
    Some((pattern, at))
}
}

The bar lines come from the song’s metronome clicks, which already say where each bar starts in every meter. A pattern chosen while another plays over the song waits as coming until the next bar line. A jump (a seek, or the song coming back round) is noticed because the step is not the one after the last, and the pattern starts again from its top on the next bar line.

The window draws a second playhead in the rack for the pattern played over the song. Two numbers, the pattern and its step, must be read together, or the window could see a new pattern with an old step. So they share one AtomicU64, the pattern in the high 32 bits and the step in the low 32:

#![allow(unused)]
fn main() {
fn store_overlay(overlay: &AtomicU64, playing: Option<(usize, usize)>) {
    let bits = playing.map_or(NO_POSITION, |(pattern, step)| {
        ((pattern as u64) << 32) | step as u64
    });
    overlay.store(bits, Ordering::Relaxed);
}
}

<< shifts the pattern’s bits up 32 places, and | (bitwise or) puts the step in the empty low half. Reading undoes it with >> 32 and a mask, bits & u64::from(u32::MAX). One load, one store: an atomic integer cannot be read half old and half new. A special value, NO_POSITION, means “nothing plays over the song”.

Testing it

The tests run the audio thread without a sound card (see Testing without a sound card). A small helper finds where sounds start in a block of samples:

#![allow(unused)]
fn main() {
fn onsets(out: &[f32]) -> Vec<usize> {
    (0..out.len())
        .filter(|&i| out[i] != 0.0 && (i == 0 || out[i - 1] == 0.0))
        .collect()
}
}

The test click is a short burst after silence, so every hit is an onset. Then a song can be checked in one line:

#![allow(unused)]
fn main() {
#[test]
fn song_mode_plays_the_clips() {
    let mut h = two_patterns();
    // Pattern 1 at bar 1, pattern 0 at bar 2: a two-bar song.
    let plays = vec![whole(1, 0), whole(0, 16)];
    send(&mut h, Command::SetSong { plays, length: 32 });
    send(&mut h, Command::SetMode(PlayMode::Song));
    send(&mut h, Command::Play);
    let out = render(&mut h, 40 * STEP);
    // Step 2 of the first clip, step 0 of the second, then the song
    // loops back to the start: step 2 of the first clip again.
    assert_eq!(onsets(&out), vec![2 * STEP, 16 * STEP, 34 * STEP]);
    assert_eq!(
        h.playhead.load(Ordering::Relaxed),
        7,
        "step 39 is step 7 of the second time round"
    );
}
}

The last assertion carries a message saying why 7 is right: after 40 steps of a 32-step song, the sequencer is on its second time round. A reader who expects 39 sees the reason as soon as the test fails.

Other tests cover the rest of this chapter: clips that overlap, pieces that repeat their pattern, patterns inserted and removed under the others, Clear sending everything to the trash, Play starting where a seek put it, and seven tests on a pattern played over the song.

Tempo, meter, swing and feel

Files: crates/lineup-core/src/meter.rs, crates/lineup-core/src/tempo.rs, crates/lineup-core/src/remeter.rs, crates/lineup-core/src/swing.rs, crates/lineup-audio/src/engine.rs, crates/lineup-app/src/playlist/tempo.rs, crates/lineup-app/src/time_picker.rs and crates/lineup-app/src/app/swing.rs

In Ferrous Lineup a step is always a sixteenth note. A waltz, a ritardando, a shuffle and a Bulgarian 7/8 are all written on that same grid. What changes is how the steps are counted and played:

The music behind all of this (beats and bars, two and three, odd meters, what a ritardando and a swing are) is explained in the user manual: Rhythm and meter, Tempo, time signatures and key changes, Swing and feel and Odd meters and the Balkans. This chapter is about the code.

TimeSignature: two numbers and a grouping

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(from = "SavedTime", into = "SavedTime")]
pub struct TimeSignature {
    /// How many notes of `unit` length make a bar: the top number.
    pub beats: u8,
    /// Which note counts as a beat: 4 for quarter notes, 8 for eighths.
    /// The bottom number.
    pub unit: u8,
    /// Where the felt beats start, when they are not the usual ones: bit
    /// `i` is set when a beat starts on the bar's `i`-th `unit` note.
    /// 0 means the usual beats (see [`TimeSignature::usual_groups`]).
    ///
    /// A `u64` keeps `TimeSignature` `Copy`, so it can be passed around
    /// as freely as a number; a `Vec` could not be.
    groups: u64,
}
}

The top number can be anything from 1 up to what fits in a pattern; the bottom one is 1, 2, 4, 8 or 16 (UNITS). There is no 32: a bar of 7/32 would end in the middle of a sixteenth-note step.

Everything else is worked out from those numbers, and the arithmetic is written so that a damaged file can’t make it divide by zero:

#![allow(unused)]
fn main() {
pub fn unit_steps(self) -> usize {
    (16 / usize::from(self.unit.clamp(1, 16))).max(1)
}

pub fn steps_per_bar(self) -> usize {
    let unit = usize::from(self.unit.clamp(1, 16));
    (usize::from(self.beats) * 16 / unit).max(1)
}
}

clamp keeps the unit between 1 and 16, so the division always has something to divide by, and max(1) keeps a bar at least one step long, because “which bar is step 50 in?” divides by the bar’s length. The menus and set_time_marker only accept time signatures that pass is_valid, but a hand-edited file can still say beats: 0 or unit: 0, and the test nonsense_does_not_divide_by_zero checks that the arithmetic survives it.

new is a const fn, so time signatures can be constants:

#![allow(unused)]
fn main() {
pub const COMMON: TimeSignature = TimeSignature::new(4, 4);

pub const ALL: [TimeSignature; 10] = [
    TimeSignature::new(2, 4),
    TimeSignature::new(3, 4),
    // ...
];
}

A grouping inside a Copy type

In 7/8 the seven eighths are felt as beats of two and three, and the order matters: 2+2+3/8 is a Bulgarian rachenitsa, 3+2+2/8 a Greek kalamatianos. The grouping is part of the time signature.

TimeSignature is passed by value everywhere, which needs it to be Copy: copied like an integer, with no heap memory. A grouping would naturally be a Vec<u8>, [2, 2, 3], but a type that holds a Vec can’t be Copy. So the grouping is a bit mask instead: bit i is set when a beat starts on the bar’s i-th note. 2+2+3/8 starts its beats on notes 0, 2 and 4, so its mask is 0b10101. A u64 has room for 64 notes (MAX_GROUPED_BEATS), more than any real bar.

Songs and rhythms are const tables, so a grouping has to be buildable at compile time too:

#![allow(unused)]
fn main() {
pub const fn of_groups(groups: &[u8], unit: u8) -> Self {
    let mut mask = 0_u64;
    let mut at = 0;
    let mut index = 0;
    // `for` loops are not allowed in a `const fn` yet: `while` is.
    while index < groups.len() {
        assert!(groups[index] > 0, "a group of no notes");
        assert!(at < Self::MAX_GROUPED_BEATS as usize, "too many notes");
        mask |= 1 << at;
        at += groups[index] as usize;
        index += 1;
    }
    assert!(at > 0 && at <= Self::MAX_GROUPED_BEATS as usize);
    let mut time = TimeSignature::new(at as u8, unit);
    // The usual grouping is written the plain way, so 3+3/8 and 6/8
    // are the same time signature.
    if mask != time.usual_mask() {
        time.groups = mask;
    }
    time
}
}

1 << at is a 1 moved at places to the left, and |= switches that bit on without touching the others. An assert! that fails inside a const fn evaluated for a constant stops the build, not the program, so a mistyped grouping in a song table never reaches anyone. For groupings typed by a person there is grouped, which checks the same things and returns an Option instead.

The last few lines keep one rule: the usual grouping is stored as 0. So "3+3/8" and "6/8" give the same value, and == says they are equal. Without it the Time menu would show 6/8 as not selected after someone typed 3+3.

The groups field is private, so code outside meter.rs can only make a grouping through grouped or of_groups. beats and unit are public, though, so someone could change beats and leave a mask that no longer fits. The private mask() covers that: a mask that does not fit the top number is ignored, and the usual beats are used.

Beats of different lengths

In 2+2+3/8 the beats are 4, 4 and 6 steps long, so “which beat is this step in?” can’t be a division. Everything asks beat_at instead:

#![allow(unused)]
fn main() {
pub struct Beat {
    /// Counted from 0: the first beat of the bar is 0.
    pub index: usize,
    /// The step it starts on, counted from the start of the bar.
    pub start: usize,
    /// How many steps it lasts.
    pub length: usize,
}
}

From the test irregular_meters_group_their_beats, where typed is short for text.parse().unwrap():

#![allow(unused)]
fn main() {
let balkan = typed("2+2+3/8");
assert_eq!(balkan.beat_starts(), [0, 4, 8]);
assert_eq!(balkan.beat_at(9).length, 6);
assert_eq!(balkan.beat_at(9).index, 2);
}

beat_at finds the last beat start at or before the step with rposition, which searches a slice from the end.

There is no “steps per beat” function at all, on purpose. Any code that assumed equal beats would be wrong in an irregular meter, and with no such function to call, nobody can make that mistake. (Removing a function is also the quickest way to find every caller: the compiler lists them.)

A bar can be asked about its beats in three ways, because three parts of the program mean different things by “beat”:

felt_groups is what the band uses for its “oom-pa”: a grouping if there is one, the three-eighth beats of 6/8, and otherwise beats of two with a three at the end. Bars of three notes or fewer, like 3/4, are one felt beat. How the band plays them is in The band.

Reading and writing “2+2+3/8”

TimeSignature implements Display, so format!("{time}") writes “3/4”, or “2+2+3/8” with the grouping as the top number, everywhere in the same way. The other direction is the standard FromStr trait, which is what makes "7/8".parse::<TimeSignature>() work:

#![allow(unused)]
fn main() {
impl FromStr for TimeSignature {
    type Err = String;

    fn from_str(text: &str) -> Result<Self, Self::Err> {
        let (top, bottom) = text
            .split_once('/')
            .ok_or(tr("write it as two numbers, like 7/8"))?;
        // ... then the bottom number, the top number or numbers, and the bar's size
    }
}
}

split_once('/') gives Some((before, after)) or None; ok_or turns the None into an error, and ? returns it at once. The error is a String the Time menu shows as it is, in red, so the messages go through tr and come out in the app’s language (Two languages).

The Time menu’s “Any other” row keeps what is being typed in a small Draft (the top number, the bottom number, and the grouping as text) in egui’s memory between frames, and builds the time signature with the same parse. If the groups don’t add up to the top number, it says so: “the groups add up to 8, not 11”.

Saving it without changing old files

A time signature without a grouping must be saved exactly as before, (beats: 7, unit: 8), so older versions keep opening the file. The attribute #[serde(from = "SavedTime", into = "SavedTime")] on TimeSignature says: to save one, turn it into a SavedTime first; to load one, read a SavedTime and turn it back:

#![allow(unused)]
fn main() {
#[derive(Serialize, Deserialize)]
struct SavedTime {
    beats: u8,
    unit: u8,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    groups: Vec<u8>,
}
}

SavedTime can hold a friendly Vec (groups: [2, 2, 3]) because it only lives for a moment while saving or loading. The From<SavedTime> conversion leaves out a grouping that does not add up to the top number, so a hand-edited file can’t make a bar whose beats don’t fit.

Meter: time signatures that change

A song can change time signature partway through: a hymn’s last line in 3/4, Mussorgsky’s Promenade alternating 5/4 and 6/4. Each change is a marker on the playlist:

#![allow(unused)]
fn main() {
pub struct TimeMarker {
    /// The step it starts on, counted from the start of the song.
    pub start: usize,
    pub time: TimeSignature,
}
}

A marker always starts a new bar. One placed in the middle of a bar cuts that bar short, which is how a score writes a bar with a beat missing.

With markers, “which bar is step 50 in?” depends on everything before step 50, so every question about bars goes to one type:

#![allow(unused)]
fn main() {
pub struct Meter {
    first: TimeSignature,
    /// Sorted by start, all after step 0, no two on the same step.
    markers: Vec<TimeMarker>,
}
}

The comment on markers is an invariant, a rule that is always true. The fields are private and Meter::new makes it true (it drops markers on step 0, sorts the rest and removes duplicates with dedup_by_key), so no method has to check it again.

bar_at walks the song in stretches, one per time signature, counting the bars it passes:

4/4 from 0, 3/4 from 32:
stretch 1: steps 0..32,  16 a bar -> bars 0 and 1
stretch 2: steps 32..,   12 a bar -> bars 2, 3, 4, ...

#![allow(unused)]
fn main() {
fn stretches(&self) -> impl Iterator<Item = (usize, usize, TimeSignature)> + '_ {
    let starts =
        std::iter::once(TimeMarker::new(0, self.first)).chain(self.markers.iter().copied());
    let ends = self
        .markers
        .iter()
        .map(|marker| marker.start)
        .chain(std::iter::once(usize::MAX));
    starts
        .zip(ends)
        .map(|(from, end)| (from.start, end, from.time))
}

pub fn bar_at(&self, step: usize) -> Bar {
    let mut bars_before = 0;
    for (start, end, time) in self.stretches() {
        let bar = time.steps_per_bar();
        if step < end {
            let index = (step - start) / bar;
            let bar_start = start + index * bar;
            return Bar {
                number: bars_before + index,
                start: bar_start,
                length: bar.min(end - bar_start),
                time,
            };
        }
        bars_before += (end - start).div_ceil(bar);
    }
    unreachable!("the last stretch never ends")
}
}

stretches builds an iterator out of others: the starts (the first time signature, then each marker) are zipped with the ends (each marker, then usize::MAX for “never”). div_ceil divides rounding up, so a short bar before a marker still counts as a bar, and bar.min(end - bar_start) gives that short bar its real length. unreachable! tells the reader, and the compiler, that the loop always returns: the last stretch ends at usize::MAX.

bars() gives every bar without end:

#![allow(unused)]
fn main() {
pub fn bars(&self) -> impl Iterator<Item = Bar> + '_ {
    let mut next = 0;
    std::iter::from_fn(move || {
        let bar = self.bar_at(next);
        next = bar.end();
        Some(bar)
    })
}
}

std::iter::from_fn turns a closure into an iterator: each call to next runs the closure. It never returns None, so the iterator never stops on its own; the playlist draws its grid with meter.bars().take_while(|bar| bar.start <= steps) and decides itself how much of it to use.

The rest of Meter is the questions the app asks: time_at, bar(number), is_bar_start, floor_to_bar, floor_to_beat, beat_end, round_up_to_bar, and position(step) for the BAR:BEAT:STEP display. Meter::steady(time) is a song with no markers, and a test checks, step by step, that it answers exactly like the TimeSignature alone. tidy() drops the markers that change nothing: one that keeps the time signature before it and falls on one of its bar lines.

Who asks the meter

• The playlist: its grid, bar numbers, sections and snapping. Snap::floor and Snap::next give the start and the end of the bar or beat under the pointer, which is what dragging a clip, a section or the loop needs.
• The channel rack and the piano roll show one pattern, not the song. They ask Project::pattern_time(pattern): the time signature where the pattern’s first clip starts, or, for a pattern not in the song, its own Pattern::time (a waltz tried from the Library is in 3/4 even in a 4/4 song), or else the project’s.
• The length of the song, rounded up to the next bar line.
• The pattern length menu, which offers whole bars (pattern_lengths: 1, 2, 3, 4, 6, 8, 12 or 16 of them, as long as they fit) and writes “4 bars” instead of “64 steps” (describe_length).

The song as it plays

Sections can repeat (Sections, repeats and loops), so the song as heard is longer than the playlist as drawn. If a 3/4 section plays twice, the song as heard has two 3/4 stretches. The arrangement’s passes say which part of the timeline plays when, and Project::played_meter builds a second Meter, in song steps:

#![allow(unused)]
fn main() {
pub fn played_meter(&self, arrangement: &Arrangement) -> Meter {
    let meter = self.meter();
    let first = arrangement
        .passes
        .first()
        .map_or(self.time_signature, |pass| meter.time_at(pass.from));
    let mut markers = Vec::new();
    for pass in &arrangement.passes {
        markers.push(TimeMarker::new(pass.start, meter.time_at(pass.from)));
        for marker in meter.markers() {
            if marker.start > pass.from && marker.start < pass.from + pass.length {
                markers.push(TimeMarker::new(
                    pass.start + marker.start - pass.from,
                    marker.time,
                ));
            }
        }
    }
    Meter::new(first, markers).tidy()
}
}

Every pass gets a marker for the time signature it starts in, plus the markers inside it, and tidy then removes the ones that change nothing, such as a 4/4 pass after another 4/4 pass on a bar line. The transport uses this meter for the position display and for Page Up/Page Down, so “the next bar” is the next bar you hear.

The metronome uses it too. played_clicks turns it into one Click per song step (Bar, Beat or None), and the app sends that list to the audio thread with Command::SetSongClicks, so the metronome clicks the beats of each bar: the two dotted quarters of 6/8, the three groups of 2+2+3/8, a higher click on every “one”. In pattern mode it is pattern_clicks, in the pattern’s own time. The count-in and the metronome’s sound are in Practice tools.

Tempo changes

Tempo, always valid

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd, Serialize, Deserialize)]
#[serde(from = "f32", into = "f32")]
pub struct Tempo {
    bpm: f32,
}
}

The field is private, so the only way to make a Tempo is Tempo::new, which clamps the value between MIN (10) and MAX (522) BPM and turns a NaN into the default tempo, 130. Every Tempo in the program is therefore valid. Files go through the same door: a tempo is saved as a plain number, and From<f32> reads it back with Tempo::new, so a file that says tempo: 9000.0 opens at 522 (Saving).

Markers, and a map

A tempo change is a marker on the playlist, like a time signature change:

#![allow(unused)]
fn main() {
pub struct TempoMarker {
    /// The step it starts on, counted from the start of the song.
    pub start: usize,
    pub tempo: Tempo,
    /// How many steps the change takes; 0 for at once. Project files
    /// leave it out when it is 0.
    #[serde(default, skip_serializing_if = "is_zero")]
    pub glide: usize,
}
}

With glide at 0 the tempo changes at once, as after a pause. With a glide it moves a little on every step until it arrives: down for a ritardando, up for an accelerando. A step is a sixteenth note, so a glide over two bars of 4/4 is 32 small changes, close enough to a curve that nobody hears the stairs. The tempo never changes in the middle of a step.

#![allow(unused)]
fn main() {
fn bpm_on(&self, step: usize, from: f32) -> f32 {
    let into = step - self.start + 1;
    if into >= self.glide {
        return self.tempo.bpm();
    }
    let done = into as f32 / self.glide as f32;
    from + (self.tempo.bpm() - from) * done
}
}

A glide of 4 steps from 100 to 60 BPM plays 90, 80, 70 and 60: the last step of the glide is already at the new tempo.

TempoMap is to tempo what Meter is to bars: the first tempo and the markers, with the same invariant, and one main question:

#![allow(unused)]
fn main() {
pub fn tempo_at(&self, step: usize) -> Tempo {
    // The marker in effect so far, and the tempo its glide started from.
    let mut current: Option<(&TempoMarker, f32)> = None;
    let bpm_on = |current: Option<(&TempoMarker, f32)>, step: usize| match current {
        Some((marker, from)) => marker.bpm_on(step, from),
        None => self.first.bpm(),
    };
    for marker in self.markers.iter().take_while(|m| m.start <= step) {
        let from = bpm_on(current, marker.start - 1);
        current = Some((marker, from));
    }
    Tempo::new(bpm_on(current, step))
}
}

A glide starts from whatever tempo was playing on the step before its marker, even halfway through another glide, so the loop carries from along: each marker asks the one before it “where were you, one step before me?”. marker.start - 1 can’t underflow, because no marker is on step 0.

The tempo strip

The strip above the playlist’s bar numbers draws the map as a line. It only needs the steps where the line bends (the start, each marker and the end of each glide), joined pairwise with windows(2):

#![allow(unused)]
fn main() {
let mut bends = vec![0, steps];
for marker in map.markers() {
    bends.push(marker.start);
    bends.push(marker.start + marker.glide);
}
bends.retain(|&step| step <= steps);
bends.sort_unstable();
bends.dedup();
let mut points = Vec::new();
for pair in bends.windows(2) {
    let (from, to) = (pair[0], pair[1]);
    points.push(pos2(layout.x(from), y(map.tempo_at(from))));
    points.push(pos2(layout.x(to), y(map.tempo_at(to.saturating_sub(1)))));
}
}

Each segment goes from the tempo on its first step to the tempo on its last, so a sudden change becomes a vertical jump and a glide a slope. The labels are written the way a score writes them: describe compares the marker’s tempo with tempo_before its step, and writes “♩ = 90” for a sudden change, “rit. → 60” for a glide down and “accel. → 140” for a glide up.

The toolbar’s TEMPO box sets the tempo the song starts at, and scale_tempo moves every marker by the same proportion:

#![allow(unused)]
fn main() {
pub fn scale_tempo(&mut self, tempo: Tempo) {
    let ratio = tempo.bpm() / self.tempo.bpm();
    self.tempo = tempo;
    for marker in &mut self.playlist.tempo_markers {
        marker.tempo = Tempo::new(marker.tempo.bpm() * ratio);
    }
}
}

Practising a piece more slowly keeps its ritardando, only slower too. While a song whose tempo changes is playing, the box shows TEMPO NOW instead: tempo_at the playhead’s place on the timeline.

A style from the Library brings a tempo of its own, and that one should land where the song really plays, not on its first note: a MIDI file often starts with a few slow notes before its real tempo. So main_tempo finds the tempo the song keeps for the most steps, and take_tempo scales the whole song so that that one becomes the style’s:

#![allow(unused)]
fn main() {
pub fn take_tempo(&mut self, tempo: Tempo) {
    let ratio = tempo.bpm() / self.main_tempo().bpm();
    self.scale_tempo(Tempo::new(self.tempo.bpm() * ratio));
}
}

main_tempo adds up, for each tempo, the steps it holds: from the start to the first marker at the starting tempo, then from each marker to the next. A tempo that comes back later adds to what it held before. Of those held longest, the first wins, so a song with one steady tempo gets that one, and a tie goes to the earlier tempo:

#![allow(unused)]
fn main() {
let (mut tempo, mut from) = (self.tempo, 0);
for marker in &self.playlist.tempo_markers {
    let start = marker.start.clamp(from, end.max(from));
    hold(tempo, start - from);
    (tempo, from) = (marker.tempo, start);
}
hold(tempo, end.saturating_sub(from));
}

hold is a closure that borrows the list held mutably, so it is declared let mut hold: calling a closure that changes what it captured changes the closure’s own state. (tempo, from) = (…, …) sets two variables at once, a destructuring assignment.

Every step at its own tempo

Project::played_tempos gives the tempo of every step of the song as it plays, so a section that slows down at its end slows down every time round:

#![allow(unused)]
fn main() {
pub fn played_tempos(&self, arrangement: &Arrangement) -> Vec<Tempo> {
    let map = self.tempo_map();
    if map.is_steady() {
        return Vec::new();
    }
    (0..arrangement.length)
        .map(|step| {
            let timeline = arrangement.timeline_step(step).unwrap_or(step);
            map.tempo_at(timeline)
        })
        .collect()
}
}

The list is built on the UI thread and sent with Command::SetSongTempos, next to the song. The audio thread may not allocate, and when a new list arrives the old one goes back to the UI thread to be freed, like old songs and old notes (Two threads). An empty list, the usual case, means “play the TEMPO box’s tempo”, and costs nothing.

A step must last as long as its own tempo says, so the tempo has to be set before the step starts. The sequencer’s due says which step starts on the next tick (The sequencer), and the audio thread asks it first, on every frame:

#![allow(unused)]
fn main() {
if let Some(step) = self.sequencer.due() {
    // ...
    let tempo = self.tempo_of_step(step);
    if tempo != self.tempo_now {
        self.set_tempo(tempo);
    }
}
if let Some(step) = self.sequencer.tick() {
}

tempo_of_step is the song’s tempo for that step in song mode, and the TEMPO box’s in pattern mode, where you work on one pattern and want a steady loop. (The part left out above, lap_tempos, is the speed trainer’s next tempo, which takes over when the loop comes round: Practice tools.)

Notes already sounding have a length in frames, worked out at the old tempo. set_tempo stretches them so they still end on the step they should:

#![allow(unused)]
fn main() {
fn set_tempo(&mut self, tempo: Tempo) {
    self.tempo_now = tempo;
    let before = self.sequencer.step_frames();
    let next_step = self.sequencer.frames_to_next_step();
    self.sequencer.set_tempo(tempo);
    let stretch = self.sequencer.step_frames() / before;
    for channel in &mut self.channels {
        channel.instrument.tempo_changed(next_step, stretch);
        channel.effects.set_tempo(tempo);
    }
    // ...
}
}

and each instrument works out what is left of every held note:

#![allow(unused)]
fn main() {
pub(crate) fn stretched(left: f64, next_step: f64, stretch: f64) -> f64 {
    if left <= next_step {
        left
    } else {
        (next_step + (left - next_step) * stretch).round()
    }
}
}

The frames up to the next step belong to the step already playing, which keeps its length; only the rest is stretched. A note with 10 000 frames left, 2 000 of them in this step, at half the tempo (a stretch of 2) has 2 000 + 8 000 × 2 = 18 000 left. Effects that follow the beat, such as a delay set in note values, get the new tempo too (The mixer).

An export plays the song through the same audio thread, so it gets the same list. Its length is no longer “steps times the length of a step”: played_seconds adds up every step at its own tempo, with tempo::seconds:

#![allow(unused)]
fn main() {
pub fn seconds(steps: usize, tempo: impl Fn(usize) -> Tempo) -> f64 {
    (0..steps)
        .map(|step| f64::from(tempo(step).seconds_per_beat()) / 4.0)
        .sum()
}
}

impl Fn(usize) -> Tempo takes any closure from a step to a tempo, so the same function serves a TempoMap in a test and the played list in played_seconds.

Putting a song in another time signature

A time signature only moves bar lines. But pick a waltz in the Library while a 4/4 song plays, and its twelve-step bars laid into sixteen-step ones play “one two three” and then a beat of silence, every bar. To sound like a waltz, every bar of the song has to become a 3/4 bar. remeter does that, with one rule: bar n of the old song becomes bar n of the new one, and every note keeps its place in its bar.

4/4: | C . . . E . . . G . . . E . . . |   16 steps
3/4: | C . . E . . G . . E . . |           12 steps

It is a mechanical stretch, the way a tape machine would do it, not the way a composer would rewrite a tune for a new meter.

Squeezing a bar, to the tick

Squeezing sixteen steps into twelve puts many notes between steps: eighth notes two steps apart become 1.5 steps apart. Rounding them to the grid would make them uneven. So the squeeze is done in ticks, 24 to a step (TICKS_PER_STEP, the unit MIDI import uses for notes off the grid, see MIDI):

#![allow(unused)]
fn main() {
pub struct Remap {
    old: Meter,
    /// Steps in one new bar.
    bar: usize,
}

impl Remap {
    pub fn tick(&self, tick: usize) -> usize {
        let bar = self.old.bar_at(tick / TICKS_PER_STEP);
        let start = bar.start * TICKS_PER_STEP;
        let length = bar.length * TICKS_PER_STEP;
        let new_bar = self.bar * TICKS_PER_STEP;
        // Rounded to the nearest tick.
        bar.number * new_bar + ((tick - start) * new_bar + length / 2) / length
    }
}
}

Two habits of integer arithmetic are in the last line. Multiply before dividing: (tick - start) / length * new_bar would be 0 for every tick inside the bar. Add half before dividing to round to the nearest whole number instead of always down. The second eighth of a 4/4 bar, tick 48 of 384, lands on (48 × 288 + 192) / 384 = 36 of a 288-tick 3/4 bar: 1.5 steps, exactly.

A Remap holds the song’s old Meter, so it works for songs that already change meter: every old bar, whatever its time signature (a short one too), becomes one whole new bar. Remap::step is the same, rounded to the nearest step, for things that live on steps.

Every bar keeps its duration

The tempo counts quarter notes. A 3/4 bar has three, a 4/4 bar four, so at the same tempo the 3/4 song would be over in three quarters of the time. So remeter scales the tempo by the same ratio as the bar: 4/4 at 112 becomes 3/4 at 84, and a bar lasts 2.14 seconds in both. Tempo markers are scaled the same way, and a meter change in the middle of the song that changed the bar length gets a tempo marker of its own, so each stretch keeps its pace.

The scaling has to come back exactly. 108.5 BPM in 7/8, put back into 4/4, must be 108.5 × 16 / 14 = 124, not 124.00001. An f32 has about seven significant digits, and the ratio 16/14 has no exact value in it. So the code multiplies first and divides last, in f64:

#![allow(unused)]
fn main() {
let scaled = |tempo: Tempo, step: usize| {
    Tempo::new((f64::from(tempo.bpm()) * bar as f64 / old_bar(step) as f64) as f32)
};
}

108.5 × 16 = 1736 is exact, and 1736 / 14 = 124 is exact too. A test takes several tempos through 7/8, 3/4, 13/16, 6/8 and 12/8 and back to 4/4, and checks they come back unchanged.

So after remeter every note still starts at the same moment, in seconds, and lasts as long. The music sounds the same; only how it is written and counted changes. What makes a song sound like a waltz is the drums and the way the chords are struck, which is why the Library and the Time box re-meter the song and give it a rhythm in the new meter. That choice of rhythm is in The Library.

Patterns that grow too long

A pattern holds at most 256 steps (MAX_STEPS). Sixteen bars of 4/4 are exactly that, but sixteen bars of 12/8 are 384. Rather than drop notes, remeter cuts such a pattern into pieces of whole bars that fit:

#![allow(unused)]
fn main() {
let chunk = MAX_STEPS / bar * bar;
}

256 / 24 × 24 is 240 steps: ten bars of 12/8, then six. The pieces are named “Theme”, “Theme (2)” and so on, and each clip of the pattern becomes clips of the pieces, one after the other. The song sounds the same; the playlist shows one clip more.

Everything else moves with its bar

Clips, sections, the loop, key markers and the band’s markers all go through song.step. A tempo marker’s glide is mapped by its two ends, so a ritardando over two bars of 4/4 lasts two bars of 3/4. Chords change on a beat, so they go to the nearest beat of the new bar (snap_to_beat). The time markers go: the whole song is in one time signature now.

Two markers one step apart can be squeezed onto the same step. Vec::dedup_by removes neighbours its closure calls equal; the closure gets the later element first and the earlier second, and may change the earlier one, which is how “the later marker wins” is written:

#![allow(unused)]
fn main() {
playlist_mut.tempo_markers.dedup_by(|later, earlier| {
    later.start == earlier.start && {
        *earlier = *later;
        true
    }
});
}

a && { ... } runs the block only when a is true: the copy happens only for markers on the same step.

remeter_song also works out every new pattern from the untouched project first, keeps a clone of the old playlist, and only then writes. Reading the project while writing it would need two borrows of the same Project at once, one shared and one mutable, which the borrow checker rightly refuses. And it runs inside project.moving_the_band(...): the band’s notes are moved along with everything else, and that is not an edit of yours, so the band keeps following the chord sheet (The band).

Keeping your place

While the song plays you are somewhere, bar 13 beat 2, say. After the squeeze, step 196 is no longer in bar 13. So after any change of meter the app finds the bar the playhead was in, and how far into it, and moves to the same bar and the same fraction of it:

#![allow(unused)]
fn main() {
let place = |step: usize| {
    let bar = old.bar_at(step);
    let into = (step - bar.start) as f64 / bar.length.max(1) as f64;
    let target = new.bar(bar.number);
    target.start + (into * target.length as f64).round() as usize
};
}

old and new are the played_meters before and after, so repeats count. The same closure moves where Play starts and where Stop returns to. It works after undo and redo too, which can swap in a song with time markers of its own, where a Remap would not fit.

Swing

Swing plays the two eighth notes of each beat long-short. The project has one amount, from 0 (“straight”) to MAX_SWING, 100 (a triplet’s two thirds and one third):

#![allow(unused)]
fn main() {
pub swing: u8,
}

The notes in the patterns never move. Instead, everything that plays the song asks for the notes as they are played:

#![allow(unused)]
fn main() {
pub fn played_notes(&self, pattern: usize, channel: usize) -> Cow<'_, [NoteEvent]> {
    let Some(written) = self.pattern(pattern).map(|p| p.notes(channel)) else {
        return Cow::Borrowed(&[]);
    };
    match self.pattern_swing(pattern) {
        0 => Cow::Borrowed(written),
        swing => Cow::Owned(swung(written, swing, self.plays_hits(channel))),
    }
}
}

Cow (“clone on write”, from std::borrow) is either borrowed or owned. Most songs don’t swing, and for them played_notes hands back the pattern’s own notes without copying one. Only a swinging pattern gets a new Vec. Both are read the same way, as a slice, and a caller that needs a Vec of its own calls .into_owned(), which copies only if it was borrowed. The '_ says the borrowed case borrows from self: the result can’t outlive the project.

The audio thread, the MIDI export and the accompaniment that follows your playing take played_notes. The piano roll, the step buttons and the chord sheet read the written notes, so the grid you edit stays a grid.

Moving the second eighth

A beat is 96 ticks. The second eighth starts on tick 48; the third note of a triplet on tick 64. So full swing is 16 ticks late:

#![allow(unused)]
fn main() {
const BEAT: usize = 4 * TICKS_PER_STEP;
const OFFBEAT: usize = BEAT / 2;
const FULL_DELAY: usize = BEAT * 2 / 3 - OFFBEAT;
const NEAR: usize = BEAT / 16;

pub fn delay(swing: u8) -> usize {
    let swing = usize::from(swing.min(MAX_SWING));
    (FULL_DELAY * swing + usize::from(MAX_SWING) / 2) / usize::from(MAX_SWING)
}
}

Adding half of 100 before dividing by 100 rounds to the nearest tick again: 50 is 8 ticks, a 7:5 swing; 70 is 11.2 and becomes 11.

swung moves every start and end that falls on or near an offbeat:

#![allow(unused)]
fn main() {
pub fn swung(notes: &[NoteEvent], swing: u8, hits: bool) -> Vec<NoteEvent> {
    let late = delay(swing);
    let played = |tick: usize| match tick % BEAT {
        offset if offset.abs_diff(OFFBEAT) < NEAR => tick + late,
        _ => tick,
    };
    notes
        .iter()
        .map(|note| {
            let start = played(note.start_tick());
            let end = match hits {
                true => note.end_tick(),
                false => played(note.end_tick()),
            };
            NoteEvent {
                velocity: note.velocity,
                ..NoteEvent::exact(note.pitch, start, end.saturating_sub(start))
            }
        })
        .collect()
}
}

The first arm is a match guard: offset is a new variable that matches anything, and the if after it decides whether the arm applies. “Near” is less than six ticks either way, because the strings of a strummed chord start a tick apart, 48, 49, 50, and all of them must move together. abs_diff is the distance between two numbers whichever is bigger; offset - OFFBEAT on a usize below 48 would underflow and panic in a debug build.

A pattern of a constant is different from a binding. Had the arm been OFFBEAT => ..., it would compare with the constant’s value, 48. Had it been a lowercase offbeat => ..., Rust would read it as a new variable matching everything, and the _ arm would never run. The compiler warns about that, and the convention of capitals for constants keeps the two apart.

A note that ends on the offbeat ends later too, so the first eighth really is long, legato into the second. Drum hits are different: a sampled drum sounds to its end however long the note is, so only their starts move (hits). The new note is built with NoteEvent::exact, the same function MIDI import uses for notes off the grid: a swung eighth on step 2 becomes step 2 with a nudge of 16 ticks, which the audio thread already plays late (The sequencer). Notes that are not on an offbeat (sixteenths, a dotted eighth and a sixteenth) stay as they are.

Where swing applies

#![allow(unused)]
fn main() {
pub fn swings_in(time: TimeSignature) -> bool {
    time.unit <= 4
}
}

Only time signatures counted in quarter notes or longer have pairs of eighths in a beat. In 6/8 or 12/8 a beat is already three eighths, and in 5/8 or 7/8 the eighth is the beat. pattern_swing returns 0 for a pattern in such a meter, and the Swing control is greyed out when no part of the song can swing, with a hint that says why. A band section played in another style can bring that style’s swing (section_swing).

No new command for the audio thread

The audio thread learns about every edit from diff, which compares the project before and after, and it compares the played notes (Telling the audio thread what changed). So changing the swing needs no command of its own: the patterns whose played notes moved are sent again, and the others are left alone. A pattern moved into 6/8, which stops swinging, is caught the same way, and so is undo, which swaps a whole earlier project in. When nothing swings, both sides of the comparison are borrowed Cows, and comparing them compares the slices without copying anything.

Remembered per style

Each rhythm in the Library carries its own swing (Rhythm::swing), and a style takes its rhythm’s: Swing, Jazz ballad, Jazz waltz, Shuffle and Five-four swing at 100, Rock and roll at 50, the rest straight. Their drum patterns are written in even eighths, as sheet music writes them, and the swing does the rest. When you change the amount, the app remembers it for that style, between runs, in app/swing.rs:

#![allow(unused)]
fn main() {
#[derive(Debug, Default)]
pub(super) struct SwingMemory {
    amounts: BTreeMap<String, u8>,
    /// Whether an amount changed since they were last stored.
    changed: bool,
}

/// What is stored: a newtype, so it has a type of its own in egui's
/// store.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
struct Remembered(BTreeMap<String, u8>);
}

egui keeps persisted values by an Id and a type. Wrapping the map in a struct of its own, a newtype, gives it a type nobody else uses, so a BTreeMap<String, u8> stored by another part of the app could never be read as this one. A BTreeMap keeps its keys sorted, so the settings file lists the styles in the same order every time. store_swings runs once a frame and writes only when changed is set.

Picking a style first gives the song the style’s own swing, in lineup-core, which knows nothing about settings; then the app puts the remembered amount in its place, in the same undo step.

Loose timing

A good player is never exactly on the grid. Loose, in the playlist’s toolbar, sets how far off it notes may land, from off to 40 ms (MAX_LOOSE_TIMING). It is saved in the project as loose_timing, in milliseconds, and the audio thread turns it into frames once, when Command::SetLooseTiming arrives.

Each note’s delay is worked out when its step starts:

#![allow(unused)]
fn main() {
fn delay(loose_frames: f64, channel: usize, song_step: usize, pitch: Note) -> f64 {
    let onset = ((song_step as u64) << 8) | channel as u64;
    let together = scatter(onset);
    let apart = scatter(onset ^ (u64::from(pitch.midi()) << 40));
    loose_frames * (0.8 * together + 0.2 * apart)
}
}

A pianist is late or early by about the same amount for all the notes of a chord, so four fifths of the delay are shared by every note a channel starts on a step, and one fifth differs from note to note. The numbers come from scatter, which mixes the bits of a seed with the SplitMix64 function:

#![allow(unused)]
fn main() {
fn scatter(seed: u64) -> f64 {
    let mut x = seed.wrapping_add(0x9E37_79B9_7F4A_7C15);
    x = (x ^ (x >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
    x = (x ^ (x >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
    x ^= x >> 31;
    // The top 53 bits, as many as an `f64` holds exactly.
    (x >> 11) as f64 / (1u64 << 53) as f64
}
}

It looks random, but the same seed always gives the same number, so a song plays the same way every time and a WAV export sounds like playback. wrapping_mul lets the multiplication wrap past u64::MAX instead of panicking in a debug build: here wrapping is the point. scatter also needs no state, which suits the audio thread: no random generator to keep, lock or seed.

A delayed note waits in a list until its frame:

#![allow(unused)]
fn main() {
pub(crate) struct Pending {
    channel: usize,
    origin: Origin,
    pitch: Note,
    velocity: u8,
    gate: u32,
    /// The frame it starts on, counted on [`AudioThread::now`]'s clock.
    at: u64,
    /// How many frames after its step that is, for a trace.
    late: u32,
}
}

The list is made with room for 512 notes (PENDING_NOTES) on the UI thread, and the audio thread never lets it grow:

#![allow(unused)]
fn main() {
// A full list never grows (that would allocate): the note
// then starts on time.
if late > 0 && pending.len() < pending.capacity() {
}

Every frame, the notes whose at has come are started, and taken out with swap_remove, which moves the last note into the gap instead of shifting the whole list down. The order of waiting notes does not matter, so the cheaper removal is the right one.

Why only late, never early? To start a note early the audio thread would have to look into the next step before it starts. Late by 0 to 20 ms sounds the same as early or late by 10 ms around a grid that is itself 10 ms late, and nobody hears a whole song 10 ms late.

In files and MIDI files

Each of these features is saved only when it is used, so a project that doesn’t use it can still be opened by older versions (Saving). format_for writes the oldest format that can hold the project:

When a file is read, every time and tempo marker goes through set_time_marker or set_tempo_marker, which refuse one that starts too late or whose bars would not fit in a pattern, as if it had been added by hand.

A Standard MIDI File keeps tempo and meter as meta events on its first track. A tempo is written as microseconds per beat, in three bytes, and a change gets an event on the step where the played tempo changes, so a glide becomes one event per step, which is how MIDI files write a ritardando:

#![allow(unused)]
fn main() {
let tempo_event = |tempo: Tempo| {
    let micros = (60_000_000.0 / f64::from(tempo.bpm())).round() as u32;
    micros.min(0xFF_FFFF).to_be_bytes()[1..].to_vec()
};
// ...
for (step, pair) in tempos.windows(2).enumerate() {
    if pair[1] != pair[0] {
        let tick = (step as u32 + 1) * TICKS_PER_STEP;
        events.push((tick, TEMPO, tempo_event(pair[1])));
    }
}
}

to_be_bytes gives the four bytes of the u32, most significant first (“big-endian”, the order MIDI files use), and [1..] drops the first, which is always 0 below 0xFF_FFFF.

A time signature event holds the top number, the bottom number as a power of two (unit.ilog2(): 2 for a quarter, 3 for an eighth), how many MIDI clocks a metronome click lasts (24 to a quarter note, so 6 per step), and a constant 8. There is one at the start and one at every change of the played meter. MIDI has no room for a grouping, so a grouped bar clicks every note (ungrouped().first_beat()). How a whole MIDI file is written is in MIDI.

Testing it

Each type has tests next to it that read like the rules they check:

• meter.rs: a_steady_meter_counts_like_its_time_signature, a_marker_off_the_bar_line_leaves_a_short_bar, the_usual_grouping_is_written_plainly (3+3/8 is 6/8), a_grouping_is_saved_only_when_there_is_one, nonsense_does_not_divide_by_zero.
• tempo.rs: a_glide_moves_a_little_every_step (the 90, 80, 70, 60 above), a_glide_starts_from_where_the_last_one_got_to (a ritardando cut short by an a tempo), seconds_add_up_every_step.
• remeter.rs: every_note_keeps_its_place_in_the_bar, notes_between_steps_keep_their_exact_place, every_bar_lasts_as_long_as_before (the song’s length in seconds, before and after, within 0.2%), a_tempo_put_in_another_meter_and_back_is_the_same_tempo, a_pattern_too_long_for_the_new_bars_is_cut.
• swing.rs: full_swing_plays_the_eighths_as_triplets, half_swing_is_seven_to_five, a_strum_on_the_offbeat_moves_as_a_whole, notes_off_the_eighths_stay.
• engine.rs plays a few notes and checks where the sound starts, frame by frame: a_song_plays_each_step_at_its_own_tempo (two steps at 120 BPM, then two at 60, which last twice as long) and loose_timing_starts_notes_a_little_late (every note within 960 frames, 20 ms at 48 kHz, after its step; not all by the same amount; and the same every time).

One test goes through the whole app: styles_tried_one_after_another_keep_the_songs_tempo opens El Choclo and takes it through seven styles and meters (among them a tango vals in 3/4 and the Time box at 7/8), in pattern mode, in song mode stopped, and in song mode playing. After each one, the tempo must be unchanged when the meter is, and the song’s own whenever it is back in 4/4. Then it plays the start of the song with the playback trace and checks that every melody note starts and lasts as it did, within 2 ms. To keep it quick in a debug build, it plays only twelve seconds, at 8000 samples a second: plenty to time notes.

Instruments: drums, sampler and Lineup Osc

Files: crates/lineup-audio/src/instrument.rs, crates/lineup-audio/src/drums.rs, crates/lineup-audio/src/dsp.rs, crates/lineup-audio/src/sample.rs and crates/lineup-audio/src/timbre.rs

Every channel has an instrument: the part that turns notes into sound. This chapter is about the two that Ferrous Lineup makes itself, the sampler, which plays a recorded or synthesized sound, and the Lineup Osc, a small synthesizer. The other two kinds play through something else: a SoundFont (SoundFonts and General MIDI) or an external synth over MIDI (MIDI). How the sounds are chosen in the app is in the manual’s Sounds.

One enum, four instruments

#![allow(unused)]
fn main() {
pub enum Instrument {
    Sampler(Sampler),
    Synth(Synth),
    SoundFont(SoundFontPlayer),
    MidiOut(MidiOut),
}
}

A common design for “many kinds of one thing” is a trait, trait Instrument, with values of type Box<dyn Instrument>. That is open: anyone could add a kind without touching this file. But every Box::new allocates, and every call goes through a pointer to a table of functions. With four kinds, all known, an enum is simpler. The audio thread matches on it, making one never allocates, and when a fifth kind is added the compiler lists every match that has to learn about it.

Every method of Instrument is a match that hands the call to the kind inside:

#![allow(unused)]
fn main() {
pub fn release_all(&mut self) {
    match self {
        Instrument::Sampler(sampler) => sampler.release_all(),
        Instrument::Synth(synth) => synth.release_all(),
        Instrument::SoundFont(player) => player.release_all(),
        Instrument::MidiOut(midi_out) => midi_out.release_all(),
    }
}
}

What an instrument can be asked:

A note of the song knows its length when it starts, so it gets a gate in frames and ends by itself; the audio thread never has to remember to stop it. A key pressed on a MIDI keyboard has no known length, so it gets HELD, u32::MAX, which never runs out: only note_off ends it.

The instrument for a channel is built by Instrument::for_channel, on the UI thread, from the project’s Channel:

#![allow(unused)]
fn main() {
Ok(match &channel.kind {
    // A drum sent over MIDI is its note of a General MIDI drum set.
    ChannelKind::Sampler(SampleSource::Builtin(drum)) => match channel.sent_on {
        Some(number) => Instrument::MidiOut(
            MidiOut::new(number).playing_as(Some(general_midi_drum(*drum))),
        ),
        None => {
            Instrument::Sampler(Sampler::new(Arc::new(drums::render(*drum, sample_rate))))
        }
    },
    ChannelKind::Sampler(SampleSource::File(path)) => {
        Instrument::Sampler(Sampler::new(samples.get(path)?))
    }
    ChannelKind::Synth => Instrument::Synth(Synth::with_timbre(
        sample_rate,
        Timbre::for_program(channel.program),
    )),
    ChannelKind::MidiOut { channel: number } => {
        Instrument::MidiOut(MidiOut::new(*number).with_program(channel.program))
    }
})
}

Drums are synthesized here and files read here (through the SampleCache), which is slow work that may allocate: exactly what the audio thread must not do. The finished instrument is sent over in a command.

Drums from a few lines of math

Ferrous Lineup ships no sound files. Its thirteen drums are computed when a drum channel is created, each in a few lines:

Most of them share one shape, the exponential decay:

#![allow(unused)]
fn main() {
fn decay(t: f32, tau: f32) -> f32 {
    (-t / tau).exp()
}
}

It is 1 at the start and falls to about 37% after tau seconds, 13% after twice that, and so on. Struck things fade this way.

Closures that remember: FnMut

All the drums are built with one helper:

#![allow(unused)]
fn main() {
fn generate(seconds: f32, sample_rate: u32, f: impl FnMut(f32) -> f32) -> Vec<f32> {
    let frames = (seconds * sample_rate as f32) as usize;
    (0..frames)
        .map(|i| i as f32 / sample_rate as f32)
        .map(f)
        .collect()
}
}

It takes a closure f from a time in seconds to a sample. The kick’s closure keeps a running phase between calls:

#![allow(unused)]
fn main() {
fn kick(sample_rate: u32) -> Vec<f32> {
    let mut phase = 0.0;
    generate(0.5, sample_rate, |t| {
        let frequency = 45.0 + 105.0 * decay(t, 0.04);
        phase += frequency / sample_rate as f32;
        (phase * TAU).sin() * decay(t, 0.15)
    })
}
}

The closure changes phase, a variable it captured from kick. A closure that changes what it captures implements the FnMut trait; Fn is for closures that only read, and FnOnce for those that can be called only once. impl FnMut(f32) -> f32 in the parameter list means “any closure of that shape”, and the compiler makes a copy of generate for each drum’s closure, as it does for generic types.

Why add up a phase instead of computing sin(t × frequency × 2π)? Because the frequency changes over time. The phase is the sum of all the small steps taken so far, so the pitch sweeps smoothly; the direct formula would jump around as the frequency changed.

Metal from six square waves

The cymbals use a trick from the analog drum machines of the early 1980s: six square waves at frequencies that are not multiples of each other, added together.

#![allow(unused)]
fn main() {
const METAL: [f32; 6] = [205.3, 304.4, 369.6, 522.7, 540.0, 800.0];

fn metal(t: f32, ratio: f32) -> f32 {
    METAL.iter().map(|&f| square(t, f * ratio)).sum::<f32>() / METAL.len() as f32
}
}

Notes whose frequencies are simple multiples of each other blend into a chord. These don’t, so together they clash and shimmer like metal. A high-pass filter keeps the bright part, and the envelope decides whether it is a closed hat, an open hat, a ride or a crash.

Every drum is then scaled with normalize so that its loudest sample is 0.9, and two tests go through Drum::ALL: every drum reaches that peak and is longer than a thousand frames (every_drum_is_audible_and_in_range), and every drum ends quietly instead of being cut off (every_drum_fades_out).

Noise and filters

dsp.rs holds the small building blocks. White noise comes from xorshift, a tiny random number generator:

#![allow(unused)]
fn main() {
pub fn next_sample(&mut self) -> f32 {
    let mut x = self.state;
    x ^= x << 13;
    x ^= x >> 17;
    x ^= x << 5;
    self.state = x;
    (x as f32 / u32::MAX as f32) * 2.0 - 1.0
}
}

Three shifts and three exclusive-ors. It is no good for security, but it sounds just like noise, never allocates, needs no crate, and gives the same “random” drums every time, which makes them testable. Its one trap is zero: xorshift from 0 stays at 0 for ever, so Noise::new starts from seed.max(1).

The filters are one-pole filters, the simplest there are. The low-pass moves its output a fraction of the way toward the input on every sample, so fast changes (high frequencies) are smoothed away:

#![allow(unused)]
fn main() {
pub fn process(&mut self, input: f32) -> f32 {
    self.state += (input - self.state) * self.coefficient;
    self.state
}
}

That is the same arithmetic as Smoothed, the volume that glides instead of jumping (Two threads). The high-pass follows the changes in its input instead, so a steady signal dies away and fast changes pass. The tests say exactly that: a constant input goes through the low-pass and is removed by the high-pass.

The sampler

#![allow(unused)]
fn main() {
pub struct Sampler {
    sample: Arc<SampleData>,
    /// Boxed so an `Instrument` stays small: commands carrying one are
    /// copied into the command queue, and a pointer is cheaper to copy
    /// than eight voices. The box is created here, on the UI thread.
    voices: Box<[SamplerVoice; SAMPLER_VOICES]>,
    notes_started: u64,
}
}

Arc<T> (“atomically reference-counted”) is a pointer that several owners share. Cloning one does not copy the data, it adds one to a counter, and the data is freed when the last Arc goes. The counter is updated atomically, so it is safe across threads, which is what lets a sample be built on the UI thread and played on the audio thread. The same sound file in three channels is in memory once.

Each of the eight voices plays one hit:

#![allow(unused)]
fn main() {
fn next_sample(&mut self, frames: &[f32]) -> f32 {
    let Some(position) = self.position else {
        return 0.0;
    };
    let index = position as usize;
    if index + 1 >= frames.len() {
        self.position = None;
        return frames.get(index).copied().unwrap_or(0.0) * self.gain;
    }
    // Linear interpolation between the two nearest frames.
    let fraction = (position - index as f64) as f32;
    let sample = frames[index] + (frames[index + 1] - frames[index]) * fraction;
    self.position = Some(position + self.increment);
    // ...
}
}

let ... else matches a pattern, or runs the else block, which must leave the function. It keeps the main path unindented: “not playing, so silence; otherwise carry on with position”.

position is a fraction of a frame, because a sound rarely moves through its frames at exactly one per output frame. A WAV recorded at 44.1 kHz played on a 48 kHz sound card must move a little slower, or it would sound higher and shorter. And a sampler plays pitches by playing faster or slower: an octave up is twice as fast, and each semitone multiplies the speed by the twelfth root of two, the same rule Note::frequency uses (Pitch classes, notes and spelling):

#![allow(unused)]
fn main() {
// Every semitone up plays the sample 2^(1/12) times faster.
let semitones = pitch.midi() as f64 - STEP_NOTE.midi() as f64;
let pitch_ratio = 2.0_f64.powf(semitones / 12.0);
let rate_ratio = self.sample.sample_rate() as f64 / output_rate as f64;
}

The voice’s increment is the two ratios multiplied. On STEP_NOTE, C4, the note a step button plays, the pitch ratio is 1 and the sound plays as recorded. Between two stored frames the voice draws a straight line, linear interpolation: not the best a sampler can do, but cheap and good enough for drums.

The velocity scales the volume, velocity / 127. A sampler ignores the gate: like a drum machine, it plays its whole sound every time, and because it has voices, a new hit does not cut off the one before.

That is right for drums and wrong for one thing: a long recording, such as a whole song imported as audio, would play on after Stop. So release_all fades out the voices of a sound longer than ten seconds, in about 15 ms, and leaves short hits ringing:

#![allow(unused)]
fn main() {
pub fn release_all(&mut self) {
    let long = self.sample.frames().len() as u64
        > u64::from(self.sample.sample_rate()) * LONG_SAMPLE_SECONDS;
    if long {
        for voice in self.voices.iter_mut().filter(|voice| !voice.is_idle()) {
            voice.fading.get_or_insert(1.0);
        }
    }
}
}

release_unless, for a clip taken away or a track muted while it plays, fades the song’s sounds whatever their length.

Starting partway

A note sounds when playback reaches the step it starts on. For a drum hit that is all there is to it, but a recording is one note on the first step of a song: started from bar 20, the song would play without it. So when playback starts, jumps, or comes round to the start of the loop, the engine’s resume_long_sounds looks back over the song for the notes that started before the playhead, and asks each instrument to resume them:

#![allow(unused)]
fn main() {
fn resume(
    &mut self,
    pitch: Note,
    velocity: u8,
    output_rate: u32,
    origin: Origin,
    elapsed: f64,
) -> bool {
    let increment = self.increment(pitch, output_rate);
    let position = elapsed * increment;
    if !self.is_long() || position + 1.0 >= self.sample.frames().len() as f64 {
        return false;
    }
    self.start_at(position, increment, velocity, Some(origin));
    true
}
}

elapsed is how many output frames ago the note started, and a voice moves increment frames of the sound for each output frame, so the voice starts elapsed * increment frames in, as far as it would have got. Only a long sound, over ten seconds, is started this way, and only if it lasts that long: a drum hit from two bars ago has long finished, and other instruments answer false. resume_long_sounds goes through every piece of a clip that starts at or before the step, and every time the piece played each note:

#![allow(unused)]
fn main() {
for note in channel.notes.get(play.pattern) {
    // Every time the piece played the note before
    // `step`, counted from the piece's start, which is
    // below zero for a time in the part of the clip the
    // piece skips.
    let first = play.start as isize - play.skip as isize + note.start as isize;
    let times = (first..play.end().min(step) as isize).step_by(length);
    for at in times.filter(|&at| at < step as isize) {
        let origin = Origin {
            pattern: play.pattern,
            pattern_step: note.start,
            song_step: at.max(0) as usize,
            over_song: false,
        };
        let elapsed = frames_between(timing, at, step);
        let started = channel.instrument.resume(
            origin,
            note.pitch,
            note.velocity,
            self.sample_rate,
            elapsed,
        );
        // ...
    }
}
}

first is where the note falls if the piece started at its own first step; it is below zero when the clip leaves out its start (skip), and step_by(length) gives each repeat of the pattern within the piece. frames_between adds up the frames of the steps from there to the playhead at the song’s tempo on each step, so a recording under a tempo change starts at the right place too.

Loading a WAV file

SampleData::load_wav reads WAV files with the hound crate. A WAV stores samples as floats or as integers of 8 to 32 bits, and both become floats between -1 and 1:

#![allow(unused)]
fn main() {
let interleaved: Vec<f32> = match spec.sample_format {
    hound::SampleFormat::Float => reader
        .samples::<f32>()
        .collect::<Result<_, _>>()
        .map_err(SampleError::Wav)?,
    hound::SampleFormat::Int => {
        let full_scale = (1_i64 << (spec.bits_per_sample - 1)) as f32;
        reader
            .samples::<i32>()
            .map(|sample| sample.map(|s| s as f32 / full_scale))
            .collect::<Result<_, _>>()
            .map_err(SampleError::Wav)?
    }
};
}

samples() gives a Result per sample, because a file can be cut off halfway. Collecting an iterator of Results into a Result<Vec<_>, _> gives Ok with every value if all were Ok, or the first Err, and stops there. The _s let the compiler fill in the types. Then interleaved.chunks(channels) takes one frame at a time (left, right) and averages it, so a stereo file becomes mono.

SampleError implements Display with translated messages, so “could not read the WAV file” reaches the user in their language. The test loads_and_mixes_to_mono writes a real 16-bit stereo WAV to the system’s temporary folder with hound::WavWriter and reads it back.

Voices

A voice is one note’s worth of sound-making: its own place in the sound, its own oscillator, its own envelope. The Lineup Osc has 16 voices and a sampler 8. Each new note takes one:

#![allow(unused)]
fn main() {
trait Voice {
    /// Whether the voice is silent and free to play a new note.
    fn is_idle(&self) -> bool;
    /// When the voice's note started, as a count of notes started so far.
    fn started(&self) -> u64;
    /// Whether the voice's note has ended and it is only fading out.
    fn is_releasing(&self) -> bool;
}

fn pick_voice<V: Voice>(voices: &mut [V]) -> &mut V {
    let oldest = |releasing: bool| {
        voices
            .iter()
            .enumerate()
            .filter(|(_, voice)| !releasing || voice.is_releasing())
            .min_by_key(|(_, voice)| voice.started())
            .map(|(index, _)| index)
    };
    let index = voices
        .iter()
        .position(Voice::is_idle)
        .or_else(|| oldest(true))
        .or_else(|| oldest(false))
        .unwrap_or(0);
    &mut voices[index]
}
}

The order is: a silent voice if there is one; otherwise the oldest voice that is only fading out; otherwise the oldest of all. Taking a busy voice is voice stealing, and every hardware synth does it when more notes are held than it has voices. A fading voice goes first because cutting a tail is far less noticeable than cutting a note still held, such as a long bass note under quick chords (the test voices_that_are_fading_out_are_stolen_first plays exactly that).

Voice is a private trait: SamplerVoice and SynthVoice are different structs, both implement it, and one generic function serves both. V: Voice is the trait bound; the function may only call what the trait promises.

Why find an index first and only then return &mut voices[index]? The searches borrow the slice to read it (iter()). A mutable reference can’t come out of a read-only search, so the code finds the position, lets the read borrows end, and borrows mutably once at the end.

started comes from a counter that goes up with every note, so “oldest” is “smallest”. A u64 won’t overflow: at a thousand notes a second it would take 584 million years.

A fixed number of voices, in a box

#![allow(unused)]
fn main() {
voices: Box::new(std::array::from_fn(|_| {
    SynthVoice::new(sample_rate, timbre.cutoff)
})),
}

The voices are a fixed-size array, so the audio thread never grows it and never allocates. std::array::from_fn builds an array by calling the closure once per element; the closure gets the index, which is not needed here, hence |_|. The sampler’s voices implement Default, so Box::default() builds them.

The array is in a Box because of the command queue to the audio thread. Every slot of the queue is as big as the biggest Command, and a command that inserts a channel carries an Instrument. Sixteen voices are over a kilobyte; a Box is one 8-byte pointer. A test pins the size down:

#![allow(unused)]
fn main() {
let size = std::mem::size_of::<Command>();
assert!(size <= 80, "a command takes {size} bytes");
}

Boxing means the voices live on the heap, and freeing them is freeing memory. That is why an instrument the audio thread is done with always goes back to the UI thread in the trash queue (Two threads): the box is made and freed on the UI thread, and the audio thread only moves the pointer.

The Lineup Osc

The Lineup Osc plays one oscillator per voice, through a soft low-pass filter, shaped by a volume envelope:

#![allow(unused)]
fn main() {
pub struct Synth {
    sample_rate: f32,
    voices: Box<[SynthVoice; SYNTH_VOICES]>,
    /// Boxed, like the voices, so an `Instrument` stays small.
    envelope: Box<EnvelopeRates>,
    notes_started: u64,
}
}

The wave

An oscillator keeps a phase, from 0 to 1 through one cycle, and the wave says what each phase sounds like:

#![allow(unused)]
fn main() {
pub fn at(self, phase: f32) -> f32 {
    match self {
        // Ramps from -1 to 1.
        Wave::Saw => phase * 2.0 - 1.0,
        // 1 for the first half of the cycle, -1 for the second.
        Wave::Square => {
            if phase < 0.5 {
                1.0
            } else {
                -1.0
            }
        }
        // Up from -1 to 1 and back down.
        Wave::Triangle => 1.0 - 4.0 * (phase - 0.5).abs(),
        Wave::Sine => (phase * std::f32::consts::TAU).sin(),
    }
}
}

Each frame, the phase moves on by frequency / sample_rate and wraps round with fract(). A sawtooth has every harmonic, so it is bright and buzzy; a square only the odd ones, which sounds hollow; a triangle has weak ones and sounds soft; a sine has none and sounds pure.

A plain sawtooth made like this contains frequencies above what the sample rate can hold, and they fold back as faint metallic tones, which is called aliasing. The low-pass filter hides most of it. Removing it properly (with “PolyBLEP” corrections, or wavetables) would be a good project.

The envelope: a state machine

A note that just switches on and off clicks, and sounds like nothing real. An envelope shapes its volume over time. The classic one has four parts, ADSR:

 volume
   1 ┤  /\
     │ /  \___________          A: attack, rising to full volume
     │/    D    S      \        D: decay, falling to...
     │                  \       S: sustain, held while the note is held
   0 ┼───────────────────\___   R: release, fading out after the note ends
       A       gate ends ^

Each voice is in one stage, and every sample may move it to the next. Code shaped like this is a state machine:

#![allow(unused)]
fn main() {
match self.stage {
    Stage::Idle => return 0.0,
    Stage::Attack => {
        self.level += envelope.attack_step;
        if self.level >= 1.0 {
            self.level = 1.0;
            self.stage = Stage::Decay;
        }
    }
    Stage::Decay => {
        let sustain = envelope.sustain;
        self.level = sustain + (self.level - sustain) * envelope.decay_factor;
    }
    Stage::Release => {
        self.level *= envelope.release_factor;
        if self.level < SILENT {
            self.stage = Stage::Idle;
            return 0.0;
        }
    }
}

// Count down the gate while the note is held, then let go. A
// `HELD` gate is not counted: only `note_off` ends it.
if self.is_held() && self.gate != HELD {
    match self.gate.checked_sub(1) {
        Some(left) => self.gate = left,
        None => self.stage = Stage::Release,
    }
}
}

• The attack rises in a straight line; decay and release are exponential: each frame keeps a fixed fraction of the distance left, the way strings and bells fade. The fractions are worked out once per instrument in EnvelopeRates::new, not on every sample: decay_factor is e^(-1 / (seconds × sample_rate)).
• checked_sub returns None instead of going below zero, so it reads as “if there is no gate left, release”.
• There is no Sustain stage. Decay approaches the sustain level and stays there, so a stage of its own would do nothing.
• SILENT is 0.0001, about -80 dB. An exponential fade never reaches zero, so the voice is called silent below it and freed.

note_off releases the voices of a pitch only if they were started with the HELD gate. A key let go on a MIDI keyboard must not end the same note that the song is playing on its own gate. release_all moves every held voice to Release, which is how Stop lets long notes fade instead of playing on.

A stolen voice is not reset: start sets the new pitch, gain and gate, and leaves the level, the phase and the filter as they were.

#![allow(unused)]
fn main() {
voice.stage = Stage::Attack;
voice.started = self.notes_started;
voice.origin = origin;
// The level, phase and filter carry on from where they were, so a
// stolen voice does not jump (and click).
}

The attack then rises from wherever the level was. Each voice is also turned down to SYNTH_VOICE_GAIN, 0.35, so a four-note chord does not come out four times too loud.

Timbres: sounding like a General MIDI instrument

The Lineup Osc can never sound like a real violin, but it can sound more like a violin than like a piano. A channel with a General MIDI program and no SoundFont plays a timbre chosen by the program’s family:

#![allow(unused)]
fn main() {
pub struct Timbre {
    pub wave: Wave,
    /// Seconds to reach full volume.
    pub attack: f32,
    /// How quickly the volume falls to the sustain level (time constant,
    /// in seconds).
    pub decay: f32,
    /// The volume a held note settles at, 0 to 1. 0 for a sound that dies
    /// away by itself, like a piano or a plucked string.
    pub sustain: f32,
    /// How quickly a note fades after it is let go (time constant).
    pub release: f32,
    /// The low-pass filter's cutoff, in Hz: lower is darker.
    pub cutoff: f32,
    /// How loud, compared with the Lineup Osc's own sound.
    pub gain: f32,
}
}

Two small const fns name the two ways instruments behave:

#![allow(unused)]
fn main() {
/// Struck or plucked: starts at once and dies away over `decay`.
const fn struck(wave: Wave, decay: f32, release: f32) -> Timbre {
    Timbre::new(wave, 0.003, decay, 0.0, release)
}

/// Bowed, blown or sung: swells in over `attack` and keeps going.
const fn held(wave: Wave, attack: f32, release: f32) -> Timbre {
    Timbre::new(wave, attack, 0.3, 0.85, release)
}
}

and for_program is one match on the program number, in General MIDI’s own order, where each family is a range of eight numbers:

#![allow(unused)]
fn main() {
let timbre = match program.min(127) {
    // Pianos.
    0..=3 => Timbre::struck(Wave::Saw, 0.9, 0.25).cutoff(1_800.0),
    // ...
    // Brass.
    56..=63 => Timbre::held(Wave::Saw, 0.04, 0.1).cutoff(2_000.0),
    // Reeds: saxophones, oboe, bassoon, clarinet.
    64..=71 => Timbre::held(Wave::Square, 0.03, 0.08).cutoff(1_800.0),
    // Pipes: flutes, recorder, ocarina.
    72..=79 => Timbre::held(Wave::Triangle, 0.05, 0.1).cutoff(3_000.0),
    // ...
    // Sound effects have no tune to play; the Lineup Osc stands in.
    _ => Timbre::LINEUP_OSC,
};
}

Range patterns (0..=3), alternatives (24..=28 | 31) and a final _ make the whole table one expression, and the compiler checks that every number from 0 to 255 lands somewhere. At the end, each timbre’s gain is multiplied by the wave’s, so a square, the loudest wave, doesn’t jump out of the mix. Timbre::for_program(None) is LINEUP_OSC, the synth’s own bright sawtooth, so a channel without a program sounds as it always did. Which program each channel gets is in SoundFonts and General MIDI.

Testing it

The tests play an instrument into a buffer and look at the numbers, since nobody can listen in a test:

• synth_plays_the_right_pitch plays A4 for a second and counts how often the output changes sign: about 880 times, two per cycle of 440 Hz.
• synth_stops_after_the_gate_and_release holds a note for a tenth of a second and checks the output is exactly zero ten release times later, with no voice playing.
• synth_plays_chords, voices_are_stolen_when_all_are_busy and voices_that_are_fading_out_are_stolen_first check the voices.
• sampler_resamples_to_the_output_rate plays one second recorded at 24 kHz on a 48 kHz output and expects 48 000 frames of sound, give or take ten; sampler_plays_higher_notes_faster expects half as many an octave up; sampler_hits_can_overlap plays two hits at once.
• held_notes_last_until_note_off checks the HELD gate.
• In timbre.rs, plucked_instruments_die_away_and_bowed_ones_keep_going checks the families, and every_wave_stays_between_minus_one_and_one the waves.

SoundFonts and General MIDI

Files: crates/lineup-core/src/general_midi.rs, crates/lineup-audio/src/soundfont.rs, crates/lineup-audio/src/instrument.rs and crates/lineup-app/src/app/sounds.rs

A channel says which instrument it plays with a number: 0 is a grand piano, 40 a violin, 52 a choir. The numbers come from General MIDI, a list every synthesizer agrees on. Three things in Ferrous Lineup turn such a number into sound:

• the Lineup Osc picks a wave and an envelope that come close to it (Timbres);
• an external synth over MIDI is told to play it with a program change (MIDI);
• a SoundFont, a file of recordings of real instruments, plays it inside the app.

This chapter is about the numbers, where a channel gets one, and the SoundFont. How to turn the sounds on and choose instruments in the app is in the manual’s Sounds.

General MIDI: 128 instruments by number

A MIDI cable or a MIDI file carries notes, not sounds. To say which sound should play them, MIDI has the program change message: “from now on, channel 3 plays program 40”. It is two bytes: 0xC2 (program change, 0xC0, on channel 3, counted from 0 as 2) and 40.

On its own, 40 means nothing. General MIDI, published in 1991, fixed a list of 128 programs, so that 40 is a violin on every synth that follows it, from a phone to a stage keyboard. The programs come in sixteen families of eight: pianos 0 to 7, chromatic percussion (celesta, vibraphone, marimba) 8 to 15, organs 16 to 23, guitars 24 to 31, basses 32 to 39, strings 40 to 47, and so on up to sound effects, 120 to 127. MIDI channel 10 is kept for drums: there, each note is a drum, 36 the kick, 38 the snare, 42 the closed hi-hat, whatever program is chosen. Manuals count programs from 1 (“41 Violin”); the bytes count from 0.

general_midi.rs in lineup-core holds the list. The programs the demos and styles use have names, and every program has its name and family:

#![allow(unused)]
fn main() {
pub const VIOLIN: u8 = 40;
pub const CELLO: u8 = 42;
pub const CHOIR_AAHS: u8 = 52;
}

#![allow(unused)]
fn main() {
/// The name of program `program`, such as "Violin" for 40.
pub fn name(program: u8) -> &'static str {
    NAMES[usize::from(program.min(LAST))]
}

/// The family program `program` belongs to, 0 (piano) to 15 (sound effects).
pub fn family(program: u8) -> usize {
    usize::from(program.min(LAST)) / 8
}
}

NAMES is a [&str; 128] and FAMILIES a [&str; 16], both in General MIDI’s order. Because the families are eight programs each, “which family” is a division by 8, and the programs of family f are f * 8..f * 8 + 8. .min(LAST) keeps a number above 127 from indexing past the end: a u8 can hold up to 255, and a damaged file could contain one. The menus are built from the same two arrays, and the names go through the translation table, so the Spanish menu says “Violín”.

The built-in drums keep their own sounds, but anything that speaks General MIDI needs each one as a note of channel 10. general_midi_drum, in midi_file.rs, is that table:

#![allow(unused)]
fn main() {
/// The note General MIDI drum sets play for each built-in drum.
pub fn general_midi_drum(drum: Drum) -> Note {
    Note::new(match drum {
        Drum::Kick => 36,
        Drum::Snare => 38,
        Drum::Clap => 39,
        Drum::HiHat => 42,
        Drum::OpenHat => 46,
        Drum::Rim => 37,
        Drum::LowTom => 45,
        Drum::HighTom => 50,
        Drum::Ride => 51,
        Drum::Crash => 49,
        Drum::Cowbell => 56,
        Drum::Shaker => 70,
        Drum::Conga => 63,
    })
}
}

37 is the General MIDI “Side Stick”, the rim shot; 70 is “Maracas”, the closest it has to a shaker; 63 is “Open Hi Conga”. drum_name goes the other way for the 47 drums from 35 to 81, so the mixer can say which drum a note plays. A test checks a few of them against the General MIDI list, and another checks the program names, so a typo in either table fails the tests.

A channel’s instrument

Channel has one field for it:

#![allow(unused)]
fn main() {
/// The General MIDI instrument the channel plays, 0 to 127 (see
/// [`general_midi`](crate::general_midi)), or `None` for none in
/// particular. MIDI files and the MIDI output send it to the synth as
/// a program change; the Lineup Osc picks a sound close to it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub program: Option<u8>,
}

Option<u8> because a channel can have no instrument in particular. Then nothing is sent to a synth, and the Lineup Osc keeps its own bright sawtooth. The two serde attributes keep old files readable: a file without the field reads as None (default), and a channel without an instrument writes no field at all (skip_serializing_if). Only a project where some channel has an instrument needs format 9, so an older Ferrous Lineup still opens the rest (The version number).

A drum channel has no program: on MIDI channel 10 the notes choose the drums. A sampler playing a WAV file has none either, since its sound is the file.

Where the number comes from

• The rack and the mixer. Right-click a channel’s name and open Instrument, or click the instrument’s name in the mixer. Both show instrument_choices: “None (the Lineup Osc’s own sound)”, then the sixteen families, each a submenu of its eight programs, numbered from 1 as in the manuals. The family the current program is in has a dot before it, so you can find it in a long list.

• The band. The chord sheet’s band panel gives each player an instrument with the same families (How the band plays a chord sheet).

• The Library. A style’s Keys and Bass channels are made by synth_named, which gives them a piano and a bass:

  #![allow(unused)]
  fn main() {
  let program = match name {
      KEYS => Some(general_midi::ACOUSTIC_GRAND_PIANO),
      BASS => Some(general_midi::FINGER_BASS),
      _ => None,
  };
  }

• Demos. Each voice of a demo names its instrument: violins and a cello for Pachelbel’s Canon, a bandoneón (General MIDI’s “Tango Accordion”) for a tango (How a demo is written). A test builds every song demo and checks that every synth channel in it has a program.

• MIDI files. Importing a file takes each MIDI channel’s first program change as its instrument (MIDI).

Where the number goes

1. MIDI export writes a program change at the very start of each channel’s track, before its first note, so the synth is ready:

   #![allow(unused)]
   fn main() {
   // The instrument first, so the synth is ready before the first note.
   if let Some(program) = channel.program
       && midi_channels[index] != DRUM_CHANNEL
   {
       let change = MidiMessage::ProgramChange {
           channel: midi_channels[index],
           program,
       };
       track.event(0, &change.bytes());
   }
   }

2. MIDI output sends it just before the channel’s first note, and again after every stop, in case the sound was changed on the synth in between (MIDI).

3. The Lineup Osc plays a Timbre for the program’s family.

4. The SoundFont plays the program’s recordings, which is the rest of this chapter.

What a SoundFont is

A sampler plays one recording at different speeds (The sampler): twice as fast sounds an octave higher. That works for a few notes, but a piano recorded on middle C and played two octaves up sounds like a toy. The timbre of a real instrument changes across its range, and sped up, its attack gets too short.

A SoundFont (a .sf2 file, a format from the sound cards of the 1990s) is a whole sampler library in one file:

• samples: short recordings, a piano’s C, E, G♯ and so on every few notes, each with the note it was recorded at. Sounds that last, like an organ or strings, have a loop: once the attack has played, the middle of the recording repeats for as long as the key is held;
• instruments: which sample to play for which keys and velocities (a soft note can play a recording of a soft note), and how: the volume envelope, a filter, vibrato;
• presets: what a MIDI program change chooses, by bank and program.

A General MIDI SoundFont puts the 128 General MIDI instruments in bank 0, in their numbered order, and a drum kit in bank 128, which a synthesizer plays on MIDI channel 10. So program 0 is always a grand piano, program 33 a fingered bass guitar, and key 36 on channel 10 a kick.

Playing a note means finding the sample whose key and velocity range holds it, and playing it faster or slower by the distance between the two notes. Every semitone is a factor of 2^(1/12), about 1.0595, so a sample of A4 (440 Hz) played for B4, two semitones up, runs 2^(2/12) ≈ 1.122 times as fast: 494 Hz.

Who reads and plays it: rustysynth

Reading an .sf2 file and playing it is a lot of code: parsing the file, the key ranges, the envelopes, the filters, the loops, mixing dozens of voices. The rustysynth crate does all of it, in plain Rust with no C library to install, under the MIT licence, which a GPL program may use. Its interface is small; in short:

#![allow(unused)]
fn main() {
let sound_font = Arc::new(SoundFont::new(&mut file)?);
let mut synthesizer = Synthesizer::new(&sound_font, &settings)?;
synthesizer.process_midi_message(0, 0xC0, 33, 0); // channel 1: program 33
synthesizer.note_on(0, 40, 100); // E2, velocity 100
synthesizer.render(&mut left, &mut right); // the next block of sound
}

soundfont::load is the first line with the errors spelled out: a file that cannot be opened is a SoundFontError::Io, and one that is not a SoundFont, or is damaged, is a SoundFontError::Invalid. Each prints a translated message, so the status bar can say “not a SoundFont file (…)” in the app’s language.

It speaks MIDI. And the app already has an instrument that speaks MIDI: the MIDI Out, which keeps track of which notes are sounding and when each one must end, and collects note-on, note-off and program-change messages in an outbox for an external synth (MIDI). So a SoundFont instrument is a MIDI Out whose messages go to a synthesizer inside the app.

A MIDI Out that plays inside the app

#![allow(unused)]
fn main() {
/// A channel's instrument played from a SoundFont.
pub struct SoundFontPlayer {
    /// Which notes sound and until when, as for an external synth; its
    /// messages go to the synthesizer once per block.
    notes: MidiOut,
    /// Boxed so an `Instrument` stays small.
    block: Box<Block>,
}

/// The synthesizer and the block of sound it rendered last.
struct Block {
    synthesizer: Synthesizer,
    sound_font: Arc<SoundFont>,
    /// [`GAIN`] or [`DRUM_GAIN`].
    gain: f32,
    left: [f32; BLOCK],
    right: [f32; BLOCK],
    /// The next frame of `left` and `right` to hand out. At `BLOCK`, a
    /// new block is due.
    read: usize,
}
}

The audio thread asks every instrument for one sample at a time. The synthesizer works in blocks of BLOCK, 64 frames, so the player hands out the block it has, and when the block runs out it passes on the messages of the last 64 frames and asks for the next block:

#![allow(unused)]
fn main() {
pub fn next_sample(&mut self) -> f32 {
    self.notes.next_sample();
    let block = &mut *self.block;
    if block.read == BLOCK {
        let synthesizer = &mut block.synthesizer;
        self.notes.flush(|message| play(synthesizer, message));
        synthesizer.render(&mut block.left, &mut block.right);
        block.read = 0;
    }
    let sample = (block.left[block.read] + block.right[block.read]) * 0.5 * block.gain;
    block.read += 1;
    sample
}
}

self.notes.next_sample() makes no sound: a MIDI Out’s next_sample counts frames, so it knows when each note’s length is up and posts its note-off. A note that starts in the middle of a block is heard from the next one: at most 64 frames late, 1.3 ms at 48 kHz, far below what anyone hears.

let block = &mut *self.block; reaches through the Box once, so the lines after it borrow block.synthesizer and block.left as separate fields. Inside the if, self.notes and block.synthesizer are borrowed at the same time, one by flush and one by the closure; Rust allows it because they are different fields.

The SoundFont’s sounds are in stereo, and every channel of the app is mono until the mixer places it with its pan (The mixer). So the two sides are added and halved.

flush is the same method that hands a MIDI Out’s messages to the MIDI port, and play turns each MidiMessage into the synthesizer’s call:

#![allow(unused)]
fn main() {
/// Hands one MIDI message to the synthesizer.
fn play(synthesizer: &mut Synthesizer, message: MidiMessage) {
    match message {
        MidiMessage::NoteOn {
            channel,
            pitch,
            velocity,
        } => synthesizer.note_on(
            i32::from(channel),
            i32::from(pitch.midi()),
            i32::from(velocity),
        ),
        MidiMessage::NoteOff { channel, pitch } => {
            synthesizer.note_off(i32::from(channel), i32::from(pitch.midi()))
        }
        MidiMessage::ProgramChange { channel, program } => {
            synthesizer.process_midi_message(i32::from(channel), 0xC0, i32::from(program), 0)
        }
    }
}
}

i32::from widens a u8 to the i32 rustysynth takes; it cannot fail, which is why it is from and not try_from.

Everything a MIDI Out already does right comes for free: notes that end after their length, held keys from the keyboard, notes that stop when their track is muted, note lengths that stretch with a tempo change. The engine also treats both alike in one more way: MIDI has one of each note per channel, so a note that starts again ends the one sounding (one_per_pitch in engine.rs).

A player is made for a program:

#![allow(unused)]
fn main() {
pub fn new(sound_font: &Arc<SoundFont>, sample_rate: u32, program: u8) -> Option<Self> {
    let notes = MidiOut::new(0).with_program(Some(program));
    Self::on(sound_font, sample_rate, notes, GAIN)
}
}

with_program makes the MIDI Out send the program change before its first note, so the synthesizer is on the right instrument when the first note arrives. A drum is a MIDI Out on channel 10 that plays one note whatever note its steps are on (playing_as), as a drum sent to an external synth does:

#![allow(unused)]
fn main() {
pub fn drum(sound_font: &Arc<SoundFont>, sample_rate: u32, drum: Note) -> Option<Self> {
    let notes = MidiOut::new(DRUM_CHANNEL).playing_as(Some(drum));
    Self::on(sound_font, sample_rate, notes, DRUM_GAIN)
}
}

One synthesizer per channel, one SoundFont for all

A synthesizer can play sixteen MIDI channels at once, so one could play the whole band. Each channel of the app gets its own instead. That way its volume, pan, effects, mute light and level meter work exactly as on any other channel, because the engine mixes channels, not MIDI channels.

The SoundFont itself is tens of megabytes, and it is not copied. It is read once into an Arc<SoundFont>, an atomically reference-counted pointer: Arc::clone copies the pointer and adds one to a counter, and the memory is freed when the last clone goes. Every synthesizer holds one clone, and so does the app. An instrument the audio thread replaces goes back on the trash queue and is dropped on the window’s thread (Freeing memory somewhere else), so even when it holds the last clone, the SoundFont is never freed on the audio thread.

Instrument has a kind for it, and a constructor that says which channels the SoundFont plays:

#![allow(unused)]
fn main() {
pub fn from_sound_font(
    channel: &Channel,
    sample_rate: u32,
    sound_font: &Arc<SoundFont>,
    drums: bool,
) -> Option<Self> {
    let player = match &channel.kind {
        ChannelKind::Synth => SoundFontPlayer::new(sound_font, sample_rate, channel.program?),
        ChannelKind::Sampler(SampleSource::Builtin(drum))
            if drums && channel.sent_on.is_none() =>
        {
            SoundFontPlayer::drum(sound_font, sample_rate, general_midi_drum(*drum))
        }
        _ => None,
    };
    player.map(Instrument::SoundFont)
}
}

The ? after channel.program returns None from the whole function when the channel has no program: that is what keeps a channel on “None” playing the Lineup Osc. A built-in drum plays the SoundFont’s kit when the drums setting is on, unless it is being sent to an external synth (sent_on). A sample file and a MIDI Out are not the SoundFont’s to play. The app’s build_instrument asks this first and falls back on Instrument::for_channel when the answer is None:

#![allow(unused)]
fn main() {
fn build_instrument(&mut self, channel: &Channel, sample_rate: u32) -> Instrument {
    if let Some((sound_font, drums)) = self.sounds.in_use()
        && let Some(instrument) =
            Instrument::from_sound_font(channel, sample_rate, sound_font, drums)
    {
        return instrument;
    }
    match Instrument::for_channel(channel, sample_rate, &mut self.samples) {
        ...
    }
}
}

Every instrument is built there, for playing and for exporting, so File > Export WAV and the video export play the SoundFont too.

A synthesizer’s two blocks of 64 samples are half a kilobyte, and every slot of the queue to the audio thread is as big as the biggest command. That is why the Block is boxed, as the other instruments box their voices (A fixed number of voices, in a box); the test commands_stay_small would catch a command that grew.

Nothing allocated on the audio thread

The audio thread never asks for memory (The golden rule). A synthesizer reserves everything it needs when it is made: its voices (VOICES, 128 per channel; a piano note can use two, its left and right samples), their buffers, the table of presets. Synthesizer::new runs on the window’s thread, inside build_instrument, and the finished instrument is sent across. Its note_on and render only reuse those voices and buffers.

on sets the synthesizer up:

#![allow(unused)]
fn main() {
let mut settings = SynthesizerSettings::new(i32::try_from(sample_rate).ok()?);
settings.block_size = BLOCK;
settings.maximum_polyphony = VOICES;
// Reverb and chorus would cost as much as the voices, once for
// every channel. The sounds are recorded with some room already.
settings.enable_reverb_and_chorus = false;
let synthesizer = Synthesizer::new(sound_font, &settings).ok()?;
}

The mixer has one reverb that every channel sends into, so a room is still there, once (The mixer). i32::try_from(sample_rate).ok()? is the careful conversion: a u32 above i32::MAX would not fit, and ? on the Option gives up instead of wrapping around. The synthesizer refuses rates below 16 kHz and above 192 kHz itself, and then the channel keeps its Lineup Osc.

Loud enough

rustysynth plays quietly, at half volume, because it expects a whole band to share it. The player turns it up by GAIN (5) and the drums by DRUM_GAIN (7). Those numbers come from a measurement, not from taste: the same notes were rendered on the Lineup Osc and on the SoundFont, and their peaks and average levels compared. A real piano dies away while the Lineup Osc holds its notes, so the two never match exactly, and another SoundFont may be louder or softer; each channel’s volume does the rest.

The offer, and the download

The app does not come with a SoundFont, because a good one is tens of megabytes. As soon as the app opens with its instruments on the Lineup Osc, before anything plays, a window offers one:

Download fetches GeneralUser GS, a free General MIDI SoundFont by S. Christian Collins, from its own repository, and keeps it in the app’s data folder: ~/.local/share/ferrouslineup/soundfonts on Linux, the Application Support folder on macOS, AppData\Roaming on Windows. Choose a file… takes any other .sf2. Not now keeps the Lineup Osc. Edit > Settings… > Audio has the same choices for later: SoundFont instruments, SoundFont drums, Choose SoundFont… and Use GeneralUser GS.

If GeneralUser GS is already in that folder, downloaded by an earlier run or an earlier version, there is nothing to download, and the window offers Use it instead:

Asked until answered

One method decides whether to ask:

#![allow(unused)]
fn main() {
pub(super) fn offer_sound_font(&mut self) {
    let sounds = &mut self.sounds;
    if !sounds.settings.on && !sounds.settings.turned_down && sounds.general_user.is_some() {
        sounds.offer_open = true;
    }
}
}

It opens the window whenever the instruments play on the Lineup Osc and the offer was not turned down. Nothing is asked while the sounds are on, even if their SoundFont is still being read, nor on a system with no folder for app data (general_user is None there).

It is called in two places. LineupApp::new calls it once the app is made, so the question is the first thing the window shows:

#![allow(unused)]
fn main() {
// Real instrument sounds are offered as soon as the window opens,
// before anything plays.
app.offer_sound_font();
}

and every way of starting to play (the ▶ button, Space, a Library preview, opening a demo) goes through set_playing, which ends with

#![allow(unused)]
fn main() {
self.playing = true;
self.offer_sound_font();
}

so an offer that was closed unanswered comes back on Play. Playing goes on while the window asks, so the sound is never held up by a question.

A run that did not close cleanly has a question of its own at the start: whether to bring back the unsaved work (see A copy of unsaved work). The two would cover each other, so the sounds wait for it:

#![allow(unused)]
fn main() {
// Unsaved work from a run that did not close cleanly is offered
// first.
if !self.sounds.offer_open || !self.recovery.pending.is_empty() {
    return;
}
}

Opening the window answers nothing. A run that closes before the question is answered asks again as the app next opens, and so does a run whose SoundFont has gone missing. Only a “no” ends the offer:

#![allow(unused)]
fn main() {
fn decline_sound_font(&mut self) {
    let sounds = &mut self.sounds;
    sounds.offer_open = false;
    sounds.settings.turned_down = true;
    sounds.turn_off();
}
}

Not now calls it, and so do closing the window before a download and Stop during one. Turning SoundFont instruments off in Settings sets turned_down too, and turning it on clears it. A “yes” turns the sounds on and clears turned_down:

#![allow(unused)]
fn main() {
// Yes: GeneralUser GS, even in place of a chosen file that is
// gone, played from as soon as it is downloaded or read.
if (download || use_it)
    && let Some(path) = self.sounds.general_user.clone()
{
    let sounds = &mut self.sounds;
    sounds.settings.file = None;
    sounds.settings.turned_down = false;
    if download {
        sounds.settings.on = true;
        sounds.changed = true;
        sounds.start(path, true);
    } else {
        sounds.offer_open = false;
        self.set_sound_font(true);
    }
}
}

Download starts the download and leaves the window open to show it. Use it closes the window and goes through set_sound_font, the same as ticking the setting, which finds the file on disk and starts reading it. Either way, when the SoundFont is ready, check_sounds gives every channel its instrument again and the status bar says “Instruments play from GeneralUser GS”. The window is drawn in egui’s Foreground order, above every other window, because a demo opens its chord sheet and brings it to the front in the same frame it starts to play.

The settings are a small struct:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(default)]
struct Settings {
    /// Whether channels play from the SoundFont.
    on: bool,
    /// Whether the built-in drums do too.
    drums: bool,
    /// A SoundFont file chosen with "Choose SoundFont…", or `None` for
    /// GeneralUser GS.
    file: Option<PathBuf>,
    /// Whether the offer of real instrument sounds was turned down, with
    /// "Not now", or the sounds were turned off in Settings. Until then,
    /// the app offers them as it opens and on Play whenever they are off.
    turned_down: bool,
}
}

They are kept between runs by name, as "sound-font", with the app’s preferences module (Kept by name, not by type):

#![allow(unused)]
fn main() {
settings: preferences::get(ctx, SETTINGS_NAME).unwrap_or_default(),
}

when the app starts, and preferences::set(ctx, SETTINGS_NAME, &self.sounds.settings) whenever they change. Kept by name, they survive an update of the app. In egui’s own memory they would not: an update would turn the sounds off, and with GeneralUser GS still on disk the app would be back on the Lineup Osc.

#[serde(default)] on the struct fills any field missing from the saved data with its value from Default, so a field can be added without losing everyone’s settings, and a field the struct no longer has is skipped. Renaming a field therefore forgets only that field: a renamed turned_down starts as false, and everyone is asked again. Default is written by hand rather than derived, because drums starts as true.

Downloading on a thread of its own

A download of 30 MB takes from a second to a minute, and reading a SoundFont takes a moment too. Both run on a thread of their own, like the WAV export, and the window keeps drawing. The thread and the window share a Progress:

#![allow(unused)]
fn main() {
/// How far a download is. Its thread writes it and the UI thread reads
/// it; atomics need no lock for that.
#[derive(Default)]
struct Progress {
    /// Bytes downloaded so far.
    done: AtomicU64,
    /// The size of the file, or 0 while it is not known.
    total: AtomicU64,
    /// Set by the UI thread to stop the download.
    cancel: AtomicBool,
}
}

Atomics are numbers two threads can read and write at the same time without a lock: the download stores how many bytes it has, the window reads it to draw the bar, and Stop stores true in cancel, which the download checks before each read of up to 64 KB. Ordering::Relaxed is enough, because no other data hangs on these numbers: a bar one frame behind is fine.

The request is made with ureq, a small HTTP client, using the certificates the operating system trusts (so it works behind a company proxy that has its own) and the proxy in HTTPS_PROXY, if there is one. The environment variable FERROUS_LINEUP_SOUNDFONT_URL gives another address, such as a copy on your own network. A file over a gigabyte is refused: no General MIDI SoundFont is that big, so it is something else.

The file is written as GeneralUser-GS.sf2.part, then read as a SoundFont, which checks it is one, and only then renamed:

#![allow(unused)]
fn main() {
fn download_to(url: &str, path: &Path, progress: &Progress) -> Result<Arc<SoundFont>, String> {
    let part = path.with_extension("sf2.part");
    let result = download_part(url, &part, progress).and_then(|()| {
        let sound_font = soundfont::load(&part).map_err(|err| err.to_string())?;
        fs::rename(&part, path).map_err(|err| err.to_string())?;
        Ok(sound_font)
    });
    if result.is_err() {
        let _ = fs::remove_file(&part);
    }
    result
}
}

A download cut off halfway, or a web page that came back instead of the file, never leaves a broken GeneralUser-GS.sf2 that would fail every time the app starts. and_then runs the second step only if the first worked, and let _ = says on purpose that a .part file that cannot be removed is not worth reporting.

Once per frame, check_sounds stores the settings if they changed and asks the thread whether it is done (JoinHandle::is_finished). While it is not, it asks egui to draw again in a tenth of a second, so the bar moves even when the mouse does not. When it is, join hands over the Arc<SoundFont>, and every channel needs a new instrument made from it. The app already knows how to do that: when channels start or stop being sent over MIDI, send_routes rebuilds the instruments whose route changed. Forgetting all the routes makes it rebuild every one on the next frame:

#![allow(unused)]
fn main() {
/// Has every channel of the audio thread given its instrument again,
/// on the next frame: the SoundFont was turned on or off.
pub(super) fn instruments_changed(&mut self) {
    self.routes_sent = None;
}
}

Turning the sounds off does the same, and every channel gets its Lineup Osc or its built-in drum back. The SoundFont stays loaded while the sounds are off, so turning them on again is instant.

Debug builds

cargo run builds without optimizations, and a synthesizer works out every sample of every voice: unoptimized, a band could be too much for the audio thread. Cargo can optimize one dependency while the rest stays quick to build, in the workspace’s Cargo.toml:

[profile.dev.package.rustysynth]
opt-level = 3

Testing it

The tests should not need a 30 MB download, and the repository should not hold one. So the test module writes a SoundFont byte by byte: one sample, a sine wave at 440 Hz that loops, two instruments (one plays the sample as recorded, one an octave higher) and three presets (program 0, program 33, and a drum kit in bank 128).

An .sf2 file is a RIFF file, the same container as a WAV file: a tree of chunks, each a four-letter name, a size and its bytes. Two small functions build them:

#![allow(unused)]
fn main() {
/// One chunk of a RIFF file: its name, its size and its bytes, padded
/// to an even length.
fn chunk(id: &[u8; 4], body: &[u8]) -> Vec<u8> {
    let mut bytes = id.to_vec();
    bytes.extend((body.len() as u32).to_le_bytes());
    bytes.extend(body);
    if body.len() % 2 == 1 {
        bytes.push(0);
    }
    bytes
}

/// A list of chunks: a chunk whose bytes are a type and other chunks.
fn list(kind: &[u8; 4], chunks: &[Vec<u8>]) -> Vec<u8> {
    let mut body = kind.to_vec();
    for each in chunks {
        body.extend(each);
    }
    chunk(b"LIST", &body)
}
}

The file is a list of three lists: INFO (a version and a name), sdta (the samples, as 16-bit numbers) and pdta (the presets, instruments and sample headers, in nine fixed-size tables). The tests then play it and listen the way an oscilloscope would: a sine wave crosses zero twice per period, so counting the crossings in a quarter of a second, times two, gives its frequency.

#![allow(unused)]
fn main() {
#[test]
fn the_program_picks_the_instrument() {
    let mut player = SoundFontPlayer::new(&tiny_sound_font(), RATE, 33).unwrap();
    player.start(Note::new(A4), 100, HELD, None);
    let sound = render(&mut player, RATE as usize / 2);
    assert!(
        (frequency(&sound) - 880.0).abs() <= 8.0,
        "{}",
        frequency(&sound)
    );
}
}

Program 33 is the instrument an octave up, so A4 comes out at 880 Hz. Other tests check that a player is silent until a note starts, that A3 comes out at 220 Hz, that a note starts within one block and ends after its length, that louder notes are louder, that a drum plays its own key whatever note it is written on, that a file that is not a SoundFont is refused, and which channels the SoundFont takes (channels_without_a_sound_in_the_sound_font_keep_theirs).

The window tests must not depend on whether the computer running them has downloaded GeneralUser GS. So every test app looks for it at a path that never exists, keep_general_user_in(no_sound_font()), and starts as if the offer had been turned down. Four tests undo that. the_app_offers_real_instrument_sounds_as_it_opens does what LineupApp::new does and checks that the window opens before anything plays, with Download, and that after Not now it does not come back, even after a restart and an update. play_offers_real_instrument_sounds_until_the_offer_is_answered presses Space and checks that the window opens while the song plays, with Download. It starts the app again without answering and checks that Play asks again. Then it clicks Not now, presses Play twice, and checks that nothing is asked, even after a restart and after an update. play_offers_a_sound_font_already_on_disk puts an empty file where GeneralUser GS goes, checks that the window offers Use it, clicks it, and checks that the file is being read. a_demo_asks_for_real_instrument_sounds_in_front_of_its_chord_sheet checks that the window is on top, and that its buttons take the click.

The mixer: levels, pan, reverb, effects and score order

Files: crates/lineup-core/src/mixer.rs, crates/lineup-core/src/effects.rs, crates/lineup-core/src/score_order.rs, crates/lineup-audio/src/reverb.rs, crates/lineup-audio/src/effects.rs, crates/lineup-audio/src/levels.rs, crates/lineup-app/src/app/mixer.rs and crates/lineup-app/src/meters.rs

The mixer (F9) is where the band is balanced. Each channel has a line: its instrument, a level meter, its volume, where it sits between the speakers (Pan), how much of it goes into the room (Reverb), its own Effects (an equalizer, a compressor and a delay), Mute and Solo. Above them are the master volume with a meter for each speaker, and the reverb that every channel shares. The lines are listed the way a conductor’s score lists instruments, in sections.

The work is split as everywhere else in the program. lineup-core holds the settings, which are saved with the song; lineup-audio turns them into sound on the audio thread; lineup-app draws the window. How to use the mixer is in the manual’s The mixer.

What is saved

The project has one Mixer:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct Mixer {
    pub master: f32,
    pub reverb: ReverbSettings,
    pub solo: Option<usize>,
}
}

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct ReverbSettings {
    pub enabled: bool,
    /// Wet fraction, from 0 to 1.
    pub mix: f32,
    /// Approximate time to decay by 60 dB, in seconds.
    pub decay: f32,
    /// High frequency absorption, from 0 to 1.
    pub damping: f32,
    pub pre_delay_ms: f32,
}
}

and each Channel has its own mix: volume and muted, and three more fields:

#![allow(unused)]
fn main() {
#[serde(default, skip_serializing_if = "is_centred")]
pub pan: f32,
#[serde(default = "full_send", skip_serializing_if = "is_full_send")]
pub reverb_send: f32,
#[serde(default, skip_serializing_if = "Effects::is_plain")]
pub effects: Effects,
}

skip_serializing_if leaves a field out of the file while it has the value of a new channel (in the middle, everything sent to the reverb, no effects), and default fills it back in when it is missing. A song whose channels are all plain is written exactly as it would be by a Ferrous Lineup with no pans or effects, so an older version still opens it. Only a song that uses them needs format 26 (pan and send) or 28 (effects) (The version number). Opening checks the ranges: a file edited by hand with a pan of −3, or a delay whose echoes would never die away, is refused with a message instead of playing a channel louder than full.

Solo is one channel number, not a flag on each channel. The project answers “is this channel heard?” in one place, so everything that plays (the audio thread, an export, a MIDI file) agrees:

#![allow(unused)]
fn main() {
pub fn channel_muted(&self, channel: usize) -> bool {
    self.channels.get(channel).is_none_or(|state| state.muted)
        || self.mixer.solo.is_some_and(|solo| solo != channel)
}
}

That is why soloing a channel reaches the audio thread as a mute change on every other channel (diff: the list of changes).

Reset mix puts the master, the reverb, the solo and every channel’s volume, pan, send and effects back as they are on a new song. The band’s players get their usual volumes back, and channels the band keeps quiet stay muted (Project::reset_mix, in band.rs).

The path of one sample

For each frame, the audio thread takes every channel through the same steps. This is the heart of the mix, in engine.rs:

#![allow(unused)]
fn main() {
let wet = self.reverb.wet();
let mut dry = [0.0; 2];
let mut send = 0.0;
for channel in &mut self.channels {
    let volume = channel.volume.next_value();
    let sample = channel.effects.process(channel.instrument.next_sample()) * volume;
    channel.peak = channel.peak.max(sample.abs());
    let amount = channel.reverb_send.next_value();
    let gains = lineup_core::Channel::pan_gains(channel.pan.next_value());
    let kept = sample * (1.0 - wet * amount);
    dry[0] += kept * gains[0];
    dry[1] += kept * gains[1];
    send += sample * amount;
}
// ...
let click = self.click.next_sample();
let stereo = self
    .reverb
    .next(dry, send, wet)
    .map(|sample| sample + click);
let volume = self.master_volume.next_value();
let stereo = stereo.map(|sample| sample * volume);
master_peak = [0, 1].map(|side| master_peak[side].max(stereo[side].abs()));
// `tanh` gently rounds off peaks above 1.0 instead of clipping them hard.
let stereo = stereo.map(f32::tanh);
}

In order:

1. The instrument makes a sample, mono.
2. The channel’s effects shape it: equalizer, compressor, delay.
3. Its volume scales it, and its peak is kept for the meter.
4. Its pan splits it between the two speakers, and its send puts part of it into the reverb.
5. The reverb adds the room to the sum of all channels.
6. The metronome’s click is added after the reverb: the room is the music’s, and a click with a tail is harder to follow.
7. The master volume scales the whole, its peaks go to the master meters, and tanh rounds off anything above full scale (Mixing a frame).

Volume, pan, send and the reverb’s wet level are all Smoothed: moved in the window, they glide to the new value over a few milliseconds instead of jumping, since a jump in the middle of a wave is heard as a click. The effects come before the volume, as on a mixing desk’s channel strip, so a compressor hears the instrument as it plays, whatever the fader says.

Pan: two speakers, one channel

Pan is a number from −1 (all left) to 1 (all right), with 0 in the middle. It becomes a gain for each speaker:

#![allow(unused)]
fn main() {
/// How loud it is in the left and the right speaker for its pan: both
/// full in the middle, and the far side fading out as it moves away.
pub fn pan_gains(pan: f32) -> [f32; 2] {
    [(1.0 - pan).min(1.0), (1.0 + pan).min(1.0)]
}
}

pan     −1.0  −0.5   0.0   0.5   1.0
left     1.0   1.0   1.0   0.5   0.0
right    0.0   0.5   1.0   1.0   1.0

In the middle both speakers play the channel at full volume, the way a mono sound plays on a stereo system. Moving a channel to one side turns the other speaker down, like the balance knob of a stereo.

This is one of several pan laws. Mixing desks often use a constant-power law instead, where the middle plays each speaker at about 0.71 (−3 dB), so a channel sounds equally loud wherever it is placed. With the law used here, a channel moved hard left sounds a little quieter than in the middle, because only one speaker plays it. The reason for keeping it is that a song where nothing is panned plays every channel at exactly its volume on both sides.

The slider writes its value as L30, C or R100, and reads what you type the same way: pan_value accepts L30, R100, C, a plain number from −100 to 100, and the Spanish I30 (izquierda) and D30 (derecha), which is what the Spanish interface shows. A double-click puts it back in the middle. A slider only senses drags, so the double-click is read from the pointer and checked against the slider’s rectangle.

The reverb: a room made of delays

A reverb imitates a room. A sound bounces off the walls, the floor and the ceiling and comes back, later and softer, thousands of times, until the echoes melt into a tail that dies away over a second or two. The mixer’s reverb is a Schroeder reverb, the oldest digital design (Manfred Schroeder, 1962), built from two kinds of delay.

A comb filter is a delay whose output is fed back into its input, a little softer each time: a sound comes back every 31 ms, say, quieter on each lap. One comb sounds like a metallic flutter, but four in parallel, with lengths that never line up, give a dense pattern of echoes. An all-pass filter is a delay that smears each echo into a cluster without changing the overall tone; three in a row turn the combs’ echoes into a smooth wash.

#![allow(unused)]
fn main() {
fn new(rate: u32, spread: usize) -> Self {
    let length =
        |samples| ((samples + spread) as f32 * rate as f32 / 48_000.0).round() as usize;
    Self {
        combs: [1493, 1601, 1747, 1867].map(|samples| Comb {
            delay: Delay::new(length(samples)),
            feedback: 0.0,
            filtered: 0.0,
        }),
        diffusers: [241, 503, 719].map(|samples| Delay::new(length(samples))),
    }
}
}

The lengths are counted in samples at 48 kHz (1493 samples is 31 ms) and scaled to the actual rate. They are all prime numbers, so no two share a factor and their echoes rarely fall on the same instant, which would sound like a ringing note. Each side of the stereo room is a Side with its own combs and all-passes; the right one is made with spread 37, so its delays are 37 samples longer and the two sides differ, which the ear hears as width.

[...].map(...) on an array gives an array of the same length, so combs is a [Comb; 4] built in one expression, with no Vec.

How long the room rings

Decay is the time the tail takes to fall by 60 dB, to a thousandth of its level: the usual measure of a room, called RT60. Each comb’s feedback is worked out from it:

#![allow(unused)]
fn main() {
fn configure(&mut self, rate: u32, decay: f32) {
    for comb in &mut self.combs {
        comb.feedback =
            10.0_f32.powf(-3.0 * comb.delay.samples.len() as f32 / (rate as f32 * decay));
    }
}
}

In decay seconds the sound goes round a comb rate × decay / length times, and is multiplied by feedback each time. For the total to be 10⁻³ (−60 dB), each lap multiplies by 10^(−3 × length / (rate × decay)). Longer combs go round fewer times, so they get a stronger feedback, and all four die away together.

Damping imitates the air and the soft walls of a real room, which swallow high frequencies sooner than low ones. Inside each comb, the echo goes through a one-pole low-pass filter on its way back in:

#![allow(unused)]
fn main() {
fn next(&mut self, input: f32, damping: f32) -> f32 {
    let out = self.delay.read();
    self.filtered = flushed(out * (1.0 - damping) + self.filtered * damping);
    self.delay.write(input + self.filtered * self.feedback);
    out
}
}

filtered moves only part of the way towards each new sample, which smooths out fast wiggles: the highs. Each lap smooths them a little more, so the tail gets darker as it fades, as in a hall.

Pre-delay is the gap before the room answers, up to 200 ms: in a big hall the first reflection arrives later than in a small room. It is one more ring buffer in front of the combs, a fifth of a second long.

Never too small, never in the way

flushed turns any value under 10⁻²⁰ into exactly 0. A fading tail gets smaller and smaller without ever reaching zero, and numbers that tiny (denormals) make many processors dozens of times slower. A reverb left to ring out in silence could then overrun the audio thread’s time.

All delay memory is reserved in Reverb::new, before the stream starts; configure only changes numbers, so moving a slider never allocates on the audio thread. A setting out of range is ignored rather than applied. Turned off, the wet level fades to zero and then Reverb::next returns the dry sound at once, doing no work. Turned on again, it starts from silence (clear), not from the tail it had when it was switched off.

The send: how much of each channel is in the room

Each channel has a send, from 0 to 1: how much of it goes into the room. The sum of all sends is the reverb’s single input, so twenty channels cost one reverb, not twenty, as with a send on a real desk. The reverb returns only the room, which next adds to the dry sound:

#![allow(unused)]
fn main() {
[
    dry[0] + left.next(delayed, damping) * wet,
    dry[1] + right.next(delayed, damping) * wet,
]
}

The line to look at in the mix is kept = sample * (1.0 - wet * amount): what goes into the room is taken out of the dry sound, in proportion to the Wet / dry setting. Check the two ends:

• Send 1 (all of it, as on every new channel): kept = sample × (1 − wet), and the whole sample goes to the room. That is a classic wet / dry mix of the whole song.
• Send 0: kept = sample, and nothing goes to the room. The channel plays dry and close, as with the reverb off, while the rest of the band stays in the room.

The room is mono going in and stereo coming out, so a channel panned hard left still has its reverb on both sides, as a guitarist on the left of a stage fills the whole hall.

Each channel’s effects

A real mixing desk has, on every channel strip, a few effects that shape one instrument before it joins the others. Each mixer line has three, in the order most desks have them: an equalizer, a compressor and a delay.

The equalizer: turning frequencies up or down

Every sound is a mix of frequencies: a note’s fundamental, and its overtones above it. An equalizer (EQ) turns ranges of them up or down. It adds no notes; it changes the colour of the ones there. The mixer’s EQ has three bands, each from −12 dB to +12 dB:

A shelf turns everything past its frequency up or down by the same amount, like a step. A bell turns its frequency up or down most, and less and less on each side. Decibels measure a ratio: +6 dB makes a band’s waves about twice as tall, −6 dB about half, 0 dB leaves it as it is.

Turning things down is the commonest use. When two instruments play in the same range, they mask each other: a piano’s lows and the bass turn into one muddy sound. Taking the lows out of the piano leaves room for the bass, and once the bass plays, the piano sounds no thinner.

On the audio thread each band is a biquad, a second-order filter, the building block of most equalizers. Each sample out is a mix of the last three samples in and the last two out:

#![allow(unused)]
fn main() {
let output = b0 * input + b1 * self.inputs[0] + b2 * self.inputs[1]
    - a1 * self.outputs[0]
    - a2 * self.outputs[1];
}

The five numbers b0, b1, b2, a1 and a2 decide what the filter does. Biquad::set works them out for a shelf or a bell, a frequency and a gain, with the formulas of Robert Bristow-Johnson’s Audio EQ Cookbook, which almost every audio program uses: a slope of 1 for the shelves, a Q of 1 for the bell. The three filters run one after the other, low, mid, high, and their numbers are only worked out again when the settings change, never for each sample. set keeps the samples the filter remembers, so moving a band while it plays does not click. The same 10⁻²⁰ floor as in the reverb keeps denormals out.

The compressor: evening out how loud a part is

Some parts come out unevenly: a bass line where some notes jump out and others get lost. A compressor turns a sound down when it gets loud:

• Under its threshold it does nothing.
• Over it, it turns the sound down by an amount its ratio sets. At 4:1, a sound 8 dB over the threshold comes out only 2 dB over: four decibels in for each one out. At 1:1 it turns nothing down, so the compressor is off. At 20:1 almost nothing gets over the threshold.
• Its gain (the “make-up gain”) turns the whole part up afterwards, since the loud notes came down. The part is as loud as it was, but steadier.

That rule is plain arithmetic, so it lives in lineup-core where a test can check it without any sound:

#![allow(unused)]
fn main() {
pub fn reduction(&self, level: f32) -> f32 {
    let over = level - self.threshold;
    if over <= 0.0 || self.ratio <= 1.0 {
        0.0
    } else {
        over * (1.0 - 1.0 / self.ratio)
    }
}
}

At 4:1, 8 dB over the threshold is turned down by 8 × (1 − ¼) = 6 dB, and comes out 2 dB over.

A compressor does not turn down each wave. It follows how loud the sound has been over the last few milliseconds: it turns down fast once a sound goes over the threshold (its attack, 10 ms) and back up more slowly once it is under again (its release, 150 ms). If it followed every wave, it would bend the wave’s shape and add a buzz. The Follower does this:

#![allow(unused)]
fn main() {
let peak = sample.abs();
let speed = if peak > self.level {
    self.attack
} else {
    self.release
};
self.level += (peak - self.level) * speed;
let level = (20.0 * self.level.log10()).max(FLOOR);
let decibels = compressor.gain - compressor.reduction(level);
10f32.powf(decibels / 20.0)
}

attack and release are worked out once from their times, as 1 − e^(−1 / (seconds × sample rate)): with that number, the level gets about two thirds of the way to a new loudness in the given time. 20 × log10 turns the level into decibels, reduction says how much to turn down, and 10^(dB / 20) turns the answer back into a number to multiply the sample by. .max(FLOOR) keeps silence, whose logarithm is minus infinity, at −100 dB.

The delay: echoes in time with the song

A delay plays the sound again a little later, and again, each echo quieter than the one before. Its time is a note value of the song, counted in steps (sixteenths):

#![allow(unused)]
fn main() {
pub const TIMES: [(u8, &'static str); 6] = [
    (1, "1/16"),
    (2, "1/8"),
    (3, "dotted 1/8"),
    (4, "1/4"),
    (6, "dotted 1/4"),
    (8, "1/2"),
];
}

So the echoes fall on the song’s rhythm, and follow the tempo when it changes. The dotted eighth is the favourite: its echoes fall three sixteenths after each note, between the beats, and a guitar or a voice playing eighth notes sounds as if it played sixteenths.

#![allow(unused)]
fn main() {
pub fn seconds(&self, tempo: Tempo) -> f32 {
    let step = tempo.seconds_per_beat() / crate::STEPS_PER_BEAT as f32;
    (f32::from(self.steps) * step).min(Delay::MOST_SECONDS)
}
}

A dotted eighth at 120 BPM is 3 × 0.125 = 0.375 s. An echo comes at most 2 seconds after the sound: a half note at 40 BPM would be 3 seconds, so at such slow tempos the longest times stop at 2.

• Feedback says how much of each echo comes back as the next one. At 50%, each echo is half as loud as the one before; at 0% there is only one. It stops at 90%, so the echoes always die away.
• Mix says how loud the echoes are next to the sound itself. 0% turns the delay off; 100% makes the first echo as loud as the note.

The delay remembers the sound it plays again in a ring buffer: a fixed array written round and round, where the sample delay_frames back is always behind the one being written:

#![allow(unused)]
fn main() {
let frames = line.len();
let read = (self.written + frames - self.delay_frames) % frames;
let echo = line.0[read];
line.0[self.written] = sample + echo * self.settings.delay.feedback;
self.written = (self.written + 1) % frames;
sample += echo * mix;
}

What goes into the line is the sound plus part of the echo; that part comes back once more delay_frames later, which is the feedback. What comes out is the sound plus the echo at the mix. Adding frames before the % keeps the subtraction from going below zero, which a usize cannot hold.

Memory made on the other side

Two seconds of sound is 96,000 samples at 48 kHz, a big allocation, and the audio thread never allocates. So the window’s thread makes the DelayLine and sends it with the settings:

#![allow(unused)]
fn main() {
SetEffects {
    channel: usize,
    effects: lineup_core::Effects,
    line: Option<DelayLine>,
},
}

It sends a line every time it sends settings with the delay on, because only the audio thread knows whether that channel already has one. ChannelEffects::set keeps the first line it gets and returns any other, which goes back on the trash queue to be freed on the window’s side:

#![allow(unused)]
fn main() {
let spare = match self.channels.get_mut(channel) {
    Some(state) => state.effects.set(effects, line, tempo),
    None => line,
};
if let Some(spare) = spare {
    self.throw_away(Garbage::DelayLine(spare));
}
}

A channel keeps its line once it has one. When its delay is turned off and on again, set fills the line with silence first, or the echoes of the last time would come back. When the tempo changes, the engine calls set_tempo on every channel’s effects, so the echoes move with it.

process first checks whether any effect is on. If none is, it returns the sample untouched: a channel without effects sounds exactly as it would without the code, and costs nothing.

Level meters: from the audio thread to the screen

A meter shows how loud a channel is now. The audio thread knows, since it makes the sound; the window’s thread draws the meter. They run at different speeds (the audio thread fills a block of a few hundred samples many times a second, the window draws about 60 frames a second), and the audio thread must never wait for the window, so a Mutex is out.

Peaks in atomics

The audio thread keeps the loudest sample of each channel over a block (channel.peak above). At the end of the block it raises a shared peak to it, if it is louder. Once a frame, the meter takes the shared peak and sets it back to silence. So no peak is missed, however blocks and frames line up, and neither side waits:

#![allow(unused)]
fn main() {
/// The peaks since the UI last took them, as the bits of `f32`s.
///
/// For numbers that are not negative, comparing their bits compares the
/// numbers, so `fetch_max` on the bits keeps the louder peak.
pub struct Levels {
    channels: [AtomicU32; MAX_CHANNELS],
    master: [AtomicU32; 2],
}
}

#![allow(unused)]
fn main() {
fn raise(slot: &AtomicU32, peak: f32) {
    // `peak > 0.0` is false for NaN too, which must not get in.
    if peak > 0.0 {
        slot.fetch_max(peak.to_bits(), Ordering::Relaxed);
    }
}

fn take(slot: &AtomicU32) -> f32 {
    f32::from_bits(slot.swap(0, Ordering::Relaxed))
}
}

Rust’s standard library has no AtomicF32. But an f32 is 32 bits, and to_bits and from_bits turn it into a u32 and back without changing a bit. Better still, for numbers that are not negative, the order of the bits as unsigned integers is the order of the numbers: the exponent sits in the high bits and the mantissa below it. So fetch_max on the bits, an atomic “keep the larger”, keeps the louder peak. Peaks are absolute values, never negative, and the if keeps NaN out (its bits would compare as larger than any number).

swap(0, …) reads the value and puts 0 (the bits of 0.0) in its place in one step, so a peak raised between a read and a reset can’t be lost. Ordering::Relaxed is enough because each peak stands alone: nothing else in memory has to be seen in a certain order along with it.

std::array::from_fn(|_| AtomicU32::new(0)) builds the arrays, since an AtomicU32 is not Copy and [AtomicU32::new(0); N] would not compile.

Decibels, and a meter that falls slowly

The ear hears loudness by ratios, not by differences, so the meter is drawn in decibels, a scale of ratios:

decibels = 20 × log10(level)        1.0 → 0 dB (full scale)
                                    0.5 → −6 dB
                                   0.25 → −12 dB
                                  0.004 → −48 dB (the meter's floor)

Each 6 dB down halves the level, wherever on the scale. A meter is lit from −48 dB at the left to 0 dB at the right: green, amber from −6 dB, red at full scale and above. The master’s meters measure after the master volume and before tanh, so red on the master means the rounding-off is at work. Hovering a meter says its level in decibels.

A meter that followed every peak exactly would flicker too fast to read. So it jumps up to a new peak at once and falls 24 dB a second:

#![allow(unused)]
fn main() {
pub fn update(&mut self, levels: &Levels, channels: usize, seconds: f32) {
    let fall = gain(-FALL_DB_PER_SECOND * seconds);
    self.channels.resize(channels, 0.0);
    for (index, shown) in self.channels.iter_mut().enumerate() {
        *shown = levels.take_channel(index).max(*shown * fall);
    }
    for (shown, peak) in self.master.iter_mut().zip(levels.take_master()) {
        *shown = peak.max(*shown * fall);
    }
}
}

seconds is the time since the last frame. Falling 24 dB a second means multiplying by 10^(−24 × seconds / 20) each frame, whatever the frame rate. Half a second after a peak, the meter shows it 12 dB down, at about a quarter.

egui only draws a frame when something happens. While a meter is still falling, the mixer asks for the next frame at once (request_repaint); when every meter is dark, it looks again every tenth of a second (request_repaint_after), which is enough to catch the notes of a MIDI keyboard played while the song is stopped.

Score order: the drums together

The channel rack keeps channels in the order they were added. A style that brings in a rim shot, a bass, a cowbell and a conga adds them at the end, so a list in rack order scatters the drums around the piano and the bass. A conductor’s score never does that: every instrument has its place, the same in every score, so a reader finds the flutes at the top and the double basses at the bottom without searching. The mixer lists channels in that order, in sections with a heading each:

The horns come above the trumpets although they sound lower, because they blend with the woodwinds and were long written next to them. The strings come last, so the double basses, the lowest part of the orchestra, end the page; a choir goes just above them, as in a requiem or an oratorio.

The drums follow the drum staff, where each drum has its own line or space: the cymbals on and above the top line (the crash highest, then the hi-hat, then the ride), the high tom in the top space, the snare in the third space, the floor tom below it and the kick in the bottom space. So the Drums section reads Crash, Hat, Open hat, Ride, High tom, Snare, Rim (a cross-stick, written where the snare is), Low tom, Kick. Hand percussion (cowbell, shaker, clap, conga) usually has staves of its own above the kit, so it comes first.

Only the mixer changes its order. The channel rack, the piano roll and the saved file keep the channels as they were added, and nothing sounds different.

Where a channel goes

score_order.rs is in lineup-core, with no UI code, so it is tested with plain cargo test. A Section is an enum in score order:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Section {
    Woodwinds,
    Brass,
    Percussion,
    Drums,
    HarpAndGuitars,
    Keyboards,
    Synths,
    Voices,
    Strings,
}
}

Deriving PartialOrd and Ord on an enum orders its variants as they are written: Section::Woodwinds < Section::Brass. The order of the score is the order of the source code.

The mixer does not look at a channel’s name to place it, but at its instrument, the General MIDI program (SoundFonts and General MIDI). A channel called “Lead” that plays a flute goes with the woodwinds. The program numbers mostly come in families already, but not always the way a score wants: General MIDI puts the timpani with the strings and the celesta with the mallets, and the score puts the timpani first in the percussion and the celesta with the keyboards. So each section lists its programs, top of the score first, and place finds a channel’s section and its rank in it:

#![allow(unused)]
fn main() {
pub fn place(channel: &Channel) -> (Section, usize) {
    match &channel.kind {
        ChannelKind::Sampler(SampleSource::Builtin(drum)) => {
            let rank = DRUMS.iter().position(|d| d == drum).unwrap_or(DRUMS.len());
            (Section::Drums, rank)
        }
        // A sound file usually takes a drum's row in the rack.
        ChannelKind::Sampler(SampleSource::File(_)) => (Section::Drums, DRUMS.len() + 1),
        ChannelKind::MidiOut {
            channel: DRUM_CHANNEL,
        } => (Section::Drums, DRUMS.len()),
        ChannelKind::Synth | ChannelKind::MidiOut { .. } => match channel.program {
            Some(program) => program_place(program),
            // The Lineup Osc, or an outside synth with no instrument named.
            None => (Section::Synths, usize::MAX),
        },
    }
}
}

ChannelKind::MidiOut { channel: DRUM_CHANNEL } matches only MIDI Out channels whose field equals the constant DRUM_CHANNEL (9, shown as 10): a const can stand in a pattern like a literal number. The next arm, MidiOut { .. }, catches every other MIDI channel; match tries the arms from the top, so the drum channel never gets that far.

#![allow(unused)]
fn main() {
fn program_place(program: u8) -> (Section, usize) {
    Section::ALL
        .into_iter()
        .find_map(|section| {
            let rank = section.programs().iter().position(|&p| p == program)?;
            Some((section, rank))
        })
        .unwrap_or((Section::Synths, usize::MAX))
}
}

find_map runs the closure on each section and stops at the first one that returns Some. Inside, the ? after position returns None from the closure when the program is not in that section, which tells find_map to try the next. A test checks that each of the 128 programs is in exactly one list, and another that each built-in drum has one place in the kit.