takomusic 2.1.2 → 4.0.0

package/README.md

@@ -1,229 +1,151 @@
-# TakoMusic
+# TakoMusic (v4)
 
-A domain-specific language (DSL) for music composition that generates VSQX, MusicXML, and MIDI files.
+TakoMusic is a music composition DSL that evaluates to a neutral `Score` IR and renders via external plugins.
+The language core is backend-agnostic and pushes sound binding to Render Profiles.
 
-## Features
+## Highlights
 
-- **MFS Language**: Write music using a simple, readable syntax
-- **Multi-format Export**: Generate VSQX (Vocaloid), MusicXML (notation), and MIDI (instruments)
-- **Advanced MIDI**: CC, pitch bend, aftertouch, NRPN, SysEx, MPE support
-- **Extended Notation**: Tuplets, grace notes, articulations, dynamics, ornaments
-- **Vocaloid Support**: Full parameter control, vibrato, growl, cross-synthesis
-- **Algorithmic Composition**: Euclidean rhythms, Markov chains, pattern generation
-- **Module System**: Organize code with imports/exports
-- **CLI Tools**: Build, check, format, play, import, record, and render
+- `score`/`clip` DSL with deterministic evaluation (`export fn main() -> Score`)
+- Rational time model (Dur/Pos) without ticks
+- Abstract sounds + render profiles decouple composition from output
+- Renderer Plugin protocol: `capabilities` / `validate` / `render`
+- Web Playground with real-time audio preview
 
-## Installation
+## Quick Start
 
 ```bash
-npm install
-npm run build
-```
+# Install
+npm install -g takomusic
 
-## Quick Start
+# Build a single file (no config needed)
+mf build song.mf
 
-### 1. Create a new project
-
-```bash
-mf init myproject           # Default template
-mf init myproject -t piano  # Piano template
-mf init --list              # List all templates
+# Or initialize a project
+mf init
+mf build
+mf render
 ```
 
-### 2. Edit src/main.mf
-
-```mfs
-export proc main() {
-  title("My First Song");
-  ppq(480);
-  timeSig(4, 4);
-  tempo(120);
-
-  track(midi, piano, { ch: 1, program: 0 }) {
-    at(1:1);
-    chord([C4, E4, G4], 1n);
-  }
-
-  track(midi, drums, { ch: 10, vel: 100 }) {
-    at(1:1);
-    drum(kick, 4n); drum(hhc, 4n);
-    drum(snare, 4n); drum(hhc, 4n);
-  }
-}
-```
+## Demo Song
 
-### 3. Build and play
+Check out `examples/cyberpunk_drive.mf` - a complete synthwave track demonstrating TakoMusic's capabilities:
+
+- 64 bars, 8 tracks, 128 BPM
+- Drums, bass, arpeggios, pads, and lead melody
+- Uses std:core, std:transform, std:theory, std:drums
 
 ```bash
-mf check              # Check for errors
-mf build              # Generate MIDI, MusicXML, VSQX
-mf play               # Live preview with FluidSynth
-mf render -p cli      # Render audio
+# Build and render the demo
+mf build examples/cyberpunk_drive.mf
+mf render examples/cyberpunk_drive.mf.score.json -p profiles/midi.mf.profile.json
 ```
 
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `mf init [dir]` | Initialize new project |
-| `mf build` | Compile to IR and output formats |
-| `mf check` | Static analysis |
-| `mf fmt` | Format source files |
-| `mf play [file]` | Live preview with FluidSynth |
-| `mf import <file>` | Import MusicXML to MFS |
-| `mf record` | Record MIDI input |
-| `mf render -p <profile>` | Render audio |
-| `mf doctor` | Check dependencies |
-
-**Available Templates:** `default`, `piano`, `orchestral`, `edm`, `chiptune`, `jazz`, `vocaloid`, `minimal`
-
 ## Documentation
 
-- **[Language Specification](docs/LANGUAGE.md)** - Complete language syntax, types, and operators
-
-- **[Builtin Functions](docs/BUILTINS.md)** - Low-level runtime functions (IR operations, MIDI control)
-- **[Standard Library](docs/STDLIB.md)** - High-level music functions (theory, patterns, dynamics, etc.)
-
-## Language Basics
-
-### Pitch & Duration Literals
-
-**Pitches:**
-- Natural: `C4`, `D4`, `E4`, `F4`, `G4`, `A4`, `B4`
-- Sharp: `C#4`, `D#4`, `F#4`, `G#4`, `A#4`
-- Flat: `Db4`, `Eb4`, `Gb4`, `Ab4`, `Bb4`
-
-**Durations:**
-- `1n` = whole, `2n` = half, `4n` = quarter
-- `8n` = eighth, `16n` = sixteenth, `32n` = thirty-second
-- `4n.` = dotted quarter, `8n.` = dotted eighth
-- `480t` = 480 ticks
-
-**Time:**
-- `1:1` = bar 1, beat 1
-- `2:3` = bar 2, beat 3
-- `1:1:240` = bar 1, beat 1, tick 240
-
-**Drum Names:** `kick`, `snare`, `hhc`, `hho`, `tom1`, `crash`, `ride`
-
-### Control Structures
-
-```mfs
-// Procedures
-proc myPattern() {
-  note(C4, 4n);
+**Web Documentation**: https://takomusic.pages.dev (includes Playground)
+
+Local documentation:
+- Language spec: `docs/LANGUAGE.md`
+- Core DSL & built-ins: `docs/BUILTINS.md`
+- Standard library: `docs/STDLIB.md`
+- Rendering and plugins: `docs/RENDERING.md`
+- Schemas: `docs/SCHEMAS.md`
+
+## Example (.mf)
+
+```tako
+import { concat, repeat } from "std:core";
+import { kick, snare, hhc } from "std:drums";
+import { majorTriad, minorTriad } from "std:theory";
+
+fn drumPart() -> Clip {
+  return clip {
+    hit(kick, q, vel: 0.9);
+    hit(hhc, e, vel: 0.5);
+    hit(hhc, e, vel: 0.5);
+    hit(snare, q, vel: 0.85);
+    hit(hhc, q, vel: 0.5);
+  };
 }
 
