math-sonify 1.4.0

//! Minimal Standard MIDI File (SMF) Type 0 writer and trajectory-to-MIDI converter.
//!
//! This module writes raw MIDI bytes without any external crate dependency.
//! It implements:
//! - Variable-Length Quantity (VLQ) encoding for delta times
//! - SMF header chunk (`MThd`)
//! - SMF track chunk (`MTrk`) with Note On/Off and tempo meta-events
//! - Trajectory-to-MIDI note mapping from attractor state series

use std::io;
use std::path::Path;

// ── MidiError ─────────────────────────────────────────────────────────────────

/// Errors produced by the MIDI writer.
#[derive(Debug)]
pub enum MidiError {
    /// An I/O error while writing the file.
    Io(io::Error),
    /// No notes to write.
    Empty,
}

impl std::fmt::Display for MidiError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            MidiError::Io(e) => write!(f, "MIDI I/O error: {e}"),
            MidiError::Empty => write!(f, "No MIDI notes to write"),
        }
    }
}

impl From<io::Error> for MidiError {
    fn from(e: io::Error) -> Self {
        MidiError::Io(e)
    }
}

// ── MidiNote ──────────────────────────────────────────────────────────────────

/// A single MIDI note with absolute timing.
#[derive(Debug, Clone, PartialEq)]
pub struct MidiNote {
    /// MIDI pitch (0–127).
    pub pitch: u8,
    /// MIDI velocity (0–127).
    pub velocity: u8,
    /// Duration in MIDI ticks.
    pub duration_ticks: u32,
    /// Absolute start time in MIDI ticks.
    pub start_tick: u32,
}

// ── VLQ encoding ──────────────────────────────────────────────────────────────

/// Encode `value` as a MIDI Variable-Length Quantity into `buf`.
///
/// VLQ stores a value in 7-bit groups, most-significant first.  Each byte has
/// the high bit set except the last one.
pub fn encode_vlq(mut value: u32, buf: &mut Vec<u8>) {
    if value == 0 {
        buf.push(0x00);
        return;
    }
    let mut bytes = [0u8; 5];
    let mut len = 0;
    while value > 0 {
        bytes[len] = (value & 0x7F) as u8;
        value >>= 7;
        len += 1;
    }
    // Write most-significant group first, with continuation bit set.
    for i in (1..len).rev() {
        buf.push(bytes[i] | 0x80);
    }
    buf.push(bytes[0]); // Last byte — no continuation bit.
}

/// Decode a VLQ from `data` starting at `offset`.
/// Returns `(value, bytes_consumed)`.
pub fn decode_vlq(data: &[u8], offset: usize) -> Option<(u32, usize)> {
    let mut value: u32 = 0;
    let mut consumed = 0;
    loop {
        if offset + consumed >= data.len() {
            return None;
        }
        let byte = data[offset + consumed];
        consumed += 1;
        value = (value << 7) | u32::from(byte & 0x7F);
        if byte & 0x80 == 0 {
            break;
        }
        if consumed >= 5 {
            return None; // Malformed VLQ
        }
    }
    Some((value, consumed))
}

// ── SMF builder ───────────────────────────────────────────────────────────────

const TICKS_PER_QUARTER: u16 = 480;

/// Write a 32-bit big-endian integer into `buf`.
fn push_u32_be(buf: &mut Vec<u8>, v: u32) {
    buf.extend_from_slice(&v.to_be_bytes());
}

/// Write a 16-bit big-endian integer into `buf`.
fn push_u16_be(buf: &mut Vec<u8>, v: u16) {
    buf.extend_from_slice(&v.to_be_bytes());
}

