Skip to content

Quick Start

Generate your first piece in under 2 minutes. YaO offers four paths — interactive Claude Code, natural language CLI, YAML specs, and the Agent SDK.

Install

pip install -e ".[dev]"

Optional extras: 

pip install -e ".[sdk]"        # Agent SDK (programmatic access)
pip install -e ".[neural]"     # Stable Audio bridge
pip install -e ".[live]"       # Realtime improvisation
pip install -e ".[annotate]"   # A/B audition + annotation UI

For SDK usage, set your API key: 

export ANTHROPIC_API_KEY=sk-…

Use the /sketch command in Claude Code for a guided 6-turn dialogue:

/sketch
> A melancholic piano piece with strings, about 90 seconds

The sketch dialogue asks about mood, instruments, structure, and constraints, then generates a complete YAML spec and composition.

Option B: Natural Language

yao conduct "upbeat jazz trio, 2 minutes, swinging and playful"

The Conductor translates your description to a spec, generates a composition, evaluates it, and iterates up to 3 times.

Japanese is also supported: 

yao conduct "雨の午後のような、メランコリックなピアノ曲、90秒"

Option C: From YAML Spec

# Create a project skeleton
yao new-project my-piece

# Edit the generated spec, then compose
yao compose my-piece/composition.yaml

Minimal spec structure:

title: "My First Piece"
genre: "cinematic"
key: "C minor"
tempo_bpm: 100
time_signature: "4/4"
total_bars: 32
instruments:
  - name: piano
    role: melody
  - name: cello
    role: accompaniment
sections:
  - name: intro
    bars: 8
    dynamics: mp
  - name: main
    bars: 16
    dynamics: mf
  - name: outro
    bars: 8
    dynamics: p
generation:
  strategy: stochastic
  seed: 42
  temperature: 0.7

Output Structure

After generation, your project contains:

outputs/projects/<name>/iterations/v001/
  full.mid              # Complete MIDI file
  stems/                # Per-instrument MIDI files
  analysis.json         # Structural analysis
  evaluation.json       # 6-dimension quality scores
  perceptual.json       # Audio perception report (if rendered)
  provenance.json       # Decision log (every note explained)
  critique.md           # Adversarial critique findings
  audio.wav             # Rendered audio (if --render-audio)

Generation Strategies

Strategy Character
rule_based Deterministic, predictable
stochastic Probabilistic, temperature-controlled
markov N-gram patterns, style-aware
phrase_aware 4-layer phrase-first pipeline (M1–M4)
twelve_tone Serial composition (P/I/R/RI)
process_music Phasing, additive, subtractive
constraint_satisfaction CSP backtracking
loop_evolution Loop-first, layer evolution
ai_seed Motif generation from intent

Iterate and Refine

# Regenerate just the chorus
yao regenerate-section my-piece chorus --seed 99

# Pin feedback to a specific location
yao pin "verse:bar4:piano — too busy, simplify"

# Arrange an existing piece in a new style
/arrange my-piece/full.mid --style jazz_ballad

# Preview without saving to disk
yao preview my-spec.yaml

# Watch for spec changes and auto-regenerate
yao watch my-spec.yaml

Combination Stack Features

The Combination Stack (Layer 2.5) provides 11 coupling modules for harmonic coupling, voice leading, reharmonization, and more. These are controlled via feature flags:

# Add to any spec to control combination stack features
features:
  chord_aware_melody: true          # Melody fits active chords (default ON)
  voice_leading_optimization: true  # Smooth chord transitions (default ON)
  reharmonization: false            # Opt-in chord substitutions
  genre_vector: false               # N-way genre blending
  rhythm_markov: false              # Markov-based rhythm generation
  polyrhythm: false                 # Polyrhythmic texture layers
  theme_recurrence: false           # Theme recurrence graph planning
  phrase_shape: false               # Phrase contour shaping
  modulation: false                 # Key modulation planning
  harmonic_devices: false           # Harmonic device library
  listening_agents: false           # Turn-based listening-agent dialog

New commands: 

# Reharmonize an existing piece
yao reharmonize outputs/projects/my-piece/v001/full.mid --intensity 0.4 --style jazz

# Generate with blended genres
yao conduct "bossa-flavored chords with drum and bass rhythm" \
  --blend bossa_nova:0.6,drum_n_bass:0.4

Option D: Agent SDK (Programmatic)

Drive the same orchestra from any Python program — web apps, Discord bots, CI pipelines, or Jupyter notebooks.

import asyncio
from yao.sdk import YaoAgent
from yao.sdk.events import IterationCompletedEvent, AudioReadyEvent

async def main():
    async with YaoAgent(project="my-piece") as agent:
        async for event in agent.conduct(
            "a calm piano piece in D minor for studying, 90 seconds",
            max_iterations=3,
        ):
            if isinstance(event, IterationCompletedEvent):
                print(f"iter {event.iteration} -> {event.iteration_path}")
            elif isinstance(event, AudioReadyEvent):
                print(f"audio: {event.wav_path}")

asyncio.run(main())

The SDK exposes 10 methods that mirror slash commands (sketch, compose, conduct, critique, regenerate_section, render, diff, evaluate, explain, chat) and streams 9 typed events for real-time UI updates.

For lower-level control, use Lane B — construct ClaudeAgentOptions manually via default_yao_options():

from yao.sdk import default_yao_options, create_yao_mcp_server
options = default_yao_options("my-project", extra_options={"max_tokens": 8192})

See SDK Quickstart for full details.

Next Steps