audio-as-code 0.1.0__py3-none-any.whl

audio_as_code/midi.py

@@ -0,0 +1,192 @@
+"""Standard MIDI type-1 export with tempo, programs, pan, and percussion mapping."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import mido
+
+from ._export_rules import (
+    MAX_MELODIC_TRACKS,
+    MAX_MIDI_TICK,
+    TICKS_PER_BEAT,
+    midi_export_pitch,
+    midi_note_ticks,
+    midi_tick,
+)
+from .instruments import DRUM_NOTES, PROGRAMS
+from .model import Song
+
+
+def _export_warnings(song: Song) -> list[str]:
+    messages = ["MIDI preserves notes and tempo; sounds depend on the receiving synthesizer."]
+    if any(track.instrument in DRUM_NOTES for track in song.tracks):
+        messages.append(
+            "Percussion uses shared channel 10, with gain in velocity and no per-track pan. "
+            "Percussion note events are grouped in the first percussion track; "
+            "other percussion track names are retained as metadata."
+        )
+    if any(track.tone is not None for track in song.tracks):
+        messages.append("Instrument tone controls are not exported.")
+    if song.tempo_map:
+        messages.append("Tempo changes are rounded to the 480-tick beat grid.")
+    if any(track.pedal for track in song.tracks):
+        messages.append(
+            "Piano pedal events use binary CC64 on the 480-tick beat grid; an open pedal "
+            "lifts at score end. Damper tails and repeated-pitch behavior depend on the receiver."
+        )
+    if song.automation or any(track.automation for track in song.tracks):
+        messages.append(
+            "Gain/pan automation is not exported; MIDI uses static track/master gain and pan."
+        )
+    if song.effects or any(track.effects for track in song.tracks):
+        messages.append("Procedural effects and their audio tails are not exported.")
+    if any(
+        track.release_seconds or any(note.release_seconds for note in track.notes)
+        for track in song.tracks
+    ):
+        messages.append("Note releases are not exported; MIDI uses written note durations.")
+    return [" ".join(messages)]
+
+
+def export_midi(song: Song, path: str | Path) -> dict:
+    song = Song.model_validate(song.model_dump())
+    melodic = [track for track in song.tracks if track.instrument not in DRUM_NOTES]
+    if len(melodic) > MAX_MELODIC_TRACKS:
+        raise ValueError(
+            f"MIDI export supports at most {MAX_MELODIC_TRACKS} melodic tracks "
+            "(channel 10 is percussion)"
+        )
+    drum_kinds = [track.instrument for track in song.tracks if track.instrument in DRUM_NOTES]
+    if len(set(drum_kinds)) != len(drum_kinds):
+        raise ValueError("MIDI export requires at most one track per drum instrument")
+    midi = mido.MidiFile(type=1, ticks_per_beat=TICKS_PER_BEAT)
+    end_tick = midi_tick(song.beats)
+    if not 1 <= end_tick <= MAX_MIDI_TICK:
+        raise ValueError("song duration cannot be represented on the MIDI tick grid")
+    tempo = mido.MidiTrack()
+    tempo.append(mido.MetaMessage("track_name", name="Tempo"))
+    tempo.append(mido.MetaMessage("set_tempo", tempo=mido.bpm2tempo(song.bpm)))
+    previous_tempo_tick = 0
+    for change in song.tempo_map:
+        tick = midi_tick(change.beat)
+        tempo.append(
+            mido.MetaMessage(
+                "set_tempo", tempo=mido.bpm2tempo(change.bpm), time=tick - previous_tempo_tick
+            )
+        )
+        previous_tempo_tick = tick
+    tempo.append(mido.MetaMessage("end_of_track", time=end_tick - previous_tempo_tick))
+    midi.tracks.append(tempo)
+    channels = iter(channel for channel in range(16) if channel != 9)
+    percussion_intervals: dict[int, list[tuple[int, int, str]]] = {}
+    track_events = []
+    percussion_events = None
+    for track in song.tracks:
+        percussion = track.instrument in DRUM_NOTES
+        channel = 9 if percussion else next(channels)
+        output = mido.MidiTrack()
+        # UTF-8 metadata is explicitly selected for titles outside Latin-1.
+        output.append(mido.MetaMessage("track_name", name=track.name))
+        if not percussion:
+            output.append(
+                mido.Message("program_change", channel=channel, program=PROGRAMS[track.instrument])
+            )
+            output.append(
+                mido.Message(
+                    "control_change",
+                    channel=channel,
+                    control=7,
+                    value=round(track.gain * song.master_gain * 127),
+                )
+            )
+            output.append(
+                mido.Message(
+                    "control_change",
+                    channel=channel,
+                    control=10,
+                    value=round((track.pan + 1) * 63.5),
+                )
+            )
+        events = []
+        for pedal in track.pedal:
+            events.append(
+                (
+                    midi_tick(pedal.beat),
+                    -1,
+                    mido.Message(
+                        "control_change",
+                        channel=channel,
+                        control=64,
+                        value=127 if pedal.down else 0,
+                    ),
+                )
+            )
+        if track.pedal and track.pedal[-1].down:
+            events.append(
+                (end_tick, -1, mido.Message("control_change", channel=channel, control=64, value=0))
+            )
+        note_ends: dict[int, int] = {}
+        for note in sorted(track.notes, key=lambda note: note.start):
+            pitch = midi_export_pitch(track, note.pitch)
+            start, end = midi_note_ticks(note, end_tick)
+            if end <= start:
+                raise ValueError(
+                    f"track {track.name!r}: note at beat {note.start} is shorter than one MIDI tick"
+                )
+            if start < note_ends.get(pitch, 0):
+                raise ValueError(
+                    f"track {track.name!r}: overlapping MIDI pitch {pitch}; "
+                    "shorten or split the notes"
+                )
+            note_ends[pitch] = end
+            if track.gain == 0 or song.master_gain == 0:
+                continue
+            if percussion:
+                percussion_intervals.setdefault(pitch, []).append((start, end, track.name))
+            velocity = note.velocity * (track.gain * song.master_gain if percussion else 1)
+            velocity = max(1, round(velocity * 127))
+            events.append(
+                (start, 1, mido.Message("note_on", channel=channel, note=pitch, velocity=velocity))
+            )
+            events.append(
+                (end, 0, mido.Message("note_off", channel=channel, note=pitch, velocity=0))
+            )
+        if percussion:
+            # All percussion shares one channel. Sorting within separate MIDI tracks
+            # cannot guarantee that a retrigger follows the previous track's note-off.
+            if percussion_events is None:
+                percussion_events = events
+            else:
+                percussion_events.extend(events)
+                events = []
+        track_events.append((output, events))
+        midi.tracks.append(output)
+    for pitch, intervals in percussion_intervals.items():
+        previous_end = 0
+        previous_track = ""
+        for start, end, track_name in sorted(intervals):
+            if start < previous_end:
+                raise ValueError(
+                    f"overlapping percussion MIDI pitch {pitch} across tracks "
+                    f"{previous_track!r} and {track_name!r}; channel 10 is shared"
+                )
+            previous_end, previous_track = end, track_name
+    for output, events in track_events:
+        previous = 0
+        # Pedal changes precede note-offs, then note-ons at the same tick.
+        for tick, _, event in sorted(events, key=lambda item: (item[0], item[1])):
+            output.append(event.copy(time=tick - previous))
+            previous = tick
+        output.append(mido.MetaMessage("end_of_track", time=end_tick - previous))
+    midi.charset = "utf-8"
+    destination = Path(path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    midi.save(str(destination))
+    return {
+        "output": str(destination),
+        "tracks": len(song.tracks),
+        "ticks_per_beat": TICKS_PER_BEAT,
+        "duration_seconds": midi.length,
+        "warnings": _export_warnings(song),
+    }

audio_as_code/model.py

@@ -0,0 +1,292 @@
+"""Versioned, portable musical data. All time values are quarter-note beats."""
+
+from __future__ import annotations
+
+import math
+import re
+from bisect import bisect_right
+from pathlib import Path
+from typing import Annotated, Literal
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StrictBool,
+    StrictInt,
+    field_validator,
+    model_validator,
+)
+
+from .instruments import KIT_NOTES, Instrument, get_instrument, require_instrument
+
+Number = Annotated[float, Field(strict=True, allow_inf_nan=False)]
+MidiPitch = Annotated[StrictInt, Field(ge=0, le=127)]
+NoteName = Annotated[str, Field(strict=True, pattern=r"^[A-Ga-g](?:#|b)?-?[0-9]$")]
+Pitch = MidiPitch | NoteName
+
+
+def midi_pitch(value: int | str) -> int:
+    """Convert scientific pitch notation (C4 = 60, A4 = 69) to MIDI."""
+    if isinstance(value, bool):
+        raise ValueError("pitch must be a MIDI integer or a note name, not a boolean")
+    if isinstance(value, int):
+        result = value
+    elif isinstance(value, str):
+        match = re.fullmatch(r"([A-Ga-g])([#b]?)(-?[0-9])", value)
+        if not match:
+            raise ValueError(f"invalid pitch {value!r}; use a name such as C4, F#3, or Bb2")
+        letter, accidental, octave = match.groups()
+        pitch_class = {"C": 0, "D": 2, "E": 4, "F": 5, "G": 7, "A": 9, "B": 11}
+        result = (int(octave) + 1) * 12 + pitch_class[letter.upper()]
+        result += {"": 0, "#": 1, "b": -1}[accidental]
+    else:
+        raise ValueError("pitch must be a MIDI integer or a note name")
+    if not 0 <= result <= 127:
+        raise ValueError(f"pitch {value!r} falls outside MIDI range 0..127")
+    return result
+
+
+class ScoreModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, validate_default=True)
+
+
+class TempoChange(ScoreModel):
+    beat: Annotated[Number, Field(ge=0)]
+    bpm: Annotated[Number, Field(ge=20, le=300)]
+
+
+class PedalEvent(ScoreModel):
+    """Binary piano damper pedal; events apply before note-offs at the same beat."""
+
+    beat: Annotated[Number, Field(ge=0)]
+    down: StrictBool
+
+
+class AutomationPoint(ScoreModel):
+    beat: Annotated[Number, Field(ge=0)]
+    value: Annotated[Number, Field(ge=-1, le=1)]
+
+
+class Automation(ScoreModel):
+    parameter: Literal["gain", "pan", "master_gain"]
+    points: Annotated[tuple[AutomationPoint, ...], Field(min_length=1, max_length=1024)]
+    interpolation: Literal["linear", "step"] = "linear"
+
+    @model_validator(mode="after")
+    def validate_points(self) -> Automation:
+        if any(a.beat >= b.beat for a, b in zip(self.points, self.points[1:], strict=False)):
+            raise ValueError("automation points must have strictly increasing beats")
+        if self.parameter != "pan" and any(point.value < 0 for point in self.points):
+            raise ValueError("gain automation values must be between 0 and 1")
+        return self
+
+
+class Delay(ScoreModel):
+    """Finite echo train: first echo at full wet gain, successive echoes decay."""
+
+    type: Literal["delay"] = "delay"
+    time_seconds: Annotated[Number, Field(ge=0.01, le=2)] = 0.25
+    feedback: Annotated[Number, Field(ge=0, le=0.85)] = 0.4
+    repeats: Annotated[StrictInt, Field(ge=1, le=16)] = 4
+    mix: Annotated[Number, Field(ge=0, le=1)] = 0.2
+
+
+class Reverb(ScoreModel):
+    """Generated stereo comb network with diffusion; no measured impulse response."""
+
+    type: Literal["reverb"] = "reverb"
+    decay_seconds: Annotated[Number, Field(ge=0.1, le=5)] = 1.2
+    mix: Annotated[Number, Field(ge=0, le=1)] = 0.2
+
+
+Effect = Annotated[Delay | Reverb, Field(discriminator="type")]
+
+
+def _validate_lanes(lanes: tuple[Automation, ...], allowed: set[str]) -> None:
+    names = [lane.parameter for lane in lanes]
+    if len(names) != len(set(names)) or not set(names) <= allowed:
+        raise ValueError(f"automation parameters must be unique and drawn from {sorted(allowed)}")
+
+
+class Note(ScoreModel):
+    pitch: Pitch = "C4"
+    start: Annotated[Number, Field(ge=0)] = 0
+    duration: Annotated[Number, Field(gt=0)] = 1
+    velocity: Annotated[Number, Field(gt=0, le=1)] = 0.8
+    release_seconds: Annotated[Number, Field(ge=0, le=10)] | None = None
+
+    @field_validator("pitch")
+    @classmethod
+    def valid_pitch(cls, value: int | str) -> int | str:
+        midi_pitch(value)
+        return value
+
+
+class Tone(ScoreModel):
+    """Instrument-specific generated tone controls; never refers to an audio asset."""
+
+    brightness: Annotated[Number, Field(ge=0, le=1)] = 0.5
+    decay_seconds: Annotated[Number, Field(ge=0.1, le=20)] | None = None
+    pluck_position: Annotated[Number, Field(ge=0.05, le=0.45)] | None = None
+    breath: Annotated[Number, Field(ge=0, le=1)] | None = None
+    vibrato_depth_cents: Annotated[Number, Field(ge=0, le=100)] | None = None
+    vibrato_rate_hz: Annotated[Number, Field(ge=0.1, le=12)] | None = None
+    glide_semitones: Annotated[Number, Field(ge=-24, le=24)] | None = None
+    detune_cents: Annotated[Number, Field(ge=0, le=40)] | None = None
+
+
+class Track(ScoreModel):
+    name: Annotated[str, Field(strict=True, min_length=1, max_length=80)]
+    instrument: Instrument = "pluck"
+    gain: Annotated[Number, Field(ge=0, le=1)] = 0.6
+    pan: Annotated[Number, Field(ge=-1, le=1)] = 0
+    tone: Tone | None = None
+    notes: tuple[Note, ...] = ()
+    release_seconds: Annotated[Number, Field(ge=0, le=10)] = 0
+    automation: Annotated[tuple[Automation, ...], Field(max_length=2)] = ()
+    effects: Annotated[tuple[Effect, ...], Field(max_length=4)] = ()
+
+    pedal: Annotated[tuple[PedalEvent, ...], Field(max_length=1024)] = ()
+
+    @field_validator("instrument", mode="before")
+    @classmethod
+    def available_instrument(cls, value: object) -> object:
+        if isinstance(value, str):
+            require_instrument(value)
+        return value
+
+    @model_validator(mode="after")
+    def validate_tone(self) -> Track:
+        _validate_lanes(self.automation, {"gain", "pan"})
+        if self.pedal:
+            if self.instrument != "piano":
+                raise ValueError("pedal events are supported only by piano")
+            if any(a.beat >= b.beat for a, b in zip(self.pedal, self.pedal[1:], strict=False)):
+                raise ValueError("pedal events must have strictly increasing beats")
+            if any(event.down != (index % 2 == 0) for index, event in enumerate(self.pedal)):
+                raise ValueError("pedal events must alternate down/up, starting with down")
+        if self.instrument == "drum_machine":
+            for note in self.notes:
+                if midi_pitch(note.pitch) not in KIT_NOTES:
+                    raise ValueError(f"drum_machine pitch must be one of {sorted(KIT_NOTES)}")
+        if self.tone is not None:
+            supported = get_instrument(self.instrument).tone_controls
+            if not supported:
+                raise ValueError(f"tone controls are not supported by {self.instrument}")
+            for name, value in self.tone.model_dump().items():
+                if value is not None and name not in supported:
+                    raise ValueError(f"{name} is not supported by {self.instrument}")
+        return self
+
+    @field_validator("name")
+    @classmethod
+    def valid_name(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("track name must contain a visible character")
+        return value
+
+
+class Song(ScoreModel):
+    schema_version: Literal["1"] = "1"
+    title: Annotated[str, Field(strict=True, min_length=1, max_length=200)] = "Untitled"
+    bpm: Annotated[Number, Field(ge=20, le=300)] = 120
+    beats: Annotated[Number, Field(gt=0, le=65536)] = 16
+    sample_rate: Literal[22050, 44100, 48000] = 44100
+    seed: Annotated[StrictInt, Field(ge=0, le=4294967295)] = 0
+    master_gain: Annotated[Number, Field(ge=0, le=1)] = 0.8
+    tracks: Annotated[tuple[Track, ...], Field(min_length=1, max_length=64)]
+    tempo_map: Annotated[tuple[TempoChange, ...], Field(max_length=1024)] = ()
+    automation: Annotated[tuple[Automation, ...], Field(max_length=1)] = ()
+    effects: Annotated[tuple[Effect, ...], Field(max_length=4)] = ()
+
+    @model_validator(mode="after")
+    def validate_arrangement(self) -> Song:
+        _validate_lanes(self.automation, {"master_gain"})
+        if any(a.beat >= b.beat for a, b in zip(self.tempo_map, self.tempo_map[1:], strict=False)):
+            raise ValueError("tempo_map must have strictly increasing beats")
+        if any(change.beat >= self.beats for change in self.tempo_map):
+            raise ValueError("tempo changes must occur before the song ends")
+        for owner in (self, *self.tracks):
+            for lane in owner.automation:
+                if lane.points[-1].beat > self.beats:
+                    raise ValueError("automation points must not exceed the song's beats")
+        names: set[str] = set()
+        count = 0
+        for track in self.tracks:
+            if track.pedal and track.pedal[-1].beat > self.beats:
+                raise ValueError("pedal events must not exceed the song's beats")
+            if track.name in names:
+                raise ValueError(f"duplicate track name: {track.name!r}")
+            names.add(track.name)
+            count += len(track.notes)
+            for index, note in enumerate(track.notes):
+                end = note.start + note.duration
+                if not math.isfinite(end) or end > self.beats + 1e-9:
+                    raise ValueError(
+                        f"track {track.name!r}, note {index}: ends at beat {end}; "
+                        f"song ends at {self.beats}"
+                    )
+        if count > 100000:
+            raise ValueError("a score may contain at most 100000 notes")
+        return self
+
+    @property
+    def seconds(self) -> float:
+        return self.beat_to_seconds(self.beats)
+
+    def beat_to_seconds(self, beat: float) -> float:
+        """Integrate piecewise-constant BPM; the last tempo continues beyond the score."""
+        if not math.isfinite(beat) or beat < 0:
+            raise ValueError("beat must be finite and nonnegative")
+        if not self.tempo_map:
+            return beat * 60 / self.bpm
+        seconds, previous, bpm = 0.0, 0.0, self.bpm
+        for change in self.tempo_map:
+            if change.beat > beat:
+                break
+            seconds += (change.beat - previous) * 60 / bpm
+            previous, bpm = change.beat, change.bpm
+        return seconds + (beat - previous) * 60 / bpm
+
+    @property
+    def render_seconds(self) -> float:
+        from .effects import effects_tail
+
+        end = self.seconds
+        for track in self.tracks:
+            dry_end = max(
+                (
+                    self.beat_to_seconds(self.note_gate_end(track, n))
+                    + self.note_release_seconds(track, n)
+                    for n in track.notes
+                ),
+                default=0.0,
+            )
+            end = max(end, dry_end + effects_tail(track.effects))
+        return end + effects_tail(self.effects)
+
+    def note_gate_end(self, track: Track, note: Note) -> float:
+        """Written key release, extended to pedal lift when caught by the damper pedal."""
+        end = note.start + note.duration
+        index = bisect_right(track.pedal, end, key=lambda event: event.beat)
+        if index and track.pedal[index - 1].down:
+            return track.pedal[index].beat if index < len(track.pedal) else max(end, self.beats)
+        return end
+
+    def note_release_seconds(self, track: Track, note: Note) -> float:
+        """A caught piano note defaults to a 120ms damper tail after pedal lift."""
+        if note.release_seconds is not None:
+            return note.release_seconds
+        if track.release_seconds:
+            return track.release_seconds
+        return 0.12 if self.note_gate_end(track, note) > note.start + note.duration else 0.0
+
+    @classmethod
+    def load(cls, path: str | Path) -> Song:
+        return cls.model_validate_json(Path(path).read_text(encoding="utf-8-sig"))
+
+    def save(self, path: str | Path) -> None:
+        destination = Path(path)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(self.model_dump_json(indent=2) + "\n", encoding="utf-8")