deepmind-midi 26.5.2

Sans-IO protocol library for Behringer DeepMind synthesizers: SysEx, NRPN, programs and device state
Documentation
//! `.syx` files: the format programs are traded in, read and written.
//!
//! A `.syx` file is a run of `SysEx` frames and nothing else. There is no
//! header, no index and no trailer, so a preset pack is 128 program dumps end to
//! end, and a single patch is one dump. That is the whole format; this module is
//! what walks it.
//!
//! ```
//! use deepmind_midi::ids::{Bank, DeviceId, ProgramNumber, ProtocolVersion};
//! use deepmind_midi::program::{Program, ProgramName};
//! use deepmind_midi::syx::{self, File, Writer};
//!
//! let mut program = Program::new(ProtocolVersion::V6);
//! program.set_name(ProgramName::new("Bass Sweep")?);
//!
//! // Write. The buffer is the host's: `MAX_PROGRAM_FRAME_LEN` sizes one
//! // program, `MAX_BANK_LEN` a whole bank.
//! let mut bytes = [0; syx::MAX_PROGRAM_FRAME_LEN];
//! let mut writer = Writer::new(&mut bytes, DeviceId::Broadcast);
//! writer.push_program(Bank::A, ProgramNumber::FIRST, &program)?;
//! let written = writer.finish();
//!
//! // Read. Every program the file carries, and where it says each belongs.
//! for entry in File::new(bytes.get(..written).unwrap_or_default()).programs() {
//!     let entry = entry?;
//!     println!("{:?} {}", entry.slot, entry.program.name());
//! }
//! # Ok::<(), deepmind_midi::Error>(())
//! ```
//!
//! # No IO
//!
//! Opening the file is the host's job. This module starts from bytes and ends at
//! bytes, so it also works on a file that never touched a disk: a pack
//! downloaded into memory, one assembled from a device, one under test.
//!
//! # Reading is lenient about the file, strict about the frame
//!
//! Files in the wild are padded, concatenated and appended to, so bytes between
//! frames are skipped. A frame that does not parse is yielded as the error it
//! failed with, and the walk goes on: one bad frame is no reason to lose the
//! other 127.
//!
//! [`Programs`] skips frames carrying something other than a program (the
//! globals, a pattern, a bank of names). Reach those through [`Frames`], which
//! hands back everything the file holds.
//!
//! # Writing does not reproduce every file byte for byte
//!
//! A program that goes in comes out unchanged; a file does not always. The
//! manual prints 278 packed bytes for a 242-byte program where padding gives
//! 280, and [`packed`](crate::sysex::packed) pads. A file written by something
//! that packs the other way reads back to identical programs and rewrites to a
//! different length. The programs are the file's content; the padding is not.
//!
//! # What a file does not say
//!
//! Which firmware wrote it. A dump carries the comms protocol version, which
//! decides how many bytes the program occupies, and nothing carries the firmware
//! version, which decides what three of the value tables mean. A host that knows
//! the firmware another way passes it to the accessors that take one; otherwise
//! it gets the current tables. See [`param`](crate::param#firmware).

mod reader;
mod writer;

pub use reader::{Entry, File, Frames, Programs};
#[cfg(feature = "alloc")]
pub use writer::bank_to_vec;
pub use writer::{
    MAX_BANK_LEN, MAX_PROGRAM_FRAME_LEN, Writer, edit_buffer_frame_len, program_frame_len,
};