/// Build the raw bytes for an SMF Type-0 MIDI file.
///
/// - `notes` must not be empty.
/// - `ticks_per_quarter` is the timing resolution (480 is standard).
/// - `tempo_us` is microseconds per beat (e.g. 500 000 = 120 BPM).
fn build_smf(notes: &[MidiNote], ticks_per_quarter: u16, tempo_us: u32) -> Vec<u8> {
    // ── Track chunk body ──────────────────────────────────────────────────────
    // Build a flat list of (abs_tick, is_note_on, pitch, velocity) events,
    // then sort by abs_tick and convert to delta-time format.

    #[derive(PartialOrd, Ord, PartialEq, Eq)]
    struct RawEvent {
        abs_tick: u32,
        /// 0 = NoteOn, 1 = NoteOff (sort NoteOff after NoteOn at same tick)
        kind_order: u8,
        pitch: u8,
        velocity: u8,
    }

    let mut events: Vec<RawEvent> = Vec::with_capacity(notes.len() * 2);
    for note in notes {
        events.push(RawEvent {
            abs_tick: note.start_tick,
            kind_order: 0,
            pitch: note.pitch,
            velocity: note.velocity,
        });
        events.push(RawEvent {
            abs_tick: note.start_tick + note.duration_ticks,
            kind_order: 1,
            pitch: note.pitch,
            velocity: 0,
        });
    }
    events.sort();

    let mut track_body: Vec<u8> = Vec::new();

    // Tempo meta-event at tick 0: FF 51 03 tt tt tt
    encode_vlq(0, &mut track_body); // delta = 0
    track_body.push(0xFF); // meta
    track_body.push(0x51); // tempo
    track_body.push(0x03); // length = 3 bytes
    track_body.push(((tempo_us >> 16) & 0xFF) as u8);
    track_body.push(((tempo_us >> 8) & 0xFF) as u8);
    track_body.push((tempo_us & 0xFF) as u8);

    let mut prev_tick: u32 = 0;
    for ev in &events {
        let delta = ev.abs_tick.saturating_sub(prev_tick);
        encode_vlq(delta, &mut track_body);
        prev_tick = ev.abs_tick;
        if ev.kind_order == 0 {
            // Note On: 0x9n pitch velocity
            track_body.push(0x90); // channel 0
            track_body.push(ev.pitch);
            track_body.push(ev.velocity);
        } else {
            // Note Off: 0x8n pitch 0
            track_body.push(0x80); // channel 0
            track_body.push(ev.pitch);
            track_body.push(0x00);
        }
    }

    // End-of-track meta-event: FF 2F 00
    encode_vlq(0, &mut track_body);
    track_body.push(0xFF);
    track_body.push(0x2F);
    track_body.push(0x00);

    // ── Header chunk ─────────────────────────────────────────────────────────
    let mut smf: Vec<u8> = Vec::new();

    // MThd
    smf.extend_from_slice(b"MThd");
    push_u32_be(&mut smf, 6); // Header length always 6
    push_u16_be(&mut smf, 0); // Format 0
    push_u16_be(&mut smf, 1); // Num tracks = 1
    push_u16_be(&mut smf, ticks_per_quarter);

    // MTrk
    smf.extend_from_slice(b"MTrk");
    push_u32_be(&mut smf, track_body.len() as u32);
    smf.extend_from_slice(&track_body);

    smf
}

// ── MidiExporter ──────────────────────────────────────────────────────────────

/// Converts attractor trajectory state series to MIDI notes and writes SMF files.
pub struct MidiExporter;

impl MidiExporter {
    /// Map a trajectory of `(x, y, z)` states to [`MidiNote`]s.
    ///
    /// - `x` maps to pitch in MIDI 48–84 (3 octaves, C3–C6).
    /// - `|y|` maps to velocity in 40–127.
    /// - Duration = 1 quarter note (480 ticks at the standard resolution).
    /// - `_sample_rate` and `_bpm` are used to compute ticks per note; here
    ///   we use one quarter note per state point at `bpm`.
    pub fn from_trajectory(
        state_series: &[(f64, f64, f64)],
        _sample_rate: f64,
        bpm: u32,
    ) -> Vec<MidiNote> {
        if state_series.is_empty() {
            return Vec::new();
        }

        // Determine x and y ranges for normalisation.
        let x_min = state_series.iter().map(|s| s.0).fold(f64::INFINITY, f64::min);
        let x_max = state_series.iter().map(|s| s.0).fold(f64::NEG_INFINITY, f64::max);
        let y_min = state_series.iter().map(|s| s.1.abs()).fold(f64::INFINITY, f64::min);
        let y_max = state_series.iter().map(|s| s.1.abs()).fold(f64::NEG_INFINITY, f64::max);

        let x_range = (x_max - x_min).max(1e-10);
        let y_range = (y_max - y_min).max(1e-10);

        // Ticks per quarter note at the given BPM (we use 1 quarter note per state).
        let ticks_per_beat = TICKS_PER_QUARTER as u32;
        let _ = bpm; // BPM used to compute the tempo_us stored in the file.

        state_series
            .iter()
            .enumerate()
            .map(|(i, &(x, y, _z))| {
                let x_norm = ((x - x_min) / x_range).clamp(0.0, 1.0);
                let y_norm = ((y.abs() - y_min) / y_range).clamp(0.0, 1.0);

                // Pitch: MIDI 48–84 (36 semitones over 3 octaves)
                let pitch = (48.0 + x_norm * 36.0).clamp(48.0, 84.0) as u8;
                // Velocity: 40–127
                let velocity = (40.0 + y_norm * 87.0).clamp(40.0, 127.0) as u8;

                MidiNote {
                    pitch,
                    velocity,
                    duration_ticks: ticks_per_beat,
                    start_tick: i as u32 * ticks_per_beat,
                }
            })
            .collect()
    }

