TakoMusic (v7)

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.

Highlights

• 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 audio preview and WAV/MIDI export

Quick Start

# Install
npm install -g takomusic

# Build a single file (no config needed)
mf build song.mf

# Or initialize a project
mf init
mf build
mf render

Quickstart Example

Try examples/quickstart.mf for a minimal, complete song example.

# Build and render the example
mf build examples/quickstart.mf
mf render examples/quickstart.mf.score.json -p profiles/midi.mf.profile.json

Documentation

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)

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);
  };
}

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);
  };
}

export fn main() -> Score {
  return score {
    meta { title "Simple Song"; }

    meter { 1:1 -> 4/4; }
    tempo { 1:1 -> 120bpm; }

    sound "piano" kind instrument { range A0..C8; }
    sound "kit" kind drumKit {
      drumKeys { kick; snare; hhc; }
    }

    track "Piano" role Instrument sound "piano" {
      place 1:1 repeat(chords(), 2);
    }

    track "Drums" role Drums sound "kit" {
      place 1:1 repeat(drumPart(), 8);
    }
  };
}

Pipeline

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 (Score IR)
6. Render via profile + renderer plugin

CLI

# Check syntax and types
mf check song.mf

# Build single file (no config required)
mf build song.mf
mf build song.mf -o output.json

# Build project with mfconfig.toml
mf build
mf build -w  # Watch mode

# Render to output format
mf render score.json -p profile.json

Renderer plugins are external executables; use --plugin to override the resolver if needed.

Standard Library

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

Versioning

TakoMusic uses multiple versioning schemes for different components:

• Language Version: v7.0 - The TakoMusic language syntax and compiler version (this package version)
• IR Schema: v4 (tako.irVersion = 4) - Score IR JSON schema version (backward compatible)
• Profile Schema: v1 (tako.profileVersion = 1) - Render profile JSON schema version
• Plugin Protocol: v1 (tako.pluginProtocolVersion = 1) - Renderer plugin communication protocol

Important: The language version and IR version are independent. IR v4 is compatible with language v4, v5, v6, v7, and future versions. The IR schema only changes when breaking changes to the Score JSON format are needed, while the language can evolve with new syntax and features that compile to the same IR.

License

AGPL-3.0