Introducción

Ferrous Lineup es un programa de código abierto, escrito en Rust, para tocar canciones con una banda de acompañamiento. Escribe los acordes de una canción compás por compás, elige un estilo, y una banda (bajo, batería y piano, con guitarra, cuerdas, vientos u órgano cuando el estilo los tiene) la toca en cualquier tonalidad y tempo. Cada parte que toca la banda cae en una pista propia, donde puedes abrirla en el piano roll, cambiarla a mano, o dejarla afuera y tocarla tú.

También es una manera de aprender armonía mientras tocas. Nombra cada acorde que oyes, con su número romano en la tonalidad y lo que hace ahí, y conoce también las otras maneras en que la música nombra la armonía: conjuntos de clases de altura, series dodecafónicas y los micromodos de Kröpfl.

Este libro trata del interior: cómo está organizado el código, cómo está diseñado y por qué, y cómo está escrita en Rust la teoría musical que conoce la aplicación. Explica el Rust que usa cada parte a medida que avanza, señalando los archivos reales, así que también es un curso de Rust construido alrededor de un programa de verdad. No hace falta saber Rust antes de leerlo; si conoces otro lenguaje de programación, puedes seguirlo. Para usar la aplicación, lee en cambio el manual de usuario: no tiene nada de código.

Cómo está organizado el libro

Los capítulos siguen el código, de la forma del programa a cómo se distribuye. Cada uno dice qué hace una parte de la aplicación, con un enlace a la página del manual sobre cómo usarla; cómo está diseñada y por qué; el Rust que usa; los archivos donde vive; y los tests que la protegen. Cada parte termina con ejercicios.

Al final están el formato del archivo de proyecto, un glosario de Rust, un glosario de música e ideas para lo que viene.

Por dónde empezar

• Para aprender Rust: lee las partes en orden, con el glosario de Rust abierto, y prueba los ejercicios al final de cada parte. Compilarlo desde el código fuente pone primero el código en marcha.
• Para aprender cómo se programa la teoría musical: empieza por la Parte III, y ten cerca el glosario de música. La teoría en sí, sin código, se enseña en el manual.
• Para cambiar algo: busca la parte de la aplicación en el índice, lee su capítulo, y ejecuta sus tests antes y después de tu cambio.

Cómo leerlo

1. En línea, en https://naelolaiz.github.io/ferrous-lineup/es/.
2. Como un solo PDF, para leer sin conexión o imprimir: ferrous-lineup-book-es.pdf. Tiene números de página, el índice de contenido al principio, un índice alfabético al final, y marcadores para cada capítulo.
3. Como archivos Markdown, en la carpeta book-es/src del repositorio, o como sitio web en tu computadora con mdbook serve --open en book-es/.

El libro también está en inglés, en https://naelolaiz.github.io/ferrous-lineup/. Cómo se construyen los libros cuenta cómo se hacen los sitios web y los PDF.

Los enlaces al código apuntan a la rama main, y los fragmentos de los capítulos están copiados de ella. Donde un fragmento deja líneas afuera, lo dice con // ....

Nombre y licencia

«Ferrous» quiere decir «de hierro» en inglés, y el óxido (rust) es óxido de hierro; un lineup es la formación de una banda, la banda que toca tus canciones.

Ferrous Lineup es software libre, publicado bajo la Licencia Pública General de GNU, versión 3 o posterior.

Compilarlo desde el código fuente

Para usar Ferrous Lineup alcanzan las descargas ya preparadas (ver Instalarlo, en el manual). Para leer su código con este libro, cambiarlo y ejecutar sus tests, compílalo tú. Son unos pocos comandos en Linux, macOS o Windows.

1. Instalar Rust

Rust se instala con rustup, una pequeña herramienta que descarga el compilador (rustc) y la herramienta de compilación (cargo) y los mantiene al día:

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

En Windows, descarga y ejecuta en cambio rustup-init.exe desde https://rustup.rs. Después reinicia la terminal y comprueba que funcionó:

cargo --version
rustc --version

Ferrous Lineup necesita Rust 1.95 o más nuevo, como dice rust-version en el Cargo.toml raíz: usa la edición 2024 del lenguaje (ver Ediciones), las cadenas de if let, que llegaron en Rust 1.88, y los bloqueos de archivos, que llegaron en 1.89, y egui y eframe, que dibujan la ventana, necesitan 1.95. Si tu Rust es más viejo, rustup update lo arregla.

2. Instalar las herramientas de compilación del sistema

Rust descarga sus propias bibliotecas, los crates, por su cuenta, pero necesita un enlazador del sistema, y en Linux algunos crates hablan con bibliotecas que trae el sistema: ALSA para el sonido, y X11 o Wayland para las ventanas.

Debian o 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

Los diálogos de archivos usan el portal del escritorio, que GNOME y KDE ya tienen; en un gestor de ventanas sin escritorio, instala xdg-desktop-portal-gtk. El MIDI pasa por el secuenciador de ALSA, que los sistemas de escritorio ya cargan; si el menú MIDI de la aplicación dice que MIDI no está disponible, cárgalo con sudo modprobe snd-seq.

macOS: las herramientas de línea de comandos de Apple traen el enlazador y las bibliotecas del sistema:

xcode-select --install

Windows: cuando rustup-init.exe lo pregunte, deja que instale las Visual Studio Build Tools; Rust usa su enlazador. Después usa los comandos de abajo en PowerShell o en el Símbolo del sistema.

3. Conseguir el código y ejecutarlo

Clona el repositorio (Git viene con las herramientas de compilación en macOS y Linux; en Windows, instálalo desde https://git-scm.com) y compila:

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

La primera compilación tarda unos minutos, porque Cargo compila cada dependencia; las siguientes compilan solo lo que cambió. --release activa las optimizaciones, que el código de audio necesita para llegar a tiempo. Mientras trabajas en el código, cargo run solo compila más rápido, y conserva la consola donde aparecen los mensajes y los pánicos.

La primera vez, una ventana encima ofrece sonidos de instrumentos reales; SoundFonts y General MIDI dice qué hace.

La ventana principal, en el manual, dice para qué sirve cada parte.

4. Desde la línea de comandos

El programa acepta algunos argumentos propios. Después de cargo run, -- dice que lo que sigue es para el programa, no para 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 es la traza de reproducción: toca un proyecto o una demostración como lo hace Archivo > Exportar WAV…, sin ventana ni tarjeta de sonido, y escribe en una tabla cada nota que empieza.

5. Ejecutar los tests

cargo test

ejecuta cada test de cada crate del workspace. Cómo se prueba el código dice qué tipos hay y cómo ejecutar algunos de ellos.

6. Construir los libros

Los libros se escriben con mdBook, una herramienta de Rust. Instálalo una vez, en la versión que usa el flujo de trabajo, y construye:

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

mdbook serve construye el sitio web, lo abre, y lo vuelve a construir cada vez que guardas una página. book/, manual/ y manual-es/ funcionan igual. Cómo se construyen los libros también imprime el PDF.

Comandos útiles

Cinco crates, y qué puede saber cada uno

Archivos: Cargo.toml, el Cargo.toml de cada crate en crates/, y crates/lineup-core/src/lib.rs

Ferrous Lineup es un solo programa, ferrous-lineup, construido a partir de cinco crates de Rust. Este capítulo trata de cómo están divididos y por qué: qué es Cargo, qué son un crate, un workspace y un módulo, un primer tipo pequeño y el Rust que muestra, y las pocas reglas que respeta todo el programa, cada una explicada en un capítulo propio más adelante en el libro. La última sección es un mapa de dónde vive cada parte de la aplicación.

Cargo

Cargo es la herramienta de compilación y el gestor de paquetes de Rust en uno. Lee los archivos Cargo.toml, descarga dependencias de crates.io, compila todo en el orden correcto, ejecuta las pruebas y mucho más. Casi nunca llamarás al compilador rustc directamente.

Crates

Un crate es la unidad de compilación de Rust: una librería o un programa. Ferrous Lineup son cinco crates, cada uno con un trabajo que puede probarse por su cuenta:

¿Por qué cinco crates en lugar de uno?

• Límites claros. lineup-core no puede depender de la interfaz por accidente, porque no incluye eframe como dependencia. El compilador hace cumplir la arquitectura por nosotros.
• Pruebas más rápidas. lineup-core depende solo de serde y ron, así que cargo test -p lineup-core compila un crate pequeño, no todo el toolkit de GUI, los drivers de audio ni los codificadores de video.
• Las dependencias pesadas quedan donde hacen falta. Solo lineup-listen decodifica formatos de audio, y solo lineup-video compila los codificadores de H.264 y MP3 desde sus fuentes en C.
• Reutilización. Sobre lineup-core y lineup-audio podría construirse un renderizador de línea de comandos o un plugin sin tocar el código de la ventana. La traza de reproducción ya funciona así: ferrous-lineup --trace toca una canción con lineup-audio sin abrir ninguna ventana (ver La traza de reproducción).

Las dependencias solo apuntan en una dirección:

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

lineup-video no sabe nada de canciones: recibe imágenes y sonido y hace un archivo con ellos.

Nombre del paquete y nombre del programa

El programa se compila a partir del paquete lineup-app, pero el archivo que escribe Cargo se llama ferrous-lineup. Los dos nombres están en lugares distintos de crates/lineup-app/Cargo.toml:

[package]
name = "lineup-app"

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

[package] name es como Cargo y los demás crates se refieren al paquete (cargo test -p lineup-app). [[bin]] describe un programa que compila el paquete; los corchetes dobles son la forma de TOML de decir «una entrada de una lista», porque un paquete puede compilar varios programas. Sin una entrada [[bin]], Cargo llamaría al programa como el paquete, lineup-app. Un crate llamado lineup-core se escribe lineup_core en las líneas use, porque un guion es un signo menos en Rust y no puede formar parte de un nombre; Cargo convierte los guiones en guiones bajos por ti.

El workspace

Un workspace es un grupo de crates que se compilan juntos y comparten un archivo Cargo.lock y una carpeta de salida target/. Mira el Cargo.toml de nivel superior:

[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 enumera los crates.
• [workspace.package] contiene los ajustes compartidos por todos los crates. Cada crate escribe version.workspace = true para heredarlos, de modo que el número de versión vive en un solo lugar. rust-version es el compilador de Rust más antiguo que puede compilar el código; uno más antiguo se detiene con un mensaje claro en lugar de un error confuso.
• [workspace.dependencies] fija la versión de cada dependencia una vez. Un crate escribe cpal.workspace = true para usarla. Así todos los crates usan la misma versión de cada librería.

Una versión como "0.18" significa «0.18.0 o cualquier 0.18.x más nueva». Las versiones exactas que eligió Cargo quedan registradas en Cargo.lock, que se incluye en el repositorio para que todos compilen exactamente el mismo código.

Ediciones

edition = "2024" elige la edición del lenguaje Rust. Las ediciones permiten a Rust hacer pequeños cambios incompatibles cada pocos años sin romper el código antiguo: cada crate declara en qué edición está escrito, y los crates de ediciones distintas funcionan bien juntos.

Módulos

Dentro de un crate, el código se organiza en módulos. Un módulo suele ser un archivo. En 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; le dice al compilador que busque pitch.rs junto a lib.rs.
• pub lo hace visible fuera del crate. Sin pub, todo en Rust es privado por defecto, visible solo dentro de su propio módulo.
• use trae un nombre al ámbito, como import en otros lenguajes. pub use además lo reexporta.

Un módulo puede tener módulos propios. harmony.rs declara pub mod chord;, y el compilador lo encuentra en harmony/chord.rs: la carpeta lleva el nombre del módulo al que pertenece.

lib.rs es la raíz del crate de una librería; main.rs es la raíz del crate de un programa. Observa que el crate se llama lineup-core en Cargo.toml pero lineup_core en el código: el código Rust no puede contener - en los nombres, así que Cargo lo sustituye por _.

Comentarios de documentación

Los comentarios que empiezan por /// documentan el elemento que tienen debajo, y //! documenta el módulo o crate que los contiene. Están escritos en Markdown. Ejecuta cargo doc --open para verlos renderizados como un sitio web navegable: cada tipo y función de Ferrous Lineup aparece con su explicación.

Un primer tipo: Note

Casi todo lineup-core son tipos pequeños con funciones propias. El más pequeño, Note en pitch.rs, muestra las piezas que usa cada capítulo posterior. Una nota se guarda como su número MIDI, de 0 a 127, y el do central es el 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 es un tuple struct: un struct cuyos campos no tienen nombre y se leen como .0, .1, etc. Con un solo campo que le da a un número un tipo propio, es un newtype, que Clases de altura, notas y su escritura explica junto con la música de la nota. El campo no tiene pub, así que el código fuera de pitch.rs no puede escribir Note(200).

Métodos: bloques impl

Las funciones de un tipo se escriben aparte de sus datos, en un bloque impl:

#![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 es una constante asociada, que se escribe Note::C4.
• Self es el tipo para el que es el impl, aquí Note.
• Una función cuyo primer parámetro es self es un método, y se llama como note.midi(). Una sin self, como new, es una función asociada, y se llama como Note::new(60). Rust no tiene constructores; new es solo el nombre de costumbre.
• La última expresión de una función, escrita sin ;, es lo que devuelve.
• midi recibe self por valor, no &self: una Note es Copy, así que pasarla copia un solo byte.

Traits, y derive

Un trait es un conjunto de métodos que un tipo promete tener, como una interfaz en otros lenguajes. El fmt::Display de la biblioteca estándar dice cómo escriben un valor {} en format! y 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())
    }
}
}

Así, Note::new(61).to_string() es "C#4" (o "Do#4" si las notas se nombran en solfeo), y cada lugar que muestra una nota la escribe de la misma manera.

Muchos traits son iguales para cualquier tipo: comparar campo por campo, copiar, imprimir para depurar. #[derive(...)] le pide al compilador que los escriba por ti:

Serialize y Deserialize vienen de serde, no del compilador (Guardar). Default es el trait de «un valor razonable para empezar»; Tempo escribe el suyo, 130 BPM:

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

Números: as

Rust nunca cambia el tipo de un número por su cuenta. as lo dice, como en octave:

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

self.0 / 12 es un u8, que no puede ser negativo, y la octava de las notas más graves es -1, así que el resultado de la división se vuelve un i8 antes de restarle 1. Los índices de una lista deben ser usize, así que as usize aparece donde un número elige un elemento.

Pánicos

Cuando un programa llega a algo que nunca debe pasar, como un índice más allá del final de una lista, Rust entra en pánico (panic): detiene el hilo y escribe dónde y por qué. assert!, assert_eq!, unwrap y expect entran en pánico a propósito cuando su condición falla, que es como falla un test (Cómo se prueba el código). Un pánico significa un error del programa, nunca una entrada mala: un archivo de proyecto dañado es un error que la aplicación muestra, y los tests se aseguran de que ningún archivo pueda hacer entrar en pánico al lector (Guardar).

Reglas que respeta todo el programa

Unas pocas decisiones dan forma a cada parte del código. Cada una tiene un capítulo que la muestra en acción:

1. El hilo de audio nunca espera. La tarjeta de sonido pide muestras cada pocos milisegundos, y una respuesta tardía es un clic. El hilo de audio nunca toma un lock, nunca reserva memoria y nunca hace una llamada al sistema; lee comandos de una cola y deja sus mensajes en otras. Ver Dos hilos.
2. La ventana es dueña del proyecto; el hilo de audio guarda su propia copia de lo justo que necesita para sonar. Los dos nunca comparten datos, así que nunca necesitan un lock.
3. Una sola manera de avisar al hilo de audio. Cada edición, y cada deshacer y rehacer, compara el proyecto antes y después y envía las diferencias. Hay un solo trozo de código que acertar, y se prueba por su cuenta. Ver Avisar al hilo de audio de lo que cambió.
4. Guardar copias, no instrucciones. Deshacer guarda copias enteras del proyecto, no una lista de cómo revertir cada edición. Una copia no puede revertirse mal. Ver Deshacer y rehacer.
5. Las cosas que se refieren unas a otras por número cambian juntas. Un clip dice «patrón 2»; si se elimina el patrón 1, el clip tiene que decir ahora «patrón 1». El proyecto es dueño de todas sus listas y solo deja que cambien a través de sus métodos. Ver El proyecto.
6. Un archivo es un contrato con el futuro. El formato de archivo tiene sus propios tipos, separados de los que usa el programa, y un número de versión que solo cambia cuando hace falta. Ver Guardar.
7. Dibujar está separado de cambiar. El código que dibuja una ventana devuelve una lista de acciones, y la aplicación las aplica en un solo lugar, con la misma función de edición. Ver Los editores.
8. La teoría musical como tipos. Las clases de alturas, las escalas, los acordes y «lo que está sonando» son tipos pequeños de Rust con métodos, probados como cualquier otro código. Ver Clases de altura, notas y su escritura.
9. Las herramientas son funciones simples. Cada herramienta de edición recibe notas y devuelve notas nuevas, sin saber nada de ventanas ni de ratones. Ver Herramientas de edición como funciones simples.
10. El conocimiento como datos. Los estilos, los ritmos y las canciones se escriben como cadenas cortas en tablas que una persona puede leer y revisar, en números romanos y pasos de un compás, de modo que la misma tabla suena en cualquier tonalidad y compás. Ver La biblioteca.
11. La banda solo escribe patrones. Probar un estilo o tocar una hoja de acordes es una edición corriente, así que deshacer, guardar y el hilo de audio funcionan sin saber que la banda existe. Ver Cómo toca la banda una hoja de acordes.
12. El mismo código, más rápido que el tiempo real. Exportar un archivo WAV, un video o una traza ejecuta exactamente el mismo código que usa la tarjeta de sonido, en un hilo propio, tan rápido como puede el equipo. Ver Exportar.

Dónde vive cada parte

Cada archivo fuente empieza con un comentario //! que dice para qué sirve; este mapa está hecho con sus primeras líneas. lineup-core:

lineup-audio: engine.rs (la tarjeta de sonido y el hilo de audio), instrument.rs, drums.rs, timbre.rs, sample.rs y soundfont.rs (los instrumentos), effects.rs y reverb.rs, levels.rs, metronome.rs, render.rs (tocar sin tarjeta de sonido) y trace.rs.

lineup-app: app.rs y los módulos de app/ (menús, archivos, edición, exportación, MIDI, ajustes), un módulo por ventana (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), y las piezas compartidas: theme.rs, widgets.rs, icons.rs e i18n.rs.

Dos hilos: la ventana y el audio

Archivos: crates/lineup-audio/src/engine.rs, crates/lineup-audio/src/dsp.rs y crates/lineup-app/src/midi.rs

La ventana y el sonido viven en hilos distintos. El hilo de la ventana dibuja unas sesenta veces por segundo y responde a clics y teclas; el hilo de audio rellena el búfer de la tarjeta de sonido cada pocos milisegundos y no debe llegar tarde nunca. Cómo se hablan los dos es la decisión más importante del programa, y es donde las reglas de propiedad de Rust empiezan a ganarse el sueldo.

  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

Cómo funciona el audio digital

El sonido es una vibración. Una tarjeta de sonido lo reproduce moviendo un altavoz según una lista de números llamados muestras, típicamente 44.100 o 48.000 por segundo (la frecuencia de muestreo). Cada muestra es un valor entre −1.0 y 1.0, la posición del altavoz en ese instante. Con dos canales (estéreo), las muestras van entrelazadas: izquierda, derecha, izquierda, derecha…

La tarjeta de sonido no nos espera. Reproduce desde un búfer pequeño y, cada pocos milisegundos, pide al programa que lo rellene llamando a una función que nosotros proporcionamos: el callback de audio. Se ejecuta en un hilo de audio separado y de alta prioridad.

La regla de oro del hilo de audio

Si el callback llega tarde, aunque sea una vez, el búfer se vacía y se oye un clic o un hueco (un underrun o xrun). Por eso el código del hilo de audio nunca debe hacer nada que pueda tardar un tiempo impredecible:

• no usar cerrojos (un Mutex retenido por la interfaz podría bloquearlo),
• no reservar ni liberar memoria (Vec::push más allá de su capacidad, String, Box::new, ni soltar el último dueño de cualquiera de ellos),
• no hacer I/O de archivos, red o consola (println! incluido),
• no esperar a otros hilos.

Todo lo demás en este capítulo se deduce de esta regla.

Enviar comandos con un ring buffer

La interfaz nunca cambia el estado del audio directamente. Envía mensajes, valores de un enum con casi cuarenta variantes. Algunas de ellas:

#![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>,
    },
    // ...
}
}

Es un enum de Rust. A diferencia de los enums de C o Java, cada variante puede llevar sus propios datos: Seek lleva un número de paso, SetNotes toda una lista de notas. Un valor de enum es exactamente una de sus variantes.

Los mensajes viajan por un ring buffer del crate rtrb: una cola de tamaño fijo, reservada una sola vez, con un escritor (el Producer) y un lector (el Consumer). Añadir y extraer nunca bloquea ni reserva memoria, así que el hilo de audio puede leerlo con seguridad.

#![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 devuelve una tupla de dos valores, que separamos con un patrón let (a, b) = .... Hay cuatro colas: los comandos de la interfaz, los valores que la interfaz debe liberar (la basura, más abajo), las teclas de un teclado MIDI (MIDI) y los mensajes para los canales de salida MIDI. En cada una, un extremo se queda en un hilo y el otro se mueve al otro.

La propiedad lo hace seguro

Aquí es donde brilla Rust. Producer se puede usar desde un hilo y Consumer desde otro, pero solo hay uno de cada, y las reglas de propiedad de Rust lo garantizan:

• Cada valor tiene exactamente un dueño. Cuando el dueño desaparece, el valor se libera (se hace drop).
• Asignar o pasar un valor lo mueve al nuevo dueño, y el nombre antiguo ya no se puede usar.

Una vez que el consumer se mueve al callback de audio, el código de la interfaz físicamente ya no puede tocarlo: el compilador lo rechazaría. Las condiciones de carrera no son «improbables»; son errores de compilación.

Comandos que llevan datos

Command no es Copy, porque un Instrument puede tener un Arc<SampleData> y SetNotes tiene un Vec. Moverlo por el ring buffer sigue estando bien: el valor se mueve a la casilla ya reservada de la cola y sale de nuevo, sin reservar memoria. El Vec de dentro se reservó en el hilo de la interfaz, antes de enviarlo.

Cuando la cola está llena

La cola guarda 4096 comandos, suficientes para un proyecto grande entero. Si alguna vez se llena, la interfaz se adelantó al hilo de audio, que la vacía al principio de cada bloque. send_wait no suelta el comando: cede y vuelve a intentarlo, hasta mil veces.

#![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 recibe el comando por valor. Cuando la cola está llena lo devuelve dentro del error, PushError::Full(returned), para que el bucle pueda intentarlo de nuevo con él: no se copia nada ni se pierde nada.

Abrir la tarjeta de sonido

AudioEngine::start usa el crate cpal, que funciona en Linux (ALSA), macOS (CoreAudio) y Windows (WASAPI), así que el mismo código funciona en los tres.

#![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 y el operador ?

Rust no tiene null ni excepciones. En su lugar:

• Option<T> es Some(value) o None. default_output_device() devuelve Option<Device> porque puede no haber tarjeta de sonido.
• Result<T, E> es Ok(value) o Err(error). default_output_config() devuelve Result<SupportedStreamConfig, cpal::Error>.

Ambos son enums normales de la librería estándar. Al ser tipos, no puedes olvidar manejar el caso que falta o falla: el compilador no te dejará usar un Device que quizá no tienes.

• .ok_or(EngineError::NoOutputDevice) convierte un Option en un Result, usando nuestro error para el caso None.
• .map_err(EngineError::Config) envuelve el error de cpal en nuestra propia variante. Observa que EngineError::Config se usa aquí como una función: las variantes de enum con datos se pueden llamar como constructores.
• ? significa «si esto es un Err, devuélvelo de la función ahora mismo; si no, dame el valor Ok». Sustituye largas cadenas de if error then return.

Un tipo de error propio

#![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 {}
}

Un enum enumera todas las formas en que puede fallar el arranque del motor. Implementar Display da a cada una un mensaje legible, y el impl std::error::Error vacío lo marca como un tipo de error en regla que funciona con el resto del ecosistema de Rust. La aplicación lo convierte en texto con err.to_string() y sigue funcionando sin sonido: todas las ventanas funcionan, y Edición > Ajustes… > Audio ofrece volver a intentarlo.

Genéricos: una función, muchos tipos de muestra

Distintas tarjetas de sonido quieren muestras en distintos formatos: floats de 32 bits, enteros de 16 bits, etc. Generamos f32 internamente y convertimos en el último momento. En lugar de escribir el código del stream seis veces, lo escribimos una vez como función genérica:

#![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 es un tipo marcador de posición, y la cláusula where enumera los trait bounds: T puede ser cualquier tipo que sea una muestra de cpal (SizedSample) y que se pueda crear a partir de un f32 (FromSample<f32>). Dentro, T::from_sample(x) hace la conversión.

Luego start elige la versión correcta con un 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 compara un valor con patrones y ejecuta la primera rama que encaja. El compilador comprueba que todos los valores posibles están cubiertos. other es un patrón comodín que además da nombre al valor.
• build_stream::<f32> (la sintaxis «turbofish» ::<>) elige T = f32. El compilador genera una copia separada y totalmente optimizada de la función para cada tipo usado. Esto se llama monomorfización, y significa que los genéricos no cuestan nada en tiempo de ejecución.
• audio_thread se mueve a la rama que se ejecute. El compilador sabe que solo una rama se ejecuta, así que esto está permitido.

El callback de audio es un closure

Dentro de 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| cuerpo es un closure: una función anónima que puede usar variables del lugar donde se escribió. La palabra clave move hace que el closure tome la propiedad de audio_thread, y con ella del consumer de comandos y de todo lo demás con lo que trabaja el hilo de audio. Eso es necesario porque el closure se ejecutará en otro hilo, mucho después de que build_stream haya devuelto, así que no puede limitarse a tomar prestadas variables locales.

La firma de cpal exige que el callback sea FnMut(&mut [T], &OutputCallbackInfo) + Send + 'static:

Si intentáramos compartir algo inseguro, como una referencia simple a los datos de la interfaz, el programa no compilaría. Así convierte Rust la regla de oro del audio en comprobaciones que el compilador hace por ti.

&mut [T] es un slice mutable: una vista prestada del búfer de la tarjeta de sonido, que rellenamos pero no poseemos.

El callback de error es el único lugar que puede tomar un cerrojo e imprimir: cpal lo llama fuera del callback de audio, cuando algo falla mientras el stream funciona, como una interfaz desenchufada. Guarda el problema más reciente para que la ventana lo muestre.

AudioThread::process

El callback de audio entrega cada búfer a un solo método. Su esquema:

#![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) = ... sigue en bucle mientras el patrón encaja, de modo que vacía todos los comandos en espera y se detiene cuando la cola está vacía.
• as_mut convierte &mut Option<Consumer> en Option<&mut Consumer>, y and_then le pide una tecla solo si hay un consumer.
• chunks_mut(channels) divide el búfer en frames, una muestra por canal de salida.
• if a && let Some(x) = b { ... } es una let chain: una condición y un patrón combinados en un solo if.

El estado del hilo de audio vive en una struct, AudioThread, en lugar de en variables sueltas dentro del closure. Así las pruebas pueden ejecutarlo con un Vec simple en lugar de una tarjeta de sonido, y el renderizador puede tocar una canción a un archivo con el mismo código.

Mezclar un frame

En cada frame, el instrumento de cada canal hace una muestra. La muestra pasa por los efectos y el volumen del canal, y luego va a los lados izquierdo y derecho según su balance, y a la reverberación tanto como dice su envío (El mezclador):

#![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 itera sobre referencias mutables, para que cada instrumento pueda avanzar su propio estado.
• Mezclar es simplemente sumar: los sonidos en el aire se suman, y las muestras también.
• Varios tambores fuertes a la vez pueden sumar más de 1.0, y una tarjeta de sonido lo recortaría con dureza. tanh (la tangente hiperbólica) deja pasar los valores pequeños casi sin cambios y dobla los grandes suavemente hacia ±1.0, un soft clipper (recortador suave).
• volume.next_value() es un valor Smoothed. Un volumen que salta hace saltar el altavoz, y eso se oye como un clic, así que en cambio se desliza hacia su objetivo: en cada muestra recorre una pequeña fracción de la distancia que queda. Es un suavizador de un polo, que se asienta en pocos milisegundos, demasiado rápido para oírse como un fundido pero suficiente para quitar el clic.

Espacio reservado de antemano

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

Un Vec tiene una longitud (cuántos elementos tiene) y una capacidad (cuántos caben en la memoria que tiene). push solo reserva memoria cuando la longitud superaría la capacidad. Reservar espacio para MAX_CHANNELS al arrancar, en el hilo de la interfaz, significa que push en el hilo de audio nunca reserva memoria. La interfaz se niega a añadir más canales que esos, así que el límite no se alcanza nunca. La lista de notas que esperan para empezar tarde, las longitudes de los patrones y el backlog de la basura se reservan del mismo modo.

Vec::remove(index) desplaza hacia abajo los elementos siguientes, lo que tampoco reserva memoria. Así es como RemoveChannel mantiene los números de canal del hilo de audio iguales a los de la lista de la interfaz.

Liberar memoria en otro sitio: la cola de basura

Cuando se elimina un canal o se sustituyen sus notas, el valor viejo puede tener el último Arc de una muestra, o un Vec de notas. Liberarlo soltaría esa memoria, y liberar puede tomar un cerrojo dentro del asignador de memoria. Así que el hilo de audio no lo libera. Lo devuelve:

#![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) pone new en place y devuelve lo que había. Es la forma de sacar un valor de un campo de un struct del que solo tienes un &mut, ya que Rust nunca deja un campo vacío. (silence envía los note-offs que el instrumento viejo todavía le debe a un sintetizador de salida MIDI.)

throw_away empuja el valor a un segundo ring buffer, que va en la dirección contraria. Garbage es un enum con una variante para cada clase de cosa que devuelve el hilo de audio: instrumentos, listas de notas, canales, canciones, listas de tempo, frases, líneas de retardo. El hilo de la interfaz vacía la cola una vez por 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) es una función normal del preludio que toma la propiedad y deja que el valor salga de ámbito. Escribirla explícitamente documenta la intención: aquí es donde se libera la memoria.

Una ráfaga de cambios entre dos frames podría llenar la cola de basura. Entonces throw_away guarda el valor en un backlog reservado de antemano, y flush_trash lo pasa a la cola al principio del bloque siguiente. Solo si también se llena el backlog, lo que significa que la interfaz lleva mucho tiempo sin recoger, el valor se libera en el hilo de audio, como último recurso.

El cursor de reproducción: un entero atómico

La interfaz quiere resaltar el paso que se está reproduciendo. El hilo de audio lo sabe. Compartirlo con un Mutex significaría que el hilo de audio podría esperar por el cerrojo, así que usamos un atómico:

#![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) }
}

Un AtomicUsize es un número que el procesador puede leer y escribir en una sola operación indivisible, de modo que dos hilos pueden usarlo sin cerrojo y sin ver nunca un valor a medio escribir. Ambos hilos tienen un Arc al mismo (Arc::clone(&playhead) crea el segundo puntero).

Ordering::Relaxed dice que solo nos importa este valor, no el orden de otras escrituras de memoria a su alrededor. Es el orden más barato y basta para mostrarlo. Los órdenes más estrictos (Acquire, Release, SeqCst) son para cuando un valor protege el acceso a otros.

Rust no tiene un paso «nulo», así que usize::MAX representa «parado», y playhead() lo convierte enseguida en un Option<usize> honesto para que ningún otro código vea nunca el número mágico.

La posición con fracción de paso, que necesitan la grabación y las vistas, es un f64, y no hay float atómico. Así que se guarda como los bits del f64 en un AtomicU64: position.to_bits() en el hilo de audio, f64::from_bits(bits) del otro lado. Dos números que siempre deben leerse juntos, como el patrón que suena sobre la canción y su paso, comparten un AtomicU64: uno en los 32 bits altos, el otro en los bajos.

Mantener vivo el stream: 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>,
    ...
}
}

El cpal::Stream no se vuelve a usar después de arrancar, pero hay que conservarlo: cuando un valor se libera, Rust ejecuta su código de limpieza (su implementación de Drop), y liberar un Stream cierra la tarjeta de sonido. Guardarlo en el motor ata la vida del sonido a la del motor. El guion bajo inicial le dice al compilador «sé que este campo no se lee nunca».

Este patrón, en el que poseer un valor significa poseer un recurso y liberarlo lo suelta, se llama RAII. Rust lo usa en todas partes: los archivos se cierran, los cerrojos se desbloquean y la memoria se libera sola cuando su dueño desaparece.

Cuando la tarjeta de sonido desaparece

Una interfaz desenchufada, un cambio de dispositivo predeterminado o un servidor de sonido que se reinició hacen que el stream informe de un error. Edición > Ajustes… > Audio ofrece entonces Reintentar (y Reiniciar audio mientras el stream funciona), que vuelve a abrir el dispositivo de salida predeterminado del sistema. El proyecto se queda: se envía entero al hilo de audio nuevo, los puertos MIDI se vuelven a conectar al motor nuevo, y una canción que estaba sonando vuelve a la misma posición y sigue.

El motor viejo se suelta antes de que arranque el nuevo, porque un dispositivo que se vuelve a abrir no puede seguir retenido por el stream muerto.

Dos cosas necesitan cuidado cuando se va un hilo de audio:

Notas que suenan en un sintetizador externo. Una nota enviada por salida MIDI recibe su note-off del hilo de audio que la tocó; cuando ese hilo ya no está, se van con él los note-offs que todavía debía. Los mensajes salen por un hilo pequeño, midi-out, que vacía la cola del hilo de audio cada milisegundo. Cuando su cola queda abandonada, su bucle termina, y antes de acabar envía All Notes Off (controlador 123) en los dieciséis canales:

#![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));
        }
    }
};
}

El hilo de envío del motor nuevo no debe arrancar antes de que el viejo haya enviado su All Notes Off, o ese mensaje podría cortar las primeras notas del motor nuevo. Así que reconnect_audio espera al hilo viejo, consultando JoinHandle::is_finished como mucho 100 ms (en la práctica cerca de un milisegundo, porque el motor viejo ya no está). No llama a join(), que podría esperar para siempre a un puerto MIDI colgado: la ventana nunca debe congelarse por un puerto.

Mensajes que deben llegar. Un note-off perdido deja una nota sonando para siempre en un sintetizador externo, así que la salida MIDI nunca pierde ninguno. Los mensajes que encuentran la cola de salida llena esperan en un backlog reservado y salen al principio del bloque siguiente. Quitar un canal o sustituir un instrumento envía sus note-offs por el mismo camino, y desconectar un puerto envía All Notes Off en los dieciséis canales antes de que se cierre la conexión.

La traza de reproducción es el caso contrario: graba cada nota para un informe, no para el sonido, así que si su cola se llena, el hilo de audio cuenta los eventos perdidos y sigue. Esperar ahí pondría la traza antes que la música. Cuando el audio se reinicia, la traza sigue en el mismo archivo: se escribe lo que dejó el hilo viejo, y se envía una cola nueva al hilo nuevo.

Probar sin tarjeta de sonido

Las pruebas al final de engine.rs construyen un AudioThread con ring buffers, empujan comandos, renderizan en un Vec<f32> y comprueban el resultado: un golpe en el frame 0 y otro 6000 frames después a 120 BPM, silencio al silenciar, ediciones que surten efecto durante la reproducción e instrumentos viejos que llegan a la basura. Una pequeña struct Harness guarda las piezas para que cada prueba sea corta.

El proyecto: patrones, canales, pistas, clips y marcas

Archivos: crates/lineup-core/src/pattern.rs, crates/lineup-core/src/project.rs, crates/lineup-core/src/playlist.rs y crates/lineup-core/src/arrangement.rs

Todo aquello con lo que trabaja el usuario es un solo valor de tipo Project: los canales del rack de canales, los patrones de notas que tocan, la lista de reproducción que ordena los patrones en una canción, y las marcas a lo largo de ella (secciones, tempo, compás, tonalidad y acordes). Es también exactamente lo que guarda un archivo de proyecto. Este capítulo trata de su forma y de las reglas que mantiene. Las ventanas que lo editan están en Los editores; cómo usarlas está en el capítulo Patrones y la lista de reproducción del manual de usuario.

Notas, pasos y patrones

Un patrón es un tramo corto de música, a menudo un compás, con una fila de notas para cada canal. Una nota es una altura, un comienzo, una duración y una velocidad, todo contado en pasos (una semicorchea cada uno en 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,
}
}

Los botones de paso del rack de canales y el piano roll editan las mismas notas. Un paso «encendido» no es más que una nota de un paso de largo en la altura por defecto, así que is_on pregunta si alguna nota empieza ahí:

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

Una sola clase de datos con dos vistas es como funcionan los estudios basados en patrones, y significa que el hilo de audio tiene una sola clase de cosa que tocar. nudge y trim colocan una nota entre pasos, para música tocada por una persona o importada de un archivo MIDI; las notas en la cuadrícula los dejan en 0.

Canales: enums con datos

#![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 },
}
}

Un canal tiene un nombre, un volumen, un interruptor de silencio, un número de instrumento General MIDI y un tipo. Los enums se anidan: un canal es un sampler, el Lineup Osc o un canal de salida MIDI, y el sonido de un sampler es o un tambor incorporado o un archivo. Cada hecho se guarda una vez y toda combinación tiene sentido. MidiOut { channel: u8 } muestra que una variante también puede tener campos con nombre, como un struct.

PathBuf es el tipo estándar para una ruta de archivo poseída. No es un String, porque los nombres de archivo en algunos sistemas no son texto UTF-8 válido; path.display() convierte uno en algo imprimible.

Drum::ALL es una constante asociada que contiene todas las variantes, para que los menús puedan iterar sobre los tambores en lugar de enumerarlos a mano.

La forma de un proyecto

Un proyecto tiene una lista de patrones, y una lista de reproducción que dice dónde suena cada uno:

#![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
}
}

Cada patrón tiene una fila de notas por canal. Los estudios basados en patrones funcionan así: un patrón es «lo que toca cada instrumento durante estos compases», así que el patrón de batería tiene filas vacías para el sintetizador.

La lista de reproducción son dos listas:

#![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
}
}

Un clip son tres números y un contador de repeticiones: qué patrón, en qué pista, empezando en qué paso de la canción y cuántas veces suena el patrón. Fíjate en lo que no está: la duración del clip. Es la duración del patrón por el número de repeticiones, así que se calcula cuando hace falta:

#![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 }
    }
}
}

Guardar también la duración supondría dos sitios que deben coincidir. Haz el patrón más largo y la duración guardada de cada clip quedaría mal. Un valor que se puede calcular a partir de otros casi siempre es mejor calcularlo que guardarlo. Lo mismo vale para el final de un clip repetido: es start + clip_length, no otro campo.

Project::playback_arrangement desenrolla las repeticiones en Plays antes de que la canción llegue al hilo de audio (ver Secciones, repeticiones y bucles más abajo); el clip es lo que dibujas, y su repeats es el pequeño «×2» que lleva encima.

map_or(0, Pattern::length) dice «si hay un patrón, llama a Pattern::length sobre él; si no, usa 0». Un método se puede pasar por nombre, como una función, cuando su único argumento es self.

Cuatro reglas, un guardián

El comentario de Project enumera las reglas que mantiene:

• cada clip de la lista de reproducción se refiere a un patrón y a una pista que existen;
• las secciones están ordenadas y nunca se solapan, y las repeticiones no se salen de rango.

La mayoría de estas reglas tratan de dos listas a la vez, así que ninguna lista puede mantenerlas por sí sola. El Project las posee todas, mantiene los campos privados para lineup-core y los cambia solo en métodos que respetan todas las reglas. Añadir un canal añade una fila a cada patrón:

#![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)
}
}

Borrar un patrón es lo interesante. Los clips se refieren a los patrones por su posición en la lista, así que cuando el patrón 1 desaparece, los clips del patrón 1 deben desaparecer también, y los clips de los patrones 2, 3, 4… deben bajar uno cada uno para que sigan reproduciendo la misma música:

#![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 conserva los elementos para los que el closure devuelve true y descarta los demás, en una sola pasada.
• for clip in &mut self.playlist.clips da una referencia mutable a cada clip por turno, así que clip.pattern -= 1 cambia el clip de la lista.
• El método devuelve el patrón borrado, envuelto en Some. Quien lo llama puede ignorarlo, guardarlo, o comprobar que la eliminación llegó a ocurrir.

La prueba removing_a_pattern_renumbers_its_followers comprueba toda la historia: tras borrar «Ritmo», los cinco clips de Ritmo desaparecen, «Acordes» es el patrón 0, y el fill sigue sonando en el compás 8.

¿Por qué usar posiciones, en lugar de dar a cada patrón un id permanente? Los ids harían más simple la eliminación (nada que renumerar) pero todo lo demás más difícil: cada búsqueda tendría que buscar un id en lugar de indexar un Vec. Para una lista de como máximo 999 patrones (normalmente muchos menos), las posiciones más un método cuidadoso son la opción más simple. Es el tipo de intercambio sin una única respuesta correcta; uno de los ejercicios de esta parte te pide que pienses en ello.

Repartir &mut Pattern con seguridad

La app necesita cambiar notas de un patrón. Project podría copiar cada método de Pattern (toggle, add_note, replace_note…) como método propio. En su lugar reparte el patrón mismo:

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

¿Es eso seguro? Con un &mut Pattern, ¿podría la app añadir una fila y romper la regla de «una fila por canal»? No, por cómo están declarados los métodos de filas en pattern.rs:

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

pub(crate) significa «público solo dentro de este crate». project.rs puede llamarlos, porque está en lineup-core; lineup-app no puede, ni siquiera con un &mut Pattern en las manos. Cada método que lineup-app sí puede llamar mantiene el número de filas tal como está. La privacidad en Rust va de módulos y crates, no de quién tiene una referencia, y eso permite a un tipo dar una referencia a otro sin regalar sus reglas.

En el lado de la app, cada edición de un patrón pasa por un pequeño ayudante:

#![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) acepta cualquier closure que reciba un patrón. FnOnce es el más permisivo de los tres traits de closures: el closure solo tiene que poder llamarse una vez, así que puede incluso mover valores que capturó.
• self.edit(label, ...) es la única función por la que pasa cada cambio del proyecto. Guarda el cambio para deshacerlo y le dice al hilo de audio qué cambió (Deshacer y rehacer, Avisar al hilo de audio de lo que cambió). label es lo que dirá Edición > Deshacer.

Nombres, e impl Into<String>

Los patrones tienen nombre. El constructor recibe el nombre primero:

#![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> acepta cualquier cosa que se pueda convertir en un String: Pattern::new("Beat", 5, 16) con un &str, o Pattern::new(format!("Pattern {n}"), 5, 16) con un String, sin que quien llama escriba .to_string(). Dentro, name.into() hace la conversión (para un String, simplemente lo mueve).

name es un campo público mientras que length y rows son privados. Mezclar está bien en Rust: name no tiene ninguna regla que mantener, así que no hay razón para esconderlo detrás de métodos. color, time y player dicen de qué color se dibuja el patrón, en qué compás se escribió, y cuál de los músicos de la banda lo escribió, si lo escribió alguno.

Clonar un patrón usa el derive Clone de Pattern:

#![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() copia el patrón entero, cada fila y cada nota, así que la copia y el original nunca comparten nada; la prueba cloned_patterns_are_independent comprueba que cambiar uno deja al otro en paz. El ? después de get(index) devuelve None de la función inmediatamente si no existe tal patrón.

Nunca dos notas en el mismo lugar

add_note se niega a añadir una nota en el mismo lugar que otra. replace_note, usado al arrastrar, también debe negarse, o una nota podría arrastrarse exactamente encima de otra, así que comprueba cada nota excepto la que se está reemplazando:

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

Así que «no hay dos notas de la misma altura que empiecen en el mismo momento» es cierto para cada patrón, y cargar un archivo puede insistir en ello. same_place compara la altura, el paso y el nudge, así que dos notas que empiezan a unos pocos ticks de distancia siguen siendo dos notas.

¿Cuánto dura la canción?

La canción termina donde termina su último clip, redondeado hacia arriba a un compás entero:

#![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 devuelve un Option, porque una lista vacía no tiene máximo; unwrap_or(0) convierte «no hay clips» en una duración de 0. chain une los dos iteradores, porque una canción puede terminar con un clip o con una sección que no tiene ningún clip justo al final. self.meter() conoce el compás, y su round_up_to_bar es una división que redondea hacia arriba: en 4/4, 17 pasos son 17.div_ceil(16) = 2 compases.

¿Dónde está un patrón mientras suena la canción?

En modo canción, el hilo de audio informa de un paso de la canción. El rack de canales y el piano roll muestran un patrón, así que necesitan saber qué paso de ese patrón está sonando, si es que hay alguno:

#![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)
}
}

Léelo como una frase: de los clips que se pueden oír, toma los de este patrón, encuentra el primero que cubra este paso de la canción y dime cuánto se adentra en el clip ese paso. El % pattern_length es lo que hace que un clip repetido vuelva a empezar su patrón en cada vuelta: un clip de 16 pasos que se repite en el paso 16 de la canción está allí en el paso 0 del patrón. audible_clips se salta los clips de pistas silenciadas:

#![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() convierte un iterador de &Clip en uno de Clip. Funciona porque Clip es Copy (tres números), y significa que quien llama recibe valores simples en lugar de referencias a la lista de reproducción.

La canción de partida

Project::demo construye una canción de ocho compases, que tocan muchas pruebas, con los mismos métodos que usa la app:

#![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 es un rango de 2 hasta, pero sin incluir, el 7: compases 3 a 7 contando desde 1, como hace la regla. El fill ocupa el lugar del beat en el compás 8. Archivo > Nuevo ritmo empieza en cambio desde Project::template: la batería y un Lineup Osc, sin notas y con una pista. Archivo > Nuevo empieza desde Project::with_band, una hoja de acordes vacía con una banda (Cómo toca la banda una hoja de acordes).

Secciones, repeticiones y bucles

Una canción tiene más forma que sus clips: una introducción, una estrofa, un estribillo que se oye dos veces, un ritmo que se repite durante ocho compases. La lista de reproducción guarda tres cosas más para eso:

• Secciones: tramos con nombre de la canción (Introducción, Estrofa, Estribillo…) en una franja sobre los números de compás. Una sección se puede tocar varias veces seguidas: se dibuja una vez y se marca «×2».
• Repeticiones de clip: un clip puede tocar su patrón una y otra vez, como al estirar un clip de patrón en otros estudios basados en patrones.
• Una región de bucle: el modo canción puede repetir solo una parte de la canción.

Las secciones no son dueñas de clips. Una sección es solo un nombre y un rango de pasos: los clips que quedan debajo forman parte de ella. Eliminar una sección deja los clips como están.

Dos tipos de paso

Aquí está la única idea que hace sencillo todo lo demás. Una vez que una sección puede repetirse, la lista de reproducción tal como se dibuja y la canción tal como se toca ya no miden lo mismo:

timeline:   | Intro | Chorus ×2 | Outro |
canción:    | Intro | Chorus | Chorus | Outro |

Así que el código habla de dos tipos de paso:

• un paso de timeline es un lugar de la lista de reproducción, tal como se dibuja;
• un paso de canción es un momento de la canción, tal como se oye.

Project::song_length es la longitud del timeline. Arrangement es la canción tal como se oye:

#![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
}
}

Un Pass dice «los pasos de timeline 32 a 63 suenan en los pasos de canción 64 a 95, y esta es la ronda 2 de 2 de la sección 1». Un Play dice «toca el patrón 3 desde el paso de canción 64 durante 32 pasos, empezando 0 pasos dentro de él». El patrón se repite en bucle mientras dura el Play, así que un clip repetido tres veces es un Play de tres patrones de largo. skip no es cero cuando una sección o la región de bucle empieza a mitad de un clip.

Project::arrangement() lo construye para la canción entera (las exportaciones lo usan), y Project::playback_arrangement() para lo que toca el modo canción: la región de bucle si la hay, la canción entera si no.

Construir el arreglo

arrange en arrangement.rs corta el timeline en trozos en los bordes de las secciones. Las secciones suenan repeats veces; los huecos entre ellas suenan una vez:

#![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
}
}

Esto solo funciona porque las secciones se mantienen ordenadas y sin solaparse nunca. Eso es una regla, así que, como con los clips, la lista es privada y solo los métodos de Project la cambian. add_section y set_section comprueban la regla y rechazan una sección que la rompería; insert_section mantiene el orden con partition_point, una búsqueda binaria que devuelve el primer lugar donde la condición deja de ser cierta:

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

Luego, para cada trozo y cada pasada, todo clip que se solape con el trozo añade un Play para la parte de él que está dentro del trozo. max y min encajan el clip en el trozo:

#![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,
    });
}
}

El hilo de audio no sabe nada de secciones

Command::SetSong lleva los plays del arreglo, y lo único que hace el hilo de audio con ellos es un resto:

#![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)
}
}

% envuelve el paso alrededor del patrón, que es todo lo que significa «repetir». Todo lo de nombres, rondas y bucles se queda en lineup-core, donde puede probarse sin tarjeta de sonido. El hilo de audio sigue siendo pequeño, y no reserva memoria: el Vec<Play> se construye en el hilo de la UI, y el viejo se devuelve para liberarlo allí.

La exportación a WAV y la exportación a MIDI usan el mismo Arrangement, así que las tres coinciden en qué es la canción. El escritor de MIDI necesita la pregunta contraria: ¿en qué pasos de canción suena una nota del paso de patrón 2? Eso es Play::song_steps_of, que usa un iterador con step_by:

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

De vuelta de la canción a la lista de reproducción

El hilo de audio cuenta pasos de canción, así que el cabezal de reproducción que comunica es un paso de canción. Para dibujarlo, la app lo convierte de nuevo en un paso de timeline con los passes del arreglo:

#![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))
}
}

El Pass viaja con él hasta la lista de reproducción, que es como una sección sabe que debe mostrar «▶ 2 de 2». El rack de canales, el piano roll y las teclas de armonía reciben el paso de timeline, así que muestran el paso correcto del clip correcto también durante una repetición.

Guardar: formato 4

Clip y Section tienen las dos un campo repeats, y la mayoría de las veces es 1. serde puede dejar un campo fuera del archivo cuando tiene su valor habitual, y volver a rellenarlo al leer un archivo que no lo tiene:

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

default nombra una función que devuelve el valor que usar, y skip_serializing_if una función que dice cuándo dejar el campo fuera. Las listas del archivo (sections, loop_region) usan el #[serde(default)] normal con Vec::is_empty y Option::is_none. Así que un proyecto que no usa nada de esto se escribe byte a byte como antes, y un Ferrous Lineup más antiguo lo abre.

Una versión más antigua también abriría un proyecto que sí usa repeticiones: se salta los campos que no conoce. Pero tocaría cada repetición una vez, que es una canción que suena mal sin una palabra de aviso. Así que format_for devuelve 4 para cualquier proyecto con secciones, una región de bucle o un clip repetido, y las versiones antiguas lo rechazan con un mensaje claro (Guardar).

Dibujarlo: un módulo dentro de un módulo

Las franjas se dibujan en un archivo propio. Un módulo de archivo puede tener hijos: mod sections; dentro de playlist.rs carga playlist/sections.rs. Un módulo hijo puede ver los elementos privados de su padre, así que sections.rs usa Layout, Snap y PlaylistAction de playlist.rs con use super::{Layout, PlaylistAction, Snap}; sin hacerlos públicos para el resto de la app.

Cada sección es su propia zona clicable, hecha con ui.interact sobre un rectángulo que elegimos nosotros, que devuelve un Response como cualquier widget:

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

El id debe ser distinto para cada sección y el mismo de un frame a otro, así que se construye a partir del número de la sección. El menú es un egui::Popup atado a esa respuesta, que se abre con un clic y solo se cierra con un clic fuera, porque contiene un campo de texto en el que escribes.

Arrastrar una sección no cambia el proyecto en cada frame, como hace arrastrar un clip. Solo se dibuja un contorno, y el proyecto cambia una vez, cuando el botón sube. Una sección se mueve dentro de una lista ordenada: si el movimiento de un frame la saltara por encima de una vecina, su número cambiaría a mitad del arrastre, y el siguiente frame movería la sección equivocada.

Escribir las repeticiones

Escribir las repeticiones en el menú de una sección convierte «Estribillo ×3» en Estribillo, Estribillo 2 y Estribillo 3, uno detrás de otro, cada uno tocado una vez, para que puedas cambiar el tercer estribillo sin cambiar los otros. La canción suena igual antes y después; una prueba lo comprueba comparando los dos arreglos.

Comparte su código con Duplicar: make_room mueve todo lo que hay después de la sección más tarde, y luego los clips que empiezan dentro de la sección se copian en el hueco. Una cosa que hay que vigilar: los clips se copian enteros. El relleno de la imagen empieza dentro del estribillo y sigue más allá de su final, así que el original y su copia se solapan. Ferrous Lineup no puede cortar un clip en dos (un clip no tiene «empieza a esta distancia dentro del patrón»); uno de los ejercicios de esta parte lo añade.

Decirle al hilo de audio lo que ha cambiado

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

Una sola entrada para cada cambio

El hilo de audio guarda su propia copia de todo lo que reproduce: el instrumento, el volumen, el paneo y las notas de cada canal, las longitudes de los patrones, la canción (ver Dos hilos). La ventana debe mantener esa copia al día, y un cambio puede tocar cualquier cosa. Un clic en un paso cambia una lista de notas. Borrar un patrón renumera todos los clips que vienen después. Escribir un acorde hace que la banda escriba patrones nuevos. Deshacer sustituye todo el proyecto por uno más antiguo, que puede diferir en cualquier cosa.

Hay tres formas de contarle un cambio al hilo de audio:

1. Enviar el proyecto entero otra vez: todos los patrones y canales, como al abrir un archivo. Sencillo, pero cada instrumento se construiría de nuevo, cortando toda nota que esté sonando, y un archivo de muestra se leería otra vez por un deshacer de un solo paso.
2. Escribir, para cada tipo de edición, los comandos que necesita, y para deshacer, los comandos que la invierten. Es un par escrito a mano para cada edición, y cada par es una ocasión de equivocarse al invertir (el capítulo siguiente cuenta más sobre esta elección).
3. Comparar el proyecto antes y después, y enviar solo lo que difiere.

Ferrous Lineup hace lo tercero, para todos los cambios, no solo para deshacer. Ninguna edición envía sus propios comandos. Todo cambio pasa por un único método, 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
}
}

Lee primero la segunda mitad, el caso normal. edit guarda una copia del proyecto, deja que el closure lo cambie y, si algo cambió, hace cuatro cosas en un solo sitio:

• sync_audio(&before) le dice al hilo de audio qué difiere. El resto de este capítulo trata de eso.
• follow_chord_sheet deja que la banda vuelva a escribir sus patrones si cambiaron la hoja de acordes, la tonalidad o los compases, como parte del mismo paso (ver Cómo toca la banda una hoja de acordes).
• file y recovery se enteran de que el proyecto cambió: la barra de título recibe su asterisco de cambios sin guardar, y se escribirá una copia de recuperación (ver Guardar). project_reverted vuelve a calcular el asterisco desde cero, porque un cambio hecho de una vez puede dejar exactamente lo que estaba guardado, como un paso que se activa y se vuelve a desactivar.
• history.record guarda before como el paso de deshacer llamado label (ver Deshacer y rehacer).

Tener un único camino compensa dos veces. Solo hay un fragmento de código que convierte cambios del proyecto en comandos, así que se puede probar a fondo por separado. Y se usa en cada clic, así que si tuviera un error lo oirías mientras editas, no solo en el raro momento en que deshaces algo inusual.

Un arrastre es un paso, no uno por fotograma

La primera mitad, la rama is_open, es el detalle de rendimiento importante. Un arrastre cambia notas en cada fotograma, sesenta veces por segundo, pero solo su primer fotograma necesita la copia para deshacer y la comparación completa. Mientras el paso está abierto, el proyecto se cambia directamente, y synced guarda el último estado que recibió el hilo de audio. sync_step_if_due compara el proyecto con ese estado y envía las diferencias como mucho cada 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 saca el synced antiguo de la estructura y deja un proyecto vacío en su lugar, así que sync_audio puede tomarlo prestado como before sin copiarlo (no podría tomar prestado self.synced mientras también toma prestado self de forma mutable). Cuando un patrón o un canal aparece o desaparece en mitad de un paso, esperar no basta: las vistas cuentan filas que el hilo de audio aún no tiene, así que sync_step se ejecuta enseguida.

Al soltar el ratón, finish_step_sync envía los últimos cambios que faltan, y el paso se cierra. Un arrastre es un paso de deshacer, una copia y un puñado de mensajes.

Deshacer y rehacer sustituyen el proyecto entero, así que siempre hacen la comparación completa:

#![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);
    }
}
}

Las dos últimas líneas son para la ventana, no para el sonido: la biblioteca muestra el estilo y el ritmo que toca esta versión del proyecto, y si deshacer cambió el compás, la reproducción sigue en el mismo compás de la canción.

Leer edit

edit recibe un closure que cambia el proyecto, y el closure recibe el proyecto como argumento:

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

¿Por qué no dejar que el closure alcance self.project por sí mismo? Porque edit ya tiene &mut self, y un closure que tomara prestado self también sería un segundo préstamo del mismo valor mientras el primero sigue en uso. El borrow checker lo rechaza. Entregarle al closure &mut self.project como argumento le presta exactamente la parte que necesita, durante exactamente lo que dura la llamada.

El tipo del closure es impl FnOnce(&mut Project) -> R. FnOnce es el trait de los closures que se llaman exactamente una vez: deja que el closure mueva un valor al proyecto, como un channel nuevo, porque nadie lo llamará una segunda vez. (Los closures Fn se pueden llamar muchas veces y solo leen lo que capturan; los FnMut pueden cambiarlo.)

R es lo que devuelva el closure, y edit se lo devuelve a quien lo llama. Muchos métodos de Project devuelven algo: add_clip devuelve el índice del clip nuevo como Option<usize>, remove_pattern el patrón que quitó, insert_bars si había sitio. Como R puede ser cualquier tipo, un closure puede ser simplemente la llamada al método, |project| project.add_clip(clip), y quien llama recibe la respuesta. Si edit pidiera impl FnOnce(&mut Project), que debe devolver (), cada una de esas necesitaría llaves y un punto y coma para tirar el valor.

edit_pattern es un pequeño envoltorio para el caso más común, un cambio en el patrón seleccionado:

#![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 compara los dos proyectos por completo: el PartialEq derivado compara cada campo, cada lista, cada nota. Si nada cambió, como un clip arrastrado de vuelta a la misma casilla o una nota borrada donde no había ninguna, no se envía nada y no se registra ningún paso de deshacer.

diff: la lista de cambios

La comparación vive en lineup-core, que conoce los proyectos pero nada del hilo de audio. Describe las diferencias con las propias palabras del proyecto:

#![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>
}

Los cambios son pasos que hay que seguir en orden, y cada número es una posición en el momento en que se aplica su cambio. Después de RemovePattern(0), el patrón que solía ser el número 1 es el número 0, y cualquier cambio posterior lo llama 0. Los valores (un volumen, una lista de notas) no están en el Change: se leen del proyecto más nuevo cuando el cambio se convierte en un comando. Eso mantiene Change pequeño y Copy.

Solo se compara lo que produce sonido. Los nombres de patrón, de canal, de pista y de sección y la tonalidad no dan ningún cambio, porque el hilo de audio nunca los ve. Silenciar una pista sí da uno: saca los clips de esa pista de la canción, así que los clips que reproduce el hilo de audio cambian.

El mezclador también se oye. Mover un canal entre los altavoces da Pan, cambiar cuánto va de él a la reverberación da ReverbSend, cambiar su ecualizador, su compresor o su delay da Effects, y cambiar el volumen maestro o la propia reverberación da Mixer. Poner un canal en Solo es un cambio de mezclador y cambia qué canales se oyen, así que diff también informa de Muted para cada canal cuyo silencio efectivo cambió. La Soltura da LooseTiming: decide cuánto puede alejarse de la cuadrícula el comienzo de una nota.

Alinear dos listas

La parte difícil son las listas. Digamos que los patrones eran [Beat, Chords, Fill] y ahora son [Beat, Fill]. Comparar elemento a elemento diría que el patrón 1 cambió de Chords a Fill y que el patrón 2 desapareció, lo cual es cierto pero torpe: enviaría otra vez todas las notas de Fill. Lo que pasó de verdad es que «se quitó el patrón 1».

Alignment lo encuentra. Cuenta cuántos elementos son iguales al principio de ambas listas, y cuántos al final. Lo que queda en medio se quitó de la lista antigua y se insertó en la nueva:

  antes:    Beat │ Chords │ Fill       start = 1 (Beat es el mismo)
  después:  Beat │        │ Fill       end   = 1 (Fill es el mismo)
                                       eliminados = 3 - 1 - 1 = 1
                                       insertados = 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,
    }
}
}

La cadena de iteradores se lee bien cuando conoces las piezas: zip recorre dos listas lado a lado, dando pares; take_while conserva pares mientras son iguales y se detiene en el primero que no lo es; count dice cuántos se conservaron. rev recorre las listas hacia atrás, para el final.

.min(room) es fácil de pasar por alto e importante. Con [A, A] convirtiéndose en [A], el principio encuentra un elemento igual, y el final también, el mismo A. Las dos cuentas juntas dirían que se conservan dos elementos de una lista de uno, y after.len() - start - end sería 1 - 1 - 1, que para un usize no es -1 sino un panic («attempt to subtract with overflow»). Limitar el final a lo que queda después del principio mantiene honesta la aritmética.

Cuando ambas listas miden lo mismo, no se añadió ni se quitó nada, así que los elementos se comparan posición por posición. Eso cubre las ediciones más comunes: un clic en un paso cambia un patrón, en su sitio.

Alignment funciona para cualquier T, porque quien llama dice qué significa «el mismo» con el closure same. Para los canales es la igualdad completa: |old, new| old == new. Para los patrones no lo es, y esa es la parte sutil. Las filas de un patrón cambian cuando los canales van y vienen: cuando entra la banda, cada patrón recibe una fila para cada uno de sus canales, así que comparar patrones enteros diría que todos los patrones cambiaron. El alineado enviaría entonces otra vez las notas de cada patrón, y la aplicación seleccionaría un patrón que solo parece nuevo.

Así que los patrones se alinean por las cosas que los identifican, no por su contenido:

#![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
}
}

Las notas y la longitud son lo que el alineador deja cambiar en su sitio. El nombre, el color y el intérprete (player) dicen qué patrón es; las notas que difieren se envían después como cambios Notes y PatternLength de todos modos.

Punteros fn: las variantes de un enum son funciones

Una vez alineadas las dos listas, los cambios son: quitar el medio de la lista antigua y luego insertar el medio de la nueva.

#![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)
}
}

y se llama así:

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

Change::RemovePattern no es aquí un valor, es una función. Toda variante de un enum que guarda datos entre paréntesis es también una función que la construye: Change::RemovePattern tiene el tipo fn(usize) -> Change. El fn(usize) -> Change en minúscula es un tipo de puntero a función: la dirección de una función normal, sin variables capturadas. Un closure que no captura nada también puede serlo. map(remove) lo llama para cada número, construyendo RemovePattern(2), RemovePattern(1) y así sucesivamente.

Las eliminaciones van desde el último hacia atrás. Quitar primero el patrón 2 deja los patrones 0 y 1 donde estaban, así que RemovePattern(1) sigue significando el patrón correcto. Hacia delante, quitar primero el patrón 1 bajaría el patrón 2 al 1, y la segunda eliminación daría con el equivocado. Las inserciones van hacia delante por la misma razón: una vez llena la posición 1, la posición 2 está justo después.

chain une dos iteradores en uno: primero todos los de removals, luego todos los de insertions. La función devuelve impl Iterator<Item = Change>, «algún iterador de cambios», sin nombrar su largo tipo real (Chain<Map<Rev<Range<usize>>, fn(usize) -> Change>, ...>).

El orden de todo

#![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();
    ...
}

Primero los patrones, luego los canales, y luego todo lo que hay dentro. El orden importa por lo que hace el hilo de audio con cada cambio:

• Un patrón insertado llega al hilo de audio sin notas en ningún canal; sus notas vienen después como cambios Notes.
• Un canal insertado llega completo: su instrumento, su volumen y sus notas en cada patrón. Así que los patrones ya deben estar correctos cuando llegue, o traería notas para un número equivocado de patrones.

Luego, para cada canal que ya existía (old_index dice dónde estaba, o None si es nuevo), se comparan el instrumento y la mezcla:

#![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));
    }
}
}

El instrumento se construye a partir de tres campos: el tipo (batería, archivo de muestra, Lineup Osc, MIDI Out), el programa General MIDI y sent_on, el puerto MIDI al que se envía una batería en lugar de sonar aquí. channel_muted no es simplemente el botón de silencio del canal: también tiene en cuenta el Solo del mezclador. Por eso un cambio de Solo aparece como un cambio Muted en los demás canales, además de un cambio Mixer.

let ... else o saca el valor del Some, o ejecuta el bloque else, que debe salir: aquí continue salta al canal siguiente.

Luego las notas, para cada patrón y cada canal antiguo:

#![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 });
        }
    }
}
}

El if let ... && ... es una let chain: el bloque se ejecuta solo si el patrón es antiguo y su longitud cambió.

Las notas que se comparan son played_notes, no las escritas. El swing retrasa las notas a contratiempo sin cambiar lo escrito (ver Tempo, compás, swing y feel), y al hilo de audio hay que enviarle lo que se oye. Así que subir el swing no cambia ninguna nota escrita, pero da un cambio Notes por cada lista que mueve. played_notes devuelve un Cow («clone on write», copiar al escribir): un Cow::Borrowed cuando las notas escritas suenan tal cual, lo que no cuesta nada, y un Cow::Owned con una copia cambiada solo cuando el swing las mueve. Dos Cow se comparan por su contenido, sea cual sea su tipo.

&[][..] es un slice vacío: [] es un array vacío, y [..] lo toma entero como slice. Un patrón nuevo se compara con «sin notas», que es exactamente lo que el hilo de audio tiene para él, así que un cambio Notes se envía solo para los canales que tienen notas en él.

Por último vienen el tempo, la soltura, el mezclador y la canción. La canción se compara a través del arreglo que el modo canción reproduce de verdad:

#![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);
}
}

Un Arrangement son los clips con sus repeticiones y las repeticiones de las secciones ya desenrolladas, recortado a la región de bucle si la hay (ver El proyecto). Compararlo detecta un clip movido, un silencio, un número de repeticiones, un bucle cambiado y un marcador de tempo en un solo cambio Song. Los marcadores de tempo forman parte de la canción porque la longitud de un paso cambia a mitad de ella.

Cuando la historia es ambigua

Digamos que hay tres canales Lineup Osc con los mismos ajustes pero notas distintas, y borras el del medio. Comparando solo los canales (nombre, instrumento, volumen, silencio), la lista antigua es [Osc, Osc, Osc] y la nueva [Osc, Osc], y el alineado no puede saber cuál se fue: encuentra dos iguales al principio y dice que se quitó el último.

No pasa nada. Las notas del segundo canal ahora difieren (tiene las que solían ser las notas del tercer canal), así que viene un cambio Notes, y el hilo de audio acaba con exactamente los canales y las notas correctos. El diff no necesita adivinar lo que hiciste de verdad. Necesita una lista de pasos que acabe en el mismo sitio, y corta donde pueda.

Probar con un modelo

¿Cómo se prueba una función como diff? Comprobar su salida exacta para cada caso sería frágil, y no demostraría que la salida es correcta. Lo que de verdad queremos saber es: si el hilo de audio sigue estos cambios, ¿acaba con el proyecto nuevo?

Así que las pruebas construyen un pequeño modelo de lo que sabe el hilo de audio: las longitudes de los patrones, el instrumento, la mezcla, los efectos y las notas por patrón de cada canal, el tempo y la canción. Es lo bastante sencillo como para fiarse de un vistazo:

#![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 le hace al modelo lo que el hilo de audio hace con cada cambio, y check lo junta todo:

#![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)
}
}

Cada prueba comprueba primero esta propiedad, y solo después, donde importa, los cambios exactos: que un clic en un paso da un único Notes, que los nombres y la tonalidad no dan nada, que deshacer un patrón borrado empieza con InsertPattern(0), que el swing cambia las notas que suenan. La última prueba monta un lío a propósito, quitando un patrón, añadiendo un canal, activando un paso, cambiando un volumen y el tempo a la vez, y también compara un proyecto vacío con la canción de demostración, como haría abrir un archivo.

Este tipo de prueba se llama basada en propiedades: comprueba una regla que debe cumplirse para cualquier entrada, en lugar de una respuesta para una entrada. Uno de los ejercicios va más allá, con proyectos cambiados al azar.

El lado de la aplicación: sync_audio

sync_audio convierte cada Change en un comando, leyendo los valores del proyecto actual:

#![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 });
            }
            ...
        }
    }
    ...
}
}

Las demás ramas son igual de directas. InsertChannel construye el instrumento del canal y lo envía con sus notas para cada patrón. Instrument construye un instrumento nuevo y envía SetInstrument. Volume, Pan, ReverbSend y Effects envían su único valor, Muted envía el silencio efectivo del canal, LooseTiming envía la cantidad nueva, Mixer envía el volumen maestro y los ajustes de la reverberación, y Song envía los tres comandos que sustituyen la canción, sus tempos y los clics del metrónomo. Tempo envía el tempo a la velocidad de práctica, si ralentizaste la canción para practicar (ver Herramientas de práctica).

into_owned convierte el Cow de played_notes en un Vec que el comando puede llevar: clona una lista prestada, y simplemente entrega una que ya es propia.

sync_audio también mantiene los propios números de la ventana apuntando a lo correcto. El patrón seleccionado es una posición, así que baja cuando se va un patrón que estaba antes, y sube cuando la banda inserta uno antes. El piano roll recuerda qué canal muestra, así que se le avisa cuando los canales van y vienen (channel_removed y channel_inserted). Como estas actualizaciones están aquí, añadir, clonar y borrar patrones selecciona el patrón correcto tanto si lo hiciste tú como si lo hizo deshacer.

El hilo de audio inserta en su sitio

Deshacer «delete pattern 0» debe volver a poner un patrón en la posición 0, no al final. Por eso los comandos del hilo de audio reciben una posición:

#![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) mueve cada elemento desde index un lugar hacia arriba y pone value en el hueco. ¿Reservaría eso memoria en el hilo de audio? Solo si el Vec estuviera lleno. El sitio para MAX_CHANNELS canales y MAX_PATTERNS patrones se reserva al crear el hilo de audio (ver Espacio reservado de antemano), y ambos comandos comprueban primero el límite, así que insert siempre cabe en memoria que ya está ahí. Mover elementos es solo copiar, lo cual está permitido en tiempo real:

#![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);
        }
        ...
    }
}
}

Un índice más allá del final se limita (index.min(len)) en lugar de rechazarse. El hilo de audio nunca debe entrar en pánico, y «insertar después del último» es la lectura más sensata de un número demasiado grande.

InsertChannel es uno de los comandos más grandes. Cada ranura de la cola de comandos es tan grande como el comando más grande, así que una prueba mantiene los comandos en 80 bytes como mucho. Las voces de un instrumento están detrás de un Box, así que un comando lleva un puntero a ellas, nunca todas ellas.

Los instrumentos vuelven de una caché

Deshacer «cargar muestra» le devuelve a un canal su instrumento antiguo, y puede que sea un archivo de muestra. Leer un archivo en el hilo de la ventana para un deshacer haría tartamudear a la ventana, y el archivo podría incluso haber desaparecido ya.

Así que la aplicación guarda una SampleCache: cada archivo de muestra leído hasta ahora, por ruta.

#![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)
    }
}
}

Un HashMap encuentra un valor por su clave en más o menos el mismo tiempo tenga las entradas que tenga. Sus claves son PathBufs con propiedad, pero get recibe un &Path prestado. Eso funciona gracias al trait Borrow: PathBuf implementa Borrow<Path>, una promesa de que un PathBuf y el Path que contiene hacen hash y se comparan de la misma manera. Así el mapa puede buscar un &Path directamente, sin construir un PathBuf solo para buscar. (Un HashMap<String, _> se puede buscar con un &str por la misma razón.)

La caché entrega clones de Arc, así que la caché y cada sampler que usa el sonido comparten una copia en memoria. Una prueba lo comprueba con Arc::ptr_eq, que pregunta si dos Arc apuntan a exactamente la misma memoria, no solo a valores iguales:

#![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");
}

Soltar un archivo sobre el rack llama a reload, no a get: puede que hayas cambiado el archivo en un editor de audio desde entonces, y volverlo a soltar debe recogerlo. Un archivo que no se puede leer no se recuerda, así que el siguiente intento lo lee otra vez. Abrir otro proyecto vacía la caché.

Instrument::for_channel recibe la caché como argumento (&mut SampleCache) en lugar de leer los archivos por sí mismo. Exportar vuelve a construir cada instrumento (ver Exportar), y gracias a la caché tampoco lee archivos.

Deshacer y rehacer

Archivos: crates/lineup-core/src/history.rs y crates/lineup-app/src/app/edit.rs

Todo cambio en una canción se puede deshacer con Ctrl+Z y rehacer con Ctrl+Mayús+Z o Ctrl+Y, y el menú Edición nombra el paso que desharía («Deshacer: mover clip»). Este capítulo trata de cómo se guarda el historial, y de cuándo termina un paso y empieza el siguiente.

Dos formas de deshacer

Hay dos formas clásicas de construir el deshacer.

El patrón comando registra cada cambio como una instrucción que sabe revertirse a sí misma: «añadir la nota Do4 en el paso 3» se deshace con «quitar la nota Do4 del paso 3». El historial es una lista de instrucciones. Usa muy poca memoria, pero cada tipo de cambio necesita su propia operación inversa, escrita a mano, y cada una es un lugar nuevo para equivocarse. Piensa en lo que necesitaría deshacer «eliminar patrón»: volver a poner el patrón en su antigua posición, con su nombre y su longitud y las notas de cada canal, volver a poner cada clip que lo usaba y renumerar de nuevo los clips de los patrones que van detrás. Si se olvida un detalle, deshacer devuelve en silencio una canción ligeramente distinta.

Las instantáneas guardan una copia completa del proyecto de antes de cada paso que se puede deshacer. Deshacer vuelve a poner la copia. No hay nada que revertir, así que no hay nada que revertir mal: haga lo que haga el cambio, la copia es exactamente lo que había antes. El coste es la memoria y el tiempo de hacer una copia.

Ferrous Lineup usa instantáneas. Un NoteEvent ocupa 24 bytes, y una canción tiene unos cientos o unos miles, así que una copia de todo el proyecto son algunos kilobytes. Incluso un proyecto grande con 10.000 notas guarda unos 240 KB de notas, y hacer una copia tarda mucho menos de un milisegundo. La aplicación guarda como mucho 256 MiB de instantáneas: una canción pequeña obtiene los 100 pasos completos, mientras que una muy grande obtiene al menos 10 (que pueden pasarse del presupuesto). Es un precio justo por un deshacer que es correcto por construcción. (Uno de los ejercicios muestra cómo abaratar mucho las copias, si un proyecto llega a ser lo bastante grande para necesitarlo.)

History<T>

El historial vive en lineup-core, y no sabe nada de proyectos:

#![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> es genérico: T es aquello que se está recordando. La aplicación usa un History<Project>; las pruebas usan un History<i32>, lo que las hace cortas y fáciles de leer:

#![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");
}
}

Mira la línea impl: impl<T> History<T>, sin ningún trait bound sobre T. Ni siquiera Clone. El historial nunca copia un T; solo mueve los valores que recibe de una lista a otra. Quien llama hace la copia (self.project.clone()) y se la entrega. Si un método de History llamara alguna vez a .clone() sobre un estado, el compilador se negaría con «no method named clone found for type parameter T», y tendríamos que escribir impl<T: Clone>. Un tipo genérico sin bounds es una promesa fuerte: el código no puede hacer nada con un T salvo guardarlo, moverlo y soltarlo.

El compilador hace una copia separada del código para cada T con el que se usa (esto es la monomorfización), así que un History<Project> es tan rápido como si se hubiera escrito a mano para Project.

Las etiquetas &'static str

Cada paso tiene una etiqueta, como "move clip", para el menú Edición. Su tipo es &'static str: una referencia a texto que vive durante todo el programa. Cada string literal escrito en el código tiene este tipo, porque el texto se guarda dentro del propio archivo del programa. Así que una etiqueta no cuesta nada: no se construye ningún String, no se reserva nada, y el historial no guarda ningún préstamo que pueda terminar demasiado pronto. El precio es que una etiqueta no se puede crear en tiempo de ejecución («rename pattern Beat»), porque ese texto no existiría hasta que el programa lo construyera.

Las etiquetas se escriben en inglés, y el menú Edición las traduce al mostrarlas, así que el historial no necesita saber el idioma de la aplicación (ver Dos idiomas).

VecDeque: una lista con dos extremos baratos

Cuando ya hay limit pasos, registrar uno más olvida el más antiguo. En un Vec, quitar el primer elemento (remove(0)) mueve todos los demás un lugar hacia abajo. Un VecDeque («cola de dos extremos», se dice «vec deck») es un ring buffer, como las colas entre los hilos (ver Dos hilos): lleva la cuenta de dónde está su frente, así que push_back y pop_front son ambos baratos.

El límite no es una constante en la aplicación. History::new lo recibe, y undo_limit_for lo calcula a partir del tamaño del proyecto:

#![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 cuenta las notas, los clips, las marcas y los nombres, las cosas cuyo número crece con la canción. Un proyecto pequeño divide 256 MiB entre unos pocos kilobytes y obtiene más que DEFAULT_LIMIT, así que se limita a 100. Un proyecto enorme obtiene menos, pero nunca menos de 10, para que deshacer no desaparezca solo porque la canción es larga. Abrir un archivo construye un History nuevo con el límite de ese proyecto. History::default() significa 100, que es lo que usan las pruebas pequeñas.

#![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;
}
}

Cada cambio nuevo vacía la lista de rehacer. Después de deshacer tres pasos y cambiar algo, esos tres pasos pertenecen a un futuro que ya no existe. (Unos pocos programas guardan un árbol entero de historiales, para no perder nunca ninguna rama; la mayoría simplemente descarta el futuro antiguo, como hace este.)

La lista de rehacer es un Vec normal, porque los pasos solo se añaden y se quitan por su final.

mem::swap: deshacer sin copiar

#![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() devuelve un Option, y el operador ? funciona sobre Option en una función que devuelve un Option: si no hay nada que deshacer, undo devuelve None al momento y no cambia nada.

std::mem::swap intercambia los valores que hay detrás de dos referencias &mut. Después, current (el proyecto de la aplicación) guarda la versión más antigua, y el paso guarda la versión de la que acabamos de salir, lista para rehacer. No se copia ni se reserva nada: un Project es sobre todo Vecs, y un Vec es un puntero, una longitud y una capacidad, así que intercambiar dos proyectos intercambia unos pocos de esos valores pequeños, sea cual sea el tamaño de la canción. El borrow checker es lo que hace esto sencillo: swap necesita dos referencias &mut, y dos referencias &mut nunca pueden apuntar al mismo valor, así que swap puede intercambiar los bytes de los dos valores sin comprobar nada.

redo es la imagen especular: saca de redo y mete en undo.

¿Cuándo termina un paso?

Arrastrar un clip por la lista de reproducción lo mueve un poco en muchos fotogramas, y cada movimiento es una edición. Si cada uno fuera su propio paso, deshacer el arrastre necesitaría tantas pulsaciones de Ctrl+Z como fotogramas hubiera. Así que el historial mantiene el paso más nuevo abierto, y record no hace nada mientras lo esté: el paso ya guarda el proyecto de antes de que empezara el arrastre, que es exactamente adonde debería volver deshacer.

La aplicación decide cuándo termina un paso, porque solo ella sabe qué está haciendo el ratón. Llama al historial al principio y al final de cada fotograma:

#![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()));
        }
    }
}
}

Sigue unos cuantos gestos a través de estas dos funciones:

• Un clic en un paso. egui informa del clic en el fotograma en que se suelta el botón. La edición de ese fotograma abre un paso, y el final del mismo fotograma lo cierra, porque ya no hay ningún botón pulsado: un cambio, un paso.
• Un arrastre. La pulsación cierra lo que estuviera abierto. Cada fotograma del arrastre edita el proyecto mientras el botón está pulsado, así que las ediciones se unen en un paso. El fotograma en que se suelta el botón lo cierra.
• Escribir un nombre de patrón. Mientras el campo de texto tiene el foco del teclado, cada letra se une al mismo paso. Hacer clic en otro sitio le quita el foco y lo cierra, así que deshacer devuelve todo el nombre antiguo de una vez.
• Escribir un tempo. Hacer clic en la casilla de BPM la convierte en un campo de texto, así que se aplica la misma regla: todo lo escrito ahí es un paso, que termina cuando sales de la casilla.
• Grabar una toma. Cada nota tocada mientras se graba se une a un mismo paso, así que un deshacer quita la toma entera.

start_frame_for_undo importa en un caso: un clic que empieza cuando un campo de texto aún tiene el foco. La pulsación cierra el paso de escritura, para que el cambio del clic no se le una.

La rama else if trata del sonido, no de deshacer. Mientras un paso está abierto, los cambios llegan al hilo de audio como mucho cada 50 ms, llevados por la edición siguiente (ver Decirle al hilo de audio lo que ha cambiado). Un arrastre que se queda quieto no hace ninguna edición siguiente, así que el fotograma envía lo que aún espera cuando toca, y request_repaint_after le pide a egui un fotograma en ese momento aunque nada se mueva.

Cerrar un paso es 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();
}
}

Envía lo que al hilo de audio aún le falte, y vuelve a calcular el asterisco de cambios sin guardar (una nota arrastrada lejos y de vuelta deja la canción como estaba guardada). Después el historial deja de aceptar cambios en el paso.

Varios clics, un paso

Algunos cambios llegan de clic en clic pero van juntos. Marcar un tempo con golpes es un clic por pulso; retocar el volumen maestro o el número de vueltas es un clic o un arrastre por retoque. Deshacer debería quitarlos todos de una vez. reopen deja que la aplicación vuelva a abrir el paso más nuevo:

#![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
}
}

y la aplicación la llama justo antes de la edición:

#![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);
}
}

Si el último paso fue otro cambio, o se deshizo algo desde entonces, la etiqueta no coincide y empieza un paso nuevo como siempre.

Todo pasa por edit

El campo del nombre del patrón muestra lo estricta que es la regla «cada cambio pasa por edit». El campo de texto de egui quiere un &mut String para cambiar. Darle el nombre del propio proyecto cambiaría el proyecto directamente, a espaldas del historial: sin paso de deshacer y sin mensaje al hilo de audio tampoco. Así que el campo edita una copia, y la copia pasa por edit cuando ha cambiado:

#![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);
}
}

El tipo Project ayuda aquí: sus listas son privadas, y solo sus métodos pueden cambiarlas (ver El proyecto). Cualquier cosa que cambie un proyecto necesita un &mut Project, y en la aplicación el único sitio que lo entrega es edit.

Atajos de teclado

#![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 es Ctrl en Linux y Windows y ⌘ en un Mac. El consume_shortcut de egui es indulgente con las teclas de más: un atajo sin Mayús también encaja cuando Mayús está pulsado. Normalmente eso es lo que quieres (en muchos teclados + necesita Mayús, y Ctrl++ debería seguir funcionando), pero aquí significa que Ctrl+Mayús+Z contaría también como Ctrl+Z. Comprobar primero rehacer, y usar else if, lo resuelve.

|| se detiene en el primer true, así que si se pulsó Ctrl+Mayús+Z, Ctrl+Y ni siquiera se mira. «Consume» significa que la pulsación se saca de la entrada de egui, para que nada más en el mismo fotograma reaccione a ella.

Estos atajos se omiten mientras un campo de texto tiene el teclado. Los campos de texto de egui tienen su propio deshacer para escribir, y allí Ctrl+Z debe deshacer las últimas letras, no el último cambio de la canción.

El menú Edición muestra los mismos atajos, escritos como los escribe el sistema («Ctrl+Z» en Linux, «⌘Z» en un Mac), y pone la etiqueta traducida en el elemento, «Deshacer: mover clip».

Deshacer y el asterisco de cambios sin guardar

El título de la ventana muestra un asterisco cuando el proyecto difiere del archivo guardado. No compara los dos proyectos en cada fotograma: una edición pone una marca, y la comparación ocurre la próxima vez que se calcula el título. Deshacer y rehacer también ponen la marca, para que puedan hacer desaparecer el asterisco cuando el proyecto vuelve a ser igual que el guardado. Un simple dirty: bool puesto en cada edición habría mantenido el asterisco después de deshacer. Guardar muestra el resto.

Abrir un archivo, o Archivo > Nuevo, sustituye todo el proyecto y vacía el historial. Deshacer metiéndote en otra canción sería desconcertante, y la pregunta «¿Guardar cambios?» ya protege lo que dejas atrás.

Guardar: el archivo .lineup, la recuperación y los archivos dañados

Archivos: 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 y crates/lineup-core/tests/damaged_files.rs

Una canción se guarda como un archivo .lineup. Este capítulo trata de qué hay en ese archivo y por qué tiene esa forma, de cómo se lee un archivo de una versión más vieja o más nueva, de cómo guardar evita dejar nunca un archivo escrito a medias, y de cómo la aplicación guarda una copia del trabajo sin guardar por si se cae. La lista numerada de versiones del formato está en la página de referencia Formato del archivo de proyecto.

Cómo es un archivo de proyecto

Un archivo .lineup es texto plano. Para ver uno, abre una demostración en Archivo > Demostraciones, usa Archivo > Guardar como… y abre el archivo guardado en un editor de texto. Archivo > Nuevo ritmo empieza una canción con un patrón vacío y una batería; este es el archivo entero que guarda:

(
    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: [],
)

Otras canciones llevan más. El canal de sintetizador de la canción de inicio toca un piano General MIDI, así que lleva program: Some(0) y su archivo dice format: 9. Sus acordes se leen como notas, una por línea:

                    (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),

Archivo > Nuevo, una hoja de acordes vacía con una banda, guarda format: 17 y termina con la banda: band: Some((style: "Pop beat", ...)).

El formato es RON, «Rusty Object Notation». Se parece a Rust: un struct es ( field: value, ... ), una lista es [ ... ], y las variantes de enum se escriben por su nombre, Sampler(Builtin(Kick)), igual que en el código. JSON también serviría, pero JSON no tiene enums, así que el mismo canal se leería como {"Sampler": {"Builtin": "Kick"}}. RON es más fácil de leer y de arreglar a mano, algo que importa en un programa con el que se aprende: puedes abrir una canción en un editor de texto y ver tus propias estructuras de datos.

serde: describir los datos una sola vez

La forma estándar de Rust de convertir valores en texto (o bytes) y de vuelta es el crate serde, abreviatura de serialize y deserialize. serde no conoce ningún formato por sí mismo. Define dos traits, Serialize y Deserialize, y los crates de formato como ron o serde_json los usan.

Casi nunca escribes esos traits a mano. Una macro derive los escribe por ti:

#![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.
}
}

La macro lee la definición del struct en tiempo de compilación y genera código que escribe cada campo por su nombre y los lee de vuelta. Para que esto funcione, el tipo de cada campo debe ser también Serialize, así que ChannelKind, SampleSource, Drum, NoteEvent, Scale, PitchClass, Track, Clip y los demás también lo derivan. String, los números, bool, Vec, Option y PathBuf vienen con serde.

El derive se activa pidiendo la feature derive de serde en Cargo.toml. Las features son partes opcionales de un crate que enciendes cuando las necesitas:

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

Las líneas #[serde(default, skip_serializing_if = ...)] son la forma silenciosa de crecer del formato de archivo. Un campo que está en su valor por defecto no se escribe en absoluto, y un campo que falta en un archivo más viejo se rellena con su valor por defecto. Por eso la batería de arriba, que no usa nada más allá del primer formato, se escribe exactamente como lo escribía la primera versión del formato: un canal en el centro y con todo en la reverberación no dice nada del paneo ni del envío a la reverberación.

Mantener las reglas al leer: from e into

Un Tempo no se puede crear fuera de 10 a 522 BPM, porque su campo es privado y Tempo::new lo limita. Un Deserialize derivado pondría el campo directamente desde el archivo, así que un archivo que diga tempo: 9000.0 crearía un tempo que el resto del programa promete que no puede existir.

El arreglo es decirle a serde que pase por un tipo que controlamos:

#![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")] significa «lee un f32 y luego conviértelo con From<f32>». Esa conversión es Tempo::new, que limita. La prueba values_out_of_range_are_clamped edita un archivo guardado para que diga 9000 BPM y comprueba que carga como 522. into = "f32" hace lo contrario al guardar, lo que además hace que el archivo diga tempo: 130.0 en lugar de tempo: (bpm: 130.0). Note hace lo mismo con su número MIDI.

Siempre en letras y en inglés

La aplicación puede mostrar los nombres de las notas en letras (C, D, E) o en solfeo (Do, Re, Mi), y sus textos en inglés o en español (ver Dos idiomas). Un archivo no debe depender de ninguna de las dos cosas: una canción guardada por alguien que lee solfeo debe abrirse para alguien que lee letras. Así que to_text y from_text fijan ambas mientras se ejecutan:

#![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 fija la forma de nombrar para el hilo, ejecuta el closure y vuelve a poner la anterior, así que la ventana vuelve a dibujar en solfeo en su siguiente fotograma.

Un tipo separado para el archivo

Project en sí no deriva serde. Sus campos son privados porque deben estar de acuerdo entre ellos (una fila por canal, clips que apuntan a patrones reales), y un Deserialize derivado los rellenaría directamente desde el archivo, estén de acuerdo o no. Así que el archivo tiene su propio 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>>,
}
}

Un ProjectFile acepta cualquier cosa con la forma correcta. Convertirlo en un Project es donde ocurre la comprobación, y se escribe como una implementación de TryFrom, el trait estándar para «una conversión que puede fallar»:

#![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)
    }
}
}

El proyecto se reconstruye por la puerta principal: add_channel, add_pattern, add_note, add_clip, los mismos métodos que llama la aplicación cuando haces clic. Esos métodos ya mantienen todas las reglas (ver El proyecto), así que un archivo nunca puede crear un proyecto que la ventana no habría podido crear. Cuando un método se niega (una nota que no cabe, un clip que reproduce un patrón que no está), el error dice dónde, para que alguien que edite el archivo a mano pueda arreglarlo: «el archivo del proyecto está dañado: el clip 1 (patrón 99, pista 1) no entra en la lista de reproducción».

type Error = FileError; es un tipo asociado: parte del trait que elige cada implementación. Con TryFrom en su sitio, la biblioteca estándar también proporciona el try_into correspondiente, así que let project: Project = file.try_into()?; también funcionaría.

Guardar va en la otra dirección con From<&Project> for ProjectFile, que copia los datos hacia fuera con to_vec() y map. No puede fallar, así que es un From, no un TryFrom.

El número de versión

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

FORMAT_VERSION es la disposición más nueva que este programa puede leer. Un archivo no siempre la usa: format_for escribe el formato más bajo que puede contener el proyecto. Un proyecto que no usa nada nuevo se queda en formato 1, para que un Ferrous Lineup más viejo pueda seguir abriéndolo. La canción de inicio necesita el formato 9, porque su canal de sintetizador toca un programa General MIDI; una canción con hoja de acordes necesita al menos el formato 12; una con sección de vientos o con un efecto en un canal necesita el 28, y una banda que toca la batería de otro estilo, el 29. El largo comentario encima de FORMAT_VERSION dice, para cada número, qué añadió y qué haría mal un programa más viejo sin él; Formato del archivo de proyecto tiene la misma lista como tabla.

Un archivo de una versión más nueva debe rechazarse con un mensaje claro, no leerse mal. La forma obvia es leer primero un struct diminuto:

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

Por defecto, serde se salta los campos que un struct no enumera, así que un Header se puede leer del archivo entero. Pero para saltarse el resto del archivo, RON tiene que mirar hacia delante a través de todo él, número a número. Con una canción larga como el Boléro, eso tardaba más de un minuto, incluso en una compilación release. Así que primero se lee el archivo entero, y solo si eso falla format_number lee el número de los primeros 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 siempre escribe format primero, así que esto mira solo donde debe estar el número. Un archivo más nuevo a menudo no se puede leer en absoluto, por campos o nombres que esta versión no conoce; entonces el número de formato por sí solo explica por qué. Si el archivo está tan roto que ni siquiera el número se puede leer, el error de RON original es el que se informa. Y si el archivo se lee pero aun así dice un formato más nuevo, también se rechaza, porque el mismo texto puede significar otra cosa en ese formato. Una marca de orden de bytes al principio (algunos editores de texto añaden una) se elimina antes, para que no pueda esconder el (.

La prueba files_from_the_future_are_refused lee un archivo un formato más nuevo que esta versión, hoy (format: 30, sparkles: true), y espera NewerFormat(30), con el mensaje «este archivo usa el formato 30, hecho por una versión más nueva de Ferrous Lineup (esta lee hasta el formato 29)».

Errores como 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),
}
}

Es el mismo patrón que EngineError (ver Un tipo de error propio) y SampleError: una variante por cada tipo de problema, una implementación de Display con un mensaje para las personas (en el idioma de la aplicación), y std::error::Error para que funcione con cualquier tratamiento de errores de Rust. Dos cosas más lo hacen cómodo de usar.

From para el ?. Dentro de una función que devuelve Result<_, FileError>, el operador ? solo puede pasar un error si sabe cómo convertirlo en un FileError. Estas implementaciones se lo enseñan:

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

Con una para io::Error, una para el error de lectura de ron y una para su error de escritura, una función puede mezclar llamadas de ambas bibliotecas y usar ? en todas ellas:

#![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. El trait Error tiene un método opcional que devuelve el error de nivel inferior que envuelve un valor. Las herramientas que informan de errores lo siguen para imprimir una cadena como «no se pudo cargar: no existe el archivo». FileError::Io devuelve su io::Error; Invalid no tiene nada debajo y devuelve 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) es un objeto trait: una referencia a algún valor que implementa Error, sin decir de qué tipo. Eso permite a un método devolver un io::Error en un caso y un error de ron en otro.

Guardar sin perder el archivo viejo

#![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(())
}
}

Escribir directamente sobre song.lineup tiene un fallo feo: si el programa se cae o el disco se llena a mitad de camino, el archivo queda mitad viejo, mitad nuevo, y ninguna de las dos versiones se puede cargar. Escribir primero en song.lineup.tmp y luego renombrarlo sobre el original lo evita, porque el sistema operativo reemplaza un archivo al renombrar en un único paso. O el renombrado ocurrió y el archivo nuevo está completo, o no ocurrió y el archivo viejo queda intacto. En Windows, el fs::rename de Rust también reemplaza un archivo existente, así que el mismo código funciona en todas partes. Las exportaciones WAV y de video y la copia de recuperación se escriben de la misma manera.

to_text termina siempre las líneas con \n (RON usaría \r\n en Windows), así que una canción es el mismo archivo en todos los sistemas, y un proyecto guardado en un ordenador no muestra diferencias en el control de versiones al guardarlo en otro.

Las pruebas guardan en std::env::temp_dir(), la carpeta del sistema para archivos temporales (/tmp en Linux, algo dentro de tu carpeta de usuario en Windows), con el id del proceso en el nombre para que dos ejecuciones de pruebas a la vez no choquen, y borran el archivo después.

Los archivos dañados nunca hacen caer la aplicación

Un archivo de proyecto puede quedar cortado por un disco lleno, editarse a mano, o ser otra cosa con un nombre .lineup. Los archivos MIDI vienen de todos los programas que existen. Leer un archivo debe terminar en un proyecto o en un mensaje de error, nunca en una caída. El archivo de pruebas damaged_files.rs lo comprueba como lo hace un fuzzer: daña archivos buenos de muchas formas pequeñas y lee cada resultado.

El daño viene de un pequeño generador de números aleatorios, xorshift, escrito en la prueba:

#![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
    }
}
}

Empieza desde una semilla fija, así que cada ejecución daña los archivos de la misma manera, y un fallo vuelve a aparecer en la siguiente ejecución. No necesita ninguna dependencia nueva. En los archivos de proyecto y las hojas de acordes, sustituye números por valores extremos (-1, 65535, 18446744073709551615, NaN), recorta trozos y repite trozos. En los archivos MIDI, cambia, recorta y repite bytes. Cada prueba lee 600 copias dañadas. Un proyecto que se lee también debe guardarse y volver a leerse.

La prueba captura un panic con std::panic::catch_unwind, así que un fallo imprime el archivo dañado que lo causó, hasta sus primeros 4000 caracteres:

#![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}");
    }
}
}

El desbordamiento es el tipo de error que atrapa. Un archivo con un cambio de tonalidad en el paso 18446744073709551615, el usize más grande, no pasa la validación, como debe ser, pero escribir el mensaje de error calculaba marker.start + 1 para decir «paso …», y eso desbordaba. Rust trata el desbordamiento de forma distinta en los dos perfiles de compilación. En una compilación debug, + entra en pánico al desbordar («attempt to add with overflow»). En una compilación release da la vuelta hasta 0, en silencio. Así que una ejecución en modo release sobre 15.000 archivos dañados no vio nada, y los mismos archivos en modo debug se caían. Los mensajes usan saturating_add(1), que se queda en el número más grande en lugar de desbordar, y la integración continua ejecuta las pruebas en modo debug (ver Cómo se prueba el código).

En la aplicación: el menú Archivo

El lado de la aplicación está en crates/lineup-app/src/app/files.rs. Sus primeras líneas explican una disposición poco habitual:

#![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 declara mod files;, y Rust busca ese módulo en app/files.rs. El archivo contiene otro bloque impl LineupApp. Un tipo puede tener cualquier número de bloques impl, en cualquier módulo de su crate, así que un tipo grande se puede dividir por temas. Al ser hijo de app, files ve los campos privados self.project, self.audio y demás, cosa que un módulo hermano como playlist no podría.

Elegir un archivo

Los diálogos de archivos vienen del crate rfd («Rusty File Dialog»), que muestra el diálogo propio del sistema: GTK o KDE en Linux (a través del portal del escritorio, o del programa zenity), el panel del Finder en macOS, el diálogo del Explorador en 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 espera hasta que el usuario elige un archivo o cancela, y devuelve un Option<PathBuf>. La ventana no se redibuja mientras el diálogo está abierto, pero la música sigue sonando, porque corre en el hilo de audio. En un sistema Linux sin portal ni zenity, pick_file devuelve None inmediatamente; el diálogo simplemente no aparece.

Guardar como… le da al archivo la extensión .lineup aunque escribas otra, así que song.txt se guarda como song.lineup, no como algo que otro importador intentaría abrir.

«¿Guardar cambios?»

¿Cómo sabe la aplicación que hay cambios sin guardar? Mantiene una copia del proyecto tal como estaba la última vez que se abrió o guardó, y compara. Pero Project deriva PartialEq, así que != recorre cada canal, nota y clip. Eso es barato una vez, pero un arrastre edita el proyecto en cada fotograma, y comparar la canción entera en cada fotograma es trabajo desperdiciado. FileState por eso guarda la respuesta:

#![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,
}

Una edición pone check_dirty, pero solo si el proyecto no tenía ya cambios. Mientras los tiene, los siguientes fotogramas de un arrastre no vuelven a pedir la comparación entera:

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

Un cambio hecho de una vez (un clic), deshacer, rehacer y el final de un arrastre pueden hacer que el proyecto vuelva a coincidir con la copia guardada, así que siempre piden una comparación nueva con project_reverted (ver Decirle al hilo de audio lo que ha cambiado). La respuesta guardada se lee en cada fotograma para el título, pero la comparación en sí solo se hace cuando la marca está puesta:

#![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
}
}

Así, un paso que se activa y se vuelve a desactivar quita el asterisco, y también una nota arrastrada lejos y de vuelta, en cuanto la sueltas.

Cualquier cosa que fuera a tirar el proyecto espera antes una respuesta:

#![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);
    }
}
}

Mientras pending guarda algo, unsaved_changes_dialog muestra un egui::Modal, una ventana que oscurece todo lo que hay detrás y se queda con todos los clics:

Guardar guarda y después lleva a cabo la acción que esperaba, a menos que guardar fallara o el usuario cancelara el diálogo de Guardar como; No guardar la lleva a cabo inmediatamente; Cancelar, Esc o un clic fuera la olvida. El valor pending es toda la máquina de estados: None significa «nada esperando», Some(Pending::Open) significa «el usuario quiere abrir un archivo, en cuanto decida sobre los cambios».

pub(super) hace el enum visible para el módulo padre (app), que lo necesita para FileState, pero no más allá.

El editor de estilos tiene su propio borrador sin guardar. Salir con un borrador editado pregunta también ¿Guardar los cambios del estilo?, así que guardar la canción nunca tira el estilo en silencio.

Cerrar la ventana

Hacer clic en la × de la ventana le pide al sistema operativo que la cierre. egui informa de la petición, y la aplicación puede decir que 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);
}
}

Cuando el usuario elige entonces Guardar o No guardar, perform(Pending::Quit) pone quitting y envía ViewportCommand::Close, que esta vez se deja pasar.

Salir mientras una exportación WAV o de video aún se está ejecutando pregunta Una exportación aún se está ejecutando, con Detener y salir y Continuar exportando. Detener espera a que la exportación se haya detenido y haya borrado su archivo sin terminar, y luego cierra, así que nunca queda un archivo escrito a medias que parezca terminado.

Atajos de teclado

#![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 es Ctrl en Linux y Windows y ⌘ en macOS, así que cada sistema tiene el atajo que esperan sus usuarios. El menú Archivo muestra también el correcto: «Ctrl+S» o «⌘S».
• consume_shortcut comprueba las teclas y las retira de la entrada, para que un campo de texto no las vea también.
• Ctrl+S también encajaría con Ctrl+Mayús+S (el Mayús de más se ignora), así que el atajo más largo se comprueba primero.

Estos valores const llaman a KeyboardShortcut::new mientras se compila. Eso está permitido porque egui lo marcó como const fn, una función lo bastante simple para ejecutarse en tiempo de compilación.

La barra de título

El título de la ventana muestra el nombre de la canción y un asterisco para los cambios sin guardar, «song.lineup* · Ferrous Lineup». Una demostración muestra su propio nombre y dice que es de solo lectura, «Für Elise (demostración, solo lectura) · Ferrous Lineup»: las demostraciones vienen dentro de la aplicación, así que Guardar pide un archivo nuevo, como Guardar como…. La aplicación envía un ViewportCommand::Title solo cuando cambia el texto, no en cada fotograma.

Abrir un archivo desde fuera

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

ferrous-lineup song.lineup empieza con la canción abierta, que es también lo que hace un gestor de archivos cuando haces doble clic en un archivo asociado a la aplicación. (El mismo primer argumento puede ser en cambio --trace, --demos o --help, que hacen su trabajo sin abrir ninguna ventana; ver La traza de reproducción.) args_os devuelve los argumentos como OsStrings, exactamente como los dio el sistema. std::env::args haría panic con un nombre de archivo que no es UTF-8 válido, cosa que Linux permite. skip(1) se salta el primer argumento, que es el nombre del propio programa.

Un archivo .lineup soltado sobre la ventana también se abre, tras la misma pregunta «¿Guardar cambios?», y un archivo MIDI, una hoja de acordes o una grabación se importan. Los demás archivos WAV soltados van al rack de canales (en Importar grabaciones está cuál WAV es cuál).

Archivo > Abrir recientes

Archivo > Abrir recientes lista los últimos diez proyectos abiertos o guardados, el más reciente primero. La lista se guarda en los datos que egui conserva, así que sobrevive a un reinicio. Cada elemento muestra el nombre del archivo, con la ruta completa en su descripción emergente. Abrir un archivo que ya no carga lo quita de la lista en lugar de dejar una entrada muerta.

La lista guarda rutas, no copias de proyectos. Si un proyecto se mueve o se renombra fuera de la aplicación, la ruta vieja se queda hasta que falla un intento de abrirlo.

Una copia del trabajo sin guardar

La aplicación escribe una copia de recuperación del proyecto mientras tiene cambios sin guardar. El primer cambio escribe una enseguida, para que la primera edición de una sesión no sea la que pierde una caída; después escribe cada treinta segundos:

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

Una ventana que nadie toca no dibuja fotogramas, así que nunca llegaría a escribir. Por eso, cuando toca una copia, autosave le pide a egui un fotograma en ese momento con request_repaint_after: la copia se pone al día en más o menos medio minuto después de un cambio, aunque nadie toque la aplicación.

Los archivos están en una carpeta recovery dentro de la carpeta de datos de la aplicación, la que le da eframe::storage_dir(APP_NAME). En Linux suele ser ~/.local/share/ferrouslineup/recovery. Cada ejecución de la aplicación nombra sus archivos según ella misma, como 4211-1793047912612-0.lineup y 4211-1793047912612-0.info: el número de proceso, el momento en que empezó en milisegundos, y un contador. Por qué cada ejecución necesita los suyos está en Dos ventanas a la vez más abajo. La copia no se escribe junto al proyecto, porque un proyecto puede estar en un medio de solo lectura, y un archivo de autoguardado en una carpeta de canciones sorprendería a cualquiera que la mirase. El pequeño archivo .info lleva la ruta y el nombre del proyecto, así que una canción recuperada vuelve como ella misma, no como «Sin título».

La copia se escribe con file::save, que escribe un archivo temporal y lo renombra. Una caída a mitad deja entera la copia anterior; el archivo de información se escribe después del proyecto, así que una caída entre los dos pierde el nombre en lugar de darle al proyecto uno equivocado.

Al arrancar, si hay una copia, un diálogo pregunta ¿Recuperar el trabajo sin guardar? y nombra la canción:

• Recuperarlo vuelve a poner el proyecto, con su ruta y su nombre, y borra la copia. También carga el archivo del disco, si aún existe, como la versión «guardada», así que el trabajo recuperado muestra correctamente el asterisco de cambios sin guardar; deshacer hasta el archivo lo quita. Si el archivo ya no está, el proyecto recuperado simplemente no está guardado.
• Descartarlo borra la copia y deja el proyecto que la aplicación habría abierto de todos modos.

Una salida limpia borra la copia, porque no hay nada que recuperar. La copia que queda es la señal de una caída, de un cierre forzado o de un corte de luz. Una copia cuyo proyecto no carga se borra al arrancar en lugar de ofrecerse. Un único recovery.lineup directamente en la carpeta de datos, como lo escribían versiones anteriores, también se ofrece.

Dos ventanas a la vez

Nada te impide arrancar Ferrous Lineup dos veces. Si cada ejecución escribiera la misma copia, la segunda ventana encontraría al arrancar la copia de la primera y la ofrecería como si la primera se hubiera caído, mientras seguía abierta; y el autoguardado de cada ventana sustituiría la copia de la otra.

Así que cada ejecución escribe su propia copia, y junto a ella un tercer archivo, <run>.lock, que bloquea antes de escribir la primera copia y mantiene mientras se ejecuta. Un bloqueo de archivo es una promesa que cumple el sistema operativo: solo un archivo abierto puede tenerlo, y cuando el programa que lo tiene termina, el sistema lo suelta, incluso en una caída o un corte de luz. Eso lo convierte en la pregunta correcta al arrancar: «¿sigue en marcha la ejecución que escribió esta copia?». Si su bloqueo se puede tomar, no sigue, y la copia se ofrece; si no, la copia pertenece a una ventana que sigue abierta y se deja en paz.

La biblioteca estándar tiene bloqueos de archivo desde Rust 1.89 (File::lock, File::try_lock y compañía). try_lock no espera: dice enseguida si consiguió el bloqueo, y su error distingue «otro lo tiene» de «este sistema no puede bloquear archivos»:

#![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,
    }
}
}

El bloqueo dura lo que dura el valor File: soltarlo lo libera. Así que una ventana que encuentra una copia guarda el File en el valor Recovered hasta que respondes a la pregunta; una tercera ventana abierta mientras tanto no puede tomar el bloqueo y no ofrece la misma copia dos veces. Cuando la aplicación se cierra, el Drop de Recovery borra su archivo de bloqueo; una copia de trabajo sin guardar se queda, sin su bloqueo, para ofrecerse la próxima vez. Un sistema que no puede bloquear archivos (Lock::Unknown) ofrece la copia de todos modos: ofrecerla dos veces no pierde nada, no ofrecerla nunca sí.

Si se cayeron dos ejecuciones, hay dos copias. La más nueva se ofrece primero, y la siguiente espera hasta que el trabajo recuperado antes se guarde o se descarte, así que recuperar una nunca sustituye a otra.

Dibujar las ventanas con egui: distribución, zoom, temas, iconos

Archivos: 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 y crates/lineup-app/src/app/about.rs

La ventana se dibuja con egui, una librería de GUI escrita en Rust, y eframe, el framework de egui para ejecutarla como app nativa en Linux, macOS y Windows. Este capítulo trata de cómo se arma la ventana principal en cada frame, del aspecto, de cómo las filas de controles caben en cualquier tamaño de ventana, de los zooms, de las ventanas que flotan sobre la lista de reproducción y del menú Ayuda. Los editores en sí, el rack de canales, el piano roll y la lista de reproducción, tienen el capítulo siguiente.

Modo inmediato

La mayoría de los toolkits de GUI son de modo retenido: creas los objetos botón una vez, los guardas en un árbol y les adjuntas callbacks. egui es de modo inmediato: en cada frame, llamas a una función que describe toda la interfaz a partir de tus propios datos, y la librería la dibuja y te dice en qué se ha hecho clic.

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

Esa línea dibuja el botón y comprueba si se ha hecho clic en él. No hay objetos botón que mantener sincronizados con tu estado. El estado son simplemente los campos de tu struct, y la interfaz es siempre una imagen de él. Esto encaja bien con Rust, porque no hay callbacks que retengan referencias a tus datos.

El precio es que un frame no puede volver atrás. Algo dibujado al principio del frame no puede saber lo que se dibuja después. Varias piezas de este capítulo (la barra de ayuda, los grupos que se reparten en filas, el zoom) lo resuelven de la misma manera: usan lo que encontró el frame anterior, de hace una sexagésima de segundo.

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 devuelve un Result. Si devuelve Err, Rust imprime el error y sale con un código de fallo.
• ViewportBuilder::default().with_title(...) es el patrón builder: cada método toma el builder y lo devuelve modificado, para que las llamadas se encadenen.
• ..Default::default() es la sintaxis de actualización de structs: «todo campo que no enumere toma su valor por defecto».
• Box::new(|cc| ...) pasa un closure que eframe llama una vez para crear nuestra app. Box pone un valor en el montículo. Aquí hace falta porque eframe acepta cualquier tipo que implemente su trait App, y para guardar un valor cuyo tipo exacto no conoce necesita un puntero a él: Box<dyn App>. La palabra clave dyn significa «algún tipo que implementa este trait, decidido en tiempo de ejecución» (un trait object).
• "--help" | "-h" es un patrón «o»: la rama coincide con cualquiera de las dos cadenas.

LineupApp: el estado

LineupApp guarda todo lo que necesita la ventana: el proyecto, el historial de deshacer, las ventanas abiertas y su propio estado, el archivo, los ajustes y la conexión con el hilo de audio. Esa conexión es un 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),
}
}

Captura una situación real: o hay un motor en marcha, o está la razón por la que no lo hay. No puedes tener ambas cosas, y no puedes no tener ninguna, así que el tipo no puede representar un estado imposible. Compáralo con la alternativa habitual, un Option<AudioEngine> más un Option<String>, que permite cuatro combinaciones de las cuales dos no tienen sentido.

Un enum ocupa lo que su variante más grande, más un poco de espacio para decir cuál es. Box deja el motor, que es grande, en el montículo, así que Audio ocupa lo que un puntero o un String, lo que sea mayor. Clippy lo señala con su lint large_enum_variant.

Usarlo:

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

if let es un match de una sola rama: si self.audio es Running, liga el motor que hay dentro a engine y ejecuta el bloque. Hacer match sobre &mut self.audio toma prestado el motor de forma mutable en lugar de moverlo fuera del struct.

Si la computadora no tiene una tarjeta de sonido que funcione, la app se abre igual y la barra de estado dice por qué, en naranja: «Audio no disponible: …». Un fallo se convierte en datos que mostramos, en lugar de un cierre inesperado.

Un frame

eframe llama a ui cada vez que la ventana necesita repintarse:

#![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();
    }
}
}

El orden es el diseño:

1. collect_garbage libera lo que devolvió el hilo de audio (ver La cola de basura).
2. before_drawing hace todo lo que debe pasar antes de dibujar nada: apunta si un clic está cerrando un menú, pone el idioma y los nombres de las notas para el frame, cierra un paso de deshacer al pulsar el ratón, escribe la copia de recuperación cuando toca, lee los atajos de teclado y las teclas de zoom, lee la entrada MIDI y mira cómo van las exportaciones e importaciones que corren en segundo plano. Mientras suena, le pide a egui otro frame enseguida (ctx.request_repaint()), para que el cursor de reproducción se mueva; si no, egui solo dibuja cuando pasa algo.
3. panels dibuja las barras de los bordes: los menús con la barra de ayuda, la barra de herramientas, la barra de estado y las teclas de armonía. Los paneles deben ir antes del área central, que ocupa el espacio que queda.
4. main_area dibuja la lista de reproducción (o la hoja de acordes, cuando llena la ventana principal) y devuelve el rectángulo que ocupó.
5. Las ventanas flotan sobre ese rectángulo. Las que se dibujan después quedan encima, por eso la hoja de acordes va la última de los tres editores.
6. end_frame_for_undo decide si el paso de deshacer termina (ver Deshacer y rehacer).

on_exit se ejecuta una vez cuando la app se cierra bien: no hay trabajo sin guardar que recuperar, así que la copia de recuperación de esta ejecución se borra.

Los muchos métodos self.algo(ui) mantienen ui corto. Cada closure que se pasa a un panel puede tomar prestado self de forma mutable, porque cada uno se ejecuta y termina antes de que empiece el siguiente, algo que el borrow checker puede ver.

Un tema es una función

egui dibuja cada widget a partir de un Style: los colores en style.visuals, los tamaños y huecos en style.spacing. Nada se pinta con un color fijo salvo que el código pida uno. Así que todo el aspecto es una función, theme::apply, llamada una vez al arrancar la app:

#![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...
    });
}
}

El aspecto toma prestado de los estudios basados en patrones: paneles gris azulado oscuro, botones grises en relieve, una luz naranja para lo que está seleccionado o encendido, y pantallas «LCD» negras para números como el tempo. Tres cosas que hay que notar en el código:

• style_mut_of(Theme::Dark, ...) cambia solo el estilo oscuro. egui guarda un estilo para oscuro y otro para claro, y la app usa siempre el oscuro.
• El bucle for recorre un array de pares de referencias mutables. Cada &mut widgets.inactive toma prestado un campo distinto, así que Rust permite varios a la vez: el borrow checker sigue los campos de un struct por separado.
• Los colores son elementos const: Color32::from_rgb es un const fn, así que se ejecuta en tiempo de compilación y no cuesta nada cuando la app se ejecuta.

Las vistas siguen teniendo sus propias constantes para las cosas que solo dibujan ellas (las filas de la lista de reproducción, las teclas del piano roll, los botones de paso), con valores que pegan con el tema.

Cambiar el estilo de unos pocos widgets

La pantalla de tempo es un DragValue, el número de egui que se arrastra o se escribe, pero dibujado en negro con dígitos verde azulados. Su estilo se cambia solo dentro de su marco:

#![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
}
}

Cada Ui tiene su propia copia del estilo (un Arc<Style>; style_mut hace una copia privada la primera vez que se cambia). El contenido del marco recibe un Ui hijo, así que el cambio se queda dentro del marco y el resto de la barra de herramientas no se toca. add es un closure que devuelve el Response del widget, así que quien lo llama puede seguir preguntando changed() fuera:

#![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))
});
}

El campo de Tempo es privado, así que el valor se copia a un bpm local, el widget edita ese, y se construye un Tempo nuevo si cambió. El Tempo sigue siendo válido se escriba lo que se escriba. Tempo::MIN..=Tempo::MAX es un rango inclusivo: a..b deja fuera b, a..=b lo incluye.

Una etiqueta más larga que la pantalla, como algunas en español, se escribe un poco más pequeña para que quepa, así que la barra de herramientas conserva su ancho en todos los idiomas.

La barra de ayuda: un mensaje del futuro

Junto a los menús, una línea dice qué hace el control que está bajo el ratón. Esa línea se dibuja primero, arriba del todo de la ventana, pero los widgets que saben sobre qué está el ratón se dibujan después, en el mismo frame. En modo inmediato no hay vuelta atrás para repintar la barra.

Así que la barra muestra lo que se encontró en el frame anterior. Los widgets dejan su ayuda en la memoria de egui, ctx.data, que es un mapa de un Id a un valor de cualquier tipo:

#![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)
}
}

Al principio del frame siguiente, la barra la saca, para que no se quede cuando el ratón se va:

#![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> usa el turbofish ::<String> para decir qué tipo sacar: el mapa puede guardar valores de muchos tipos bajo el mismo Id. El request_repaint es la parte sutil. egui solo dibuja un frame cuando pasa algo. Cuando el ratón se pone sobre un botón, ese frame apunta la ayuda, pero la barra sigue mostrando la antigua. Pedir un frame más muestra la ayuda nueva enseguida, en lugar de la próxima vez que se mueva el ratón.

Filas que caben en cualquier ventana

La barra de herramientas tiene el modo de reproducción, el transporte, las pantallas de tempo y de posición, el selector de patrones, los cinco botones de ventana, la cuenta de entrada, el metrónomo y el volumen maestro. En una ventana de 1280 puntos de ancho cabe en una fila; una prueba, the_toolbar_fits_on_one_row_at_1280_points, comprueba que siga siendo así. Una ventana más estrecha o con zoom tiene que seguir llegando a todos los controles.

egui coloca los widgets uno detrás de otro. ui.horizontal los pone en una fila y sigue más allá del borde si no caben: lo que queda más allá del borde sigue estando, solo que no se dibuja. ui.horizontal_wrapped es la misma fila, salvo que un widget que no cabría empieza una fila nueva. La barra de herramientas y la barra de teclas de armonía son filas que se reparten, así que en una ventana estrecha su segunda parte baja.

Grupos que se reparten: el ancho del frame pasado

Los botones de la barra de herramientas van en grupos, cada uno dentro de un marco oscuro. Una fila que se reparte decide si pasa a la fila siguiente preguntándole a un widget cuánto quiere ocupar antes de colocarlo. Un marco no puede responder a eso: Frame::show dibuja su contenido en el espacio que quede, y solo sabe su tamaño después. Así que theme::wrapping usa el frame anterior. egui vuelve a dibujar la ventana muchas veces por segundo, así que el ancho de la última vez es una muy buena estimación:

#![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() es el id que egui le daría al siguiente widget. Depende de cuántos widgets vinieron antes en este Ui, así que es el mismo en cada frame mientras la barra se dibuje en el mismo orden. Eso lo convierte en una clave para recordar algo de un grupo.
• get_temp::<f32> le pide a la memoria de egui un f32; el turbofish le dice a Rust qué tipo buscar, porque nada más en la línea lo dice.
• La cadena if let ... && ... (una «let chain») solo ejecuta end_row cuando hay un ancho de la vez anterior, la distribución se reparte, la fila ya tiene algo y el grupo no cabe. El primer frame de todos todavía no tiene ancho, así que el grupo puede sobresalir durante un frame, cosa que nadie ve.

theme::group y lcd_frame envuelven sus marcos en él, y keep_together ofrece lo mismo a cualquier grupo de widgets, con un guess para el primer frame de todos. Ese primer frame importa dentro de una ventana: las ventanas de egui crecen para que quepa su contenido, y un solo frame de contenido demasiado ancho basta para ensanchar una ventana para siempre. La barra de herramientas del piano roll mantiene juntos sus grupos de esta manera, así que un nombre de escala largo (el de Fa# mayor, «Fa# Sol# La# Si Do# Re# Mi#») pasa su grupo a una segunda fila en lugar de ensanchar la ventana.

Texto que se acorta, y de derecha a izquierda

Repartirse en varias filas les va bien a los botones. Para una línea larga de texto, como un mensaje de estado, a menudo es mejor cortarla. Todo texto en egui tiene un modo de ajuste: Wrap lo parte en más líneas, Truncate lo corta con «…» y Extend lo deja seguir. Un área entera puede ponerlo para todo su texto mediante su estilo:

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

Una etiqueta truncada muestra el texto entero cuando apuntas a ella, así que no se pierde nada.

La barra de estado tiene dos partes: mensajes a la izquierda y los controles de zoom de la lista de reproducción a la derecha. Si los mensajes se dibujaran primero, uno largo («Audio no disponible: no se pudieron leer los ajustes del dispositivo…») ocuparía todo el espacio y empujaría fuera el zoom. Así que la barra se distribuye de derecha a izquierda: el zoom entra primero, desde el borde derecho, y los mensajes se quedan con lo que sobra:

#![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);
        });
    });
}
}

En una distribución de derecha a izquierda, el primer widget es el que está más a la derecha, por eso zoom_control añade su botón + antes del porcentaje y del botón −.

Zoom

Hay dos tipos de zoom.

El tamaño de la interfaz hace todo más grande o más pequeño: texto, botones, menús. egui dibuja en puntos, no en píxeles. Cuántos píxeles ocupa un punto es pixels_per_point: la escala propia de la pantalla (1.0, 1.5 o 2.0 en la mayoría) multiplicada por el factor de zoom de egui. ctx.set_zoom_factor cambia el segundo.

Las áreas hacen zoom de lo que dibujan sin cambiar el texto. Como en la mayoría de los programas de música, la lista de reproducción y el piano roll hacen zoom en sus dos direcciones por separado: el zoom horizontal hace más anchos los compases y los pasos (menos tiempo en pantalla, con más detalle), el vertical hace más altas las pistas y las teclas del piano. Los pasos del rack de canales son botones cuadrados, así que tiene un solo zoom para las dos direcciones.

¿Qué hay bajo el puntero?

Las teclas y la rueda hacen zoom de lo que está bajo el puntero. En Rust, «una de estas clases» es un enum, y una variante puede llevar un valor:

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

Target::at lo encuentra. egui mantiene una pila de capas: el fondo, donde se dibujan los paneles, luego cada ventana encima, luego los menús y los tooltips. ctx.layer_id_at(pos) dice qué capa está arriba en un punto:

#![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,
    }
}
}

Cada rama tiene una guarda, el if después del patrón. El patrón Some(layer) coincide con cualquier capa, y la rama solo se toma si la guarda también es verdadera; si no, match prueba la rama siguiente. La última rama, _, recoge todo lo que queda.

Las barras de herramientas, las teclas de armonía y la lista de reproducción se dibujan todas en la misma capa de fondo, así que la capa sola no puede distinguirlas. Por eso la lista de reproducción recuerda dónde se dibujó, y la guarda comprueba playlist.contains(pos). Las teclas de zoom se leen al principio de un frame, antes de dibujar nada, así que este es el rectángulo del frame anterior. Si el puntero está fuera de la ventana, las teclas hacen zoom de lo último en que se hizo clic.

La hoja de acordes es texto, así que sigue el tamaño de la interfaz, en su propia ventana o en el lugar de la lista de reproducción. En ese lugar tapa la lista de reproducción, y el último rectángulo de la lista mentiría, así que zoom_shortcuts pasa uno vacío en su lugar:

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

Rect::NOTHING no contiene ningún punto, así que la guarda nunca es verdadera, y las teclas caen en Target::Interface.

Todas las maneras de hacer zoom (teclas, rueda, pellizco en el touchpad) llaman a los mismos pocos métodos de Target, y solo ellos miran de qué clase es:

#![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) comprueba la variante y a la vez saca de ella el Area a la variable area. La interfaz tiene un solo tamaño, así que ahí axis no se usa: Ctrl y Alt hacen lo mismo.

Un zoom por área y por eje

Cada área guarda un número por dirección, en la memoria de egui, bajo una clave hecha de las dos cosas:

#![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))
}
}

El rack no es two_way, así que sus dos ejes comparten la clave horizontal: hacerle zoom «vertical» le hace zoom en las dos direcciones. Los valores se guardan con insert_persisted, así que egui los guarda con las posiciones de las ventanas y son los mismos la próxima vez que arranca la app. El nombre "zoom-2" está porque un significado anterior de «zoom» (una escala para todo lo de la ventana, texto incluido) se guardaba bajo "zoom": un nombre nuevo hace que los valores viejos simplemente no se encuentren, en lugar de leerse de la manera equivocada.

Todas las maneras de hacer zoom por pasos pasan por step_zoom, que recorre una escalera de tamaños:

#![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,
];
}

Cada paso es más o menos una quinta parte mayor que el anterior, así que cuesta tantos pasos ir de 100% a 200% como de 400% a 800%. Así es como el zoom se siente natural: los ojos comparan tamaños por proporción, no por diferencia. Cada área y eje tiene su propio tramo dentro de la escalera (las pistas y las teclas solo pueden achicarse hasta que sus nombres dejan de caber), y los botones se ponen grises en los extremos. Los tamaños de la interfaz son una lista más corta propia, del 50% al 250%, los mismos que ofrece Ajustes > Apariencia.

Leer la rueda nosotros mismos

egui da un único zoom_delta() para Ctrl+rueda, sin idea de dirección. Así que la app lee los eventos de rueda en bruto del frame y los clasifica según las teclas modificadoras pulsadas:

#![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 con un patrón es como Rust elige una variante de un enum y nombra sus campos al mismo tiempo; .. ignora los campos que no necesitamos.

En Linux (X11), un golpe de rueda a veces llega como dos eventos, y hacer zoom de dos pasos por golpe se siente a saltos. Así que los golpes se suman y hacen zoom de un paso como mucho por 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);
    }
}
}

Un frame dura unos pocos milisegundos, así que girar la rueda rápido sigue haciendo zoom paso a paso. Un touchpad manda en cambio muchos movimientos diminutos en lugar de golpes (MouseWheelUnit::Point); esos multiplican el zoom de forma suave.

Hacer zoom sobre lo que señalas

Cuando el zoom cambia, el paso y la nota que están bajo el puntero deben seguir bajo el puntero. La cuadrícula está dentro de un scroll area, así que eso significa elegir un desplazamiento nuevo. Lo que está bajo el puntero está en from + anchor dentro del contenido, donde from es cuánto se ha desplazado la vista y anchor dónde está el puntero dentro de la vista. Hacer zoom por ratio lo mueve a (from + anchor) * ratio. Para que se quede bajo el puntero, el desplazamiento nuevo debe ser eso menos anchor. En el 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)));
}

Los términos KEY_WIDTH están porque el teclado de piano de la izquierda no se estira: solo crece lo que está a su derecha.

Hubo que apagar una cosa más. Los scroll areas de egui tienen una banda elástica: te desplazas más allá del final y la vista vuelve de un salto. En el frame de un zoom, el scroll area todavía conoce el tamaño viejo del contenido, así que el desplazamiento nuevo parece ir más allá del final, y la vista se deslizaría de vuelta después de cada zoom. widgets::no_rubber_band la apaga para las cuadrículas:

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

El rack de canales se dibuja con widgets normales de egui, que no tienen zoom propio. widgets::zoom_contents los hace más grandes multiplicando los tamaños del texto y los espacios del estilo de la ventana, igual que lcd_frame cambia sus colores: solo dentro del rack.

Ventanas sobre la lista de reproducción

El rack de canales, el piano roll, la hoja de acordes, el mezclador y las demás son egui::Window, que flotan sobre todo. Se mantienen dentro del rectángulo de la lista de reproducción con Window::constrain_to(area), así que una ventana nunca tapa la barra de herramientas, las teclas de armonía ni la barra de estado:

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

Cada show de egui devuelve un InnerResponse: .inner es lo que devolvió el closure (aquí las acciones de la lista de reproducción) y .response dice dónde se dibujó.

Con qué ventanas se abre una canción

Lo que estudias en una canción son sus compases y acordes; lo que editas en un ritmo son los pasos de un patrón. Así que la app decide qué mostrar según lo que se abrió:

#![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();
}
}

Las demostraciones de canciones, Archivo > Nuevo y una hoja de acordes importada llaman a show_chord_sheet; Archivo > Nuevo ritmo llama a show_beat. Abrir un archivo guardado deja las ventanas como están, porque las elegiste tú. Una demostración es una canción o un estilo, un enum, y solo las canciones se abren en la hoja:

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

La aplicación misma se abre con las ventanas que estaban abiertas la última vez que se cerró. app/windows.rs las guarda como un struct pequeño de bool, uno por cada ventana del menú Ver:

#![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,
}
}

Su Default es la primera vez: la hoja de acordes, las teclas de armonía y la Biblioteca sobre la lista de reproducción, sin rack. #[serde(default)] en el struct rellena una ventana añadida más tarde a la lista con su valor en Default, así que una copia guardada más antigua se sigue leyendo. El editor de estilos y los diálogos quedan fuera: cada uno se abre para algo, un estilo o una pregunta, que la siguiente ejecución no tiene.

App::save, a la que eframe llama cada 30 segundos y cuando se cierra la ventana, escribe el struct entre las preferencias guardadas por nombre (ver Guardado por nombre, no por tipo), y LineupApp::new lo vuelve a leer:

#![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();
}

Escribirlas solo al guardar, en lugar de a cada clic en un botón de ventana, libra de esa tarea a los muchos lugares que abren y cierran ventanas. the_app_first_opens_on_the_chord_sheet_then_with_the_windows_left_open comprueba las dos ejecuciones: la primera se abre en la hoja, y después de cerrarla con F5 y abrir el mezclador con F9, el siguiente arranque encuentra el mezclador abierto y la hoja cerrada.

Ventanas del tamaño de lo que muestran

egui recuerda el tamaño de cada ventana y lo guarda con el resto de su memoria cuando la app se cierra. Eso está bien para una ventana en la que trabajas, como el piano roll: la hiciste grande porque la querías grande. Está mal para una ventana que es tan grande como lo que muestra: arrastra el mezclador a lo ancho una vez, y desde entonces se abriría por toda la lista de reproducción, con sus canales en una esquina. Así que hay dos tipos de ventana:

#![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,
}
}

El mezclador, la lista de atajos, el entrenamiento auditivo, la serie dodecafónica, los conjuntos de clases de alturas y los micromodos se abren cada vez al tamaño de su contenido, hasta la altura de la lista de reproducción, y hacen scroll más allá. El piano roll, la hoja de acordes, la partitura guía y Ajustes se abren a su propio tamaño la primera vez después de que la app arranca, y conservan el tamaño que les des mientras se ejecuta.

widgets::open_at lo hace. Averigua si la ventana se está abriendo ahora (no se dibujó en el último frame) y, si es así, le da un tamaño fijo para ese único 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
}
}

Tres cosas en él merecen una mirada:

• std::mem::replace(place, new) pone new en place y devuelve lo que había. Aquí lee «¿se había abierto antes esta ventana?» y la marca como abierta, en un solo paso. La bandera se guarda con get_temp_mut_or, que egui no guarda, así que vuelve a ser false cada vez que la app arranca.
• egui acomoda una ventana a medida que la dibuja, así que en su primer frame la ventana se dibuja antes de que nada sepa cuán grande es su contenido. request_discard le pide a egui que tire ese frame y lo dibuje otra vez; solo ves el segundo, ya al tamaño correcto.
• El «tamaño» dado es un ancho estrecho y la mayor altura. egui agranda una ventana para que quepa un contenido más ancho, pero nunca la hace más alta que él, así que la ventana acaba exactamente tan grande como lo que muestra. Para que eso funcione, nada en ella puede llenar todo el espacio que se le da, como un scroll area que no se encoge hasta su contenido.

Una ventana cuyo contenido cambia mientras está abierta, como el mezclador cuando se añade un canal o el rack cuando otro patrón tiene menos canales, se ajusta otra vez con fit_when_changed. Calcula el hash de un resumen del contenido (el nombre y el instrumento de cada canal, por ejemplo) y ajusta la ventana otra vez cuando el hash cambia.

Clics que hacen lo que querías decir

Dos ayudantes de widgets.rs hacen que las cuadrículas respondan al clic que querías hacer.

Un toque rápido. En un touchpad, un toque puede pulsar y soltar el botón dentro de un mismo frame. El press_origin() de egui se olvida en cuanto el botón está arriba, así que en ese frame es None. press_pos lee en cambio la pulsación de la lista de eventos del frame, que además dice dónde bajó el botón, no dónde está el puntero al final del 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 recorre los eventos hasta que el closure devuelve Some, y devuelve eso. Option::is_none_or se lee bien aquí: «no se pidió ningún botón, o es este».

Un clic que cierra un menú. Abre una lista desplegable y haz clic en la cuadrícula para cerrarla: egui cierra el menú, pero el clic también llega a la cuadrícula, que dibujaría una nota, colocaría un clip o encendería un paso. En la mayoría de los programas ese clic solo cierra el menú. Así que al principio de cada frame, antes de dibujar nada y mientras el menú que se va a cerrar sigue abierto, la app recuerda si el botón que ahora está abajo bajó mientras había un menú abierto:

#![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;
        }
    });
}
}

Las cuadrículas preguntan dismissing(ctx) e ignoran la pulsación, el arrastre y la soltada que le pertenecen. El valor vive en la memoria temporal de egui, un lugar cómodo para un poco de estado compartido entre widgets que no se conocen entre sí.

Recordar entre ejecuciones

egui guarda algo de estado propio entre frames en su memoria: el factor de zoom, dónde está cada ventana, cuán ancho es un panel que se puede redimensionar. eframe puede guardar esa memoria cuando la app se cierra y cargarla cuando arranca. Solo lo hace con su feature persistence, que viene apagada por defecto porque trae serde y ron. Encenderla es una línea en el Cargo.toml del workspace:

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

Con ella, eframe recuerda también el tamaño y la posición de la ventana principal. Escribe un archivo llamado app.ron en el lugar donde cada sistema guarda los datos de las apps (en Linux, ~/.local/share/ferrouslineup/), cada 30 segundos y cuando se cierra la ventana.

La app guarda la mayoría de sus propias elecciones duraderas en la misma memoria, con insert_persisted en lugar de insert_temp: los zooms de las áreas, los ajustes, los archivos recientes, los filtros de la biblioteca. Cada módulo guarda lo suyo bajo un Id propio, y eframe los guarda todos juntos. Lo que se guarda con insert_temp se olvida al cerrar la app.

Guardado por nombre, no por tipo

egui encuentra un valor en su memoria por dos cosas: el Id bajo el que se guardó y su tipo de Rust, a través del TypeId del tipo. Un TypeId es un número que el compilador calcula a partir de la ruta del tipo, sus campos y el crate en el que está, y la parte del crate cambia con la versión del crate y con la versión del compilador. Así que después de una actualización de la app, o de compilar con un Rust más nuevo, o de añadir un campo al tipo, get_persisted busca bajo un número nuevo y no encuentra nada: el ajuste vuelve a su valor por defecto, y el valor viejo queda sin leer en app.ron. El SoundFont lo mostró: con el mismo app.ron, la versión 0.4.0 tocaba con GeneralUser GS y una compilación numerada 0.4.1 lo tenía desactivado.

eframe tiene un almacenamiento propio, el mismo app.ron, que encuentra los valores por un nombre: un &str que no cambia sea cual sea la versión. eframe se lo da a la app solo dos veces: como cc.storage cuando la app arranca, y a App::save, cada 30 segundos y al cerrar la ventana. El módulo app/preferences.rs une las dos cosas. Guarda cada preferencia por nombre, escrita como texto RON, en un único mapa:

#![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>>>);
}

Un acceso al mapa vive en la memoria temporal de egui, así que cualquier código con el Context llega a él, como a cualquier otro valor guardado ahí:

#![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);
    }
}
}

La app lee el mapa del almacenamiento de eframe antes de crear nada más,

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

guarda otro acceso a él, y se lo devuelve a eframe para que lo escriba:

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

El Arc<Mutex<…>> deja que los dos accesos compartan un mismo mapa. El bloqueo se mantiene solo mientras se lee o se escribe una línea, y solo lo toma el hilo de la ventana. Como los valores son texto RON hasta que se piden, un tipo puede cambiar sus campos y seguir leyendo lo que guardó una versión anterior, con #[serde(default)] para los campos que todavía no existían.

Los ajustes de sonido (SoundFonts y General MIDI) se guardan así, como "sound-font", y también las ventanas abiertas, como "open-windows". Las demás elecciones de arriba siguen en la memoria de egui, así que una actualización puede olvidarlas; pasar una al nuevo sistema es cuestión de llamar a preferences::get y preferences::set con un nombre en lugar de get_persisted e insert_persisted con un Id.

Features de Cargo

Una feature es un interruptor que ofrece un crate para encender código opcional. Dentro de eframe, el código que guarda la memoria está detrás de #[cfg(feature = "persistence")], así que sin la feature ni siquiera se compila. Encender una feature en un crate puede encender features en otros: la persistence de eframe enciende la de egui, que añade derives de serde a los tipos que egui guarda en su memoria. Puedes ver lo que ofrece un crate en la tabla [features] de su Cargo.toml, o en su página de docs.rs.

Dibujos pintados, no escritos

Los cinco botones de ventana de la barra de herramientas y los interruptores de cuenta de entrada y metrónomo son botones cuadrados con un dibujo; el nombre, lo que muestra la ventana y su tecla aparecen cuando el ratón está encima. Un emoji sería la manera fácil de dibujar algo así, pero un emoji es un carácter, dibujado por una fuente, y algunos sistemas no tienen ninguna fuente con esos caracteres: allí los botones mostrarían cajas vacías. Así que los dibujos de icons.rs están pintados, con líneas, rectángulos y polígonos, de la misma manera en todos los sistemas.

Cada dibujo es una función sencilla con la misma firma, y Rust puede nombrar esa firma como un tipo:

#![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) es un tipo puntero a función. Cualquier función con esa firma puede guardarse en una variable de tipo Picture, ponerse en un array o pasarse a otra función, sin un Box ni un genérico.

Cada dibujo se pinta en un cuadrado, y sus puntos se dan como fracciones del cuadrado, de 0 a 1, para que el mismo dibujo pueda pintarse a cualquier tamaño:

#![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);
    }
}
}

La hoja de acordes es una página con nombres de acordes a dos por línea, el rack tres filas de pasos con algunos encendidos, el piano roll un teclado con tres notas, las teclas de armonía un teclado con dos teclas negras, el metrónomo su cuerpo y su brazo.

La barra de herramientas dibuja sus cinco botones de ventana a partir de un array. Cada entrada guarda el nombre, el bool que dice si esa ventana está abierta, el dibujo y la ayuda:

#![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...
}
}

Hay cinco préstamos &mut de self en un array. El borrow checker lo permite porque cada uno toma prestado un campo distinto: self.chord_sheet.open, self.rack_open, self.piano_roll.open y así. Dos &mut al mismo campo no compilarían.

La prueba every_picture_stays_in_its_square pinta cada dibujo en un cuadrado de 16 puntos y comprueba que ninguna forma se sale de él, y the_window_buttons_open_and_close_their_windows hace clic en cada uno de los cinco y comprueba que su ventana se abre, que el botón se enciende y que un segundo clic la cierra.

Todas las teclas en una lista

Ayuda > Atajos de teclado, o F1, abre una ventana con cada tecla a la que responde la app, sección por sección.

La lista son datos: un Vec de secciones, cada una con un título, una nota sobre cuándo funcionan sus teclas y sus líneas. Las teclas de una línea son de una de cuatro clases:

#![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),
}
}

Donde la app tiene una constante para un atajo, la lista usa esa misma constante: files::SAVE, edit::UNDO, piano_roll::OCTAVE_UP, view::MIXER. Así, si una tecla cambia, la lista cambia con ella. Convertir unas Keys en texto usa el format_shortcut de egui, que escribe «Ctrl+Shift+Z» en Linux y Windows y «⇧⌘Z» en un Mac, como lo escriben los menús.

Como la lista son datos, también se puede probar como datos. no_two_global_shortcuts_share_a_key reúne las teclas de las secciones que funcionan en cualquier sitio y falla si alguna tecla aparece dos veces, porque esa tecla haría dos cosas a la vez.

Ayuda: el manual y Acerca de

Ayuda > Manual de usuario abre las páginas web del manual de usuario en el idioma de la app. La dirección vive en una función de about.rs, así que el menú Ayuda y la ventana Acerca de se la piden a ella:

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

El match no tiene rama _ a propósito. Añade un tercer idioma, y el compilador se detiene aquí hasta que decidas qué manual reciben sus lectores. pub(super) hace que manual se vea desde app.rs y desde los módulos que tiene dentro, como shortcuts.rs, donde está el menú Ayuda, y desde ningún otro lado.

En el menú, el botón le pide a egui que abra esa dirección en una pestaña nueva del navegador:

#![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();
}
}

Ayuda > Acerca de Ferrous Lineup dice qué versión estás usando, con qué licencia, y dónde encontrar el manual de usuario, este libro (cada uno también en PDF), el código y la lista de problemas conocidos. Es lo primero que hay que mirar antes de informar de uno.

Todo lo que dice sobre el programa sale de Cargo.toml, leído mientras se compila el programa:

#![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!("NOMBRE") es una macro que el compilador sustituye por el valor de la variable de entorno NOMBRE mientras compila, como un &'static str. Cargo pone CARGO_PKG_VERSION, CARGO_PKG_DESCRIPTION, CARGO_PKG_REPOSITORY y algunas más a partir de la sección [package] de Cargo.toml (la app toma su versión, su licencia y su repositorio del [workspace.package] del workspace). Una variable que no existe es un error de compilación, no una sorpresa para el usuario.
• concat! junta literales en uno solo en tiempo de compilación, así que ISSUES también es una constante. Ahí no se podría usar format!: construye un String mientras el programa se ejecuta, y una const tiene que conocerse antes.

Así, cuando un lanzamiento cambia la versión en Cargo.toml, la ventana cambia con ella, y nadie tiene que acordarse de un segundo sitio. Las compilaciones de lanzamiento comparan la etiqueta con este mismo número.

El dibujo es el mismo que el escritorio muestra para la ventana de la app: WINDOW_ICON, 256 × 256 píxeles de bytes rojo, verde, azul y alfa, incluidos en el programa con include_bytes!. egui dibuja las imágenes a partir de texturas, imágenes guardadas en la tarjeta gráfica, así que los bytes se convierten en una textura la primera vez que se abre la ventana y se guardan en la memoria de egui:

#![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
}
}

Un TextureHandle funciona como un Arc: un clon es barato, y la textura sigue en la tarjeta gráfica mientras viva algún clon. El que se guarda en la memoria de egui hace que la imagen se envíe a la tarjeta una sola vez, no en cada frame. WINDOW_ICON es una constante de main.rs, sin pub; about.rs puede leerla igualmente como crate::WINDOW_ICON, porque un elemento privado es visible en su propio módulo y en todos los módulos que hay dentro de él.

ui.hyperlink_to(texto, url) dibuja un enlace. Al pulsarlo no se abre el navegador directamente: egui añade un OutputCommand::OpenUrl a lo que devuelve el frame, y eframe pide al sistema que abra la dirección. Eso hace que el clic sea fácil de probar. help_about_shows_the_version_the_license_and_where_the_book_is abre Ayuda > Acerca de Ferrous Lineup, comprueba que la línea de la versión y cada enlace se dibujan, pulsa El libro y comprueba que el frame pidió la dirección del libro, sin que se abra ningún navegador. help_user_manual_opens_the_manual_in_the_apps_language hace lo mismo con Ayuda > Manual de usuario, en inglés y en español.

Probar una ventana sin pantalla

Todas las pruebas nombradas en este capítulo dibujan la app sin pantalla. egui::Context::run_ui (o run_pass) toma la entrada de un frame, la posición del ratón, las teclas y los clics, y devuelve todo lo que egui le pasaría a la tarjeta gráfica, sin dibujarlo. Una prueba puede entonces encontrar un widget por su Id o su texto, comprobar dónde quedó, hacer clic en él en el frame siguiente y leer el estado de la app. app/ux_tests.rs tiene la mayoría; Cómo se prueba el código cuenta el resto.

Hay un detalle de estas pruebas que conviene conocer. Lo que devuelve run_ui incluye la textura de la fuente. egui comprueba, solo en las compilaciones de depuración, que una textura así no se descarta sin usarse, y si pasa, entra en pánico. Así que las pruebas que se quedan con la salida la vacían antes:

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

Una prueba que pasa en una compilación de release y falla en una de depuración suele ser una de estas comprobaciones: debug_assert! solo se compila en las compilaciones de depuración, y una librería puede tener muchas. Por eso la CI ejecuta las pruebas en una compilación de depuración.

Los editores: rack de canales, piano roll y lista de reproducción

Archivos: 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 y crates/lineup-app/src/app.rs

Tres ventanas editan la música en sí. La lista de reproducción llena la ventana principal: patrones colocados como clips sobre pistas, que juntos forman la canción. El rack de canales (F6) muestra un patrón como filas de pasos, una fila por canal. El piano roll (F7) muestra un canal de un patrón como notas sobre una cuadrícula, con las notas agudas arriba. El rack y el piano roll flotan sobre la lista de reproducción, como cuenta el capítulo anterior.

Las tres están hechas de la misma manera, y eso es lo primero de lo que trata este capítulo.

Dibujar devuelve acciones

Ninguno de los editores cambia el proyecto. Cada uno solo lo mira y devuelve lo que hizo el usuario, como una lista de acciones. Las del rack son un 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 es un préstamo compartido: la función puede leer el proyecto pero no cambiarlo, y el compilador lo hace cumplir. Después la app aplica las acciones:

#![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 devuelve None cuando la ventana está cerrada, y su inner es None cuando la ventana está plegada, así que las acciones vienen envueltas dos veces. .and_then(|window| window.inner) desenvuelve el Option de fuera y devuelve el de dentro; .unwrap_or_default() convierte None en un Vec vacío.

Esta separación también resuelve un rompecabezas de préstamos. Mientras el rack se dibuja, tiene un préstamo compartido del proyecto, así que no podría cambiarlo a la vez (eso necesitaría un &mut al mismo tiempo, cosa que el borrow checker prohíbe). Reunir primero las acciones y aplicarlas cuando el dibujo ha terminado mantiene los dos préstamos separados en el tiempo.

apply es un único match con una rama por acción. Cada rama que cambia la canción pasa por edit o edit_pattern, que llevan el historial de deshacer y le dicen al hilo de audio qué cambió (ver Decirle al hilo de audio lo que ha cambiado):

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

La misma acción hace lo mismo venga de donde venga: un clic, una tecla o un menú. El piano roll devuelve RollAction y la lista de reproducción PlaylistAction, y la app las aplica de la misma manera.

El patrón seleccionado

El rack y el piano roll muestran un patrón, el seleccionado. La app lo guarda:

#![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,
    // ...
}
}

Es un campo de la app, no del proyecto: es dónde estás mirando, no parte de la canción, así que no se guarda, y seleccionar un patrón no cuenta como un cambio sin guardar. Los editores lo reciben como argumento, así que siguen siendo funciones de lo que se les da.

El cursor de reproducción que reciben depende del modo. En el modo patrón, el paso del hilo de audio es un paso del patrón seleccionado. En el modo canción es un paso de la canción, y la app le pregunta al proyecto dónde está el patrón seleccionado en ese momento:

#![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 busca un clip del patrón, en una pista que no esté silenciada, que cubra el paso de la canción, y devuelve None si no hay ninguno. Así, mientras suena la canción, el cursor del rack corre cada vez que suena un clip del patrón seleccionado, y desaparece en los compases donde no.

El rack de canales

Escribir tus propios widgets

egui tiene botones y deslizadores, pero no botones de paso ni perillas. Hacer uno lleva tres movimientos: reservar espacio, leer el ratón, pintar.

#![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 reserva un rectángulo en la distribución y dice qué interacciones queremos (Sense::click()). Devuelve el rectángulo y un Response que describe lo que hizo el ratón ahí en este frame. step_size(ui) es el tamaño del paso multiplicado por el zoom del rack.
• is_rect_visible se salta el pintado de las filas que quedan fuera de la vista.
• El Painter dibuja formas. Los colores son constantes Color32 definidas arriba del archivo, así que la paleta vive en un solo sitio.
• lerp_to_gamma mezcla algo de naranja en el paso que suena, un poco menos en un paso encendido, para que un paso encendido siga blanco.
• Devolver el Response permite a quien llama usarlo como cualquier widget de serie: if response.clicked() { ... }.

Los pulsos alternan colores, para que puedas contarlos, y vuelven a empezar en cada compás para que todos los compases se vean iguales: en 3/4, oscuro, claro, oscuro. El rack le pregunta al compás en qué pulso cae cada paso (time.beat_at(step).index), así que en 6/8 agrupa sus pasos de tres en tres.

La perilla usa Sense::click_and_drag(), convierte el movimiento vertical del ratón en un cambio de valor, y llama a response.mark_changed() para que quien la llama pueda usar .changed() como en un deslizador. Su aguja se dibuja con un poco de trigonometría: el ángulo recorre 270 grados, y (sin, -cos) del ángulo da la dirección (la y de la pantalla crece hacia abajo, de ahí el menos).

Menús

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

context_menu abre un menú con el clic derecho; menu_button abre uno con un clic normal (el botón «Añadir canal»). Los dos reciben un closure que dibuja el contenido del menú, y ui.close() cierra el menú tras una elección. add_enabled_ui(false, ...) pone en gris todo lo que hay dentro, y así se desactiva «Añadir canal» cuando el rack está lleno:

#![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| { /* ... */ });
});
}

Arrastrar y soltar

egui informa de los archivos que se arrastran sobre la ventana en input.raw.hovered_files, y de los que se sueltan en input.raw.dropped_files. Mientras dibuja, el rack guarda el rectángulo de cada fila; después busca la fila que está bajo el ratón:

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

position devuelve el índice del primer elemento para el que el closure es verdadero, o None. Un archivo WAV soltado sobre una fila sustituye el sonido de ese canal; un archivo soltado en cualquier otro sitio se convierte en un canal nuevo con el nombre del archivo (path.file_stem() es el nombre del archivo sin su extensión). Un archivo de proyecto, MIDI o de hoja de acordes, o una grabación, se deja para la app, que lo abre o lo importa.

La carga ocurre en LineupApp::load_sample, en el hilo de la ventana, porque leer archivos es lento y nunca debe ocurrir en el hilo de audio. Lee el archivo antes de cambiar nada, así que un archivo roto deja el canal como estaba y pone la razón en la barra de estado.

Una fila de luces sobre los pasos

Una caja de ritmos tiene una fila de lucecitas, una sobre cada paso, y la luz sobre el paso que suena corre junto con la música. El rack también tiene esa fila. Las luces deben quedar exactamente sobre los pasos, pero los pasos empiezan después de la luz de silencio, la perilla, el candado y el nombre del canal, y sus anchos cambian con el zoom del rack. En lugar de sumar esos anchos (y equivocarse la próxima vez que se añada un control a una fila), el rack deja que las filas se lo digan:

#![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 reserva una franja vacía arriba, así que las filas van debajo. Cada row devuelve dónde empiezan sus pasos (ui.cursor().left() justo antes del primer paso); get_or_insert guarda el valor de la primera fila e ignora los demás. Cuando las filas terminan, step_lights pinta en la franja reservada. egui dibuja todo al final del frame, así que pintar en un espacio reservado antes no es problema.

step_lights recibe un slice de StepMark, un enum pequeño que dice si cada paso empieza un compás, empieza un pulso o ninguna de las dos cosas:

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

La luz sobre el primer paso de cada compás es un poco más brillante que las demás, y la luz sobre el primer paso de cada pulso un poco más brillante que las de los pasos intermedios, así que la fila se puede contar como los pasos que tiene debajo. Cada luz se coloca un ancho de paso (el botón más el hueco que lo sigue) después de la anterior, la misma aritmética que usa el mini piano roll, así que luces, botones y vistas previas se alinean con cualquier zoom.

Un mini piano roll para las melodías

Un canal cuyas notas son todas pasos simples muestra botones de paso. Cualquier otro canal muestra widgets::mini_roll, un dibujo diminuto de sus notas, y un clic en él abre el piano roll. El widget tiene que alinearse con los botones de paso, que tienen un hueco entre ellos:

#![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);
}

El rango de alturas se comprime en la altura de la fila, pero nunca menos de una octava, para que tres notas cercanas no llenen la fila de arriba abajo:

#![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 es un closure que crea un iterador nuevo cada vez que se le llama, porque min y max gastan uno cada uno. La columna que suena se rellena de un naranja transparente (gamma_multiply(0.25) deja el color a una cuarta parte de su fuerza), igual que se tiñen los botones de paso.

La batería en otro patrón, y un rack que se ajusta

Las canciones suelen guardar su batería en un patrón propio, «Batería de A» junto a «A». El rack de «A» mostraría filas de batería sin nada, y parecería roto. Así que cuando un patrón no tiene pasos de batería y otros sí, drums_elsewhere lo dice encima de las filas, con un botón para cada uno de esos patrones.

El rack se abre tan grande como sus filas. natural_size las suma (los controles, los pasos, las luces, el menú «Añadir canal», sitio para una barra de desplazamiento), y la ventana recibe ese tamaño durante un frame cada vez que las filas cambian, como las ventanas del tamaño de lo que muestran. Se puede hacer más pequeña igualmente, y entonces se desplaza. Cuando caben todas las filas, la rueda del ratón sola desplaza los pasos hacia los lados. egui tiene un ajuste de estilo justo para eso, que funciona cuando el scroll area permite una sola dirección:

#![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])
}

El piano roll

Una ventana con estado propio

El rack de canales es una función: todo lo que muestra sale del proyecto. El piano roll necesita recordar cosas que el proyecto no conoce, de un frame al siguiente: qué canal muestra, qué dibuja un clic, las notas seleccionadas, un arrastre en curso. Así que es un struct con métodos:

#![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,
    // ...
}
}

Aun así nunca cambia el proyecto él mismo. show devuelve una lista de RollAction, como hace el rack:

#![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,
    // ...
}
}

Así que el struct guarda estado de la vista, que nunca se guarda en el archivo, y el proyecto guarda el estado del documento (las notas), que sí.

La ventana se construye así:

#![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;
}

• El título cambia con el patrón y el canal, y egui normalmente identifica una ventana por su título. .id(...) le da en cambio una identidad fija, para que conserve su posición y su tamaño cuando cambias de canal.
• .open(&mut open) añade el botón de cerrar: egui pone open a false cuando se pulsa.
• Si la ventana tomara prestado &mut self.open mientras el closure toma prestado &mut self (para llamar a self.contents), self.open quedaría prestado de forma mutable dos veces a la vez, cosa que Rust prohíbe. Copiar el bool fuera y volver a meterlo evita el solape.

Píxeles y música: Grid

Casi todo el código de dibujo convierte pasos y alturas en posiciones de pantalla, o la posición del puntero de vuelta en un paso y una altura. Esa aritmética vive en un solo sitio:

#![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
}
}

Las notas agudas están arriba, así que la fila cuenta hacia abajo desde HIGHEST. cell_at limita el valor, así que un arrastre que sale de la cuadrícula sigue obteniendo la celda más cercana, y devuelve una tupla, (usize, Note), que quien llama desarma con let (step, pitch) = grid.cell_at(pos);. note_rect dibuja una nota desde su inicio exacto hasta su final exacto, incluido cuánto se aparta del paso, así que un tresillo queda entre dos pasos, como se oye.

Como Grid es Copy y sus métodos toman self por valor, se puede pasar a todas las funciones de dibujo sin ningún & ni lifetimes. Para un struct de unos pocos números, copiar es tan barato como pasar una referencia.

Al 100% el patrón entero cabe a lo ancho de la ventana, así que el ancho del paso se calcula en cada frame a partir del ancho de la ventana. Al hacer zoom los pasos se ensanchan, y la cuadrícula se desplaza hacia los lados bajo el teclado.

Un teclado que se queda, carriles que siguen

La cuadrícula está dentro de un scroll area, pero dos cosas no deben desplazarse con ella. Las teclas del piano se dibujan en el borde izquierdo de lo visible (keys_left: visible.left()), encima de la cuadrícula, así que las notas se deslizan por debajo. El carril de acordes sobre la cuadrícula y el carril de velocidad debajo se dibujan fuera del scroll area, así que no saben cuánto se ha desplazado la cuadrícula. Un struct pequeño lleva lo que necesitan para alinearse:

#![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,
}
}

Cada carril construye su propia Grid a partir de él (Lanes::grid), desplazada por scroll_x, y usa las mismas funciones que la cuadrícula de notas para encontrar dónde está un paso. Una única fuente de verdad para «¿dónde está el paso 12?» es lo que mantiene alineadas tres franjas dibujadas por separado.

La entrada del ratón como una pequeña máquina de estados

egui informa de lo que hace el ratón en este frame. Un arrastre dura muchos frames, así que el piano roll lo recuerda en un 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 es largo, pero cada parte responde a una pregunta:

1. ¿Se acaba de pulsar el botón izquierdo sobre la cuadrícula? Si dio en una nota, empieza un Move, o un Resize si la pulsación fue cerca del extremo derecho de la nota. Si dio en una celda vacía, añade lo que dibuja un clic (una nota o un acorde); una sola nota nueva también empieza un Move, para que puedas colocar y arrastrar en un solo gesto.
2. ¿Está el botón derecho pulsado sobre una nota? Bórrala. Comprobarlo en cada frame significa que puedes barrer varias notas para borrarlas todas.
3. ¿Está el botón izquierdo arriba? Entonces cualquier arrastre ha terminado.
4. ¿Hay un arrastre en curso? Calcula dónde estaría ahora la nota y, si eso difiere de donde está, envía un ReplaceNote.

La cuarta parte usa una let chain con tres condiciones, y la sintaxis de actualización de structs para cambiar uno o dos campos:

#![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) en un patrón copia la nota fuera del &NoteEvent que devuelve get. Comparar changed != note (gracias al PartialEq derivado) hace que no se envíe nada mientras el puntero se quede dentro de la misma celda, aunque este código se ejecute en cada frame. snapped lleva la altura a la tonalidad cuando Ajustar a la escala está encendido.

Dos detalles hacen que los clics caigan donde se quería. Un clic derecho rápido puede pulsar y soltar el botón dentro de un mismo frame, así que «¿está el botón pulsado?» ya es falso cuando se dibuja el frame. El código pregunta en cambio «¿se pulsó en este frame, o está pulsado?»:

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

Y en el frame en que baja el botón izquierdo, la pulsación se atiende donde el botón bajó, que widgets::press_pos lee de los eventos del frame (ver Clics que hacen lo que querías decir): una mano rápida puede pulsar y seguir moviéndose en el mismo frame.

Cuando el puntero está sobre una celda vacía, el piano roll dibuja el contorno de lo que colocaría un clic, a partir del mismo stamp_notes que usa el clic. Con «Acorde de la tonalidad (séptima)» elegido, ves el acorde entero antes de colocarlo.

La selección guarda notas, no posiciones

La manera más simple de recordar qué notas están seleccionadas serían sus posiciones en la lista del canal: selection: Vec<usize>. El arrastre de una sola nota hace exactamente eso (Drag::Move { index, .. }), y ahí funciona porque nada más cambia la lista durante un arrastre.

Una selección vive mucho más que un arrastre. Mientras hay notas seleccionadas, una herramienta las saca de la lista y pone las nuevas al final, deshacer coloca un proyecto anterior entero, y borrar una nota sube un lugar a todas las que van después. Después de cualquiera de esas cosas, la posición 3 puede ser otra nota, o no ser ninguna nota. Una selección de posiciones seleccionaría en silencio las notas equivocadas, y la siguiente herramienta cambiaría notas que nunca elegiste.

Así que la selección guarda las propias notas:

#![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>,
}

Esto funciona porque un canal nunca tiene dos notas en el mismo lugar: la regla del patrón (misma altura, mismo inicio, mismo desplazamiento) hace único el valor de cada nota, de modo que un valor nombra exactamente una nota. NoteEvent es Copy y PartialEq, así que guardar copias y compararlas es barato y fácil.

Al comienzo de cada frame, las notas que han desaparecido se olvidan:

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

Y cuando el piano roll sustituye algunas notas, hace que la selección las siga, de modo que pulsar ↑ tres veces mueve el mismo acorde tres veces:

#![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 es la única puerta por la que pasa todo cambio de grupo: las herramientas, el arrastre de grupo y el carril de velocidad. Ordena las notas nuevas igual que lo hará el patrón, le pregunta al patrón si el cambio está permitido, y solo entonces envía la acción. Ordenarlas también aquí significa que la selección guarda exactamente las notas que estarán en el patrón, y comprobar antes significa que un movimiento rechazado no hace nada en absoluto en lugar de hacer media cosa.

La comparación cuesta un poco: contains recorre la lista entera, así que comprobar cada nota contra la selección lleva un tiempo proporcional al número de notas multiplicado por el tamaño de la selección. Para un piano roll con unos cientos de notas, eso está muy por debajo de un milisegundo. Si algún día importara, un HashSet<NoteEvent> haría cada comprobación de tiempo constante (NoteEvent ya deriva Hash para eso).

Seleccionar con el ratón

Ctrl+clic sobre una nota la añade a la selección, o la quita:

#![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 es «Ctrl» en Linux y Windows y «⌘» en un Mac, así que el mismo código sigue las costumbres de cada sistema.

Ctrl+arrastrar sobre un espacio vacío dibuja un recuadro. Solo se guarda la esquina donde empezó; la selección se reconstruye desde cero en cada frame, a partir de esa esquina y del puntero, así que volver a achicar el recuadro deselecciona notas:

#![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 hace un rectángulo a partir de dos esquinas cualesquiera, en el sentido en que se haya arrastrado el recuadro, e intersects es verdadero cuando dos rectángulos se solapan aunque sea un poco, así que basta con que el recuadro toque una nota.

Mover un grupo

Pulsar una nota seleccionada (en cualquier sitio salvo su extremo derecho, que sigue cambiando el largo) empieza un arrastre de grupo:

#![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,
}
}

En cada frame del arrastre, la posición nueva se calcula a partir de los originales, con la distancia entera desde la celda de inicio hasta el puntero:

#![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));
}

Mover las notas un poco en cada frame (desde moved) sería la manera obvia, pero los pequeños errores se irían sumando: un movimiento rechazado en el borde del patrón se perdería, y las notas acabarían en otro sitio que bajo el puntero. Empezar cada vez desde los originales hace que las notas estén siempre exactamente donde dice el puntero, y arrastrar de vuelta al inicio las deja exactamente como estaban.

Las herramientas (ver Herramientas de edición como funciones simples) se encadenan con Option::and_then: desplazar, y si eso funcionó, transportar el resultado. map ajusta las notas a la tonalidad cuando Ajustar a la escala está encendido, pero solo una vez que se han movido, así que arrastrar una selección un semitono arriba y de vuelta abajo la mete en la tonalidad. filter rechaza después las notas que quedan fuera de las filas que muestra el piano roll. La sustitución va de moved (lo que está ahora en el patrón) a new, y moved se actualiza con lo que devolvió replace.

El arrastre se saca de self mientras se trabaja con él:

#![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 necesita &mut self, el struct entero. Si drag fuera una referencia dentro de self.group_drag, el borrow checker se negaría: una parte de self estaría prestada mientras todo self se presta de forma mutable. Option::take saca el arrastre y deja None, así que drag es un valor aparte y self queda libre; el arrastre se vuelve a poner al final.

Cada frame del arrastre produce un ReplaceNotes, y cada uno pasa por edit_pattern. Aun así forman un solo paso de deshacer, porque un paso sigue abierto mientras se mantiene pulsado un botón del ratón (ver Deshacer y rehacer). Y como el paso ya está abierto, edit no vuelve a copiar el proyecto entero en cada frame; le envía al hilo de audio lo que cambió como mucho cada 50 ms, y el resto al soltar el botón. Nada en el piano roll tiene que saber nada de ninguna de las dos cosas.

Quién recibe las teclas

Las flechas y Suprimir son útiles en el piano roll, pero el rack y la lista de reproducción también las usan, y una tecla que cambia notas en una ventana que no estás mirando sería una sorpresa desagradable. Así que las teclas de los editores van a la ventana en la que se hizo clic la última vez, y a ninguna otra:

#![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 recuerda la capa de la última pulsación (cada ventana es una capa, ver ¿Qué hay bajo el puntero?), en la memoria de egui, y responde si es esta. Una ventana que la app abre por ti, como cuando un doble clic en un clip abre el piano roll, recibe el teclado con widgets::give_keyboard, como si se hubiera hecho clic en ella. La lista de reproducción comparte la capa de fondo con las barras de herramientas, así que para ella también importa el lugar del clic (editor_keyboard_in). Las teclas se ignoran mientras un campo de texto tiene el teclado, para que escribir el nombre de un patrón nunca mueva notas, y mientras hay un menú abierto.

Espacio, que toca y detiene, tiene el problema contrario: debe funcionar en todas partes, pero egui también deja pulsar con Espacio un botón que tiene el foco. Haz clic en ▶ Play, pulsa Espacio, y el atajo detendría la música mientras el botón la volvía a poner. Así que los atajos se leen antes de dibujar ningún panel, y consume_key se lleva la pulsación una vez usada:

#![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...
}
}

El orden de los atajos de teclado

Cada tecla es un KeyboardShortcut: una tecla y sus modificadores.

#![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 es una const fn, una función lo bastante simple como para ejecutarse mientras se compila, y por eso sus resultados pueden ser const. Son pub(crate) para que la lista de Ayuda > Atajos de teclado use las mismas constantes (ver Todas las teclas en una lista).

El piano roll le pregunta a egui si se pulsó cada uno con input.consume_shortcut(&shortcut). Eso devuelve true una vez, y «consume» la pulsación para que nada más reaccione a ella. Un detalle de egui importa aquí: compara los atajos de forma lógica, lo que significa que unas teclas Mayús o Alt de más no impiden la coincidencia. Mayús+↑ cuenta también como una pulsación de ↑. Comprobados en el orden equivocado, Mayús+↑ se lo comería el atajo de «subir un semitono» antes de que el de «subir una octava» llegara a verlo. Así que la lista va de lo más específico a lo menos:

#![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 se detiene en el primer atajo pulsado, así que como mucho se usa una herramienta por frame, y a los atajos más cortos de después ni siquiera se les pregunta.

Un enum para el menú y las teclas

El menú Herramientas y las teclas producen los dos una 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,
}
}

y use_tool convierte cualquier Tool en una llamada a la función correspondiente de lineup_core::tools, seguida de replace. Una herramienta cambia las notas seleccionadas, o todas las notas cuando no hay ninguna seleccionada; Borrar solo borra una selección. Venga del menú o de una tecla, una herramienta sigue exactamente el mismo camino, así que las dos nunca pueden comportarse distinto. El menú muestra la tecla de cada herramienta a su lado, escrita como el sistema escribe las teclas, así que sirve también como lista de atajos.

Un menú que se queda abierto

Los menús de egui se cierran con cualquier clic dentro de ellos, que es lo correcto para una lista de órdenes. Pero el menú Herramientas también tiene opciones: el orden y la velocidad del arpegio. Cerrar el menú al elegir «arriba y abajo» te obligaría a abrirlo otra vez para pulsar «Arpegiar los acordes». Así que a este menú se le dice que se cierre solo con un clic fuera de él, y cada herramienta lo cierra a mano:

#![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 es un closure guardado en una variable y llamado muchas veces. Asigna a picked, una variable de fuera, así que toma prestado picked de forma mutable mientras exista el closure, y hay que declararlo let mut item (llamarlo cambia lo que capturó: es un FnMut). El ui se le pasa como argumento en cada llamada en lugar de capturarlo, porque el código entre las llamadas también usa ui, y un closure que lo retuviera lo bloquearía. Los menús que tienen un campo de texto, como el menú de sección de la lista de reproducción, se quedan abiertos de la misma manera, para que un clic en el campo no los cierre.

Notas fantasma: oír los otros canales

Un acorde a menudo se reparte entre instrumentos: el pad toca Do y Sol, el bajo toca Mi, y juntos forman C/E. Mirando solo el canal que se edita, el piano roll diría «C5» (un power chord) donde tú oyes C/E.

Así que el piano roll puede escuchar también a los otros canales. No a todos: los canales de batería tienen pasos simples, y un bombo no forma parte de la armonía. Un canal cuenta si alguna de sus notas no es un paso simple:

#![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 es la lista de canales cuyas notas cuentan para la armonía: este, y los otros cuando «Notas fantasma» está marcado. La línea que nombra el acorde bajo el puntero, las sugerencias de acorde siguiente y los nombres de las notas reciben todos heard, y reúnen sus notas con una pequeña función auxiliar:

#![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 llama al closure por cada canal, recibe cada vez un iterador de notas, y los une todos en un solo iterador, como si las notas de los canales fueran una sola lista.
• El resultado toma prestados pattern y channels, así que no debe sobrevivirlos. <'a> nombra ese préstamo, y + 'a en el tipo de retorno dice «este iterador no vive más que 'a». analyze acepta cualquier iterador de notas, así que lee las notas directamente del patrón, sin copiarlas antes a un Vec.
• move hace que el closure tome sus propias copias de lo que usa: step (un número) y pattern (una referencia, que es lo que se copia, no el patrón). Sin move, el closure tomaría prestada la variable step, que pertenece a sounding y desaparece cuando esta devuelve, mientras el iterador sigue vivo.

Las notas fantasma se pintan antes que las de este canal, de modo que las de este canal quedan siempre encima, en gris con un borde fino. Solo se dibujan: los clics miran únicamente las notas de este canal, así que las notas fantasma nunca pueden seleccionarse, moverse ni borrarse por accidente. Cuando ningún otro canal toca melodías o acordes, la casilla aparece en gris, y su texto al pasar el ratón dice por qué.

El carril de acordes: chunk_by, y luego medir

El carril sobre la cuadrícula nombra la armonía. Su primera fila nombra lo que toca este canal en cada paso; su segunda fila, Todo, nombra cómo suena ahí la canción entera, pulso a pulso, tal como lo calcula Oír la armonía. Cada fila une los pasos vecinos con la misma armonía en un solo bloque:

#![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 parte un slice en tramos allí donde el closure dice que dos vecinos no van juntos. Cada run es un slice del vector original, así que no se copia nada. Comparar armonías enteras, y no sus etiquetas, importa: todo grupo de notas sin nombre de acorde lleva la etiqueta «?», y unir por etiqueta convertiría varios acordes distintos sin nombre seguidos en un solo bloque «?» largo, como si se mantuviera un acorde.

Ejecutar analyze en cada paso y en cada frame parece mucho, pero son como mucho unos cientos de bucles pequeños sobre unas pocas notas. Mide antes de optimizar: aquí ni siquiera se nota.

Un nombre tiene que caber en su bloque. Cortado por los bordes, «E7/B» en un bloque estrecho mostraría «7/», que no es un nombre en absoluto, y para quien aprende armonía mirando la pantalla un nombre equivocado es peor que ninguno. egui dibuja el texto en dos pasos. Primero lo compone: elige el glifo de cada carácter en la fuente, y calcula dónde va cada uno y cuánto espacio ocupa el conjunto. El resultado es una galley (el nombre viene de la imprenta: la galera, una bandeja de tipos compuestos en líneas, lista para imprimir). Después pinta la galley. painter.text(...) hace las dos cosas a la vez; para decidir antes de dibujar, los dos pasos se separan:

#![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 compone el texto en una sola línea, y name.size() es cuánto mide de ancho y de alto. Si cabe en el bloque, con un punto de margen a cada lado, se pinta esa misma galley; nada se compone dos veces. galley recibe la esquina superior izquierda del texto, así que el centro se corre hacia atrás la mitad del tamaño. Si no cabe, no se dibuja nada; apuntar al bloque sigue nombrando el acorde entero en la línea bajo la barra de herramientas.

Resaltado de la escala

paint_rows colorea cada fila preguntándole a la escala por su clase de altura, con un match sobre una tupla de dos bool:

#![allow(unused)]
fn main() {
let fill = match (is_root, in_scale) {
    (true, _) => ROOT_ROW,
    (false, true) => SCALE_ROW,
    (false, false) => OTHER_ROW,
};
}

Las teclas de la izquierda llevan un punto en las notas de la tonalidad (naranja para la tónica), y las notas fuera de la tonalidad se dibujan en rojo. La tonalidad es la de la canción allí donde suena el patrón (project.pattern_key), así que un patrón usado después de un cambio de tonalidad se muestra en la nueva. Cambia la tonalidad y todos los colores la siguen en el frame siguiente, porque nada se guarda en caché: el modo inmediato dibuja a partir del estado actual cada vez.

El carril de velocidad

Hacerle sitio

El carril está bajo la cuadrícula. La cuadrícula es un ScrollArea que llena la altura que se le da. Si se le diera toda la altura que queda en la ventana, empujaría el carril por debajo del borde; las ventanas de egui crecen para que quepa su contenido, así que la ventana crecería, la cuadrícula llenaría la nueva altura, el carril volvería a quedar fuera, y la ventana iría creciendo unos píxeles en cada frame. Así que a la cuadrícula se le da exactamente la altura que queda cuando el carril tiene su parte:

#![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);
}

Lo fácil de olvidar es item_spacing: egui pone un pequeño hueco después de cada widget, aquí después del scroll area y después del espacio. Una manera simple de pillar una ventana que crece sola es hacer dos capturas de pantalla con unos segundos de diferencia y compararlas.

Fijar velocidades

El carril es un único widget que detecta clics y arrastres. Mientras el botón está pulsado sobre él, la altura del puntero fija la velocidad, y su posición x elige el paso:

#![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);
}
}

• La altura es una fracción de 0 (abajo) a 1 (arriba), escalada al 1 a 127 de MIDI. clamp la mantiene dentro incluso cuando el puntero sale del carril durante un arrastre. Convertir un float con as nunca da la vuelta (300.0 pasa a 255 y -5.0 a 0), pero 0 sería una nota que no se oye, así que el clamp asegura que la velocidad sea al menos 1.
• Un acorde tiene varias notas en el mismo paso. Cambian todas, salvo que algunas estén seleccionadas: entonces solo cambian las seleccionadas. Así se hace que la nota de arriba de un acorde suene más fuerte que las demás, como hacen los pianistas para destacar una melodía.
• Las notas que ya tienen esa velocidad quedan fuera de old, así que mantener el botón quieto no envía el mismo cambio en cada frame.

Barrer el carril cambia cada paso a medida que el puntero pasa por encima, y todo el barrido es un solo paso de deshacer, como cualquier arrastre.

La velocidad también se ve en la cuadrícula. El color de una nota se multiplica por un factor entre 0,55 y 1 según su velocidad (fill.gamma_multiply(0.55 + 0.45 * f32::from(note.velocity) / 127.0)), así que las notas suaves son más oscuras, pero nunca tanto como para desaparecer.

Encontrar tus notas

El piano roll muestra un canal de un patrón, y esa pareja puede estar vacía mientras la canción suena de lo lindo: los acordes de una canción pueden estar en «Acordes», no en «Ritmo». Una cuadrícula vacía sin una palabra de explicación parece notas perdidas. Así que el piano roll hace dos cosas.

Primero, sigue a las notas. Cuando se abre, o cambia el patrón, y el canal mostrado no tiene notas ahí, pasa al canal con más notas de melodía o de acordes:

#![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 devuelve el último de varios máximos iguales. Comparar la tupla (count, Reverse(channel)) deshace los empates hacia el número de canal más bajo: std::cmp::Reverse envuelve un valor e invierte su orden. Los pasos de batería se dejan fuera a propósito: en un patrón de solo batería, el piano roll no salta al bombo, cuyas «notas» son todas el mismo paso simple. Un canal que elegiste tú, en el rack o en el editor, se conserva.

Para notar que la ventana se abre, el piano roll recuerda si estaba abierta en el frame anterior. open es un campo público que cambian el botón de la barra de herramientas, F7 y el menú Ver, así que este es el único sitio que ve todas las maneras de entrar:

#![allow(unused)]
fn main() {
let opened = self.open && !self.was_open;
// ... at the end of `show`:
self.was_open = open;
}

Al abrirse, también se desplaza al centro de las notas. El centro no se calcula partiendo las alturas por la mitad: con enteros, / tira el resto, y 41 / 2 + 67 / 2 da 53, una fila por debajo del centro de verdad, 54. En cambio, le pide a egui que centre todo el bloque de filas, desde arriba de la nota más aguda hasta abajo de la más grave:

#![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));
}

Segundo, cuando el canal de verdad no tiene notas en el patrón, lo dice sobre la cuadrícula, con botones para ir adonde están las notas:

Encontrar los patrones donde toca el canal es un filtro sobre todos ellos, que conserva el índice (para seleccionarlo) y el nombre (para mostrarlo):

#![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();
}

El &str del vector toma prestado de project. Eso está bien porque el vector solo vive mientras se dibuja este frame, y project dura más. Un botón para otro patrón no puede seleccionarlo directamente: el patrón seleccionado pertenece a la app. Así que devuelve RollAction::SelectPattern, igual que cualquier otro cambio sale del piano roll.

El mensaje se coloca sobre la cuadrícula en lugar de ocupar una línea encima, para que la cuadrícula no salte hacia arriba cuando se dibuja la primera nota y el mensaje desaparece. Se dibuja después de la cuadrícula, en un Ui hijo colocado encima, y la cuadrícula recuerda dónde se dibujó en el frame anterior (self.banner) y deja en paz los clics de ahí: un clic en uno de sus botones no debe dibujar también una nota debajo.

Conectarlo en la aplicación

La app tiene un PianoRoll y, mientras dibuja las ventanas, llama:

#![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, ...) toma prestado un campo de forma mutable y otro de forma inmutable a la vez, cosa que el borrow checker permite porque son campos distintos. Después apply_roll cambia el patrón con edit_pattern, como hace el rack:

#![allow(unused)]
fn main() {
RollAction::ReplaceNotes { channel, old, new, label } => {
    self.edit_pattern(label, |pattern| {
        pattern.replace_notes(channel, &old, &new);
    });
}
}

Cuando se quita un canal, PianoRoll::channel_removed o bien suelta su canal (ya no existe) o bien baja en uno su número de canal, para seguir mostrando el mismo canal; channel_inserted hace lo contrario cuando deshacer devuelve un canal.

En una ventana baja, de menos de 420 puntos, la cuadrícula va primero: las líneas de ayuda bajo la barra de herramientas pasan al tooltip de la línea que nombra el acorde, así que una pantalla pequeña sigue mostrando una docena de filas de notas.

La lista de reproducción

Una rejilla grande: show_viewport

La lista de reproducción puede ser mucho más grande que la ventana: decenas de compases, y tantas pistas como use la canción. Va dentro de un scroll area. Pero algunas partes no deben desplazarse: los nombres de las pistas a la izquierda, y los números de compás y las franjas de encima arriba.

ScrollArea::show_viewport lo hace posible. Su closure recibe la parte visible del contenido, como un rectángulo medido desde la esquina superior izquierda del contenido:

#![allow(unused)]
fn main() {
let output = area.show_viewport(ui, |ui, viewport| {
    self.grid(ui, viewport, project, current, playhead, &mut actions)
});
}

grid reserva el tamaño entero del contenido, y luego calcula dónde está en pantalla la parte visible:

#![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 es el contenido entero en coordenadas de pantalla (su esquina superior izquierda se mueve hacia arriba y a la izquierda al desplazarte). Sumar esa esquina a viewport da visible, la parte de la pantalla donde se ve el contenido. Entonces:

• las pistas y los clips se dibujan en su lugar dentro del contenido, así que se desplazan;
• los nombres de las pistas se dibujan en visible.left(), y la regla y las franjas en visible.top(), así que se quedan quietos mientras los clips se deslizan por debajo.

Se dibujan después de los clips, así que los tapan.

La aritmética de pasos, pistas y píxeles vive en un pequeño struct Copy, como en el 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,
}
}

Cada pista puede tener su propia altura, así que Layout guarda dónde empieza cada pista (track_tops), calculado una vez por frame. Para encontrar la pista bajo el puntero, cell_at usa partition_point, una búsqueda binaria en esa lista ordenada: el número de comienzos que quedan por encima del puntero, menos uno, es la pista.

Widgets reales en una zona pintada: ui.put

Todo en la rejilla se pinta a mano, pero los nombres de las pistas deben ser campos de texto editables y las luces de silencio deben ser la misma luz que en el rack. ui.put coloca cualquier widget en el rectángulo que elijas:

#![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 });
}
}

• Un closure |ui: &mut Ui| -> Response cuenta como widget: egui implementa su trait Widget para cualquier closure así. Así es como un widget con forma de función, como mute_light, se puede pasar a put.
• El campo de texto edita una copia del nombre. Si cambió, la copia va en una acción RenameTrack, y la app cambia el proyecto. La lista de reproducción mantiene la regla de que nunca cambia el proyecto ella misma.
• Frame::NONE quita el borde del campo, así que parece una etiqueta hasta que haces clic en él.

Colocar, mover y estirar clips

Colocar, mover y borrar clips sigue el modelo del piano roll: una pulsación decide qué es el arrastre, y el arrastre sigue al puntero hasta que se suelta el botón.

#![allow(unused)]
fn main() {
struct ClipDrag {
    index: usize,
    grab: usize,
    stretch: bool,
}
}

Una pulsación en un espacio vacío coloca un clip del patrón seleccionado y empieza a moverlo; una pulsación en un clip empieza a mover ese clip y selecciona su patrón; una pulsación en el borde derecho de un clip empieza a estirarlo, lo que repite su patrón tantas veces como quepan hasta el puntero. La pulsación se atiende donde bajó el botón:

#![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 conserva el valor solo si el closure devuelve true, así que pressed_at es Some solo en el frame de una pulsación, sobre la rejilla.

Las posiciones se ajustan a la rejilla que elijas en la barra de herramientas: un compás, un pulso o un paso. Dónde caen compases y pulsos depende del compás en ese punto de la canción, así que el ajuste le pregunta al Meter de la canción:

#![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 o Mayús y un clic añaden un clip a la selección, Ctrl o Mayús y un arrastre en un espacio vacío dibujan un recuadro alrededor de clips, y arrastrar uno de varios clips seleccionados los mueve todos, sin salirse de la lista de reproducción.

Doble clic en un clip para editarlo

En la mayoría de los programas de música, haces doble clic en un clip para editarlo. egui cuenta los clics:

#![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));
}
}

La app elige el editor: el piano roll, en el canal con más notas, cuando el patrón tiene melodías o acordes; el rack de canales cuando solo tiene batería. En los dos casos la ventana pasa al frente, y se lleva el teclado:

#![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);
    }
}
}

La capa de una ventana se nombra con el id que se le dio a la ventana, y por eso el rack y el piano roll obtienen el suyo de pequeñas funciones (rack_id() y PianoRoll::id()) en lugar de escribir el mismo Id::unique(...) en varios sitios.

Dibujar las notas de un clip: Box<dyn Fn>

Cada clip muestra un esbozo de su patrón. Los patrones de batería se ven mejor como un secuenciador de pasos diminuto (una línea por canal), y cualquier cosa con melodía como un piano roll diminuto (las notas agudas más arriba). Las dos necesitan maneras distintas de convertir una nota en una altura, elegidas una vez por 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)
};
}

Cada closure tiene su propio tipo, sin nombre, así que las dos ramas del if producen valores de tipos distintos, y una variable solo puede tener un tipo. Box<dyn Fn(usize, u8) -> f32> es el tipo común: «un closure en el montículo que recibe un canal y una altura y devuelve una altura en pantalla». dyn Fn es un trait object, como dyn App en main.rs. La palabra clave move hace que cada closure se quede con lo que usa (used, lowest…), que debe sobrevivir al if que los creó.

Esto se ejecuta en el hilo de la ventana, una vez por clip y por frame, así que la pequeña reserva de memoria del Box no importa. En el hilo de audio sí importaría.

El color de un clip es el de su patrón. Cada patrón guarda un color, un lugar en la paleta de la lista de reproducción, guardado en el archivo del proyecto. No sale del número del patrón, porque entonces borrar el primer patrón cambiaría el color de todos los demás.

Solo las pistas que usas

Un proyecto tiene solo las pistas hasta su último clip: Archivo > Nuevo tiene una pista, una demostración tiene las que usa. Debajo de la última pista hay una fila de reserva más tenue: coloca un clip en ella (o arrastra uno hasta ella) y se convierte en una pista. Su cabecera tiene también un botón ➕ Nueva pista.

Project::clip_fits decide si un clip puede ir en un sitio. Se permite una fila más que las pistas, la que está justo debajo de la última pista, siempre que la lista de reproducción no esté llena:

#![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 y move_clip llaman después a open_track, que añade una pista cuando el clip está en esa fila nueva. Como la pista y el clip se añaden en la misma edición, un solo Ctrl+Z quita los dos. La vista de la lista de reproducción solo tiene que dibujar una fila más: Layout tiene su indicador spare y un método rows(), y cell_at limita a rows().

Las demostraciones se construyen sobre una lista de reproducción de dieciséis pistas, porque nombrar la pista 0 y la pista 1 es más fácil cuando existen; al final, remove_unused_tracks quita las pistas vacías de abajo. Los archivos guardados antes de que se recortaran las pistas necesitan casi lo mismo, con una diferencia: una pista que alguien renombró o silenció se dejó así a propósito, así que al cargar solo se quitan las pistas que están exactamente como empieza una pista nueva. Dos reglas, un bucle, que recibe la regla como 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 significa «cualquier función o closure que reciba un número de fila y una pista y responda sí o no». El compilador hace una copia de trim_tracks para cada closure, así que esto no cuesta nada en tiempo de ejecución. Comparar con Track::numbered(index + 1) funciona porque Track deriva PartialEq: una pista en blanco es igual a una completamente nueva para su fila.

Recortar solo quita pistas por debajo del último clip. Una pista vacía en medio se queda, porque quitarla subiría una fila todos los clips de debajo.

Insertar, mover y borrar pistas

Un clip nombra su pista por número. Inserta una pista en la fila 2, y todo clip en la fila 2 o más abajo debe bajar una, o la batería de repente quedaría en la pista equivocada:

#![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 es la imagen en espejo: quita los clips de la pista con retain, y luego sube una fila los de debajo. swap_tracks intercambia dos filas y los clips que hay en ellas. Quien cambia la lista arregla los números que apuntan a ella, y por eso los campos son privados y solo los métodos de Project los cambian (ver El proyecto). Cada uno de ellos es una sola llamada dentro de edit, así que deshacer devuelve una pista borrada con sus clips.

El menú es el context_menu de egui sobre el campo del nombre de la pista. Un campo de texto sigue abriendo un menú con el clic derecho, porque escribir solo necesita el botón izquierdo. El borde inferior de una pista se puede arrastrar para hacerla más alta o más baja, y un doble clic en él le devuelve su altura habitual.

Seguir el cursor de reproducción más allá de los nombres

Con Seguir el cursor de reproducción activado, la lista de reproducción se desplaza para mantener el cursor a la vista. Cuando una canción llega al final y vuelve a empezar, o un bucle vuelve a su inicio, el cursor salta a la izquierda y la vista lo sigue. Pero los nombres de las pistas de la izquierda se dibujan sobre los compases, y para el scroll area no existen: mostrar el cursor podría dejarlo debajo de ellos. Así que a follow_x se le dice cuánto mide la parte fija, y el rectángulo que muestra llega esa distancia más a la izquierda:

#![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 se desplaza lo menos posible para que el rectángulo quede dentro de la vista. Hacia la izquierda, eso deja el borde izquierdo del rectángulo en el borde izquierdo de la vista, covered puntos a la izquierda del cursor, así que el cursor acaba a la derecha de los nombres. La lista de reproducción pasa HEADER_WIDTH (sus nombres), el piano roll KEY_WIDTH (su teclado). Hacia la derecha no cambia nada. Solo un paso nuevo desplaza la vista, así que puedes seguir desplazándote a mano mientras suena la música.

Probar las ventanas

Las herramientas y el proyecto están cubiertos por pruebas unitarias, y muchos comportamientos de los editores por pruebas que dibujan la ventana sin pantalla (ver Probar una ventana sin pantalla). Pero algunos problemas solo aparecen cuando una persona usa la ventana: una ventana que crece un poco en cada frame, un menú que se cierra al elegir una opción dentro de él, un acorde que cae por encima del puntero en lugar de alrededor. Es un buen hábito para cualquier código de interfaz: escribe la lógica para que se pueda probar sin la ventana, y después prueba la ventana igualmente.

Dos idiomas: traducciones, y letras o solfeo

Archivos: 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 y crates/lineup-app/src/app/settings.rs

Dos ajustes cambian cómo te habla Ferrous Lineup:

• Edición > Ajustes… > Apariencia > Idioma (con la app en inglés, Edit > Settings… > Appearance > Language) escribe los menús, las ventanas y los ajustes en English o en Español.
• Edición > Ajustes… > Armonía > Nomenclatura de notas (en inglés, Harmony > Note naming) nombra las notas, las tonalidades y los acordes con letras (C, F#, Bb major, Am7) o en solfeo (Do, Fa#, Sib mayor, Lam7).

Son independientes: puedes tener los menús en español con letras, o los menús en inglés con solfeo. Pero mientras no elijas una nomenclatura, sigue al idioma: con los menús en español las notas se nombran en solfeo, como en las escuelas de habla hispana, y con los menús en inglés, con letras. Cuando eliges una, se queda, cambies después al idioma que cambies. Los dos ajustes cambian solo lo que ves. Una canción guardada con una elección se abre exactamente igual para quien tenga la otra.

Con el español elegido, todo lo que escribe la app está en español: los menús, las ventanas, las ayudas, los avisos y los nombres de las demos, los estilos, los instrumentos y los canales. En inglés solo quedan los mensajes que llegan del sistema operativo o de una biblioteca (por ejemplo, por qué no se pudo abrir un dispositivo de audio) y los nombres de géneros que el español usa tal cual, como swing o funk. Este libro nombra los menús, las ventanas y los botones como los escribe la app en español. La mayoría de las capturas de este libro se hicieron con la app en inglés.

Las notas Do, Re, Mi

En inglés y en alemán, las notas se nombran con letras. En español, italiano, francés y portugués, y en los países que los hablan, se nombran con sílabas:

letras    C    D    E    F    G    A    B
solfeo    Do   Re   Mi   Fa   Sol  La   Si

Los sostenidos y los bemoles se escriben detrás de la sílaba igual que detrás de la letra: Fa sostenido es Fa# y Si bemol es Sib. Una tonalidad se nombra igual, así que Si♭ mayor es Sib mayor (o Sib major con los menús en inglés), y el modo dórico sobre Re es Re dórico.

Esto es el Do fijo: Do es siempre la misma nota, sea cual sea la tonalidad. Algunos métodos de entrenamiento auditivo usan un do móvil, en el que do es la tónica de la tonalidad (en Sol mayor, do es Sol). La app usa siempre el Do fijo, como las escuelas de España y América Latina, porque el nombre de una nota no debe cambiar con la tonalidad.

Los números de octava no cambian: el Do central es C4 con letras y Do4 en solfeo, y cada octava va de Do a Si. Algunos libros franceses y españoles numeran las octavas una más abajo y llaman Do3 al Do central. La app mantiene una sola numeración, así que una nota conserva su número la nombres como la nombres.

Los acordes en solfeo

Un cifrado es una fundamental, una cualidad y, a veces, una nota en el bajo. En solfeo solo cambian los nombres de las notas:

letras    C    Am7     G7/B     Bdim     F#m7b5    Eb+
solfeo    Do   Lam7    Sol7/Si  Sidim    Fa#m7b5   Mib+

A la primera manera se le llama cifrado americano y a la segunda cifrado latino. Las partituras de jazz y de pop suelen ir en cifrado americano, también en español, y por eso este libro escribe así los cifrados; muchos profesores y cancioneros usan el latino. Con el solfeo elegido, la hoja de acordes, las teclas de armonía, el piano roll, los cambios de tonalidad de la lista de reproducción y los ejemplos de las ayudas escriben las notas, las tonalidades y los acordes de la segunda manera.

Escribir un acorde de las dos maneras

Puedes escribir un acorde de cualquiera de las dos maneras, esté elegida la que esté: Am7 y Lam7 son el mismo acorde. Al pulsar Intro, el compás lo muestra como el ajuste nombra las notas.

Unos pocos nombres se pueden leer de las dos maneras. o es una forma de escribir un acorde disminuido (Bo es B°), así que Do podría ser Do mayor (solfeo) o Re disminuido (letras), y Do7 podría ser C7 o D°7. La app lee esos nombres como el ajuste nombra las notas: con el solfeo elegido, Do es Do mayor. Los nombres que solo tienen sentido de una manera se leen de esa manera: Faug es Fa aumentado aunque esté elegido el solfeo, porque «Fa» seguido de «ug» no es un acorde, y Fam es Fa menor aunque estén elegidas las letras.

La cualidad se escribe igual en los dos: Fa aumentado es Faaug en solfeo. Se lee bien, pero Fa+ se ve mejor, y la app también lo lee.

En la hoja de acordes, escribir sobre un compás seleccionado empieza a escribir en él, pero L es la tecla que cambia entre patrón y canción. Con el solfeo elegido, los acordes de La empiezan por L, así que ahí L empieza a escribir. Con las letras elegidas, ningún acorde empieza por L, y L cambia de modo como siempre.

Qué se guarda

Los proyectos, los estilos guardados, el texto de la hoja de acordes que copia Ctrl+C y las trazas de reproducción se escriben siempre con letras, y en inglés. Los ajustes no llegan nunca a ellos. Así que una canción que guardaste viendo Lam7 contiene Am7, y se abre con Am7 o con Lam7 según los ajustes de quien la abra.

En el código

Dos ajustes, guardados como el de los números romanos

Language y NoteNaming (los dos en lineup-core) se guardan como el ajuste de los números romanos en menor: un enum con un #[default], un Cell dentro de thread_local! que toda función puede leer, y un with que lo fija un rato y lo devuelve con un guard en un Drop, incluso tras un 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) };
}
}

Una nota se escribe en cientos de lugares, a través de su implementación de Display ({} en format!). Un valor por hilo permite que todos sigan el ajuste sin pasarlo hacia abajo por cada función:

#![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()))
    }
}
}

La ventana fija los dos valores a partir de los ajustes guardados antes de dibujar cada fotograma:

#![allow(unused)]
fn main() {
pub fn apply_settings(ctx: &egui::Context) {
    language(ctx).set();
    note_naming(ctx).set();
}
}

Una exportación de video dibuja sus vistas en un hilo propio, que empieza con los valores por defecto, así que se lleva el idioma y la nomenclatura consigo, como ya se llevaba el ajuste de los números romanos.

Solfeo hasta que elijas

egui guarda las preferencias de la ventana como valores bajo un Id, y get_persisted da None para un Id bajo el que no se guardó nada. Ese None es lo que distingue «nunca elegido» de una elección, así que la nomenclatura recurre al idioma solo entonces:

#![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,
    }
}
}

Leer nunca guarda nada; solo lo hace set_note_naming, que se llama cuando haces clic en una nomenclatura en los Ajustes. Así que hasta ese clic cada fotograma vuelve a preguntar al idioma, y pasar al español pasa las notas al solfeo. El match no tiene un brazo _ a propósito: un tercer idioma no compilaría hasta que alguien diga cómo nombra las notas.

Traducir: la clave es el texto en inglés

Cada texto que muestra la interfaz está escrito en inglés en el código y pasa por tr. Vive en lineup-core, no en la app, para que también se traduzcan los textos que escribe el núcleo, los nombres de los estilos, los instrumentos, los acordes y las escalas:

#![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)),
    }
}
}

El catálogo en español está en i18n/es.rs: un gran match para los menús, las ventanas principales y los ajustes, y, en los archivos de i18n/es/, tablas de pares por área (la app, la teoría, los instrumentos, la biblioteca, las canciones), reunidas una sola vez en un 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 construye el mapa la primera vez que se usa, en el hilo que lo pida primero, y a partir de ahí todos los hilos lo comparten. flatten convierte las cinco tablas en una sola serie de pares, y collect construye el mapa con ellos.

Usar el propio texto en inglés como clave tiene dos ventajas. El código se sigue leyendo con naturalidad (tr("Settings"), no tr(SETTINGS_TITLE)), y un texto que aún no tiene traducción se queda simplemente en inglés, gracias a unwrap_or_else. El precio es que cambiar un texto en inglés obliga a cambiar también su clave en el catálogo, o se pierde el español; una prueba lo detecta (ver más abajo).

Tanto el argumento como el resultado son &'static str: texto escrito en el propio programa, que vive tanto como el programa. Así tr puede devolver cualquiera de los dos sin copiar nada.

Unos cuantos parientes de tr cubren los demás casos:

• trf("{} steps a bar", &[&12]) pone sus argumentos donde el texto traducido tiene {}, así que el español puede poner el número entre otras palabras: «12 pasos por compás».
• trc("clef", "Bass") es para una palabra cuya traducción depende de dónde se muestra: la clave de fa es «Fa», el instrumento «Bajo». El catálogo la tiene como "clef|Bass".
• tr_name traduce los nombres que la app da a las cosas, un canal, una pista o un patrón: «Bass» es «Bajo», «Pattern 12» es «Patrón 12» y «A drums» es «Batería de A». Un nombre que escribiste tú se queda como lo escribiste.
• Un texto del catálogo puede nombrar notas entre llaves, como en "{Bb} mayor"; se nombran como dice el ajuste (ver Ejemplos que siguen el ajuste). Un texto así se construye una vez para cada nomenclatura y se conserva, con Box::leak, que convierte un String en un &'static str que nunca se libera. Hay un número limitado de textos y dos nomenclaturas, así que la memoria conservada tiene un límite.

Nombres en pantalla, letras en los archivos

Como Display sigue el ajuste, todo lo que convierta una nota en texto y lo guarde guardaría solfeo. Los lugares por donde los datos salen del programa trabajan con letras, a través de 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))?;
    // …
}
}

Un marcador de acorde se guarda como su texto, mediante los atributos de serde into = "String" y try_from = "String" (ver Series dodecafónicas). Sus conversiones también trabajan con letras, así que un marcador se guarda como Am7 lo guarde quien lo guarde:

#![allow(unused)]
fn main() {
impl From<HarmonyName> for String {
    fn from(harmony: HarmonyName) -> Self {
        NoteNaming::Letters.with(|| harmony.to_string())
    }
}
}

Los estilos guardados, el texto de la hoja de acordes y la traza de reproducción hacen lo mismo. Los cifrados de la propia biblioteca están escritos con letras en el código fuente, así que también se leen con letras.

Leer un nombre de las dos maneras

NoteName::read_as lee una nota al principio de un texto con una nomenclatura, y devuelve el nombre y el resto del texto. Para el solfeo prueba cada sílaba:

#![allow(unused)]
fn main() {
NoteNaming::Solfege => Letter::ALL.into_iter().find_map(|letter| {
    text.strip_prefix(letter.solfege())
        .map(|rest| (letter, rest))
})?,
}

strip_prefix devuelve el texto que sigue al prefijo si el texto empieza por él, y None si no. find_map devuelve el primer Some. «Sol» y «Si» empiezan los dos por S, pero ninguno es el principio del otro, así que solo uno puede coincidir.

read_either prueba las dos nomenclaturas, primero la del ajuste, y se queda con la primera lectura cuyo resto encaja (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))
}
}

Qué significa «encajar» depende de quién llama, así que es un closure. Un cifrado encaja cuando el resto es una cualidad y quizá un bajo; un nombre de nota completo encaja cuando no queda nada:

#![allow(unused)]
fn main() {
pub fn parse(text: &str) -> Option<NoteName> {
    NoteName::read_either(text, str::is_empty).map(|(name, _)| name)
}
}

str::is_empty es una función, y una función puede pasarse allí donde se espera un closure con los mismos argumentos.

El lifetime 'a dice que el resto que recibe fits, y que se devuelve, es un trozo de text, no una copia. Así funciona «Faug» con el solfeo elegido: «Fa» deja «ug», que fits rechaza, así que se prueba la lectura con letras, F con «aug», y se queda esa.

Ejemplos que siguen el ajuste

Las ayudas de la hoja de acordes y de los ajustes dan acordes de ejemplo. Se escriben con las notas entre llaves, {A}m7 {D}7, y with_notes nombra cada una como dice el ajuste, así que con el solfeo elegido la ayuda dice «Lam7 Re7». Las llaves alrededor de algo que no es un nombre de nota, como el conjunto {0,1,4} de la misma ayuda, se dejan como están.

L de La

ChordSheet::takes_l dice si una L escrita ahora le corresponde a la hoja: la hoja tiene el teclado, hay un compás seleccionado, todavía no se está escribiendo en él, y las notas se nombran en solfeo. El atajo L de la app lo mira primero:

#![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() está ahí porque, con el teclado para tocar activado, las letras tocan notas, y L cambia entre patrón y canción como siempre.

Fuera de la app

El archivo de escritorio de Linux tiene líneas en español junto a las inglesas, por ejemplo GenericName[es]=Banda de acompañamiento, que un escritorio en español muestra en sus menús. El archivo AppStream que leen las tiendas de software da a cada párrafo de la descripción un gemelo en español, <p xml:lang="es">, y appstreamcli validate lo comprueba.

Las pruebas

every_window_writes_in_spanish abre seis demostraciones en español con todas las ventanas abiertas, y después los atajos, Acerca de, la exportación de video, el editor de estilos, cada página de los Ajustes y cada menú. Falla si algo le pidió a tr un texto que no tiene español en el catálogo, o si algún texto dibujado en pantalla es un texto en inglés que el catálogo sí tiene en español, lo que detecta el texto dibujado sin pasar por tr. En el núcleo, every_name_and_description_the_app_shows_has_spanish hace lo mismo con cada nombre de instrumento, estilo, acorde, escala y demostración que el núcleo le da a la app.

solfege_changes_how_names_look_not_what_is_saved construye cada canción de demostración dos veces, una con letras y otra con solfeo, y comprueba que el archivo guardado y el texto de la hoja de acordes son idénticos, y que cada acorde, escrito como lo muestra la hoja en solfeo, se lee de vuelta como el mismo acorde.

names_are_read_in_letters_or_solfege lee Sib7, Fa#m, Sol y Reb, y comprueba que Do7 empieza por Re con las letras elegidas y por Do con el solfeo. solfege_is_a_way_of_showing_names comprueba que Am7 se muestra como Lam7, G/B como Sol/Si y Si♭ mayor como Sib mayor, y que Lam7 y Am7 son el mismo acorde.

in_solfege_l_types_la_chords_and_in_letters_it_switches_mode selecciona un compás de la hoja de acordes, pulsa L con el solfeo elegido y escribe Lam7, y comprueba que el modo no cambió y que el compás tiene La menor séptima; con las letras, L cambia el modo y deja el compás como estaba.

spanish_names_notes_in_solfege_until_a_naming_is_chosen cambia el idioma de un lado a otro sin nomenclatura elegida, y la nomenclatura lo sigue; luego elige una nomenclatura y vuelve a cambiar el idioma, y la nomenclatura se queda. spanish_names_notes_in_solfege_and_keeps_letters_once_chosen lo hace como lo harías tú: menús en español, Armonía, Letras (C, D, E…) y un reinicio de la app, tras el cual las notas siguen en letras.

Ejercicios: la forma del programa

Estos ejercicios practican el Rust de esta parte sobre el código real. Cada uno dice lo que ya existe, para que lo amplíes en lugar de construirlo otra vez. Algunos son pequeños trabajos con un final claro; los que se llaman «Piénsalo» son preguntas, sin código que escribir.

Hazlos en una rama tuya. Ejecuta cargo test después de cada cambio, y cargo fmt --all --check y cargo clippy --workspace --all-targets -- -D warnings antes de dar uno por terminado: CI ejecuta los tres.

Crates e hilos

1. Rómpelo a propósito (cualquier crate)

Aprender a leer los errores del compilador es la mitad de aprender Rust. Prueba cada una de estas cosas, lee el error y luego deshazla:

• En AudioEngine::new (engine.rs), llama dos veces seguidas a build_stream::<f32>(&device, config.clone(), audio_thread, Arc::clone(&problems)), de modo que la segunda llamada falle porque audio_thread se movió a la primera.
• Quita move del closure del callback de audio en build_stream.
• Añade una variante SetName(String) a Command. ¿Por qué Command no puede ser Copy? ¿Qué variantes ya lo hacen imposible, y qué dice el compilador cuando pides Clone?
• Haz pub el campo de Note (en lineup-core/src/pitch.rs) y escribe Note(200) en app.rs. ¿Por qué compila eso, y por qué es una mala idea?

Practica: propiedad, closures move, tipos Copy y no Copy, privacidad.

2. Piénsalo: el hilo de audio

• ¿Por qué sería peor Command::InsertChannel { instrument: Box<Instrument>, ... } que enviar el instrumento por valor? (Instrument ya mete en una caja sus arrays de voces; ¿qué ganaría una segunda caja?)
• ¿Qué pasaría si la ventana olvidara llamar a collect_garbage?
• Garbage es un único enum con una variante por cada clase de cosa que se tira. ¿Qué costaría una cola de basura por cada clase, y qué ganaría?
• AudioEngine::playhead usa Ordering::Relaxed. ¿Podría la ventana ver alguna vez un número de paso que nunca sonó?

El proyecto

3. Eliminar todas las pistas vacías (lineup-core y lineup-app, fácil)

Eliminar una pista ya existe: lee Project::remove_track y el elemento «Eliminar la pista» del menú contextual de la pista. Quita la pista y sus clips, y sube una posición los clips de las pistas de debajo, igual que hace remove_pattern con los patrones.

Lo que falta es una forma de quitar todas las pistas vacías a la vez. remove_unused_tracks solo quita las pistas vacías del final de la lista de reproducción (llama a trim_tracks). Añade remove_empty_tracks, que quite una pista esté donde esté si no tiene clips, y un elemento para ella en el menú de la pista. ¿Qué índices tienes que visitar, y en qué orden, para que los clips sigan apuntando a las pistas correctas? ¿Qué debería pasar si eso dejara sin pistas? Escribe primero un test con la canción de ejemplo, y luego el método.

Practica: retain, mantener reglas que abarcan dos listas, probar el orden de los cambios de índice.

4. Piénsalo: posiciones o identificadores

Los clips se refieren a los patrones por su posición en la lista, y por eso remove_pattern tiene que renumerarlos. Imagina en cambio que cada patrón tiene un identificador permanente (struct PatternId(u32)) que nunca cambia.

• ¿Qué métodos de Project se vuelven más sencillos, y cuáles más difíciles?
• ¿Qué cambiaría en el archivo, y en los ChannelNotes del hilo de audio?
• ¿Sería más fácil deshacer con identificadores o con posiciones?

Avisar al hilo de audio de lo que cambió

5. Ediciones al azar para el diff (lineup-core, media)

Los tests del diff comprueban casos elegidos a mano. Escribe uno que compruebe mil al azar: empieza con la demo, haz una edición al azar (activar un paso, añadir o quitar un patrón o un canal, cambiar un volumen, mover un clip…), llama a check_both_ways(&before, &after) y repite desde el proyecto nuevo.

Para tener azar sin ningún crate, un pequeño generador «xorshift» basta para los 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
    }
}
}

Arráncalo con un número fijo (no 0, que se queda en 0 para siempre), para que un fallo vuelva a ocurrir cada vez que ejecutes el test. Si quieres ir más lejos, el crate proptest hace esto como es debido, y cuando encuentra un caso que falla lo reduce a la lista de ediciones más corta que sigue fallando.

Prueba también varias ediciones al azar entre dos comprobaciones, como las que puede contener un paso de deshacer. ¿Produce diff alguna vez una lista larga donde bastaría una corta? ¿Es eso un problema?

Practica: tests basados en propiedades, azar reproducible.

6. Canales emparejados por nombre (lineup-core, media)

diff empareja los canales de dos proyectos con |old, new| old == new, y los patrones con same_pattern. Escribe same_channel(old: &Channel, new: &Channel) -> bool, que diga que dos canales son el mismo cuando tienen el mismo nombre, y pásala a Alignment::new en su lugar. Ejecuta los tests del diff. Luego busca un caso en que dé la respuesta equivocada: ¿qué pasa con dos canales llamados «Piano»?

Practica: funciones como argumentos, qué significa «el mismo».

7. Piénsalo: qué enviar

• SetNotes envía la lista entera de notas de un canal con cada cambio. ¿A partir de qué tamaño sería eso un problema, y qué enviarías en su lugar?
• La ventana envía la duración de la canción junto con sus piezas, en lugar de dejar que la calcule el hilo de audio. ¿Qué haría falta para que dos copias de ese cálculo coincidieran siempre, y cómo notarías que se separan? Las piezas son los Play que hace Project::playback_arrangement. ¿Por qué es más sencillo desplegar las repeticiones del lado de la ventana que enseñarle al hilo de audio qué son las secciones?
• Deshacer mientras suena la canción. Cuando deshacer quita un canal, sus notas que suenan se cortan en el acto, porque el canal va a la basura. En el caso de tres canales Lineup Osc idénticos, el hilo de audio quita el último canal y da sus notas a otro. ¿La nota de qué canal sigue sonando, y podrías llegar a oír la diferencia?

Deshacer y rehacer

8. Una ventana con el historial (lineup-app, fácil)

Añade Edición > Historial…, una ventanita que liste cada paso que se puede deshacer o rehacer, el más nuevo arriba, con la posición actual marcada. Hacer clic en un paso salta hasta él.

Necesitas dos métodos en History: uno que dé las etiquetas para deshacer y otro las de rehacer, cada uno como iterador (self.undo.iter().map(|step| step.label)). Volver cinco pasos atrás son cinco llamadas a history.undo. ¿Debería ejecutarse sync_audio después de cada una, o una vez al final, comparando con el proyecto de antes de la primera? ¿Cuál es más barato, y acaba el hilo de audio igual en los dos casos? (El ejercicio 5 responde a la última pregunta.)

Practica: iteradores sobre campos privados, rev(), reutilizar diff.

9. Copias más baratas (lineup-core, difícil)

Cada paso de deshacer copia el proyecto entero, con todos sus patrones, aunque un clic en un paso cambie un solo patrón. (Un arrastre copia una vez, cuando abre su paso, no en cada fotograma, pero la copia sigue siendo el proyecto entero.) Abarata las copias compartiendo lo que no cambió: guarda los patrones como Vec<Arc<Pattern>>.

Clonar un Vec<Arc<Pattern>> copia solo los punteros y suma uno a cada contador; los patrones mismos se comparten entre el proyecto actual y cada copia del historial. Para cambiar uno, usa Arc::make_mut, que da un &mut Pattern y antes hace una copia privada solo si el patrón está compartido («clonar al escribir»). Así, Project::pattern_mut pasa a ser self.patterns.get_mut(index).map(Arc::make_mut).

Después diff puede saltarse rápido los patrones sin cambios: si Arc::ptr_eq dice que dos patrones son la misma memoria, seguro que son iguales. Haz un proyecto de prueba con 999 patrones llenos de notas, y mide el tiempo de una edición antes y después con std::time::Instant. ¿Sigue funcionando sin cambios el PartialEq del proyecto? ¿Tiene que cambiar el formato del archivo?

Practica: Arc para compartir, clonar al escribir, medir antes de optimizar.

10. Piénsalo: etiquetas y lo que abarca deshacer

• Las etiquetas de los pasos son &'static str, así que «rename pattern» no puede decir qué patrón. Una etiqueta String permitiría «rename pattern Beat», pero la mayoría de las etiquetas son texto fijo, y un String reservaría memoria para cada una. Busca std::borrow::Cow<'static, str>: ¿cómo permite que una etiqueta sea de los dos tipos, y que reserve memoria solo cuando haga falta?
• El volumen master forma parte del mezclador del proyecto, así que deshacer lo devuelve a su valor anterior, y se guarda con la canción. El patrón seleccionado, el zoom y las ventanas abiertas no. ¿Esperarías que deshacer cambiara alguno de ellos? ¿Qué tendría que pasar a Project para eso, y qué significaría para el archivo guardado?

Guardar

11. Un campo nuevo del proyecto y su test de formato (lineup-core, media)

Objetivo. Añadir un campo inofensivo a un proyecto, guardarlo sin romper los archivos antiguos, y demostrar que una canción que lo usa se escribe con el formato siguiente. ProjectFile, sus valores por defecto de serde y los tests de archivo ya existen; este es el ejercicio completo más pequeño para hacer crecer el formato.

Archivos. crates/lineup-core/src/project.rs, crates/lineup-core/src/file.rs.

Pasos.

1. Añade pub notes: String a Project, inicializado a String::new() en Project::empty.
2. Añade notes: String a ProjectFile, con #[serde(default, skip_serializing_if = "String::is_empty")], y cópialo en los dos sentidos.
3. Sube FORMAT_VERSION en uno, a 30 (si otro ejercicio ya tomó el 30, usa el siguiente número libre). En format_for, devuelve el número nuevo en primer lugar cuando !project.notes.is_empty(); deja todo lo demás como está.
4. Escribe tres tests en file.rs: un proyecto vacío se queda en su formato anterior y no tiene línea notes:; un proyecto con notas es del formato nuevo y sobrevive a guardar y abrir; y un archivo escrito antes de que existiera el campo se lee con las notas vacías.

Ejecuta. cargo test -p lineup-core file.

Terminado cuando. Los textos de proyecto antiguos siguen abriéndose, el campo nuevo sobrevive a guardar y abrir, y format_for da el número nuevo solo para una canción que lo necesita. files_from_the_future_are_refused construye su archivo con FORMAT_VERSION + 1, así que sigue pasando.

12. Una copia de recuperación dañada (lineup-app, fácil)

Objetivo. Hacer fiable la recuperación tras un cierre inesperado cuando la copia en disco no lo es. app/recovery.rs ya escribe una copia del proyecto, un archivo .info y un archivo de bloqueo por cada ventana en la carpeta recovery de la carpeta de datos de la app, ofrece la copia en el siguiente arranque y elimina una copia que no se puede cargar. El test a_recovery_copy_comes_back_with_its_file cubre el camino feliz. Añade los otros.

Archivos. crates/lineup-app/src/app/recovery.rs.

Pasos.

1. Míralo a mano: abre una demo, escribe un acorde en el primer compás, espera un momento y fuerza el cierre de la app. No uses Archivo > Salir. Arráncala otra vez y elige Recuperarlo. Cierra la canción recuperada sin guardarla.
2. Lee Files, load y write, y los tests al final del archivo.
3. Añade un test que tome Files::of_run(&folder, "test"), cree la carpeta, escriba basura en su archivo project, ponga al lado un archivo info válido, llame a load(files.clone(), None) y compruebe que devuelve None y que los dos archivos han desaparecido.
4. Añade un segundo test que escriba un proyecto válido en files.project con file::save, pero sin el archivo info. Comprueba que load sigue devolviendo el proyecto, sin ruta y sin nombre, para que el diálogo lo llame «Sin título».
5. Borra la carpeta temporal al final de cada test, como hacen los que ya existen.

Ejecuta. cargo test -p lineup-app recovery.

Terminado cuando. Los dos tests pasan, y el primero falla si se borra la llamada a files.remove() en la rama de error de load.

13. Olvidar un proyecto reciente (lineup-app, media)

Archivo > Abrir recientes recuerda los últimos diez proyectos en los datos persistentes de egui, y sigue siendo correcto cuando un archivo se movió o se borró (la apertura falla y la ruta se quita). Lee app/recent.rs.

Amplíalo: un elemento «Borrar recientes» que olvide la lista entera, y una pequeña ✕ junto a cada entrada que olvide una. La ✕ no debe abrir además el archivo, así que fíjate en el orden en que compruebas los dos clics. ¿Por qué se guarda la lista como Vec<String> y no como Vec<PathBuf>, y qué le pasa a una ruta que no es UTF-8?

Practica: menús de egui, persistencia, rutas que no son UTF-8.

14. Leer números despacio (lineup-core y RON, media)

El número de versión explica por qué la app ya no lee el formato de un archivo con un struct de un solo campo: saltarse el resto del archivo hacía que RON mirara hacia delante, número tras número, hasta el final del texto.

1. Supón que una canción guardada tiene 2 MB de texto con 120 000 números. Si saltarse cada número lee, de media, medio archivo, ¿cuántos bytes se leen en total? A unos 2 GB por segundo, ¿cuánto tarda? ¿Y una canción el doble de larga?
2. Busca la búsqueda hacia delante en el código de RON: en la versión que nombra Cargo.lock, src/parse.rs busca ".." en self.src()[skip..]. Reescribe esa línea para que busque solo en los primeros raw_float_len caracteres. (Pista: corta self.src()[skip..][..raw_float_len], y piensa qué pasaría si el corte terminara en medio de un carácter.) Después compáralo con cómo lo hace RON 0.12.3, y lee su comentario sobre por qué un .. no puede quedar a caballo del final.
3. format_number devuelve None para (tempo: 120.0, format: 25). ¿Por qué no importa que solo lea el principio del archivo? (Mira el orden de los campos en ProjectFile, y to_text.)

Practica: pensar en ritmos de crecimiento, leer el código de una biblioteca, porciones de cadenas.

15. Piénsalo: archivos

• has_unsaved_changes compara el proyecto entero con la copia guardada, pero solo después de que una edición o un deshacer active check_dirty, no en cada fotograma. ¿Cuántas notas, más o menos, necesitaría un proyecto para que una comparación ocupe una parte notable de un fotograma (unos 16 milisegundos)? ¿Por qué project_edited activa check_dirty solo cuando dirty ya es falso? ¿Qué añadiría a este diseño un contador que cada edición incrementara?
• El archivo de proyecto tiene sus propios tipos (ProjectFile, PatternFile) en lugar de derivar Serialize en el propio Project. ¿Qué fallaría el día que alguien renombrara un campo de Project, si el archivo lo usara directamente?
• Un Ferrous Lineup más antiguo se niega a abrir un archivo con un número de formato más nuevo. ¿Podría cargar lo que entiende e ignorar el resto? ¿Cuándo ayudaría eso, y cuándo perdería sin avisar el trabajo de alguien?
• El test de archivos dañados escribe NaN en lugar de números. ¿Qué pasa cuando un archivo de proyecto dice tempo: NaN? ¿Y master: NaN? Busca el código que decide cada caso, y di por qué son distintos.

Dibujar las ventanas

16. Un doble clic restablece el volumen (lineup-app, fácil)

Haz que un doble clic en el deslizador VOL de la barra de herramientas devuelva el volumen master a lineup_core::Mixer::default().master (0.8). Un botón de restablecer no cabría: la barra de herramientas tiene que caber en una fila en una ventana de 1280 puntos de ancho, también en español, y the_toolbar_fits_on_one_row_at_1280_points lo comprueba.

Llama a LineupApp::set_master_volume (en app/mixer.rs) en lugar de asignar el campo, para que el cambio sea un paso que se pueda deshacer y el diff envíe al hilo de audio Command::SetMasterVolume. Ejecuta la app y comprueba que el deslizador se mueve.

Practica: entrada en modo inmediato, Response, encaminar un cambio a través de edit.

17. Recordar el nivel de las pistas (lineup-app y lineup-core, media)

El nivel de las pistas de las teclas de armonía vuelve a Breve cada vez que arranca la app. Otras elecciones se recuerdan: Recordar entre ejecuciones muestra cómo, y settings.rs guarda la elección de los grados en menor con get_persisted e insert_persisted bajo un Id propio. Haz lo mismo con HintLevel: dale Serialize y Deserialize de serde en lineup-core (que ya depende de serde), y léelo y escríbelo donde HarmonyKeys guarda hints. ¿Qué otras elecciones recordarías de la misma manera?

Practica: derives de serde entre crates, los datos persistentes de egui.

18. Pistas en todas partes (lineup-app, pequeño)

theme::hint da a un widget una línea en la barra de pistas y el mismo texto como tooltip. La barra de herramientas, las teclas de armonía y algunos botones de la lista de reproducción lo usan; el rack de canales y el piano roll todavía usan on_hover_text a secas. Cámbialos a theme::hint, y haz que la barra de pistas muestre el nombre del patrón cuando no hay nada bajo el ratón. ¿Por qué theme::hint toma el Response por valor y lo devuelve, en lugar de tomar &Response?

Practica: propiedad a través de una función, el Response de egui, leer el módulo de otro antes de cambiarlo.

19. F10 para el metrónomo, y su línea en F1 (lineup-app, fácil)

Objetivo. El metrónomo es un interruptor en la barra de herramientas y en Edición > Ajustes… > Reproducción. Dale una tecla y añade la tecla a la lista de F1. F10 está libre; no uses M a secas, que toca una nota cuando el teclado del equipo hace de piano.

Archivos. 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.

Pasos.

1. En practice.rs, añade una constante KeyboardShortcut para F10, como view.rs guarda F5 a F8.
2. En LineupApp::keyboard_shortcuts, léela en el mismo sitio protegido que Inicio y Fin: no mientras un campo de texto tiene el teclado, y no mientras se usa un control. Llama a set_metronome con lo contrario de practice.view().metronome.
3. Añade una línea a la sección En cualquier lugar de shortcuts.rs: «Metronome on or off». Usa la constante en lugar de escribir la tecla dos veces.
4. Añade un test sin pantalla en ux_tests.rs: pulsa F10 y comprueba practice.view().metronome; púlsala otra vez y comprueba que está apagado.

Ejecuta.

cargo test -p lineup-app shortcuts
cargo test -p lineup-app metronome

Terminado cuando. F10 activa y desactiva el botón de la barra de herramientas, F1 lo lista en «En cualquier lugar», y no_two_global_shortcuts_share_a_key sigue pasando. Una línea nueva de la lista de F1 es texto en inglés: el test every_window_writes_in_spanish te avisa de que también necesita una en español (mira Dos idiomas).

20. Un dibujo y una versión (lineup-app, fácil)

• Dibuja otro icono para Seguir el cursor de reproducción en icons.rs: un cursor con dos flechas. ¿Qué test te avisa cuando una línea se sale de su cuadrado?
• Añade un botón Copiar versión a la ventana Acerca de Ferrous Lineup que ponga «Ferrous Lineup» y la versión real en el portapapeles con ctx.copy_text. ¿Puede el texto ser una const, construida con concat! y env!?

Practica: dibujar con egui, cadenas en tiempo de compilación.

21. Piénsalo: listas y ventanas

• En shortcuts.rs, la sección de las teclas de armonía usa Written("1 to 7"). ¿Por qué no siete KeyboardShortcut en un Any? ¿Qué mostraría entonces la lista?
• La partitura guía se abre con Opening::FirstTime. ¿Qué cambiaría para ti si usara EveryTime? Pruébalo, y di cuál prefieres.

Los editores

22. Vaciar una fila (lineup-app, fácil)

Hacer clic derecho en un paso ya lo vacía (RackAction::ClearStep). Añade «Vaciar los pasos» al menú del nombre de un canal en channel_menu, con una nueva RackAction::ClearRow { channel }. En LineupApp::apply, llama a edit_pattern para apagar todos los pasos de ese canal, sin enviar a mano un comando al hilo de audio: el diff de la edición envía las notas nuevas. ¿Por qué es mejor una edición de toda la fila que un bucle de ediciones de un paso?

Practica: el patrón de acciones, mantener proyecto y audio a la par.

23. Pintar pasos arrastrando (lineup-app, media)

En el rack haces clic en un paso cada vez. Dale a widgets::step_button un Sense::click_and_drag() y haz que Rows::steps pinte cada paso por el que pasa el puntero. Rows se reconstruye en cada fotograma y solo devuelve acciones, así que guarda el primer paso, y si se estaba encendiendo o apagando, en LineupApp (o en la memoria de egui) y pásalo.

Añade RackAction::SetStep { channel, step, on } en lugar de reutilizar ToggleStep, para que un paso que el puntero cruza dos veces no vuelva atrás. Comprueba response.hovered() junto con ui.input(|i| i.pointer.primary_down()), y deja de pintar cuando el puntero sale de la fila. ¿Debería ser todo el arrastre un solo paso de deshacer? Mira ¿Cuándo termina un paso?

Practica: estado en modo inmediato, entrada de egui, el patrón de acciones.

24. Mostrar el grado de la escala en las teclas (lineup-app, fácil)

paint_keys en piano_roll.rs dibuja un punto en cada tecla de la escala. Dibuja en su lugar el número del grado (1 para la tónica, 2, 3…), con Scale::degree_of. Una serie dodecafónica ya numera sus notas; deja ese camino como está. Los músicos usan estos números todo el tiempo («el acorde de quinto grado», «una séptima menor»).

Practica: Option en el código de dibujo, painter.text.

25. Las luces del rack (lineup-app, fácil)

1. Haz que la luz encendida sea verde en vez de naranja. ¿Dónde se define el color, y qué más lo usa?
2. Da a las luces del primer paso de cada compás un color propio, en vez de solo uno más brillante.
3. Mientras la canción toca un patrón distinto del que muestra el rack, las luces se quedan apagadas. Añade una nota tenue en el rack, como «No suena ahora», para ese caso. ¿Qué valores de channel_rack::show te dicen que suena la canción?

Practica: leer código de dibujo, colores de egui.

26. Nombres de acorde más cortos (lineup-app, media)

La franja de acordes del piano roll omite un nombre que no cabe en su bloque. Haz que pruebe antes un nombre más corto: para un acorde con bajo, el acorde sin su bajo («E7» para «E7/B»), y luego la fundamental sola («E»). Mide cada uno con layout_no_wrap y dibuja el primero que quepa. ¿Sigue siendo un acorde sin su bajo el nombre correcto de lo que suena?

Practica: medir el texto antes de dibujarlo, iteradores con find.

27. Copiar un clip arrastrando con Alt (lineup-app, fácil)

Ctrl+D duplica los clips seleccionados, pero arrastrar una copia es más rápido cuando la quieres en otro sitio. Mayús ya está ocupada (Mayús+clic añade un clip a la selección), así que usa Alt.

En PlaylistView::handle_input, lee las teclas modificadoras con ui.input(|input| input.modifiers.alt). El plan obvio es añadir una copia al pulsar y arrastrar la copia. Pero add_clip rechaza un clip del mismo patrón que ya empieza en el mismo sitio, así que no se puede añadir una copia encima del original. En su lugar, recuerda en ClipDrag que este arrastre copia, y añade la copia solo cuando el puntero llega a otra celda. ¿Qué índice recibe el clip nuevo en Project::playlist().clips(), y cómo se entera el arrastre?

Practica: leer la entrada de egui, reutilizar acciones que ya tienes.

28. Un selector de color para los patrones (lineup-app, media)

Los colores de los patrones ya se guardan. Pattern tiene un color público (un índice en PALETTE, en playlist.rs), PatternFile lo escribe cuando no es el lugar del patrón en la lista, y los archivos que no lo tienen cargan con el lugar del patrón como color. Lee PatternFile y pattern_color.

Lo que falta es el selector. Añade uno al menú ⋯ del patrón en la barra de herramientas, con un cuadradito por cada color de la paleta, que cambie el color del patrón con edit_pattern. Después añade «Restablecer colores», que devuelva a cada patrón su lugar en la lista. ¿Necesita un cambio de color un FORMAT_VERSION nuevo? ¿Qué hace un Ferrous Lineup más antiguo con un archivo que lo tiene?

Practica: hacer evolucionar un formato de archivo, #[serde(default)], encaminar un cambio a través de edit.

29. Ir a un compás (lineup-app, media)

Inicio, Fin, RePág y AvPág ya mueven el cursor de reproducción: lee las teclas de transporte en LineupApp::keyboard_shortcuts, seek y skip_bars. Añade una pequeña casilla «compás» junto a la posición, donde escribir un número de compás y pulsar Intro lleve allí. El primer paso de un compás depende de cada cambio de compás anterior: ¿qué función convierte ya un paso en un compás, y puede ir en el otro sentido? Mientras escribes en la casilla, Inicio y Fin tienen que mover el cursor del texto, no el de reproducción: ¿qué impide que hagan las dos cosas?

Practica: el foco del teclado, convertir compases en pasos.

30. Piénsalo: lo que recuerda un arrastre

El arrastre de una sola nota en el piano roll recuerda la nota por su índice en la lista (Drag::Move { index, .. }), mientras que una selección recuerda las notas mismas. ¿Qué podría salir mal con el índice si la lista se mantuviera ordenada por inicio, y una nota se moviera mientras se arrastra?

Dos idiomas

31. Letras y solfeo (lineup-core y la app)

1. Con el solfeo elegido, escribe Do en un compás vacío de la hoja de acordes. Luego elige letras y escribe Do en el compás siguiente. ¿Qué contiene cada compás, y por qué son distintos?
2. Escribe en solfeo los siete acordes de Si♭ mayor, y compruébalos en las teclas de armonía. ¿Qué acorde es disminuido?
3. Un proyecto se guarda con letras más de una vez: file::to_text hace su trabajo dentro de NoteNaming::Letters.with, y lo mismo hace From<HarmonyName> for String. Quita todos los NoteNaming::Letters.with de los dos, dejando lo que hay dentro, y ejecuta cargo test -p lineup-core solfege. ¿Qué comprobación falla, y qué encontraría en tu archivo un amigo que usa letras? Luego vuelve a poner solo el de From<HarmonyName>. Los tests vuelven a pasar: ¿por qué, y por qué conservar también los otros?
4. with_notes deja {0,1,4} como está. Busca la línea de with_notes que lo decide, y di qué haría con {Do}.
5. note_naming podría guardar la nomenclatura del idioma la primera vez que no encuentra ninguna, con insert_persisted, para que la siguiente lectura la encuentre. Quedaría más ordenado. ¿Qué fallaría entonces para alguien que arranca la app en inglés y la cambia a español una semana después?

Practica: ajustes locales a cada hilo, porciones de cadenas, leer tests.

El secuenciador: temporización a la muestra

Archivos: crates/lineup-core/src/sequencer.rs y crates/lineup-audio/src/engine.rs

El hilo de audio toca un patrón o la canción contando frames de audio. Quien cuenta es un tipo pequeño de lineup-core, el secuenciador, que no sabe nada de sonido: solo dice en qué frame empieza cada paso. Todo lo que suena en un paso, las notas de cada canal en cada clip, es cosa del hilo de audio, en engine.rs. Este capítulo sigue un paso desde la cuenta de frames hasta las notas que empieza. Cómo funciona el hilo de audio en sí está en Dos hilos; cómo doblan los pasos los cambios de tempo, los compases y el swing está en Tempo, compás, swing y sensación.

La aritmética

Un paso es una semicorchea, y un pulso una negra, así que un pulso tiene cuatro pasos (STEPS_PER_BEAT). A un tempo de T pulsos por minuto y una frecuencia de muestreo de R frames por segundo, un pulso dura R × 60 / T frames y un paso un cuarto de eso:

frames por paso = R × 60 / T / 4

120 BPM, 48 kHz:  48000 × 60 / 120 / 4 = 6000 frames       (exacto)
130 BPM, 44.1 kHz: 44100 × 60 / 130 / 4 = 5088.46... frames (no entero)

#![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
}
}

Si 5088.46 se redondeara a 5088, cada paso se quedaría 0.46 frames corto. Son unos 10 microsegundos, nada que fueras a oír una sola vez, pero se acumula: al cabo de unos minutos la batería iría audiblemente por delante de cualquier otra cosa que corra a 130 BPM. Por eso el secuenciador conserva la fracción, en un f64.

El tick

El hilo de audio llama a tick una vez por cada frame que produce:

#![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 cuenta hacia atrás de uno en uno cada frame. Cuando llega a cero, se dispara el siguiente paso y se suma al contador la longitud de un paso entero, no se asigna. La fracción que sobrara se queda en el contador, de modo que los límites de los pasos caen en 0, 5088.46, 10176.92… redondeados al frame más cercano cada vez, pero sin derivar nunca. % es el operador de resto: devuelve el número de paso a 0 al final del bucle.

Como un paso empieza en el frame exacto donde empieza, y no al principio del bloque de audio que lo contiene, la temporización no depende del tamaño del búfer de la tarjeta de sonido. Eso es lo que significa exacto a la muestra.

Qué más puede decir el secuenciador

Otras partes del programa le preguntan al secuenciador algo más que «qué paso suena ahora»:

• position da el paso con la fracción que ha pasado: 4.5 es la mitad del paso 4. La grabación la usa para poner una tecla tocada entre dos pasos en el más cercano (MIDI).
• laps cuenta cuántas veces volvió el bucle al principio por seguir tocando después de su último paso. Un salto al principio no cuenta. El entrenador de velocidad acelera en cada vuelta (Herramientas de práctica).
• due dice qué paso empieza en el próximo tick, sin avanzar. El hilo de audio lo pregunta antes de tick, así que una canción cuyo tempo cambia puede poner el tempo nuevo antes de que empiece ese paso, y el paso entero dura lo que debe.
• start_at salta, de modo que el paso dado se dispara en el próximo tick; un paso más allá del final da la vuelta, como lo haría la reproducción.

set_tempo cambia la longitud de los pasos que vienen; el paso que ya suena conserva los frames que le quedan. set_length vuelve al paso 0 si el siguiente paso queda más allá del nuevo final.

Por qué vive en lineup-core

El secuenciador no tiene nada que ver con tarjetas de sonido. Solo cuenta. Tenerlo en lineup-core significa que se prueba en milisegundos, sin audio, y la cuenta previa usa otro propio.

Probar con iteradores

#![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()
}
}

Esta función auxiliar hace avanzar el secuenciador frames veces y lista cada paso que se disparó junto con el frame en que se disparó:

• 0..frames es un rango, que es un iterador sobre números.
• filter_map llama al closure para cada frame y se queda solo con los resultados Some, desenvueltos.
• Option::map convierte Some(step) en Some((frame, step)), una tupla.
• collect() reúne los resultados en un Vec. Rust deduce qué colección construir a partir del tipo de retorno.

Los tests comprueban luego números de frame exactos:

#![allow(unused)]
fn main() {
assert_eq!(
    fired,
    vec![(0, 0), (6_000, 1), (12_000, 2), (18_000, 3), (24_000, 0)]
);
}

y que un minuto a 130 BPM da exactamente 520 pasos (130 pulsos × 4), el último a menos de un frame de donde lo ponen 519 pasos exactos. Los guiones bajos en literales numéricos como 6_000 los ignora el compilador y solo sirven para que los números grandes se lean mejor.

Modo patrón y modo canción

#![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,
}
}

El secuenciador es el mismo en los dos modos. Cuenta pasos de 0 a cierta longitud y repite. Solo cambia la longitud: la del patrón seleccionado en modo patrón, la de la canción en modo canción.

#![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);
}
}

Una canción vacía tendría longitud 0, y un bucle de cero pasos no tiene sentido, así que se convierte en un compás en silencio.

La canción llega como Command::SetSong { plays, length }: los trozos de patrones que hay que tocar, con cada repetición ya desplegada, y la longitud. El hilo de audio podría calcular la longitud, pero Project ya lo hace, y dos copias de un mismo cálculo pueden separarse. Qué es un Play, y cómo los construye el proyecto, está en Secciones, repeticiones y bucles.

Notas para cada patrón: ChannelNotes

Cada canal necesita una lista de notas por patrón. Un Vec de Vecs lo resuelve, pero hay una trampa. Cuando se añade un patrón, el hilo de audio tiene que añadir una lista vacía a cada canal. Vec::new() en sí no cuesta nada: un Vec vacío todavía no tiene memoria propia. Pero añadirlo al Vec exterior reserva memoria si el Vec exterior está lleno. Para ir sobre seguro, el Vec exterior tiene que tener sitio para todos los patrones que pueda llegar a haber, reservado antes de llegar al hilo de audio.

Esa es una regla sobre cómo se construyó el valor, y Rust puede hacer cumplir reglas así con un newtype, un struct con un único campo privado:

#![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());
        }
    }
}
}

Como el campo es privado, el código de fuera de engine.rs no puede escribir ChannelNotes(some_vec). La única forma de crear uno es ChannelNotes::new, que siempre reserva sitio para MAX_PATTERNS listas. Así que cada ChannelNotes que recibe el hilo de audio tiene el sitio, e insert_empty nunca puede reservar memoria. La comprobación len < capacity lo asegura del todo: si alguna vez estuviera lleno, preferiría saltarse la inserción antes que reservar memoria. .0 es la forma de llegar al campo de un struct tupla (uno cuyos campos no tienen nombre). El test channel_notes_have_room_for_every_pattern deja fijada la promesa.

Del lado de la ventana, enviar un canal construye uno con un iterador, una lista por patrón:

#![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 recibe impl IntoIterator<Item = Vec<NoteEvent>>, así que acepta este iterador, un array como [steps(&[0]), steps(&[2])] en los tests, o un Vec de listas. Las notas son played_notes, no las escritas: con swing, la segunda corchea de cada pulso llega tarde (Tempo, compás, swing y sensación).

Los patrones van y vienen

RemovePattern saca la lista del patrón de cada canal. Las listas que vienen después bajan un lugar, exactamente como Project::remove_pattern renumera los clips, así que los dos lados siguen de acuerdo en qué significa «el patrón 2». Cada lista quitada va a la cola de basura, para liberarla en el hilo de la ventana:

#![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();
        ...
    }
}
}

El bucle cuenta con un índice en lugar de for channel in &mut self.channels, porque el cuerpo llama a self.throw_away, que necesita &mut self. Un bucle for sobre &mut self.channels mantendría un préstamo mutable de una parte de self durante todo el bucle, y self.throw_away necesitaría otro. Con un índice, cada préstamo de self.channels[index] termina en la misma línea.

Clear lo vacía todo antes de enviar un proyecto nuevo, al abrir un archivo:

#![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 saca el último elemento de un Vec, o devuelve None cuando está vacío, así que while let Some(..) sigue hasta que no queda nada.
• silence le dice a un sintetizador externo que suelte las notas que tiene un canal MIDI Out, porque un sintetizador solo para una nota cuando se lo dicen.
• clear sobre un Vec<usize> pone su longitud a cero pero conserva su memoria, así que aquí no se libera nada, y los push posteriores no reservan memoria.
• std::mem::take saca el valor y deja en su lugar el valor por defecto del tipo, aquí un Vec vacío (que no posee memoria).

Abrir un proyecto tira hasta MAX_CHANNELS (32) canales, cada uno con su instrumento y sus notas, y la canción, sus tempos y los golpes de su metrónomo, y por eso la cola de basura tiene 1024 lugares.

Empezar las notas de un paso

Cuando se dispara un paso, el hilo de audio empieza las notas que comienzan en él. En modo patrón es un patrón. En modo canción, un paso de la canción puede estar dentro de varios clips a la vez, uno por pista, y cada clip tiene su propia idea de «qué paso»:

#![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(),
            );
        }
    }
    ...
}
}

Un clip que empieza en el paso 32 de la canción toca el paso 2 de su patrón en el paso 34 de la canción. Si dos clips se solapan (un clip de acordes y uno de ritmo, en dos pistas), los dos empiezan sus notas. Un clip que repite su patrón es un solo Play largo, y pattern_step toma el paso de la canción módulo la longitud del patrón, así que el patrón vuelve a empezar una y otra vez dentro de él.

Tomar prestado solo lo necesario

start_pattern_notes es una función normal, no un método:

#![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>,
) { ... }
}

Si fuera un método que recibe &mut self, llamarlo dentro de for play in &self.plays no compilaría: el bucle toma prestado self.plays para leer, y la llamada tomaría prestado todo self para cambiarlo. Como función que recibe &mut self.channels, toma prestado solo ese campo, que no se solapa con self.plays. Dar forma a los argumentos de una función para que tome prestado solo lo que necesita es una forma habitual de trabajar con el comprobador de préstamos en lugar de contra él.

Origin dice de dónde vienen las notas: el patrón, el paso del patrón, el paso de la canción, y si vienen de un patrón tocado sobre la canción (más abajo). Cada voz guarda el origen de la nota que toca, y así el hilo de audio sabe después si la canción todavía la toca.

Timing agrupa los números que siempre viajan juntos:

#![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,
}
}

Sin él, la función recibiría nueve argumentos, varios de ellos números sueltos, y una llamada con cuatro números seguidos es fácil de escribir en el orden equivocado. (El lint too_many_arguments de Clippy protesta a partir de ocho, y la legibilidad sufre antes.)

Cuánto se sostiene una nota

La longitud de una nota está en pasos; el instrumento quiere frames. El hilo de audio la calcula cuando empieza la nota, y la llama 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;
}

Una nota que se pasa del final de su patrón, o del trozo de la canción que la toca, se corta ahí (room), para que el último acorde de un patrón no quede colgando sobre el clip siguiente. nudge y trim son fracciones de paso, en ticks: una nota de una interpretación MIDI puede empezar un poco después de su paso y acabar un poco antes del último. Con la temporización suelta, cada nota además empieza un poco tarde a propósito. Una nota que empieza tarde espera en pending, una lista reservada de antemano, hasta que llega su frame. Las dos cosas están en Tempo, compás, swing y sensación.

Cuando la canción cambia bajo una nota que suena

La canción puede cambiar mientras suena: se mueve o se borra un clip, se silencia una pista, la banda escribe patrones nuevos. Una nota que ya empezó sonaría hasta el final de su gate, aunque la canción ya no la toque. Así que cuando llega una canción nueva mientras se toca, el hilo de audio suelta las notas que ya no toca:

#![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);
    }
    ...
}
}

Una nota se sigue tocando si algún trozo de la canción nueva toca el mismo paso del mismo patrón en el mismo paso de la canción. release_unless recibe la prueba como closure (impl Fn(Origin) -> bool), así que cada clase de instrumento puede soltar a su manera: una voz del sintetizador pasa a su release, un sampler apaga su sonido rápidamente, un MIDI Out envía un note-off. Las teclas pulsadas en un teclado y las previsualizaciones no tienen origen, así que nunca se cortan. notes_stop_when_the_song_no_longer_plays_them lo comprueba.

El closure toma prestados self.plays y self.pattern_lengths, y el bucle toma prestado self.channels para cambiarlo. Está permitido porque son campos distintos: desde la edición 2021, un closure que usa self.plays captura solo ese campo, no todo self, así que escribir self.plays dentro del closure también funcionaría. Las dos referencias locales solo dejan claro qué partes de self lee.

Saltar, y cambiar de modo

Command::Seek(step) mueve la posición de inicio. Con la reproducción parada, es donde empieza el siguiente Play. Mientras suena, la reproducción salta allí en el acto:

#![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);
    }
}
}

Las notas que esperan en pending son de la posición anterior, así que se descartan. Cambiar entre modo patrón y modo canción empieza el bucle nuevo desde arriba, y suelta las notas sostenidas por la misma razón. Parar suelta todas las notas, también las teclas pulsadas: cada una pasa a su release, así que el sonido se apaga en un momento y no queda colgando.

Un patrón sobre la canción

▶ Tocar sobre la canción, en el rack de canales, toca el patrón seleccionado sobre la canción mientras suena, para probarlo con el resto de la banda (Command::SetOverlay). Empieza en la siguiente línea de compás de la canción, para entrar a tiempo, y se repite mientras suena:

#![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))
}
}

Las líneas de compás salen de los golpes del metrónomo de la canción, que ya dicen dónde empieza cada compás en cualquier compás. Un patrón elegido mientras otro suena sobre la canción espera como coming hasta la siguiente línea de compás. Un salto (un seek, o la canción que vuelve a empezar) se nota porque el paso no es el siguiente al último, y el patrón vuelve a empezar desde arriba en la siguiente línea de compás.

La ventana dibuja un segundo cursor en el rack para el patrón que suena sobre la canción. Dos números, el patrón y su paso, tienen que leerse juntos, o la ventana podría ver un patrón nuevo con un paso viejo. Así que comparten un único AtomicU64, el patrón en los 32 bits altos y el paso en los 32 bajos:

#![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);
}
}

<< desplaza los bits del patrón 32 lugares hacia arriba, y | (o bit a bit) pone el paso en la mitad baja, que está vacía. Leer lo deshace con >> 32 y una máscara, bits & u64::from(u32::MAX). Una carga, un guardado: un entero atómico no se puede leer mitad viejo y mitad nuevo. Un valor especial, NO_POSITION, significa «nada suena sobre la canción».

Cómo se prueba

Los tests hacen funcionar el hilo de audio sin tarjeta de sonido (mira Probar sin tarjeta de sonido). Una pequeña función auxiliar encuentra dónde empiezan los sonidos en un bloque de muestras:

#![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()
}
}

El clic de prueba es una ráfaga corta después de silencio, así que cada golpe es un inicio. Entonces una canción se comprueba en una línea:

#![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"
    );
}
}

La última aserción lleva un mensaje que dice por qué 7 es correcto: después de 40 pasos de una canción de 32, el secuenciador va por su segunda vuelta. Quien espere 39 ve la razón en cuanto el test falla.

Otros tests cubren el resto del capítulo: clips que se solapan, trozos que repiten su patrón, patrones insertados y quitados debajo de los demás, Clear mandándolo todo a la basura, Play empezando donde lo puso un seek, y siete tests sobre un patrón tocado sobre la canción.

Tempo, compás, swing y sensación

Archivos: 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 y crates/lineup-app/src/app/swing.rs

En Ferrous Lineup un paso es siempre una semicorchea. Un vals, un ritardando, un shuffle y un 7/8 búlgaro se escriben todos sobre esa misma cuadrícula. Lo que cambia es cómo se cuentan los pasos y cómo se tocan:

La música que hay detrás de todo esto (pulsos y compases, el dos y el tres, las métricas irregulares, qué es un ritardando y qué es el swing) se explica en el manual de usuario: Ritmo y métrica, Tempo, compases y cambios de tonalidad, Swing y sensación y Métricas irregulares y los Balcanes. Este capítulo trata del código.

TimeSignature: dos números y una agrupación

#![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,
}
}

El número de arriba puede ser cualquiera, desde 1 hasta lo que quepa en un patrón; el de abajo es 1, 2, 4, 8 o 16 (UNITS). No hay 32: un compás de 7/32 terminaría en mitad de un paso de semicorchea.

Todo lo demás se calcula a partir de esos números, y la aritmética está escrita para que un archivo dañado no pueda hacerla dividir por cero:

#![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 deja la unidad entre 1 y 16, así que la división siempre tiene por qué dividir, y max(1) mantiene un compás de al menos un paso, porque «¿en qué compás está el paso 50?» divide por la longitud del compás. Los menús y set_time_marker solo aceptan indicaciones de compás que pasan is_valid, pero un archivo editado a mano todavía puede decir beats: 0 o unit: 0, y el test nonsense_does_not_divide_by_zero comprueba que la aritmética lo aguanta.

new es una const fn, así que las indicaciones de compás pueden ser constantes:

#![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),
    // ...
];
}

Una agrupación dentro de un tipo Copy

En 7/8 las siete corcheas se sienten como pulsos de dos y de tres, y el orden importa: 2+2+3/8 es una rachenitsa búlgara, 3+2+2/8 un kalamatianós griego. La agrupación es parte de la indicación de compás.

TimeSignature se pasa por valor en todas partes, y para eso tiene que ser Copy: se copia como un entero, sin memoria en el montón. Lo natural sería guardar la agrupación en un Vec<u8>, [2, 2, 3], pero un tipo que contiene un Vec no puede ser Copy. Así que la agrupación es una máscara de bits: el bit i está encendido cuando un pulso empieza en la nota i del compás. 2+2+3/8 empieza sus pulsos en las notas 0, 2 y 4, así que su máscara es 0b10101. Un u64 tiene sitio para 64 notas (MAX_GROUPED_BEATS), más que cualquier compás real.

Las canciones y los ritmos son tablas const, así que una agrupación también tiene que poder construirse al compilar:

#![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 es un 1 desplazado at posiciones a la izquierda, y |= enciende ese bit sin tocar los demás. Un assert! que falla dentro de una const fn evaluada para una constante detiene la compilación, no el programa, así que una agrupación mal escrita en la tabla de una canción nunca llega a nadie. Para las agrupaciones que escribe una persona está grouped, que comprueba lo mismo y devuelve un Option.

Las últimas líneas mantienen una regla: la agrupación habitual se guarda como 0. Así "3+3/8" y "6/8" dan el mismo valor, y == dice que son iguales. Sin ella, el menú Compás mostraría 6/8 sin seleccionar después de que alguien escribiera 3+3.

El campo groups es privado, así que el código de fuera de meter.rs solo puede crear una agrupación con grouped u of_groups. beats y unit son públicos, eso sí, de modo que alguien podría cambiar beats y dejar una máscara que ya no encaja. El mask() privado lo cubre: una máscara que no encaja con el número de arriba se ignora, y se usan los pulsos habituales.

Pulsos de distinta longitud

En 2+2+3/8 los pulsos duran 4, 4 y 6 pasos, así que «¿en qué pulso está este paso?» no puede ser una división. Todo le pregunta a beat_at:

#![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,
}
}

Del test irregular_meters_group_their_beats, donde typed es una forma corta de 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 busca el último comienzo de pulso en el paso o antes con rposition, que recorre un slice desde el final.

No hay ninguna función de «pasos por pulso», a propósito. Cualquier código que supusiera pulsos iguales estaría mal en una métrica irregular, y sin una función así que llamar nadie puede cometer ese error. (Quitar una función es además la forma más rápida de encontrar a todos los que la llaman: el compilador los enumera.)

A un compás se le puede preguntar por sus pulsos de tres maneras, porque tres partes del programa entienden cosas distintas por «pulso»:

felt_groups es lo que usa la banda para su «um-pa»: la agrupación si la hay, los pulsos de tres corcheas del 6/8, y si no, pulsos de dos con uno de tres al final. Los compases de tres notas o menos, como 3/4, son un solo pulso sentido. Cómo los toca la banda está en La banda.

Leer y escribir «2+2+3/8»

TimeSignature implementa Display, así que format!("{time}") escribe «3/4», o «2+2+3/8» con la agrupación como número de arriba, en todas partes del mismo modo. La dirección contraria es el trait estándar FromStr, que es lo que hace funcionar "7/8".parse::<TimeSignature>():

#![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('/') da Some((antes, después)) o None; ok_or convierte el None en un error, y ? lo devuelve en el acto. El error es un String que el menú Compás muestra tal cual, en rojo, así que los mensajes pasan por tr y salen en el idioma de la aplicación («escríbelo como dos números, como 7/8»; ver Dos idiomas).

La fila «Otro» del menú Compás guarda lo que se va escribiendo en un pequeño Draft (el número de arriba, el de abajo, y la agrupación como texto) en la memoria de egui entre fotogramas, y construye la indicación de compás con el mismo parse. Si los grupos no suman el número de arriba, lo dice: «los grupos suman 8, no 11».

Guardarla sin cambiar los archivos viejos

Una indicación de compás sin agrupación tiene que guardarse exactamente como antes, (beats: 7, unit: 8), para que las versiones anteriores sigan abriendo el archivo. El atributo #[serde(from = "SavedTime", into = "SavedTime")] de TimeSignature dice: para guardarla, conviértela antes en un SavedTime; para cargarla, lee un SavedTime y conviértelo de vuelta:

#![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 puede tener un Vec cómodo (groups: [2, 2, 3]) porque solo vive un momento, mientras se guarda o se carga. La conversión From<SavedTime> deja fuera una agrupación que no suma el número de arriba, así que un archivo editado a mano no puede crear un compás cuyos pulsos no encajen.

Meter: indicaciones de compás que cambian

Una canción puede cambiar de compás a mitad de camino: la última línea de un himno en 3/4, la Promenade de Músorgski alternando 5/4 y 6/4. Cada cambio es una marca en la lista de reproducción:

#![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,
}
}

Una marca siempre empieza un compás nuevo. Una que se pone en mitad de un compás lo deja más corto, que es como una partitura escribe un compás al que le falta un pulso.

Con marcas, «¿en qué compás está el paso 50?» depende de todo lo que hay antes del paso 50, así que todas las preguntas sobre compases van a un solo tipo:

#![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>,
}
}

El comentario de markers es un invariante, una regla que siempre se cumple. Los campos son privados y Meter::new la hace cumplir (quita las marcas del paso 0, ordena las demás y elimina duplicados con dedup_by_key), así que ningún método tiene que volver a comprobarla.

bar_at recorre la canción por tramos, uno por indicación de compás, contando los compases que pasa:

4/4 desde 0, 3/4 desde 32:
tramo 1: pasos 0..32,  16 por compás -> compases 0 y 1
tramo 2: pasos 32..,   12 por compás -> compases 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 construye un iterador a partir de otros: los comienzos (la primera indicación de compás, luego cada marca) se emparejan con zip con los finales (cada marca, luego usize::MAX para «nunca»). div_ceil divide redondeando hacia arriba, así que un compás corto antes de una marca sigue contando como compás, y bar.min(end - bar_start) le da a ese compás corto su longitud real. unreachable! le dice al lector, y al compilador, que el bucle siempre devuelve algo: el último tramo termina en usize::MAX.

bars() da todos los compases, sin fin:

#![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 convierte un closure en un iterador: cada llamada a next ejecuta el closure. Nunca devuelve None, así que el iterador no se detiene solo; la lista de reproducción dibuja su cuadrícula con meter.bars().take_while(|bar| bar.start <= steps) y decide ella cuánto usar.

El resto de Meter son las preguntas que hace la aplicación: time_at, bar(number), is_bar_start, floor_to_bar, floor_to_beat, beat_end, round_up_to_bar, y position(step) para el indicador COMPÁS:PULSO:PASO. Meter::steady(time) es una canción sin marcas, y un test comprueba, paso a paso, que responde exactamente igual que la TimeSignature sola. tidy() quita las marcas que no cambian nada: una que mantiene la indicación de compás anterior y cae en una de sus líneas de compás.

Quién le pregunta al compás

• La lista de reproducción: su cuadrícula, los números de compás, las secciones y el ajuste. Snap::floor y Snap::next dan el principio y el final del compás o del pulso bajo el puntero, que es lo que necesita arrastrar un clip, una sección o el bucle.
• El rack de canales y el piano roll muestran un patrón, no la canción. Preguntan Project::pattern_time(pattern): la indicación de compás donde empieza el primer clip del patrón, o, para un patrón que no está en la canción, su propio Pattern::time (un vals probado desde la Biblioteca está en 3/4 aunque la canción esté en 4/4), o si no, la del proyecto.
• La longitud de la canción, redondeada hasta la siguiente línea de compás.
• El menú de longitud del patrón, que ofrece compases enteros (pattern_lengths: 1, 2, 3, 4, 6, 8, 12 o 16, mientras quepan) y escribe «4 compases» en vez de «64 pasos» (describe_length).

La canción tal como suena

Las secciones pueden repetirse (Secciones, repeticiones y bucles), así que la canción tal como se oye es más larga que la lista de reproducción tal como se dibuja. Si una sección en 3/4 suena dos veces, la canción que se oye tiene dos tramos de 3/4. Las pasadas del arreglo dicen qué parte de la línea de tiempo suena cuándo, y Project::played_meter construye un segundo Meter, en pasos de la canción:

#![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()
}
}

Cada pasada recibe una marca con la indicación de compás en que empieza, más las marcas que hay dentro, y luego tidy quita las que no cambian nada, como una pasada en 4/4 después de otra en 4/4 sobre una línea de compás. El transporte usa este compás para el indicador de posición y para RePág/AvPág, así que «el compás siguiente» es el siguiente que se oye.

El metrónomo también lo usa. played_clicks lo convierte en un Click por cada paso de la canción (Bar, Beat o None), y la aplicación envía esa lista al hilo de audio con Command::SetSongClicks, así que el metrónomo marca los pulsos de cada compás: las dos negras con puntillo del 6/8, los tres grupos del 2+2+3/8, un clic más agudo en cada «uno». En modo patrón es pattern_clicks, en el compás del propio patrón. La cuenta previa y el sonido del metrónomo están en Herramientas de práctica.

Cambios de tempo

Tempo, siempre válido

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

El campo es privado, así que la única forma de crear un Tempo es Tempo::new, que deja el valor entre MIN (10) y MAX (522) BPM y convierte un NaN en el tempo por defecto, 130. Todo Tempo del programa es, por tanto, válido. Los archivos pasan por la misma puerta: un tempo se guarda como un número sin más, y From<f32> lo lee con Tempo::new, así que un archivo que dice tempo: 9000.0 se abre a 522 (Guardar).

Marcas, y un mapa

Un cambio de tempo es una marca en la lista de reproducción, como un cambio de compás:

#![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,
}
}

Con glide en 0 el tempo cambia de golpe, como después de una pausa. Con un glide se mueve un poco en cada paso hasta llegar: hacia abajo en un ritardando, hacia arriba en un accelerando. Un paso es una semicorchea, así que un cambio gradual a lo largo de dos compases de 4/4 son 32 cambios pequeños, tan cerca de una curva que nadie oye los escalones. El tempo nunca cambia en mitad de un paso.

#![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
}
}

Un cambio gradual de 4 pasos de 100 a 60 BPM toca 90, 80, 70 y 60: el último paso del cambio ya está en el tempo nuevo.

TempoMap es al tempo lo que Meter a los compases: el primer tempo y las marcas, con el mismo invariante, y una pregunta principal:

#![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))
}
}

Un cambio gradual parte del tempo que sonaba en el paso anterior a su marca, aunque fuera en mitad de otro cambio gradual, así que el bucle lleva from consigo: cada marca le pregunta a la anterior «¿dónde estabas un paso antes de mí?». marker.start - 1 no puede desbordarse hacia abajo, porque ninguna marca está en el paso 0.

La franja de tempo

La franja que está sobre los números de compás de la lista de reproducción dibuja el mapa como una línea. Solo necesita los pasos donde la línea se dobla (el principio, cada marca y el final de cada cambio gradual), unidos de dos en dos con 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)))));
}
}

Cada tramo va del tempo de su primer paso al tempo del último, así que un cambio de golpe se convierte en un salto vertical y un cambio gradual en una pendiente. Las etiquetas se escriben como las escribe una partitura: describe compara el tempo de la marca con el de tempo_before de su paso, y escribe «♩ = 90» para un cambio de golpe, «rit. → 60» para uno gradual hacia abajo y «accel. → 140» para uno hacia arriba.

El cuadro TEMPO de la barra de herramientas fija el tempo con el que empieza la canción, y scale_tempo mueve todas las marcas en la misma proporción:

#![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);
    }
}
}

Practicar una pieza más despacio conserva su ritardando, solo que más lento también. Mientras suena una canción cuyo tempo cambia, el cuadro muestra TEMPO AHORA: tempo_at del lugar del cabezal en la línea de tiempo.

Un estilo de la Biblioteca trae un tempo propio, y ese tiene que caer donde la canción toca de verdad, no en su primera nota: un archivo MIDI empieza a menudo con unas pocas notas lentas antes de su tempo real. Así que main_tempo busca el tempo que la canción mantiene durante más pasos, y take_tempo escala toda la canción para que ese se convierta en el del estilo:

#![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 suma, para cada tempo, los pasos que dura: desde el principio hasta la primera marca con el tempo inicial, y luego desde cada marca hasta la siguiente. Un tempo que vuelve más tarde se suma a lo que ya duraba. De los que duran más, gana el primero, así que una canción con un único tempo constante obtiene ese, y un empate va al tempo anterior:

#![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 es un cierre que toma prestada la lista held de forma mutable, así que se declara let mut hold: llamar a un cierre que cambia lo que capturó cambia el estado del propio cierre. (tempo, from) = (…, …) asigna dos variables a la vez, una asignación por desestructuración.

Cada paso a su propio tempo

Project::played_tempos da el tempo de cada paso de la canción tal como suena, así que una sección que frena al final frena cada vez que se repite:

#![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()
}
}

La lista se construye en el hilo de la interfaz y se envía con Command::SetSongTempos, junto con la canción. El hilo de audio no puede reservar memoria, y cuando llega una lista nueva la vieja vuelve al hilo de la interfaz para liberarse, como las canciones viejas y las notas viejas (Dos hilos). Una lista vacía, el caso habitual, significa «toca el tempo del cuadro TEMPO», y no cuesta nada.

Un paso tiene que durar lo que dice su propio tempo, así que el tempo debe fijarse antes de que el paso empiece. due, del secuenciador, dice qué paso empieza en el próximo tick (El secuenciador), y el hilo de audio lo pregunta primero, en cada 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 es el tempo de la canción para ese paso en modo canción, y el del cuadro TEMPO en modo patrón, donde se trabaja sobre un patrón y se quiere un bucle estable. (La parte que se omite arriba, lap_tempos, es el próximo tempo del entrenador de velocidad, que entra cuando el bucle vuelve a empezar: Herramientas de práctica.)

Las notas que ya suenan tienen una longitud en frames, calculada con el tempo anterior. set_tempo las estira para que sigan terminando en el paso que deben:

#![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);
    }
    // ...
}
}

y cada instrumento calcula lo que queda de cada nota sostenida:

#![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()
    }
}
}

Los frames hasta el próximo paso pertenecen al paso que ya suena, que conserva su longitud; solo se estira el resto. A una nota con 10 000 frames por delante, 2 000 de ellos en este paso, a la mitad del tempo (un estiramiento de 2) le quedan 2 000 + 8 000 × 2 = 18 000. Los efectos que siguen el pulso, como un eco ajustado en valores de nota, también reciben el tempo nuevo (El mezclador).

Una exportación toca la canción con el mismo hilo de audio, así que recibe la misma lista. Su longitud ya no es «pasos por la longitud de un paso»: played_seconds suma cada paso a su propio tempo, con 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 acepta cualquier closure que vaya de un paso a un tempo, así que la misma función sirve para un TempoMap en un test y para la lista tocada en played_seconds.

Pasar una canción a otro compás

Una indicación de compás solo mueve líneas de compás. Pero si eliges un vals en la Biblioteca mientras suena una canción en 4/4, sus compases de doce pasos puestos en compases de dieciséis tocan «un dos tres» y luego un pulso de silencio, en cada compás. Para sonar a vals, cada compás de la canción tiene que convertirse en un compás de 3/4. remeter lo hace, con una regla: el compás n de la canción vieja pasa a ser el compás n de la nueva, y cada nota conserva su lugar en su compás.

4/4: | Do . . . Mi . . . Sol . . . Mi . . . |   16 pasos
3/4: | Do . . Mi . . Sol . . Mi . . |           12 pasos

Es un estiramiento mecánico, como lo haría un magnetófono, no como un compositor reescribiría una melodía para otro compás.

Apretar un compás, al tick

Apretar dieciséis pasos en doce deja muchas notas entre pasos: corcheas separadas por dos pasos pasan a estar a 1,5 pasos. Redondearlas a la cuadrícula las volvería desiguales. Así que el apretón se hace en ticks, 24 por paso (TICKS_PER_STEP, la unidad que usa la importación MIDI para las notas fuera de la cuadrícula, ver 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
    }
}
}

En la última línea hay dos costumbres de la aritmética con enteros. Multiplicar antes de dividir: (tick - start) / length * new_bar daría 0 para cada tick dentro del compás. Sumar la mitad antes de dividir para redondear al entero más cercano en vez de siempre hacia abajo. La segunda corchea de un compás de 4/4, el tick 48 de 384, cae en (48 × 288 + 192) / 384 = 36 de un compás de 3/4 de 288 ticks: 1,5 pasos, exactos.

Un Remap guarda el Meter viejo de la canción, así que sirve para canciones que ya cambian de compás: cada compás viejo, en cualquier indicación (también uno corto), se convierte en un compás nuevo entero. Remap::step es lo mismo, redondeado al paso más cercano, para lo que vive en pasos.

Cada compás conserva su duración

El tempo cuenta negras. Un compás de 3/4 tiene tres, uno de 4/4 cuatro, así que con el mismo tempo la canción en 3/4 terminaría en tres cuartas partes del tiempo. Por eso remeter escala el tempo en la misma proporción que el compás: 4/4 a 112 pasa a ser 3/4 a 84, y un compás dura 2,14 segundos en los dos. Las marcas de tempo se escalan igual, y un cambio de compás en mitad de la canción que cambiaba la longitud del compás recibe una marca de tempo propia, para que cada tramo conserve su paso.

El escalado tiene que volver exacto. 108,5 BPM en 7/8, devuelto a 4/4, tiene que ser 108,5 × 16 / 14 = 124, no 124,00001. Un f32 tiene unas siete cifras significativas, y la razón 16/14 no tiene valor exacto en él. Así que el código multiplica primero y divide al final, en 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 es exacto, y 1736 / 14 = 124 también. Un test lleva varios tempos por 7/8, 3/4, 13/16, 6/8 y 12/8 y de vuelta a 4/4, y comprueba que vuelven sin cambios.

Así que después de remeter cada nota sigue empezando en el mismo momento, en segundos, y dura lo mismo. La música suena igual; solo cambia cómo se escribe y cómo se cuenta. Lo que hace que una canción suene a vals es la batería y la forma de atacar los acordes, y por eso la Biblioteca y el cuadro Compás pasan la canción al nuevo compás y le dan un ritmo en él. Cómo se elige ese ritmo está en La biblioteca.

Patrones que se quedan largos

Un patrón tiene como mucho 256 pasos (MAX_STEPS). Dieciséis compases de 4/4 son justo eso, pero dieciséis compases de 12/8 son 384. En vez de perder notas, remeter corta un patrón así en trozos de compases enteros que quepan:

#![allow(unused)]
fn main() {
let chunk = MAX_STEPS / bar * bar;
}

256 / 24 × 24 son 240 pasos: diez compases de 12/8, y luego seis. Los trozos se llaman «Tema», «Tema (2)» y así sucesivamente, y cada clip del patrón se convierte en clips de los trozos, uno detrás de otro. La canción suena igual; la lista de reproducción muestra un clip más.

Todo lo demás se mueve con su compás

Los clips, las secciones, el bucle, las marcas de tonalidad y las marcas de la banda pasan todos por song.step. El cambio gradual de una marca de tempo se traslada por sus dos extremos, así que un ritardando a lo largo de dos compases de 4/4 dura dos compases de 3/4. Los acordes cambian en un pulso, así que van al pulso más cercano del compás nuevo (snap_to_beat). Las marcas de compás desaparecen: ahora toda la canción está en una sola indicación de compás.

Dos marcas a un paso de distancia pueden quedar apretadas en el mismo paso. Vec::dedup_by quita los vecinos que su closure considera iguales; el closure recibe primero el elemento posterior y después el anterior, y puede cambiar el anterior, que es como se escribe «gana la marca posterior»:

#![allow(unused)]
fn main() {
playlist_mut.tempo_markers.dedup_by(|later, earlier| {
    later.start == earlier.start && {
        *earlier = *later;
        true
    }
});
}

a && { ... } ejecuta el bloque solo cuando a es verdadero: la copia solo ocurre para marcas en el mismo paso.

remeter_song además calcula todos los patrones nuevos a partir del proyecto sin tocar, se guarda un clon de la lista de reproducción vieja, y solo entonces escribe. Leer el proyecto mientras se escribe necesitaría dos préstamos del mismo Project a la vez, uno compartido y otro mutable, cosa que el comprobador de préstamos rechaza con razón. Y se ejecuta dentro de project.moving_the_band(...): las notas de la banda se mueven con todo lo demás, y eso no es una edición tuya, así que la banda sigue la hoja de acordes (La banda).

No perder el sitio

Mientras la canción suena estás en algún lugar, compás 13, pulso 2, por ejemplo. Después del apretón, el paso 196 ya no está en el compás 13. Así que después de cualquier cambio de compás la aplicación busca el compás en que estaba el cabezal, y cuánto había avanzado en él, y va al mismo compás y a la misma fracción:

#![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 y new son los played_meter de antes y de después, así que las repeticiones cuentan. El mismo closure mueve el lugar desde donde toca ▶ y al que vuelve ⏹. Funciona también después de deshacer y rehacer, que pueden traer una canción con marcas de compás propias, donde un Remap no encajaría.

Swing

El swing toca las dos corcheas de cada pulso larga-corta. El proyecto tiene una cantidad, de 0 («sin swing») a MAX_SWING, 100 (los dos tercios y el tercio de un tresillo):

#![allow(unused)]
fn main() {
pub swing: u8,
}

Las notas de los patrones nunca se mueven. En cambio, todo lo que toca la canción pide las notas tal como se tocan:

#![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», de std::borrow) es o bien prestado o bien propio. La mayoría de las canciones no tienen swing, y para ellas played_notes devuelve las notas del propio patrón sin copiar ninguna. Solo un patrón con swing recibe un Vec nuevo. Los dos se leen igual, como un slice, y quien necesita un Vec propio llama a .into_owned(), que solo copia si era prestado. El '_ dice que el caso prestado toma prestado de self: el resultado no puede vivir más que el proyecto.

El hilo de audio, la exportación MIDI y el acompañamiento que sigue lo que tocas usan played_notes. El piano roll, los botones de paso y la hoja de acordes leen las notas escritas, así que la cuadrícula que editas sigue siendo una cuadrícula.

Mover la segunda corchea

Un pulso son 96 ticks. La segunda corchea empieza en el tick 48; la tercera nota de un tresillo, en el tick 64. Así que el swing completo llega 16 ticks tarde:

#![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)
}
}

Sumar la mitad de 100 antes de dividir por 100 vuelve a redondear al tick más cercano: 50 son 8 ticks, un swing de 7:5; 70 son 11,2 y quedan en 11.

swung mueve cada comienzo y cada final que cae en un contratiempo o cerca de él:

#![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()
}
}

El primer brazo es una guarda de match: offset es una variable nueva que encaja con cualquier cosa, y el if que la sigue decide si el brazo se aplica. «Cerca» es menos de seis ticks a cada lado, porque las cuerdas de un acorde rasgueado empiezan con un tick de diferencia, 48, 49, 50, y todas tienen que moverse juntas. abs_diff es la distancia entre dos números, sea cual sea el mayor; offset - OFFBEAT sobre un usize menor que 48 se desbordaría hacia abajo y entraría en pánico en una compilación de depuración.

Un patrón de constante es distinto de un enlace a variable. Si el brazo fuera OFFBEAT => ..., compararía con el valor de la constante, 48. Si fuera un offbeat => ... en minúsculas, Rust lo leería como una variable nueva que encaja con todo, y el brazo _ no se ejecutaría nunca. El compilador avisa de eso, y la convención de mayúsculas para las constantes mantiene separados los dos casos.

Una nota que termina en el contratiempo también termina más tarde, así que la primera corchea de verdad es larga, ligada a la segunda. Los golpes de batería son distintos: un tambor muestreado suena hasta el final por mucho que dure la nota, así que solo se mueven sus comienzos (hits). La nota nueva se construye con NoteEvent::exact, la misma función que usa la importación MIDI para las notas fuera de la cuadrícula: una corchea con swing en el paso 2 pasa a ser el paso 2 con un nudge de 16 ticks, que el hilo de audio ya sabe tocar tarde (El secuenciador). Las notas que no están en un contratiempo (semicorcheas, una corchea con puntillo y una semicorchea) quedan como están.

Dónde se aplica el swing

#![allow(unused)]
fn main() {
pub fn swings_in(time: TimeSignature) -> bool {
    time.unit <= 4
}
}

Solo las indicaciones de compás que se cuentan en negras o en notas más largas tienen pares de corcheas en un pulso. En 6/8 o 12/8 un pulso ya son tres corcheas, y en 5/8 o 7/8 la corchea es el pulso. pattern_swing devuelve 0 para un patrón en un compás así, y el control Swing aparece en gris cuando ninguna parte de la canción puede tener swing, con una pista que dice por qué. Una sección de la banda tocada en otro estilo puede traer el swing de ese estilo (section_swing).

Ningún comando nuevo para el hilo de audio

El hilo de audio se entera de cada edición por diff, que compara el proyecto antes y después, y compara las notas tocadas (Decirle al hilo de audio lo que ha cambiado). Así que cambiar el swing no necesita un comando propio: los patrones cuyas notas tocadas se movieron se envían de nuevo, y los demás se quedan como están. Un patrón que pasa a 6/8, y deja de tener swing, se detecta igual, y lo mismo deshacer, que pone en su sitio un proyecto anterior entero. Cuando nada tiene swing, los dos lados de la comparación son Cow prestados, y compararlos compara los slices sin copiar nada.

Recordado por estilo

Cada ritmo de la Biblioteca lleva su propio swing (Rhythm::swing), y un estilo toma el de su ritmo: Swing, Jazz ballad, Jazz waltz, Shuffle y Five-four swing a 100, Rock and roll a 50, el resto sin swing. Sus patrones de batería están escritos en corcheas iguales, como los escriben las partituras, y el swing hace el resto. Cuando cambias la cantidad, la aplicación la recuerda para ese estilo, entre una ejecución y otra, en 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 guarda los valores persistentes por un Id y un tipo. Envolver el mapa en un struct propio, un newtype, le da un tipo que nadie más usa, así que un BTreeMap<String, u8> guardado por otra parte de la aplicación nunca podría leerse como este. Un BTreeMap mantiene sus claves ordenadas, así que el archivo de ajustes enumera los estilos siempre en el mismo orden. store_swings se ejecuta una vez por fotograma y solo escribe cuando changed está activo.

Elegir un estilo le da primero a la canción el swing propio del estilo, en lineup-core, que no sabe nada de ajustes; luego la aplicación pone en su lugar la cantidad recordada, en el mismo paso de deshacer.

Soltura

Un buen músico nunca está exactamente en la cuadrícula. Soltura, en la barra de herramientas de la lista de reproducción, fija cuánto pueden desviarse las notas, de no a 40 ms (MAX_LOOSE_TIMING). Se guarda en el proyecto como loose_timing, en milisegundos, y el hilo de audio la convierte en frames una sola vez, cuando llega Command::SetLooseTiming.

El retraso de cada nota se calcula cuando empieza su paso:

#![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)
}
}

Un pianista se adelanta o se atrasa más o menos lo mismo en todas las notas de un acorde, así que cuatro quintos del retraso son comunes a todas las notas que un canal empieza en un paso, y un quinto cambia de nota a nota. Los números salen de scatter, que mezcla los bits de una semilla con la función SplitMix64:

#![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
}
}

Parece aleatorio, pero la misma semilla da siempre el mismo número, así que una canción suena igual cada vez y una exportación WAV suena como la reproducción. wrapping_mul deja que la multiplicación dé la vuelta más allá de u64::MAX en vez de entrar en pánico en una compilación de depuración: aquí dar la vuelta es justo lo que se busca. scatter tampoco necesita estado, lo que le viene bien al hilo de audio: ningún generador aleatorio que guardar, bloquear o sembrar.

Una nota retrasada espera en una lista hasta su 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,
}
}

La lista se crea con sitio para 512 notas (PENDING_NOTES) en el hilo de la interfaz, y el hilo de audio nunca la deja crecer:

#![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() {
}

En cada frame se empiezan las notas cuyo at ha llegado, y se sacan con swap_remove, que pone la última nota en el hueco en vez de desplazar toda la lista. El orden de las notas que esperan no importa, así que la forma más barata de quitarlas es la correcta.

¿Por qué solo tarde, nunca antes? Para empezar una nota antes, el hilo de audio tendría que mirar el paso siguiente antes de que empiece. Tarde entre 0 y 20 ms suena igual que antes o después 10 ms alrededor de una cuadrícula que va ella misma 10 ms tarde, y nadie oye una canción entera 10 ms tarde.

En archivos y en archivos MIDI

Cada una de estas funciones se guarda solo cuando se usa, así que un proyecto que no la usa todavía lo pueden abrir versiones anteriores (Guardar). format_for escribe el formato más antiguo que puede contener el proyecto:

Al leer un archivo, cada marca de compás y de tempo pasa por set_time_marker o set_tempo_marker, que rechazan una que empieza demasiado tarde o cuyos compases no cabrían en un patrón, como si se hubiera añadido a mano.

Un Standard MIDI File guarda el tempo y el compás como metaeventos en su primera pista. Un tempo se escribe como microsegundos por pulso, en tres bytes, y un cambio recibe un evento en el paso donde cambia el tempo tocado, así que un cambio gradual se convierte en un evento por paso, que es como los archivos MIDI escriben un 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 da los cuatro bytes del u32, el más significativo primero («big-endian», el orden que usan los archivos MIDI), y [1..] quita el primero, que siempre es 0 por debajo de 0xFF_FFFF.

Un evento de indicación de compás lleva el número de arriba, el de abajo como potencia de dos (unit.ilog2(): 2 para una negra, 3 para una corchea), cuántos relojes MIDI dura un clic de metrónomo (24 por negra, así que 6 por paso), y un 8 fijo. Hay uno al principio y uno en cada cambio del compás tocado. MIDI no tiene sitio para una agrupación, así que un compás agrupado marca cada nota (ungrouped().first_beat()). Cómo se escribe un archivo MIDI entero está en MIDI.

Cómo se prueba

Cada tipo tiene a su lado tests que se leen como las reglas que comprueban:

• 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 es 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 (el 90, 80, 70, 60 de más arriba), a_glide_starts_from_where_the_last_one_got_to (un ritardando cortado por un 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 (la duración de la canción en segundos, antes y después, con menos de un 0,2 % de diferencia), 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 toca unas pocas notas y comprueba dónde empieza el sonido, frame a frame: a_song_plays_each_step_at_its_own_tempo (dos pasos a 120 BPM, luego dos a 60, que duran el doble) y loose_timing_starts_notes_a_little_late (cada nota dentro de los 960 frames, 20 ms a 48 kHz, después de su paso; no todas con el mismo retraso; y lo mismo cada vez).

Un test recorre la aplicación entera: styles_tried_one_after_another_keep_the_songs_tempo abre El Choclo y lo pasa por siete estilos y compases (entre ellos un tango vals en 3/4 y el cuadro Compás en 7/8), en modo patrón, en modo canción parado y en modo canción sonando. Después de cada uno, el tempo tiene que seguir igual cuando el compás no cambia, y ser el de la canción cada vez que vuelve a 4/4. Luego toca el principio de la canción con la traza de reproducción y comprueba que cada nota de la melodía empieza y dura lo mismo que antes, con menos de 2 ms de diferencia. Para que sea rápido en una compilación de depuración, solo toca doce segundos, a 8000 muestras por segundo: de sobra para medir notas.

Instrumentos: batería, sampler y Lineup Osc

Archivos: crates/lineup-audio/src/instrument.rs, crates/lineup-audio/src/drums.rs, crates/lineup-audio/src/dsp.rs, crates/lineup-audio/src/sample.rs y crates/lineup-audio/src/timbre.rs

Cada canal tiene un instrumento: la parte que convierte las notas en sonido. Este capítulo trata de los dos que Ferrous Lineup hace por sí mismo, el sampler, que toca un sonido grabado o sintetizado, y el Lineup Osc, un sintetizador pequeño. Los otros dos tipos tocan a través de otra cosa: una SoundFont (SoundFonts y General MIDI) o un sintetizador externo por MIDI (MIDI). Cómo se eligen los sonidos en la aplicación está en Sonidos, del manual.

Un enum, cuatro instrumentos

#![allow(unused)]
fn main() {
pub enum Instrument {
    Sampler(Sampler),
    Synth(Synth),
    SoundFont(SoundFontPlayer),
    MidiOut(MidiOut),
}
}

Un diseño habitual para «muchas clases de una misma cosa» es un trait, trait Instrument, con valores de tipo Box<dyn Instrument>. Es abierto: cualquiera podría añadir una clase sin tocar este archivo. Pero cada Box::new reserva memoria, y cada llamada pasa por un puntero a una tabla de funciones. Con cuatro clases, todas conocidas, un enum es más sencillo. El hilo de audio hace match sobre él, crear uno nunca reserva memoria, y cuando se añade una quinta clase el compilador enumera cada match que tiene que enterarse.

Cada método de Instrument es un match que pasa la llamada a la clase de dentro:

#![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(),
    }
}
}

Lo que se le puede pedir a un instrumento:

Una nota de la canción sabe su longitud cuando empieza, así que recibe un gate en frames y termina sola; el hilo de audio nunca tiene que acordarse de pararla. Una tecla pulsada en un teclado MIDI no tiene una longitud conocida, así que recibe HELD, u32::MAX, que nunca se acaba: solo note_off la termina.

El instrumento de un canal lo construye Instrument::for_channel, en el hilo de la interfaz, a partir del Channel del proyecto:

#![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))
    }
})
}

Aquí se sintetizan los tambores y se leen los archivos (a través de la SampleCache), un trabajo lento que puede reservar memoria: justo lo que el hilo de audio no debe hacer. El instrumento terminado se envía en un comando.

Una batería hecha con unas líneas de matemáticas

Ferrous Lineup no trae archivos de sonido. Sus trece tambores se calculan cuando se crea un canal de batería, cada uno en unas pocas líneas:

Casi todos comparten una forma, el decaimiento exponencial:

#![allow(unused)]
fn main() {
fn decay(t: f32, tau: f32) -> f32 {
    (-t / tau).exp()
}
}

Vale 1 al principio y cae a un 37 % después de tau segundos, a un 13 % después del doble, y así. Las cosas golpeadas se apagan así.

Closures que recuerdan: FnMut

Todos los tambores se construyen con una sola función auxiliar:

#![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()
}
}

Recibe un closure f que va de un tiempo en segundos a una muestra. El closure del bombo guarda una phase que avanza entre llamadas:

#![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)
    })
}
}

El closure cambia phase, una variable que capturó de kick. Un closure que cambia lo que captura implementa el trait FnMut; Fn es para los closures que solo leen, y FnOnce para los que solo se pueden llamar una vez. impl FnMut(f32) -> f32 en la lista de parámetros significa «cualquier closure con esa forma», y el compilador hace una copia de generate para el closure de cada tambor, como hace con los tipos genéricos.

¿Por qué ir sumando una fase en vez de calcular sin(t × frecuencia × 2π)? Porque la frecuencia cambia con el tiempo. La fase es la suma de todos los pasitos dados hasta ahora, así que la altura se desliza sin saltos; la fórmula directa saltaría de un lado a otro al cambiar la frecuencia.

Metal con seis ondas cuadradas

Los platillos usan un truco de las cajas de ritmos analógicas de principios de los 80: seis ondas cuadradas a frecuencias que no son múltiplos unas de otras, sumadas.

#![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
}
}

Las notas cuyas frecuencias son múltiplos sencillos unas de otras se funden en un acorde. Estas no, así que juntas chocan y brillan como metal. Un filtro de paso alto se queda con la parte brillante, y la envolvente decide si es un charles cerrado, uno abierto, un ride o un crash.

Después, cada tambor se escala con normalize para que su muestra más fuerte sea 0,9, y dos tests recorren Drum::ALL: cada tambor llega a ese pico y dura más de mil frames (every_drum_is_audible_and_in_range), y cada uno termina en silencio en vez de cortarse (every_drum_fades_out).

Ruido y filtros

dsp.rs guarda las piezas pequeñas. El ruido blanco sale de xorshift, un generador de números aleatorios diminuto:

#![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
}
}

Tres desplazamientos y tres o exclusivos. No sirve para seguridad, pero suena igual que el ruido, nunca reserva memoria, no necesita ningún crate, y da los mismos tambores «aleatorios» cada vez, lo que permite probarlos. Su única trampa es el cero: xorshift desde 0 se queda en 0 para siempre, así que Noise::new empieza desde seed.max(1).

Los filtros son de un polo, los más sencillos que hay. El de paso bajo mueve su salida una fracción del camino hacia la entrada en cada muestra, así que los cambios rápidos (las frecuencias altas) se suavizan:

#![allow(unused)]
fn main() {
pub fn process(&mut self, input: f32) -> f32 {
    self.state += (input - self.state) * self.coefficient;
    self.state
}
}

Es la misma aritmética que Smoothed, el volumen que se desliza en vez de saltar (Dos hilos). El de paso alto sigue en cambio los cambios de su entrada, así que una señal constante se apaga y los cambios rápidos pasan. Los tests dicen exactamente eso: una entrada constante atraviesa el paso bajo y el paso alto la elimina.

El 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») es un puntero que comparten varios dueños. Clonarlo no copia los datos, suma uno a un contador, y los datos se liberan cuando se va el último Arc. El contador se actualiza de forma atómica, así que es seguro entre hilos, y eso es lo que permite construir una muestra en el hilo de la interfaz y tocarla en el hilo de audio. El mismo archivo de sonido en tres canales está una sola vez en memoria.

Cada una de las ocho voces toca un golpe:

#![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 encaja un patrón, o ejecuta el bloque else, que tiene que salir de la función. Mantiene el camino principal sin sangría: «si no suena, silencio; si no, sigue con position».

position es una fracción de frame, porque un sonido rara vez recorre sus frames exactamente a uno por frame de salida. Un WAV grabado a 44,1 kHz y tocado en una tarjeta de sonido de 48 kHz tiene que avanzar un poco más despacio, o sonaría más agudo y más corto. Y un sampler toca alturas tocando más deprisa o más despacio: una octava arriba es el doble de rápido, y cada semitono multiplica la velocidad por la raíz duodécima de dos, la misma regla que usa Note::frequency (Clases de altura, notas y su escritura):

#![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;
}

El increment de la voz es el producto de las dos razones. En STEP_NOTE, Do4, la nota que toca un botón de paso, la razón de altura es 1 y el sonido se toca como se grabó. Entre dos frames guardados la voz traza una recta, interpolación lineal: no es lo mejor que puede hacer un sampler, pero es barata y basta para la batería.

La velocidad escala el volumen, velocity / 127. Un sampler ignora el gate: como una caja de ritmos, toca su sonido entero cada vez, y como tiene voces, un golpe nuevo no corta el anterior.

Eso está bien para la batería y mal para una cosa: una grabación larga, como una canción entera importada como audio, seguiría sonando después de Detener. Así que release_all apaga en unos 15 ms las voces de un sonido de más de diez segundos, y deja resonar los golpes cortos:

#![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, para un clip que se quita o una pista que se silencia mientras suena, apaga los sonidos de la canción sea cual sea su longitud.

Empezar por la mitad

Una nota suena cuando la reproducción llega al paso en que empieza. Para un golpe de batería eso es todo, pero una grabación es una nota en el primer paso de una canción: empezada desde el compás 20, la canción sonaría sin ella. Así que cuando la reproducción empieza, salta o vuelve al comienzo del bucle, resume_long_sounds, en el motor, mira hacia atrás en la canción las notas que empezaron antes del cursor de reproducción, y le pide a cada instrumento que las retome con resume:

#![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 es cuántos frames de salida hace que empezó la nota, y una voz avanza increment frames del sonido por cada frame de salida, así que la voz empieza elapsed * increment frames adentro, tan lejos como habría llegado. Solo un sonido largo, de más de diez segundos, empieza así, y solo si dura tanto: un golpe de batería de hace dos compases ya terminó hace rato, y los demás instrumentos responden false. resume_long_sounds recorre cada trozo de un clip que empieza en el paso o antes, y cada vez que el trozo tocó cada nota:

#![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 es donde cae la nota si el trozo empezara en su propio primer paso; es menor que cero cuando el clip deja fuera su comienzo (skip), y step_by(length) da cada repetición del patrón dentro del trozo. frames_between suma los frames de los pasos desde ahí hasta el cursor de reproducción, al tempo de la canción en cada paso, así que una grabación bajo un cambio de tempo también empieza en el lugar justo.

Cargar un archivo WAV

SampleData::load_wav lee archivos WAV con el crate hound. Un WAV guarda las muestras como números de coma flotante o como enteros de 8 a 32 bits, y los dos se convierten en flotantes entre -1 y 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() da un Result por muestra, porque un archivo puede estar cortado a la mitad. Recoger un iterador de Result en un Result<Vec<_>, _> da Ok con todos los valores si todos eran Ok, o el primer Err, y se detiene ahí. Los _ dejan que el compilador complete los tipos. Después, interleaved.chunks(channels) toma un frame cada vez (izquierdo, derecho) y lo promedia, así que un archivo estéreo queda en mono.

SampleError implementa Display con mensajes traducidos, así que «no se pudo leer el archivo WAV» le llega al usuario en su idioma. El test loads_and_mixes_to_mono escribe un WAV estéreo real de 16 bits en la carpeta temporal del sistema con hound::WavWriter y lo vuelve a leer.

Voces

Una voz es lo necesario para hacer sonar una nota: su propio punto en el sonido, su propio oscilador, su propia envolvente. El Lineup Osc tiene 16 voces y un sampler 8. Cada nota nueva toma una:

#![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]
}
}

El orden es: una voz en silencio si la hay; si no, la voz más antigua de las que solo se están apagando; si no, la más antigua de todas. Tomar una voz ocupada es robar una voz, y todo sintetizador de hardware lo hace cuando se sostienen más notas de las voces que tiene. Una voz que se apaga va primero porque cortar una cola se nota mucho menos que cortar una nota todavía sostenida, como un bajo largo debajo de acordes rápidos (el test voices_that_are_fading_out_are_stolen_first toca justo eso).

Voice es un trait privado: SamplerVoice y SynthVoice son structs distintos, los dos lo implementan, y una sola función genérica sirve para ambos. V: Voice es la restricción de trait; la función solo puede llamar a lo que el trait promete.

¿Por qué buscar primero un índice y solo después devolver &mut voices[index]? Las búsquedas toman prestado el slice para leerlo (iter()). Una referencia mutable no puede salir de una búsqueda de solo lectura, así que el código encuentra la posición, deja que terminen los préstamos de lectura, y toma prestado de forma mutable una vez, al final.

started sale de un contador que sube con cada nota, así que «la más antigua» es «la menor». Un u64 no se desborda: a mil notas por segundo tardaría 584 millones de años.

Un número fijo de voces, en un Box

#![allow(unused)]
fn main() {
voices: Box::new(std::array::from_fn(|_| {
    SynthVoice::new(sample_rate, timbre.cutoff)
})),
}

Las voces son un array de tamaño fijo, así que el hilo de audio nunca lo hace crecer y nunca reserva memoria. std::array::from_fn construye un array llamando al closure una vez por elemento; el closure recibe el índice, que aquí no hace falta, de ahí |_|. Las voces del sampler implementan Default, así que las construye Box::default().

El array va en un Box por la cola de comandos hacia el hilo de audio. Cada hueco de la cola es tan grande como el Command más grande, y un comando que inserta un canal lleva un Instrument. Dieciséis voces pasan del kilobyte; un Box es un puntero de 8 bytes. Un test fija el tamaño:

#![allow(unused)]
fn main() {
let size = std::mem::size_of::<Command>();
assert!(size <= 80, "a command takes {size} bytes");
}

Meterlas en un Box significa que las voces viven en el montón, y liberarlas es liberar memoria. Por eso un instrumento con el que el hilo de audio ha terminado vuelve siempre al hilo de la interfaz por la cola de basura (Dos hilos): el box se crea y se libera en el hilo de la interfaz, y el hilo de audio solo mueve el puntero.

El Lineup Osc

El Lineup Osc toca un oscilador por voz, a través de un filtro de paso bajo suave, moldeado por una envolvente de volumen:

#![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,
}
}

La onda

Un oscilador guarda una fase, de 0 a 1 a lo largo de un ciclo, y la onda dice cómo suena cada fase:

#![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(),
    }
}
}

En cada frame la fase avanza frequency / sample_rate y vuelve a empezar con fract(). Una diente de sierra tiene todos los armónicos, así que es brillante y zumbona; una cuadrada solo los impares, que suena hueco; una triangular los tiene débiles y suena suave; una senoide no tiene ninguno y suena pura.

Una diente de sierra hecha así contiene frecuencias por encima de lo que puede representar la frecuencia de muestreo, y vuelven plegadas como tonos metálicos débiles, lo que se llama aliasing. El filtro de paso bajo esconde la mayor parte. Quitarlo de verdad (con correcciones «PolyBLEP», o con tablas de onda) sería un buen proyecto.

La envolvente: una máquina de estados

Una nota que solo se enciende y se apaga hace clic, y no se parece a nada real. Una envolvente moldea su volumen a lo largo del tiempo. La clásica tiene cuatro partes, ADSR:

 volumen
   1 ┤  /\
     │ /  \___________          A: ataque, subiendo al volumen completo
     │/    D    S      \        D: decaimiento, bajando hasta...
     │                  \       S: sostenido, mientras la nota se sostiene
   0 ┼───────────────────\___   R: liberación, apagándose al terminar la nota
       A    fin del gate ^

Cada voz está en una etapa, y cada muestra puede moverla a la siguiente. El código con esta forma es una máquina de estados:

#![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,
    }
}
}

• El ataque sube en línea recta; el decaimiento y la liberación son exponenciales: cada frame conserva una fracción fija de la distancia que queda, como se apagan las cuerdas y las campanas. Las fracciones se calculan una vez por instrumento en EnvelopeRates::new, no en cada muestra: decay_factor es e^(-1 / (segundos × frecuencia de muestreo)).
• checked_sub devuelve None en vez de bajar de cero, así que se lee como «si no queda gate, suelta».
• No hay etapa Sustain. El decaimiento se acerca al nivel de sostenido y se queda ahí, así que una etapa propia no haría nada.
• SILENT es 0,0001, unos -80 dB. Un apagado exponencial nunca llega a cero, así que por debajo de ese valor la voz se da por callada y se libera.

note_off suelta las voces de una altura solo si se empezaron con el gate HELD. Una tecla que se suelta en un teclado MIDI no debe terminar la misma nota que la canción toca con su propio gate. release_all pasa todas las voces sostenidas a Release, que es como Detener deja que las notas largas se apaguen en vez de seguir sonando.

Una voz robada no se reinicia: start pone la altura, la ganancia y el gate nuevos, y deja el nivel, la fase y el filtro como estaban.

#![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).
}

El ataque sube entonces desde donde estuviera el nivel. Cada voz se baja además a SYNTH_VOICE_GAIN, 0,35, para que un acorde de cuatro notas no salga cuatro veces más fuerte.

Timbres: sonar como un instrumento General MIDI

El Lineup Osc nunca podrá sonar como un violín de verdad, pero puede sonar más a violín que a piano. Un canal con un programa General MIDI y sin SoundFont toca un timbre elegido según la familia del programa:

#![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,
}
}

Dos pequeñas const fn dan nombre a las dos formas en que se comportan los instrumentos:

#![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)
}
}

y for_program es un solo match sobre el número de programa, en el orden del propio General MIDI, donde cada familia es un rango de ocho números:

#![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,
};
}

Los patrones de rango (0..=3), las alternativas (24..=28 | 31) y un _ final hacen de toda la tabla una sola expresión, y el compilador comprueba que cada número de 0 a 255 cae en algún sitio. Al final, la ganancia de cada timbre se multiplica por la de su onda, para que una cuadrada, la onda más fuerte, no destaque en la mezcla. Timbre::for_program(None) es LINEUP_OSC, la diente de sierra brillante propia del sintetizador, así que un canal sin programa suena como siempre. Qué programa recibe cada canal está en SoundFonts y General MIDI.

Cómo se prueba

Los tests tocan un instrumento en un búfer y miran los números, ya que en un test nadie puede escuchar:

• synth_plays_the_right_pitch toca La4 durante un segundo y cuenta cuántas veces cambia de signo la salida: unas 880, dos por cada ciclo de 440 Hz.
• synth_stops_after_the_gate_and_release sostiene una nota una décima de segundo y comprueba que la salida es exactamente cero diez tiempos de liberación después, sin ninguna voz sonando.
• synth_plays_chords, voices_are_stolen_when_all_are_busy y voices_that_are_fading_out_are_stolen_first comprueban las voces.
• sampler_resamples_to_the_output_rate toca un segundo grabado a 24 kHz en una salida de 48 kHz y espera 48 000 frames de sonido, con un margen de diez; sampler_plays_higher_notes_faster espera la mitad una octava arriba; sampler_hits_can_overlap toca dos golpes a la vez.
• held_notes_last_until_note_off comprueba el gate HELD.
• En timbre.rs, plucked_instruments_die_away_and_bowed_ones_keep_going comprueba las familias, y every_wave_stays_between_minus_one_and_one las ondas.

SoundFonts y General MIDI

Archivos: crates/lineup-core/src/general_midi.rs, crates/lineup-audio/src/soundfont.rs, crates/lineup-audio/src/instrument.rs y crates/lineup-app/src/app/sounds.rs

Un canal dice qué instrumento toca con un número: 0 es un piano de cola, 40 un violín, 52 un coro. Los números vienen de General MIDI, una lista en la que están de acuerdo todos los sintetizadores. En Ferrous Lineup, tres cosas convierten ese número en sonido:

• el Lineup Osc elige una onda y una envolvente que se le acercan (Timbres);
• a un sintetizador externo se le pide por MIDI que lo toque, con un cambio de programa (MIDI);
• un SoundFont, un archivo de grabaciones de instrumentos reales, lo toca dentro de la aplicación.

Este capítulo trata de los números, de dónde saca uno cada canal, y del SoundFont. Cómo activar los sonidos y elegir instrumentos en la aplicación está en el capítulo Sonidos del manual.

General MIDI: 128 instrumentos por número

Un cable MIDI o un archivo MIDI llevan notas, no sonidos. Para decir qué sonido debe tocarlas, MIDI tiene el mensaje de cambio de programa: «a partir de ahora, el canal 3 toca el programa 40». Son dos bytes: 0xC2 (cambio de programa, 0xC0, en el canal 3, que contado desde 0 es el 2) y 40.

Por sí solo, 40 no significa nada. General MIDI, publicado en 1991, fijó una lista de 128 programas, para que el 40 sea un violín en cualquier sintetizador que la siga, desde un teléfono hasta un teclado de escenario. Los programas vienen en dieciséis familias de ocho: pianos del 0 al 7, percusión cromática (celesta, vibráfono, marimba) del 8 al 15, órganos del 16 al 23, guitarras del 24 al 31, bajos del 32 al 39, cuerdas del 40 al 47, y así hasta los efectos de sonido, del 120 al 127. El canal MIDI 10 está reservado a la batería: allí cada nota es un tambor, el 36 el bombo, el 38 la caja, el 42 el charles cerrado, sea cual sea el programa elegido. Los manuales cuentan los programas desde 1 («41 Violin»); los bytes cuentan desde 0.

general_midi.rs, en lineup-core, guarda la lista. Los programas que usan las demostraciones y los estilos tienen nombre, y cada programa tiene su nombre y su familia:

#![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 es un [&str; 128] y FAMILIES un [&str; 16], los dos en el orden de General MIDI. Como cada familia tiene ocho programas, «qué familia» es una división por 8, y los programas de la familia f son f * 8..f * 8 + 8. .min(LAST) impide que un número mayor que 127 indexe más allá del final: un u8 puede valer hasta 255, y un archivo dañado podría traer uno. Los menús se construyen con esos mismos dos arrays, y los nombres pasan por la tabla de traducciones, así que el menú en español dice «Violín».

La batería integrada conserva sus propios sonidos, pero todo lo que habla General MIDI necesita cada tambor como una nota del canal 10. general_midi_drum, en midi_file.rs, es esa tabla:

#![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,
    })
}
}

El 37 es el «Side Stick» de General MIDI, el golpe de aro; el 70 son las «Maracas», lo más parecido que tiene a un shaker; el 63 es «Open Hi Conga», la conga aguda abierta. drum_name va en sentido contrario para los 47 tambores del 35 al 81, y así el mezclador puede decir qué tambor toca una nota. Un test compara unos cuantos con la lista de General MIDI, y otro comprueba los nombres de los programas, de modo que una errata en cualquiera de las dos tablas hace fallar los tests.

El instrumento de un canal

Channel tiene un campo para él:

#![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> porque un canal puede no tener ningún instrumento en particular. Entonces no se envía nada a un sintetizador, y el Lineup Osc conserva su diente de sierra brillante. Los dos atributos de serde mantienen legibles los archivos viejos: un archivo sin el campo se lee como None (default), y un canal sin instrumento no escribe el campo (skip_serializing_if). Solo un proyecto en el que algún canal tiene instrumento necesita el formato 9, así que un Ferrous Lineup más antiguo sigue abriendo el resto (El número de versión).

Un canal de batería no tiene programa: en el canal MIDI 10 son las notas las que eligen los tambores. Un sampler que toca un archivo WAV tampoco lo tiene, porque su sonido es el archivo.

De dónde sale el número

• El rack y el mezclador. Haz clic derecho en el nombre de un canal y abre Instrumento, o haz clic en el nombre del instrumento en el mezclador. Los dos muestran instrument_choices: «Ninguno (el sonido propio del Lineup Osc)», y luego las dieciséis familias, cada una un submenú con sus ocho programas, numerados desde 1 como en los manuales. La familia del programa actual lleva un punto delante, para encontrarla en una lista larga.

• La banda. El panel de la banda de la hoja de acordes da a cada músico un instrumento con las mismas familias (Cómo toca la banda una hoja de acordes).

• La biblioteca. Los canales Teclados y Bajo de un estilo los crea synth_named, que les da un piano y un bajo:

  #![allow(unused)]
  fn main() {
  let program = match name {
      KEYS => Some(general_midi::ACOUSTIC_GRAND_PIANO),
      BASS => Some(general_midi::FINGER_BASS),
      _ => None,
  };
  }

• Las demostraciones. Cada voz de una demostración dice su instrumento: violines y un violonchelo en el Canon de Pachelbel, un bandoneón («Acordeón de tango» en General MIDI) en un tango (Cómo se escribe una demostración). Un test construye cada canción de demostración y comprueba que todos sus canales de sintetizador tienen programa.

• Los archivos MIDI. Al importar un archivo, cada canal MIDI toma como instrumento su primer cambio de programa (MIDI).

Adónde va el número

1. La exportación MIDI escribe un cambio de programa al principio de la pista de cada canal, antes de su primera nota, para que el sintetizador esté listo:

   #![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. La salida MIDI lo envía justo antes de la primera nota del canal, y de nuevo después de cada parada, por si entretanto se cambió el sonido en el propio sintetizador (MIDI).

3. El Lineup Osc toca un Timbre según la familia del programa.

4. El SoundFont toca las grabaciones del programa, que es el resto de este capítulo.

Qué es un SoundFont

Un sampler toca una grabación a distintas velocidades (El sampler): al doble de velocidad suena una octava más aguda. Eso funciona para unas pocas notas, pero un piano grabado en el Do central y tocado dos octavas más arriba suena a juguete. El timbre de un instrumento real cambia a lo largo de su registro, y acelerado, su ataque se vuelve demasiado corto.

Un SoundFont (un archivo .sf2, un formato de las tarjetas de sonido de los años noventa) es toda una biblioteca de sampler en un solo archivo:

• muestras: grabaciones cortas, el do, el mi, el sol♯ de un piano y así cada pocas notas, cada una con la nota en la que se grabó. Los sonidos que duran, como un órgano o las cuerdas, tienen un bucle: una vez sonado el ataque, el centro de la grabación se repite mientras la tecla siga pulsada;
• instrumentos: qué muestra tocar para qué teclas y velocidades (una nota suave puede tocar la grabación de una nota suave), y cómo: la envolvente de volumen, un filtro, el vibrato;
• presets: lo que elige un cambio de programa MIDI, por banco y programa.

Un SoundFont General MIDI pone los 128 instrumentos de General MIDI en el banco 0, en su orden numerado, y un kit de batería en el banco 128, que el sintetizador toca en el canal MIDI 10. Así, el programa 0 es siempre un piano de cola, el 33 un bajo eléctrico tocado con los dedos, y la tecla 36 del canal 10 un bombo.

Tocar una nota es buscar la muestra cuyo rango de teclas y velocidades la contiene, y tocarla más rápido o más lento según la distancia entre las dos notas. Cada semitono es un factor de 2^(1/12), alrededor de 1,0595, así que una muestra de La4 (440 Hz) tocada para Si4, dos semitonos más arriba, va 2^(2/12) ≈ 1,122 veces más rápido: 494 Hz.

Quién lo lee y lo toca: rustysynth

Leer un archivo .sf2 y tocarlo es mucho código: interpretar el archivo, los rangos de teclas, las envolventes, los filtros, los bucles, mezclar decenas de voces. El crate rustysynth lo hace todo, en Rust puro sin ninguna biblioteca de C que instalar, con la licencia MIT, que un programa GPL puede usar. Su interfaz es pequeña; en resumen:

#![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 es la primera línea con los errores explicados: un archivo que no se puede abrir es un SoundFontError::Io, y uno que no es un SoundFont, o está dañado, es un SoundFontError::Invalid. Cada uno imprime un mensaje traducido, así que la barra de estado puede decir «no es un archivo SoundFont (…)» en el idioma de la aplicación.

Habla MIDI. Y la aplicación ya tiene un instrumento que habla MIDI: la salida MIDI (MidiOut), que lleva la cuenta de qué notas suenan y cuándo debe acabar cada una, y junta mensajes de nota activada, nota desactivada y cambio de programa en un buzón de salida para un sintetizador externo (MIDI). Así que un instrumento de SoundFont es una salida MIDI cuyos mensajes van a un sintetizador dentro de la aplicación.

Una salida MIDI que toca dentro de la aplicación

#![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,
}
}

El hilo de audio pide a cada instrumento una muestra cada vez. El sintetizador trabaja en bloques de BLOCK, 64 frames, así que el reproductor reparte el bloque que tiene, y cuando se le acaba le pasa los mensajes de los últimos 64 frames y le pide el bloque siguiente:

#![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() no hace sonido: el next_sample de una salida MIDI cuenta frames, para saber cuándo se cumple la duración de cada nota y enviar su nota desactivada. Una nota que empieza a mitad de un bloque se oye desde el siguiente: como mucho 64 frames tarde, 1,3 ms a 48 kHz, muy por debajo de lo que nadie oye.

let block = &mut *self.block; atraviesa el Box una sola vez, y así las líneas siguientes toman prestados block.synthesizer y block.left como campos separados. Dentro del if, self.notes y block.synthesizer están prestados a la vez, uno por flush y otro por el closure; Rust lo permite porque son campos distintos.

Los sonidos del SoundFont son estéreo, y cada canal de la aplicación es mono hasta que el mezclador lo coloca con su balance (El mezclador). Así que los dos lados se suman y se dividen por dos.

flush es el mismo método que entrega los mensajes de una salida MIDI al puerto MIDI, y play convierte cada MidiMessage en la llamada correspondiente del sintetizador:

#![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 ensancha un u8 al i32 que pide rustysynth; no puede fallar, y por eso es from y no try_from.

Todo lo que una salida MIDI ya hace bien viene gratis: notas que acaban al cumplirse su duración, teclas sostenidas desde el teclado, notas que se callan cuando se silencia su pista, duraciones que se estiran con un cambio de tempo. El motor también trata a las dos igual en una cosa más: MIDI tiene una sola nota de cada altura por canal, así que una nota que vuelve a empezar termina la que suena (one_per_pitch en engine.rs).

Un reproductor se crea para un programa:

#![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 hace que la salida MIDI envíe el cambio de programa antes de su primera nota, de modo que el sintetizador está en el instrumento correcto cuando llega la primera nota. Un tambor es una salida MIDI en el canal 10 que toca una sola nota, sea cual sea la nota de sus pasos (playing_as), como hace un tambor enviado a un sintetizador externo:

#![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)
}
}

Un sintetizador por canal, un SoundFont para todos

Un sintetizador puede tocar dieciséis canales MIDI a la vez, así que uno solo podría tocar toda la banda. En cambio, cada canal de la aplicación tiene el suyo. Así su volumen, su balance, sus efectos, su luz de silencio y su medidor de nivel funcionan exactamente como en cualquier otro canal, porque el motor mezcla canales, no canales MIDI.

El SoundFont en sí ocupa decenas de megabytes, y no se copia. Se lee una vez en un Arc<SoundFont>, un puntero con recuento de referencias atómico: Arc::clone copia el puntero y suma uno a un contador, y la memoria se libera cuando desaparece el último clon. Cada sintetizador guarda un clon, y la aplicación otro. Un instrumento que el hilo de audio reemplaza vuelve por la cola de basura y se descarta en el hilo de la ventana (Liberar memoria en otro sitio), así que, aunque guarde el último clon, el SoundFont nunca se libera en el hilo de audio.

Instrument tiene una variante para él, y un constructor que dice qué canales toca el SoundFont:

#![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)
}
}

El ? después de channel.program devuelve None de toda la función cuando el canal no tiene programa: eso es lo que mantiene en el Lineup Osc un canal en «Ninguno». Un tambor integrado toca el kit del SoundFont cuando el ajuste de la batería está activado, salvo que se esté enviando a un sintetizador externo (sent_on). Un archivo de muestra y una salida MIDI no le tocan al SoundFont. El build_instrument de la aplicación pregunta esto primero y recurre a Instrument::for_channel cuando la respuesta es 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) {
        ...
    }
}
}

Todos los instrumentos se construyen ahí, para tocar y para exportar, así que Archivo > Exportar WAV… y la exportación de video también suenan con el SoundFont.

Los dos bloques de 64 muestras de un sintetizador ocupan medio kilobyte, y cada hueco de la cola hacia el hilo de audio es tan grande como el comando más grande. Por eso el Block va en un Box, igual que los demás instrumentos guardan sus voces en uno (Un número fijo de voces, en un Box); el test commands_stay_small detectaría un comando que creciera.

Nada se reserva en el hilo de audio

El hilo de audio nunca pide memoria (La regla de oro). Un sintetizador reserva todo lo que necesita al crearse: sus voces (VOICES, 128 por canal; una nota de piano puede usar dos, su muestra izquierda y la derecha), sus buffers, la tabla de presets. Synthesizer::new se ejecuta en el hilo de la ventana, dentro de build_instrument, y el instrumento terminado se envía al otro lado. Su note_on y su render solo reutilizan esas voces y esos buffers.

on prepara el sintetizador:

#![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()?;
}

El mezclador tiene una reverberación a la que envían todos los canales, así que la sala sigue ahí, una sola vez (El mezclador). i32::try_from(sample_rate).ok()? es la conversión cuidadosa: un u32 mayor que i32::MAX no cabría, y ? sobre el Option se rinde en lugar de dar la vuelta. El propio sintetizador rechaza frecuencias de muestreo por debajo de 16 kHz y por encima de 192 kHz, y entonces el canal se queda con su Lineup Osc.

Con volumen suficiente

rustysynth toca bajo, a medio volumen, porque espera que lo comparta toda una banda. El reproductor lo sube por GAIN (5) y la batería por DRUM_GAIN (7). Esos números salen de una medición, no del gusto: se tocaron las mismas notas con el Lineup Osc y con el SoundFont, y se compararon sus picos y sus niveles medios. Un piano real se apaga mientras el Lineup Osc sostiene sus notas, así que los dos nunca coinciden del todo, y otro SoundFont puede sonar más fuerte o más suave; el volumen de cada canal hace el resto.

La oferta, y la descarga

La aplicación no trae un SoundFont, porque uno bueno ocupa decenas de megabytes. Apenas la aplicación se abre con sus instrumentos en el Lineup Osc, antes de que nada suene, una ventana ofrece uno:

Descargar baja GeneralUser GS, un SoundFont General MIDI gratuito de S. Christian Collins, desde su propio repositorio, y lo guarda en la carpeta de datos de la aplicación: ~/.local/share/ferrouslineup/soundfonts en Linux, la carpeta Application Support en macOS, AppData\Roaming en Windows. Elegir un archivo… toma cualquier otro .sf2. Ahora no se queda con el Lineup Osc. Edición > Ajustes… > Audio tiene las mismas opciones para más adelante: Instrumentos del SoundFont, Batería del SoundFont, Elegir SoundFont… y Usar GeneralUser GS.

Si GeneralUser GS ya está en esa carpeta, descargado por una ejecución o una versión anterior, no hay nada que descargar, y la ventana ofrece Usarlo en su lugar:

Se pregunta hasta que se responde

Un solo método decide si preguntar:

#![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;
    }
}
}

Abre la ventana siempre que los instrumentos suenan con el Lineup Osc y la oferta no fue rechazada. No se pregunta nada mientras los sonidos están activados, aunque su SoundFont todavía se esté leyendo, ni en un sistema sin carpeta para datos de aplicaciones (ahí general_user es None).

Se llama en dos lugares. LineupApp::new lo llama una vez creada la aplicación, así que la pregunta es lo primero que muestra la ventana:

#![allow(unused)]
fn main() {
// Real instrument sounds are offered as soon as the window opens,
// before anything plays.
app.offer_sound_font();
}

y todas las formas de empezar a tocar (el botón ▶, Espacio, una escucha previa de la biblioteca, abrir una demostración) pasan por set_playing, que termina con

#![allow(unused)]
fn main() {
self.playing = true;
self.offer_sound_font();
}

así que una oferta cerrada sin responder vuelve al reproducir. La reproducción sigue mientras la ventana pregunta, así que el sonido nunca espera a una pregunta.

Una ejecución que no se cerró bien tiene su propia pregunta al arrancar: si recuperar el trabajo sin guardar (ver Una copia del trabajo sin guardar). Las dos se taparían, así que los sonidos esperan a esa:

#![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;
}
}

Abrir la ventana no responde nada. Una ejecución que se cierra antes de responder vuelve a preguntar la próxima vez que se abre la aplicación, y lo mismo pasa si su SoundFont desapareció. Solo un «no» termina la oferta:

#![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();
}
}

Ahora no la llama, y también cerrar la ventana antes de una descarga y Detener durante una. Desmarcar Instrumentos del SoundFont en los ajustes también marca turned_down, y marcarlo lo borra. Un «sí» activa los sonidos y borra 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);
    }
}
}

Descargar empieza la descarga y deja la ventana abierta para mostrarla. Usarlo cierra la ventana y pasa por set_sound_font, igual que marcar el ajuste, que encuentra el archivo en el disco y empieza a leerlo. En los dos casos, cuando el SoundFont está listo, check_sounds vuelve a dar a cada canal su instrumento y la barra de estado dice «Los instrumentos suenan desde GeneralUser GS». La ventana se dibuja en el orden Foreground de egui, encima de todas las demás, porque una demostración abre su hoja de acordes y la trae al frente en el mismo frame en que empieza a sonar.

Los ajustes son una pequeña 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,
}
}

Se guardan entre ejecuciones por nombre, como "sound-font", con el módulo preferences de la aplicación (Guardado por nombre, no por tipo):

#![allow(unused)]
fn main() {
settings: preferences::get(ctx, SETTINGS_NAME).unwrap_or_default(),
}

al arrancar la aplicación, y preferences::set(ctx, SETTINGS_NAME, &self.sounds.settings) cada vez que cambian. Guardados por nombre, sobreviven a una actualización de la aplicación. En la memoria propia de egui no sobrevivirían: una actualización desactivaría los sonidos y, con GeneralUser GS todavía en el disco, la aplicación volvería al Lineup Osc.

#[serde(default)] sobre la struct rellena cualquier campo que falte en los datos guardados con su valor de Default, de modo que se puede añadir un campo sin perder los ajustes de nadie, y un campo que la struct ya no tiene se salta. Por eso renombrar un campo olvida solo ese campo: un turned_down renombrado empieza en false, y se vuelve a preguntar a todos. Default está escrito a mano en lugar de derivado, porque drums empieza en true.

Descargar en un hilo propio

Una descarga de 30 MB tarda entre un segundo y un minuto, y leer un SoundFont también lleva un momento. Las dos cosas se hacen en un hilo propio, como la exportación WAV, y la ventana sigue dibujándose. El hilo y la ventana comparten un 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,
}
}

Los atómicos son números que dos hilos pueden leer y escribir a la vez sin un cerrojo: la descarga guarda cuántos bytes lleva, la ventana lo lee para dibujar la barra, y Detener guarda true en cancel, que la descarga mira antes de cada lectura de hasta 64 KB. Ordering::Relaxed basta, porque ningún otro dato depende de estos números: una barra que va un frame atrasada no importa.

La petición la hace ureq, un cliente HTTP pequeño, con los certificados en los que confía el sistema operativo (así funciona detrás del proxy de una empresa que tenga los suyos) y con el proxy de HTTPS_PROXY, si lo hay. La variable de entorno FERROUS_LINEUP_SOUNDFONT_URL da otra dirección, como una copia en tu propia red. Un archivo de más de un gigabyte se rechaza: ningún SoundFont General MIDI es tan grande, así que es otra cosa.

El archivo se escribe como GeneralUser-GS.sf2.part, luego se lee como SoundFont, lo que comprueba que lo es, y solo entonces se renombra:

#![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
}
}

Una descarga cortada a medias, o una página web que llegó en lugar del archivo, nunca deja un GeneralUser-GS.sf2 roto que fallaría cada vez que arranca la aplicación. and_then ejecuta el segundo paso solo si el primero salió bien, y let _ = dice a propósito que no vale la pena informar de un archivo .part que no se puede borrar.

Una vez por frame, check_sounds guarda los ajustes si cambiaron y pregunta al hilo si ha terminado (JoinHandle::is_finished). Mientras no, le pide a egui que vuelva a dibujar dentro de una décima de segundo, para que la barra avance aunque el ratón no se mueva. Cuando termina, join entrega el Arc<SoundFont>, y cada canal necesita un instrumento nuevo hecho con él. La aplicación ya sabe hacerlo: cuando algunos canales empiezan o dejan de enviarse por MIDI, send_routes reconstruye los instrumentos cuya ruta cambió. Olvidar todas las rutas hace que los reconstruya todos en el frame siguiente:

#![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;
}
}

Desactivar los sonidos hace lo mismo, y cada canal recupera su Lineup Osc o su tambor integrado. El SoundFont sigue cargado mientras los sonidos están desactivados, así que volver a activarlos es instantáneo.

Compilaciones de depuración

cargo run compila sin optimizaciones, y un sintetizador calcula cada muestra de cada voz: sin optimizar, una banda podría ser demasiado para el hilo de audio. Cargo puede optimizar una sola dependencia mientras el resto sigue compilando rápido, en el Cargo.toml del workspace:

[profile.dev.package.rustysynth]
opt-level = 3

Cómo se prueba

Los tests no deberían necesitar una descarga de 30 MB, y el repositorio no debería guardar ninguna. Así que el módulo de tests escribe un SoundFont byte a byte: una muestra, una onda senoidal de 440 Hz en bucle, dos instrumentos (uno toca la muestra tal como se grabó, otro una octava más aguda) y tres presets (el programa 0, el programa 33 y un kit de batería en el banco 128).

Un archivo .sf2 es un archivo RIFF, el mismo contenedor que un archivo WAV: un árbol de chunks, cada uno con un nombre de cuatro letras, un tamaño y sus bytes. Dos funciones pequeñas los construyen:

#![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)
}
}

El archivo es una lista de tres listas: INFO (una versión y un nombre), sdta (las muestras, como números de 16 bits) y pdta (los presets, los instrumentos y las cabeceras de las muestras, en nueve tablas de tamaño fijo). Luego los tests lo tocan y escuchan como lo haría un osciloscopio: una onda senoidal cruza el cero dos veces por periodo, así que contar los cruces en un cuarto de segundo, por dos, da su frecuencia.

#![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)
    );
}
}

El programa 33 es el instrumento una octava más agudo, así que el La4 sale a 880 Hz. Otros tests comprueban que un reproductor está en silencio hasta que empieza una nota, que el la3 sale a 220 Hz, que una nota empieza dentro de un bloque y acaba al cumplirse su duración, que las notas más fuertes suenan más fuerte, que un tambor toca su propia tecla sea cual sea la nota en la que está escrito, que se rechaza un archivo que no es un SoundFont, y qué canales toma el SoundFont (channels_without_a_sound_in_the_sound_font_keep_theirs).

Los tests de ventana no deben depender de si el ordenador que los ejecuta ha descargado GeneralUser GS. Así que cada aplicación de prueba lo busca en una ruta que nunca existe, keep_general_user_in(no_sound_font()), y arranca como si la oferta ya se hubiera rechazado. Cuatro tests deshacen eso. the_app_offers_real_instrument_sounds_as_it_opens hace lo que hace LineupApp::new y comprueba que la ventana se abre antes de que nada suene, con Descargar, y que tras Ahora no no vuelve, ni tras reiniciar ni tras una actualización. play_offers_real_instrument_sounds_until_the_offer_is_answered pulsa Espacio y comprueba que la ventana se abre mientras la canción suena, con Descargar. Vuelve a arrancar la aplicación sin responder y comprueba que reproducir pregunta otra vez. Luego hace clic en Ahora no, reproduce dos veces, y comprueba que no se pregunta nada, ni tras reiniciar ni tras una actualización. play_offers_a_sound_font_already_on_disk pone un archivo vacío donde va GeneralUser GS, comprueba que la ventana ofrece Usarlo, hace clic y comprueba que el archivo se está leyendo. a_demo_asks_for_real_instrument_sounds_in_front_of_its_chord_sheet comprueba que la ventana queda encima, y que sus botones reciben el clic.

El mezclador: niveles, balance, reverberación, efectos y orden de partitura

Archivos: 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 y crates/lineup-app/src/meters.rs

El mezclador (F9) es donde se equilibra la banda. Cada canal tiene una línea: su instrumento, un medidor de nivel, su volumen, dónde se ubica entre los altavoces (Balance), cuánto de él va a la sala (Reverberación), sus propios Efectos (un ecualizador, un compresor y un delay), Silenciar y Solo. Encima están el volumen Principal, con un medidor para cada altavoz, y la reverberación que comparten todos los canales. Las líneas aparecen como una partitura de director presenta los instrumentos, por secciones.

El trabajo se reparte como en todo el programa. lineup-core guarda los ajustes, que se guardan con la canción; lineup-audio los convierte en sonido en el hilo de audio; lineup-app dibuja la ventana. Cómo usar el mezclador está en el capítulo El mezclador del manual.

Qué se guarda

El proyecto tiene un 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,
}
}

y cada Channel tiene su propia mezcla: volume y muted, y tres campos más:

#![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 deja un campo fuera del archivo mientras tiene el valor de un canal nuevo (en el centro, todo enviado a la reverberación, sin efectos), y default lo vuelve a poner cuando falta. Una canción cuyos canales son todos así se escribe exactamente igual que con un Ferrous Lineup sin balances ni efectos, así que una versión más antigua la sigue abriendo. Solo una canción que los usa necesita el formato 26 (balance y envío) o el 28 (efectos) (El número de versión). Al abrir se comprueban los rangos: un archivo editado a mano con un balance de −3, o un delay cuyos ecos no se apagarían nunca, se rechaza con un mensaje en lugar de tocar un canal más fuerte que el máximo.

El Solo es un número de canal, no una marca en cada canal. El proyecto responde «¿se oye este canal?» en un solo sitio, y así todo lo que suena (el hilo de audio, una exportación, un archivo MIDI) está de acuerdo:

#![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)
}
}

Por eso poner un canal en solo llega al hilo de audio como un cambio de silencio en todos los demás (diff: la lista de cambios).

Restablecer mezcla devuelve el principal, la reverberación, el solo y el volumen, el balance, el envío y los efectos de cada canal a como están en una canción nueva. Los músicos de la banda recuperan sus volúmenes de siempre, y los canales que la banda deja callados siguen silenciados (Project::reset_mix, en band.rs).

El camino de una muestra

En cada frame, el hilo de audio lleva cada canal por los mismos pasos. Este es el corazón de la mezcla, en 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);
}

Por orden:

1. El instrumento hace una muestra, mono.
2. Los efectos del canal le dan forma: ecualizador, compresor, delay.
3. Su volumen la escala, y su pico se guarda para el medidor.
4. Su balance la reparte entre los dos altavoces, y su envío manda una parte a la reverberación.
5. La reverberación añade la sala a la suma de todos los canales.
6. El clic del metrónomo se suma después de la reverberación: la sala es de la música, y un clic con cola es más difícil de seguir.
7. El volumen principal escala el conjunto, sus picos van a los medidores del principal, y tanh redondea lo que pase del máximo (Mezclar un frame).

El volumen, el balance, el envío y el nivel húmedo de la reverberación son todos Smoothed: al moverlos en la ventana, se deslizan hasta el nuevo valor en unos milisegundos en lugar de saltar, porque un salto en mitad de una onda se oye como un clic. Los efectos van antes que el volumen, como en el canal de una mesa de mezclas, así que un compresor oye el instrumento tal como toca, diga lo que diga el fader.

El balance: dos altavoces, un canal

El balance es un número de −1 (todo a la izquierda) a 1 (todo a la derecha), con 0 en el centro. Se convierte en una ganancia para cada altavoz:

#![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)]
}
}

balance  −1.0  −0.5   0.0   0.5   1.0
izq.      1.0   1.0   1.0   0.5   0.0
der.      0.0   0.5   1.0   1.0   1.0

En el centro los dos altavoces tocan el canal a todo volumen, como suena un sonido mono en un equipo estéreo. Mover un canal hacia un lado baja el otro altavoz, como la perilla de balance de un equipo de música.

Esta es una de varias leyes de panorama. Las mesas de mezclas suelen usar en cambio una ley de potencia constante, en la que el centro toca cada altavoz a alrededor de 0,71 (−3 dB), para que un canal suene igual de fuerte esté donde esté. Con la ley que se usa aquí, un canal llevado del todo a la izquierda suena un poco más bajo que en el centro, porque solo lo toca un altavoz. La razón para mantenerla es que una canción en la que nada tiene balance toca cada canal exactamente a su volumen en los dos lados.

El deslizador escribe su valor como I30, C o D100 en español (L30 y R100 en inglés), y lee lo que escribes de la misma manera: pan_value acepta L30, R100, C, un número simple de −100 a 100, y los españoles I30 (izquierda) y D30 (derecha). Un doble clic lo devuelve al centro. Un deslizador solo detecta arrastres, así que el doble clic se lee del puntero y se compara con el rectángulo del deslizador.

La reverberación: una sala hecha de retardos

Una reverberación imita una sala. Un sonido rebota en las paredes, el suelo y el techo y vuelve, más tarde y más suave, miles de veces, hasta que los ecos se funden en una cola que se apaga en uno o dos segundos. La reverberación del mezclador es una reverberación de Schroeder, el diseño digital más antiguo (Manfred Schroeder, 1962), hecho con dos tipos de retardo.

Un filtro peine es un retardo cuya salida vuelve a su entrada, un poco más suave cada vez: un sonido vuelve cada 31 ms, por ejemplo, más bajo en cada vuelta. Un solo peine suena como un aleteo metálico, pero cuatro en paralelo, con longitudes que nunca coinciden, dan un patrón denso de ecos. Un filtro pasatodo es un retardo que esparce cada eco en un racimo sin cambiar el tono general; tres seguidos convierten los ecos de los peines en una capa uniforme.

#![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))),
    }
}
}

Las longitudes se cuentan en muestras a 48 kHz (1493 muestras son 31 ms) y se escalan a la frecuencia real. Todas son números primos, así que ningún par comparte un factor y sus ecos casi nunca caen en el mismo instante, lo que sonaría como una nota que resuena. Cada lado de la sala estéreo es un Side con sus propios peines y pasatodos; el derecho se crea con spread 37, así que sus retardos son 37 muestras más largos y los dos lados difieren, lo que el oído percibe como amplitud.

[...].map(...) sobre un array da un array de la misma longitud, así que combs es un [Comb; 4] construido en una sola expresión, sin Vec.

Cuánto resuena la sala

El Decaimiento es el tiempo que tarda la cola en bajar 60 dB, a una milésima de su nivel: la medida habitual de una sala, llamada RT60. La realimentación de cada peine sale de ahí:

#![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));
    }
}
}

En decay segundos el sonido da rate × decay / longitud vueltas a un peine, y en cada vuelta se multiplica por feedback. Para que el total sea 10⁻³ (−60 dB), cada vuelta multiplica por 10^(−3 × longitud / (rate × decay)). Los peines más largos dan menos vueltas, así que reciben una realimentación más fuerte, y los cuatro se apagan a la vez.

La Amortiguación imita el aire y las paredes blandas de una sala real, que se tragan las frecuencias agudas antes que las graves. Dentro de cada peine, el eco pasa por un filtro pasabajos de un polo antes de volver a entrar:

#![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 se mueve solo una parte del camino hacia cada muestra nueva, lo que suaviza las oscilaciones rápidas: los agudos. Cada vuelta los suaviza un poco más, así que la cola se oscurece mientras se apaga, como en una sala de conciertos.

El Predelay es el hueco antes de que la sala responda, hasta 200 ms: en una sala grande la primera reflexión llega más tarde que en una habitación pequeña. Es un buffer circular más delante de los peines, de una quinta parte de segundo.

Nunca demasiado pequeña, nunca un estorbo

flushed convierte cualquier valor menor que 10⁻²⁰ en exactamente 0. Una cola que se apaga se hace cada vez más pequeña sin llegar nunca a cero, y los números tan diminutos (denormales) hacen que muchos procesadores vayan decenas de veces más lentos. Una reverberación que se deja sonar en silencio podría entonces pasarse del tiempo del hilo de audio.

Toda la memoria de los retardos se reserva en Reverb::new, antes de que arranque el stream; configure solo cambia números, así que mover un deslizador nunca reserva memoria en el hilo de audio. Un ajuste fuera de rango se ignora en lugar de aplicarse. Desactivada, el nivel húmedo baja hasta cero y entonces Reverb::next devuelve el sonido seco enseguida, sin hacer ningún trabajo. Activada de nuevo, empieza desde el silencio (clear), no desde la cola que tenía cuando se apagó.

El envío: cuánto de cada canal está en la sala

Cada canal tiene un envío, de 0 a 1: cuánto de él va a la sala. La suma de todos los envíos es la única entrada de la reverberación, así que veinte canales cuestan una reverberación, no veinte, como con un envío en una mesa real. La reverberación devuelve solo la sala, que next suma al sonido seco:

#![allow(unused)]
fn main() {
[
    dry[0] + left.next(delayed, damping) * wet,
    dry[1] + right.next(delayed, damping) * wet,
]
}

La línea que hay que mirar en la mezcla es kept = sample * (1.0 - wet * amount): lo que entra en la sala se quita del sonido seco, en proporción al ajuste Húmedo / seco. Comprueba los dos extremos:

• Envío 1 (todo, como en cada canal nuevo): kept = sample × (1 − wet), y toda la muestra va a la sala. Es una mezcla húmedo / seco clásica de toda la canción.
• Envío 0: kept = sample, y nada va a la sala. El canal suena seco y cercano, como con la reverberación desactivada, mientras el resto de la banda sigue en la sala.

La sala es mono a la entrada y estéreo a la salida, así que un canal llevado del todo a la izquierda sigue teniendo su reverberación en los dos lados, como un guitarrista a la izquierda del escenario llena toda la sala.

Los efectos de cada canal

Una mesa de mezclas real tiene, en cada canal, unos cuantos efectos que dan forma a un instrumento antes de que se una a los demás. Cada línea del mezclador tiene tres, en el orden que tienen en la mayoría de las mesas: un ecualizador, un compresor y un delay.

El ecualizador: subir o bajar frecuencias

Todo sonido es una mezcla de frecuencias: la fundamental de una nota, y sus armónicos por encima. Un ecualizador (EQ) sube o baja rangos de ellas. No añade notas; cambia el color de las que hay. El EQ del mezclador tiene tres bandas, cada una de −12 dB a +12 dB:

Un estante (shelf) sube o baja todo lo que pasa de su frecuencia en la misma cantidad, como un escalón. Una campana sube o baja su frecuencia más que nada, y cada vez menos a cada lado. Los decibelios miden una proporción: +6 dB hace las ondas de una banda casi el doble de altas, −6 dB casi la mitad, 0 dB la deja como está.

Bajar es el uso más común. Cuando dos instrumentos tocan en el mismo registro, se tapan: los graves de un piano y el bajo se vuelven un solo sonido turbio. Quitar los graves al piano deja sitio al bajo, y cuando el bajo toca, el piano no suena más delgado.

En el hilo de audio cada banda es un biquad, un filtro de segundo orden, la pieza básica de la mayoría de los ecualizadores. Cada muestra de salida es una mezcla de las tres últimas muestras de entrada y las dos últimas de salida:

#![allow(unused)]
fn main() {
let output = b0 * input + b1 * self.inputs[0] + b2 * self.inputs[1]
    - a1 * self.outputs[0]
    - a2 * self.outputs[1];
}

Los cinco números b0, b1, b2, a1 y a2 deciden qué hace el filtro. Biquad::set los calcula para un estante o una campana, una frecuencia y una ganancia, con las fórmulas del Audio EQ Cookbook de Robert Bristow-Johnson, que usa casi todo programa de audio: una pendiente de 1 para los estantes y un Q de 1 para la campana. Los tres filtros van uno detrás de otro, graves, medios, agudos, y sus números solo se recalculan cuando cambian los ajustes, nunca en cada muestra. set conserva las muestras que el filtro recuerda, así que mover una banda mientras suena no hace clic. El mismo suelo de 10⁻²⁰ que en la reverberación mantiene fuera los denormales.

El compresor: igualar lo fuerte que suena una parte

Algunas partes salen desiguales: una línea de bajo en la que unas notas saltan y otras se pierden. Un compresor baja un sonido cuando se vuelve fuerte:

• Por debajo de su umbral no hace nada.
• Por encima, baja el sonido en una cantidad que fija su relación. A 4:1, un sonido 8 dB por encima del umbral sale solo 2 dB por encima: cuatro decibelios de entrada por cada uno de salida. A 1:1 no baja nada, así que el compresor está apagado. A 20:1 casi nada pasa del umbral.
• Su ganancia (la «ganancia de compensación») sube toda la parte después, ya que las notas fuertes bajaron. La parte suena tan fuerte como antes, pero más pareja.

Esa regla es aritmética simple, así que vive en lineup-core, donde un test puede comprobarla sin ningún sonido:

#![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)
    }
}
}

A 4:1, 8 dB por encima del umbral se bajan 8 × (1 − ¼) = 6 dB, y salen 2 dB por encima.

Un compresor no baja cada onda. Sigue lo fuerte que ha sonado el sonido en los últimos milisegundos: baja deprisa cuando un sonido pasa del umbral (su ataque, 10 ms) y vuelve a subir más despacio cuando vuelve a estar por debajo (su liberación, 150 ms). Si siguiera cada onda, deformaría su forma y añadiría un zumbido. El Follower hace esto:

#![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 y release se calculan una vez a partir de sus tiempos, como 1 − e^(−1 / (segundos × frecuencia de muestreo)): con ese número, el nivel recorre unos dos tercios del camino hacia una nueva intensidad en el tiempo dado. 20 × log10 convierte el nivel en decibelios, reduction dice cuánto bajar, y 10^(dB / 20) convierte la respuesta de nuevo en un número por el que multiplicar la muestra. .max(FLOOR) mantiene el silencio, cuyo logaritmo es menos infinito, en −100 dB.

El delay: ecos a tiempo con la canción

Un delay vuelve a tocar el sonido un poco más tarde, y otra vez, cada eco más bajo que el anterior. Su tiempo es una figura de la canción, contada en pasos (semicorcheas):

#![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"),
];
}

Así los ecos caen en el ritmo de la canción, y siguen el tempo cuando cambia. La corchea con puntillo («1/8 con puntillo» en el menú) es la favorita: sus ecos caen tres semicorcheas después de cada nota, entre los pulsos, y una guitarra o una voz que toca corcheas suena como si tocara semicorcheas.

#![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)
}
}

Una corchea con puntillo a 120 BPM son 3 × 0,125 = 0,375 s. Un eco llega como mucho 2 segundos después del sonido: una blanca a 40 BPM serían 3 segundos, así que a tempos tan lentos los tiempos más largos se quedan en 2.

• La Realimentación dice cuánto de cada eco vuelve como el siguiente. Al 50 %, cada eco suena la mitad que el anterior; al 0 % hay uno solo. Se detiene en el 90 %, así que los ecos siempre se apagan.
• La Mezcla dice lo fuertes que son los ecos al lado del propio sonido. 0 % apaga el delay; 100 % hace el primer eco tan fuerte como la nota.

El delay recuerda el sonido que vuelve a tocar en un buffer circular: un array fijo que se escribe dando vueltas, donde la muestra de delay_frames atrás siempre va detrás de la que se está escribiendo:

#![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;
}

Lo que entra en la línea es el sonido más una parte del eco; esa parte vuelve otra vez delay_frames más tarde, y eso es la realimentación. Lo que sale es el sonido más el eco a la mezcla. Sumar frames antes del % impide que la resta baje de cero, lo que un usize no puede guardar.

Memoria hecha al otro lado

Dos segundos de sonido son 96 000 muestras a 48 kHz, una reserva grande, y el hilo de audio nunca reserva memoria. Así que el hilo de la ventana crea la DelayLine y la envía con los ajustes:

#![allow(unused)]
fn main() {
SetEffects {
    channel: usize,
    effects: lineup_core::Effects,
    line: Option<DelayLine>,
},
}

Envía una línea cada vez que envía ajustes con el delay activado, porque solo el hilo de audio sabe si ese canal ya tiene una. ChannelEffects::set se queda con la primera línea que recibe y devuelve cualquier otra, que vuelve por la cola de basura para liberarse del lado de la ventana:

#![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));
}
}

Un canal conserva su línea una vez que la tiene. Cuando su delay se apaga y se vuelve a encender, set llena antes la línea de silencio, o volverían los ecos de la vez anterior. Cuando cambia el tempo, el motor llama a set_tempo en los efectos de cada canal, así que los ecos se mueven con él.

process mira primero si algún efecto está activado. Si ninguno lo está, devuelve la muestra intacta: un canal sin efectos suena exactamente como sonaría sin este código, y no cuesta nada.

Medidores de nivel: del hilo de audio a la pantalla

Un medidor muestra lo fuerte que suena un canal ahora. El hilo de audio lo sabe, porque hace el sonido; el hilo de la ventana dibuja el medidor. Van a velocidades distintas (el hilo de audio llena un bloque de unos cientos de muestras muchas veces por segundo, la ventana dibuja unos 60 frames por segundo), y el hilo de audio nunca debe esperar a la ventana, así que un Mutex queda descartado.

Picos en atómicos

El hilo de audio guarda la muestra más fuerte de cada canal durante un bloque (channel.peak más arriba). Al final del bloque sube un pico compartido hasta ella, si es más fuerte. Una vez por frame, el medidor toma el pico compartido y lo devuelve al silencio. Así no se pierde ningún pico, se alineen como se alineen bloques y frames, y ningún lado espera:

#![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))
}
}

La biblioteca estándar de Rust no tiene AtomicF32. Pero un f32 son 32 bits, y to_bits y from_bits lo convierten en un u32 y de vuelta sin cambiar un bit. Mejor aún: para números no negativos, el orden de los bits como enteros sin signo es el orden de los números, porque el exponente está en los bits altos y la mantisa debajo. Así que fetch_max sobre los bits, un «quédate con el mayor» atómico, se queda con el pico más fuerte. Los picos son valores absolutos, nunca negativos, y el if deja fuera los NaN (sus bits se compararían como mayores que cualquier número).

swap(0, …) lee el valor y pone 0 (los bits de 0.0) en su lugar en un solo paso, así que un pico que llegue entre una lectura y un reinicio no se puede perder. Ordering::Relaxed basta porque cada pico va solo: nada más en memoria tiene que verse en un orden determinado junto con él.

std::array::from_fn(|_| AtomicU32::new(0)) construye los arrays, ya que un AtomicU32 no es Copy y [AtomicU32::new(0); N] no compilaría.

Decibelios, y un medidor que cae despacio

El oído percibe la intensidad por proporciones, no por diferencias, así que el medidor se dibuja en decibelios, una escala de proporciones:

decibelios = 20 × log10(nivel)      1.0 → 0 dB (el máximo)
                                    0.5 → −6 dB
                                   0.25 → −12 dB
                                  0.004 → −48 dB (el suelo del medidor)

Cada 6 dB menos reducen el nivel a la mitad, en cualquier punto de la escala. Un medidor se ilumina desde −48 dB a la izquierda hasta 0 dB a la derecha: verde, ámbar desde −6 dB, rojo en el máximo y por encima. Los medidores del principal miden después del volumen principal y antes de tanh, así que el rojo en el principal significa que el redondeo está actuando. Al pasar el ratón por un medidor, dice su nivel en decibelios.

Un medidor que siguiera cada pico exactamente parpadearía demasiado rápido para leerlo. Así que salta hacia arriba a un pico nuevo enseguida y cae 24 dB por segundo:

#![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 es el tiempo desde el frame anterior. Caer 24 dB por segundo es multiplicar por 10^(−24 × segundos / 20) en cada frame, sea cual sea la frecuencia de frames. Medio segundo después de un pico, el medidor lo muestra 12 dB más abajo, a una cuarta parte, más o menos.

egui solo dibuja un frame cuando pasa algo. Mientras un medidor sigue cayendo, el mezclador pide el siguiente frame enseguida (request_repaint); cuando todos los medidores están apagados, vuelve a mirar cada décima de segundo (request_repaint_after), lo que basta para captar las notas de un teclado MIDI tocado con la canción parada.

Orden de partitura: la batería junta

El rack de canales guarda los canales en el orden en que se añadieron. Un estilo que trae un aro, un bajo, un cencerro y una conga los añade al final, así que una lista en el orden del rack desperdiga la batería alrededor del piano y del bajo. Una partitura de director nunca hace eso: cada instrumento tiene su lugar, el mismo en todas las partituras, para que quien la lee encuentre las flautas arriba y los contrabajos abajo sin buscar. El mezclador lista los canales en ese orden, por secciones con un título cada una:

Las trompas van encima de las trompetas aunque suenan más graves, porque se funden con las maderas y durante mucho tiempo se escribieron junto a ellas. Las cuerdas van al final, así que los contrabajos, la parte más grave de la orquesta, cierran la página; un coro va justo encima de ellas, como en un réquiem o un oratorio.

La batería sigue el pentagrama de batería, donde cada tambor tiene su línea o su espacio: los platillos en la línea superior y por encima (el crash el más alto, luego el charles, luego el ride), el tom agudo en el espacio superior, la caja en el tercer espacio, el tom de pie debajo y el bombo en el espacio inferior. Así que la sección Batería se lee Crash, Charles, Charles abierto, Ride, Tom agudo, Caja, Aro (un golpe de aro, escrito donde va la caja), Tom grave, Bombo. La percusión de mano (cencerro, shaker, palmas, conga) suele tener sus propios pentagramas encima de la batería, así que va primero.

Solo el mezclador cambia su orden. El rack de canales, el piano roll y el archivo guardado mantienen los canales como se añadieron, y nada suena distinto.

Dónde va un canal

score_order.rs está en lineup-core, sin código de interfaz, así que se prueba con un simple cargo test. Un Section es un enum en orden de partitura:

#![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,
}
}

Derivar PartialOrd y Ord en un enum ordena sus variantes tal como están escritas: Section::Woodwinds < Section::Brass. El orden de la partitura es el orden del código fuente.

El mezclador no mira el nombre de un canal para ubicarlo, sino su instrumento, el programa General MIDI (SoundFonts y General MIDI). Un canal llamado «Melodía» que toca una flauta va con las maderas. Los números de programa ya vienen casi siempre por familias, pero no siempre como los quiere una partitura: General MIDI pone los timbales con las cuerdas y la celesta con las láminas, y la partitura pone los timbales los primeros de la percusión y la celesta con los teclados. Así que cada sección lista sus programas, de arriba abajo, y place encuentra la sección de un canal y su puesto en ella:

#![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),
        },
    }
}
}