    /// Write `notes` to a Standard MIDI File at `path`.
    pub fn write(notes: &[MidiNote], path: &Path) -> Result<(), MidiError> {
        if notes.is_empty() {
            return Err(MidiError::Empty);
        }
        let tempo_us = 500_000u32; // 120 BPM default
        let bytes = build_smf(notes, TICKS_PER_QUARTER, tempo_us);
        std::fs::write(path, &bytes)?;
        Ok(())
    }
}

// ── tests ─────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    // 1. VLQ encoding: value 0
    #[test]
    fn vlq_zero() {
        let mut buf = Vec::new();
        encode_vlq(0, &mut buf);
        assert_eq!(buf, &[0x00]);
    }

    // 2. VLQ encoding: value 127 (fits in one byte)
    #[test]
    fn vlq_127() {
        let mut buf = Vec::new();
        encode_vlq(127, &mut buf);
        assert_eq!(buf, &[0x7F]);
    }

    // 3. VLQ encoding: value 128 (needs two bytes)
    #[test]
    fn vlq_128() {
        let mut buf = Vec::new();
        encode_vlq(128, &mut buf);
        assert_eq!(buf, &[0x81, 0x00]);
    }

    // 4. VLQ encoding: value 16383 (max for two bytes)
    #[test]
    fn vlq_16383() {
        let mut buf = Vec::new();
        encode_vlq(16383, &mut buf);
        assert_eq!(buf, &[0xFF, 0x7F]);
    }

    // 5. VLQ round-trip
    #[test]
    fn vlq_round_trip() {
        for &v in &[0u32, 1, 63, 127, 128, 255, 256, 16383, 16384, 0x0FFFFFFF] {
            let mut buf = Vec::new();
            encode_vlq(v, &mut buf);
            let (decoded, _consumed) = decode_vlq(&buf, 0).expect("decode failed");
            assert_eq!(decoded, v, "round-trip failed for {}", v);
        }
    }

    // 6. Note pitch in bounds
    #[test]
    fn note_pitch_in_bounds() {
        let series: Vec<(f64, f64, f64)> = (-10..=10)
            .map(|i| (i as f64, (i as f64).abs(), 0.0))
            .collect();
        let notes = MidiExporter::from_trajectory(&series, 44100.0, 120);
        for note in &notes {
            assert!(note.pitch >= 48 && note.pitch <= 84,
                "pitch {} out of range 48..84", note.pitch);
        }
    }

    // 7. Note velocity in bounds
    #[test]
    fn note_velocity_in_bounds() {
        let series: Vec<(f64, f64, f64)> = (0..20)
            .map(|i| (i as f64, (i as f64 - 10.0), 0.0))
            .collect();
        let notes = MidiExporter::from_trajectory(&series, 44100.0, 120);
        for note in &notes {
            assert!(note.velocity >= 40 && note.velocity <= 127,
                "velocity {} out of range 40..127", note.velocity);
        }
    }

    // 8. Note count matches series length
    #[test]
    fn note_count_matches_series() {
        let series: Vec<(f64, f64, f64)> = (0..50).map(|i| (i as f64, i as f64, 0.0)).collect();
        let notes = MidiExporter::from_trajectory(&series, 44100.0, 120);
        assert_eq!(notes.len(), 50);
    }

    // 9. Empty series → empty notes
    #[test]
    fn empty_series_empty_notes() {
        let notes = MidiExporter::from_trajectory(&[], 44100.0, 120);
        assert!(notes.is_empty());
    }

    // 10. Duration = ticks_per_quarter for each note
    #[test]
    fn note_duration_one_quarter() {
        let series = vec![(0.0f64, 0.0f64, 0.0f64), (1.0, 1.0, 1.0)];
        let notes = MidiExporter::from_trajectory(&series, 44100.0, 120);
        for note in &notes {
            assert_eq!(note.duration_ticks, TICKS_PER_QUARTER as u32);
        }
    }

    // 11. start_tick is sequential with ticks_per_quarter spacing
    #[test]
    fn notes_start_tick_sequential() {
        let series: Vec<(f64, f64, f64)> = (0..5).map(|i| (i as f64, 0.0, 0.0)).collect();
        let notes = MidiExporter::from_trajectory(&series, 44100.0, 120);
        for (i, note) in notes.iter().enumerate() {
            assert_eq!(note.start_tick, i as u32 * TICKS_PER_QUARTER as u32);
        }
    }

    // 12. SMF header starts with MThd
    #[test]
    fn smf_header_mthd() {
        let notes = vec![MidiNote { pitch: 60, velocity: 80, duration_ticks: 480, start_tick: 0 }];
        let bytes = build_smf(&notes, 480, 500_000);
        assert_eq!(&bytes[0..4], b"MThd");
    }

    // 13. SMF header length field = 6
    #[test]
    fn smf_header_length_six() {
        let notes = vec![MidiNote { pitch: 60, velocity: 80, duration_ticks: 480, start_tick: 0 }];
        let bytes = build_smf(&notes, 480, 500_000);
        let hlen = u32::from_be_bytes([bytes[4], bytes[5], bytes[6], bytes[7]]);
        assert_eq!(hlen, 6);
    }

    // 14. SMF format field = 0
    #[test]
    fn smf_format_zero() {
        let notes = vec![MidiNote { pitch: 60, velocity: 80, duration_ticks: 480, start_tick: 0 }];
        let bytes = build_smf(&notes, 480, 500_000);
        let fmt = u16::from_be_bytes([bytes[8], bytes[9]]);
        assert_eq!(fmt, 0);
    }

    // 15. SMF track count = 1
    #[test]
    fn smf_track_count_one() {
        let notes = vec![MidiNote { pitch: 60, velocity: 80, duration_ticks: 480, start_tick: 0 }];
        let bytes = build_smf(&notes, 480, 500_000);
        let ntracks = u16::from_be_bytes([bytes[10], bytes[11]]);
        assert_eq!(ntracks, 1);
    }

    // 16. SMF track chunk starts with MTrk
    #[test]
    fn smf_track_mtrk() {
        let notes = vec![MidiNote { pitch: 60, velocity: 80, duration_ticks: 480, start_tick: 0 }];
        let bytes = build_smf(&notes, 480, 500_000);
        assert_eq!(&bytes[14..18], b"MTrk");
    }

    // 17. write() to temp file succeeds
    #[test]
    fn write_to_file() {
        let dir = std::env::temp_dir();
        let path = dir.join("test_midi.mid");
        let notes = vec![MidiNote { pitch: 60, velocity: 80, duration_ticks: 480, start_tick: 0 }];
        MidiExporter::write(&notes, &path).expect("write failed");
        assert!(path.exists());
        let _ = std::fs::remove_file(&path);
    }

    // 18. write() with empty notes returns Err
    #[test]
    fn write_empty_notes_error() {
        let dir = std::env::temp_dir();
        let path = dir.join("test_midi_empty.mid");
        let result = MidiExporter::write(&[], &path);
        assert!(result.is_err());
    }

    // 19. VLQ: all byte groups have continuation bit set except last
    #[test]
    fn vlq_continuation_bit() {
        let mut buf = Vec::new();
        encode_vlq(300, &mut buf); // 300 = 0b10_0101100, needs 2 bytes
        assert_eq!(buf.len(), 2);
        assert!(buf[0] & 0x80 != 0, "first byte should have continuation bit");
        assert!(buf[1] & 0x80 == 0, "last byte should not have continuation bit");
    }

    // 20. Trajectory with all-same x → pitch should be constant
    #[test]
    fn trajectory_same_x_constant_pitch() {
        let series: Vec<(f64, f64, f64)> = (0..5).map(|i| (5.0_f64, i as f64, 0.0)).collect();
        let notes = MidiExporter::from_trajectory(&series, 44100.0, 120);
        let first_pitch = notes[0].pitch;
        for note in &notes {
            assert_eq!(note.pitch, first_pitch);
        }
    }
}