-// Loops
-for (i in 1..=4) {
-  myPattern();
+fn chords() -> Clip {
+  return clip {
+    chord(majorTriad(C4), w, vel: 0.6);
+    chord(minorTriad(A3), w, vel: 0.6);
+    chord(majorTriad(F3), w, vel: 0.6);
+    chord(majorTriad(G3), w, vel: 0.6);
+  };
 }
 
-// Conditionals
-if (x > 0) {
-  note(C4, 4n);
-} else {
-  rest(4n);
-}
-```
+export fn main() -> Score {
+  return score {
+    meta { title "Simple Song"; }
 
-### Modules
+    meter { 1:1 -> 4/4; }
+    tempo { 1:1 -> 120bpm; }
 
-```mfs
-// phrases/drums.mf
-export proc BEAT_8() {
-  drum(kick, 8n);
-  drum(hhc, 8n);
-}
+    sound "piano" kind instrument { range A0..C8; }
+    sound "kit" kind drumKit {
+      drumKeys { kick; snare; hhc; }
+    }
 
-// main.mf
-import { BEAT_8 } from "./phrases/drums.mf";
+    track "Piano" role Instrument sound "piano" {
+      place 1:1 repeat(chords(), 2);
+    }
 
-export proc main() {
-  track(midi, drums, { ch: 10 }) {
-    for (bar in 1..=4) {
-      BEAT_8();
+    track "Drums" role Drums sound "kit" {
+      place 1:1 repeat(drumPart(), 8);
     }
-  }
+  };
 }
 ```
 
-### Standard Library Import
+## Pipeline
 
-```mfs
-import { major, minor } from "std:theory";
-import { euclidean } from "std:patterns";
-import { crescendo } from "std:dynamics";
-```
+1. Parse `.mf` -> AST
+2. Resolve/import + typecheck (Pos/Dur separation)
+3. Evaluate `main()` -> `Score`
+4. Normalize IR (bar:beat -> absolute Pos)
+5. Emit `score.json` (IR v4)
+6. Render via profile + renderer plugin
 
-## Configuration (mfconfig.toml)
-
-```toml
-[project]
-name = "my-song"
-version = "1.0.0"
-entry = "src/main.mf"
-dist = "dist"
-out = "out"
-
-[profiles.cli]
-backend = "headless"
-musicxml_out = "dist/vocal.musicxml"
-band_mid_out = "dist/band.mid"
-render_out = "out/mix.mp3"
-vocal_cmd = ["neutrino", "{musicxml}", "{vocal_wav}"]
-midi_cmd = ["fluidsynth", "-ni", "soundfont.sf2", "{mid}", "-F", "{band_wav}"]
-mix_cmd = ["ffmpeg", "-i", "{vocal_wav}", "-i", "{band_wav}", "-y", "{mix_wav}"]
-```
-
-## External Tools
-
-### FluidSynth (Live Preview & MIDI Rendering)
+## CLI
 
 ```bash
-# Windows
-winget install FluidSynth.FluidSynth
-
-# macOS
-brew install fluid-synth
+# Check syntax and types
+mf check song.mf
 
-# Linux
-apt install fluidsynth
-```
+# Build single file (no config required)
+mf build song.mf
+mf build song.mf -o output.json
 
-### NEUTRINO (Vocal Synthesis)
+# Build project with mfconfig.toml
+mf build
+mf build -w  # Watch mode
 
-1. Download from official site
-2. Set `NEUTRINO_DIR` environment variable
-3. Configure `vocal_cmd` in mfconfig.toml
+# Render to output format
+mf render score.json -p profile.json
+```
 
-### FFmpeg (Audio Mixing)
+Renderer plugins are external executables; use `--plugin` to override the resolver if needed.
 
-```bash
-# Windows
-winget install FFmpeg
+## Standard Library
 
-# macOS
-brew install ffmpeg
+| Module | Description |
+|--------|-------------|
+| `std:core` | `concat`, `repeat`, `overlay`, `padTo`, `slice`, `shift` |
+| `std:transform` | `transpose`, `stretch`, `quantize`, `swing`, `humanize` |
+| `std:theory` | Chords, scales, intervals, progressions |
+| `std:curves` | `linear`, `easeInOut`, `piecewise` |
+| `std:drums` | Drum keys and patterns |
+| `std:vocal` | `text`, `align`, `vibrato`, `autoBreath` |
 
-# Linux
-apt install ffmpeg
-```
+## Versioning
 
-## Error Codes
-
-| Code | Description |
-|------|-------------|
-| E050 | Global function called after track started |
-| E110 | Pitch out of range (0-127) |
-| E200 | Vocal note overlap |
-| E210 | Invalid/empty lyric in vocal track |
-| E220 | drum() used in vocal track |
-| E221 | chord() used in vocal track |
-| E300 | Top-level execution in imported module |
-| E310 | Recursion detected |
-| E400 | Import not found / undefined symbol / no main() |
-| E401 | For range bounds must be compile-time constants |
+- Language: v4
+- IR schema: `tako.irVersion = 4`
+- Profile schema: `tako.profileVersion = 1`
+- Plugin protocol: `tako.pluginProtocolVersion = 1`
 
 ## License
 

package/dist/__tests__/evaluator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=evaluator.test.d.ts.map

package/dist/__tests__/evaluator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/evaluator.test.ts"],"names":[],"mappings":""}