Crate symphoxy

Crate symphoxy 

Source
Expand description

§Symphoxy - Music as Code

Symphoxy is a flexible, powerful music composition library that treats music as code. Create complex musical compositions using an intuitive, simple API.

§Core Concepts

  • Notes: Individual musical sounds with pitch, duration, timbre, and volume
  • Lines: Sequences of notes played one after another (melodies/rhythms)
  • Pieces: Multiple lines played simultaneously (harmony/polyphony)
  • Chords: Groups of pitches played together

§Quick Start

use symphoxy::prelude::*;

// Create individual notes
let c4 = C4;
let d4 = NotePitch::new(293.66); // Either manually specify frequency...
let e4 = d4.semitone(1);         // ...or use semitone offsets

// Build melodies by adding notes together
let melody = piano(quarter(c4) + quarter(d4) + half(e4)); // C-D-E

// Create harmony by stacking lines with *
let bass_line = bass(whole(C4.octave(-1))); // C3
let piece = melody * bass_line;

// Create chords
let c_major = Chord::from_degrees(&MajorScale(C4), &[1, 3, 5]);
let chord_piece = piano(quarter(c_major));

§Key Features

§Fluent API

Chain operations naturally:

use symphoxy::prelude::*;

// Create a melody with two instruments
let complex_line = piano(dotted(quarter)(C4))
    .volume(0.8) +
    electric_guitar(tie(eighth, sixteenth)(A4))
    .volume(1.2);

§Rich Timbres

Built-in instrument sounds:

use symphoxy::prelude::*;

let piano_note = piano(quarter(C4));
let guitar_note = electric_guitar(quarter(C4));
let bass_note = bass(quarter(C4));
// Different notes have different drum kit sounds
let drum_hit = drums(quarter(C4.octave(1))); // Kick drum at C5

§Flexible Note Lengths

Standard and custom durations:

use symphoxy::prelude::*;

let notes = piano(whole(C4)) + piano(half(C4)) + piano(quarter(C4)) + piano(eighth(C4));
let dotted_half = piano(dotted(half)(C4));
let tied_notes = piano(tie(quarter, eighth)(C4));

§Chord Support

use symphoxy::prelude::*;

// Build chords from pitches
let chord = Chord::new([C4, NotePitch::new(329.63), NotePitch::new(392.00)]);

// Play all notes simultaneously  
let simultaneous = piano(quarter(chord.clone()));

// You can also use a "striker" function to play it with a specific pattern
fn striker_fn(pitch: NotePitch) -> Line {
    piano(quarter(pitch) + eighth(REST) + eighth(pitch))
}

let simultaneous_patterned = chord.strike(striker_fn);

// Or arpeggiate
let arpeggio_notes: Vec<Note> = chord.0.into_iter()
    .map(|pitch| piano(eighth(pitch)))
    .collect();
let arpeggio = Line::from(arpeggio_notes);

§Architecture

The library follows a composable design:

  1. Core Types: Note, NotePitch, NoteLength, Timbre
  2. Collections: Line (sequential), Piece (simultaneous), Chord (harmonic)
  3. Traits: LengthFluid, TimbreFluid, ChordFluid for flexibility
  4. Scales: Support for different musical scales and tuning systems
  5. Instruments: Guitar fret/tuning support and other instrument-specific tools

§Features

  • interactive-tui: Interactive terminal interface for playback and file export
  • wav-output: Export compositions to WAV audio files
  • live-output: Real-time audio playback

§Philosophy

Rather than relying heavily on traditional music notation, Symphoxy embraces a “piano roll” approach where music is constructed programmatically. This makes it accessible to developers while remaining powerful enough for complex compositions.

The design prioritizes:

  • Ergonomics: Intuitive, readable code
  • Flexibility: Multiple ways to express the same musical ideas
  • Composability: Building complex pieces from simple parts
  • Performance: Zero-cost abstractions where possible

Re-exports§

pub use instrument_tools::strings::Frets;
pub use instrument_tools::strings::GuitarFrets;
pub use instrument_tools::strings::GuitarTuning;
pub use instrument_tools::strings::StringTuning;
pub use note::chord::Chord;
pub use note::chord::ChordFluid;
pub use note::bass;
pub use note::drums;
pub use note::electric_guitar;
pub use note::piano;
pub use note::sine;
pub use note::dotted;
pub use note::double_whole;
pub use note::eighth;
pub use note::half;
pub use note::quarter;
pub use note::sixteenth;
pub use note::tie;
pub use note::whole;
pub use note::LengthFluid;
pub use note::TimbreFluid;
pub use note::Note;
pub use note::NoteKind;
pub use note::NoteLength;
pub use note::NotePitch;
pub use note::Timbre;
pub use note::REST;
pub use piece::line::Line;
pub use piece::Piece;
pub use scales::tet12::get_note_name;
pub use scales::tet12::get_note_name_with_octave;
pub use scales::tet12::Tet12;
pub use scales::tet12::A4;
pub use scales::tet12::C4;
pub use scales::Scale;

Modules§

instrument_tools
Instrument-specific tools and utilities.
note
Musical note types, timbres, lengths, and related functionality.
piece
Core musical composition types and functions.
prelude
Commonly used types and functions for music composition.
scales
Musical scales and tuning systems.

Structs§

MusicPlayer
Creates a configuration for this music library

Enums§

InteractiveTui
Interactive TUI for playing music pieces in a terminal interface. Allows users to select modes and configure playback options interactively.