# System: Score → Render Pipeline (Sprint 9)

Effective: 2026-04-14
Primary Workflow: **Compose-then-Render**
Target View: **Session View**

## Overview

The Score → Render pipeline introduces a decoupled architecture where musical composition is separated from Ableton Live execution. This allows for:
1. **Incremental Composition**: Build a song piece-by-piece in a JSON score.
2. **Offline Generation**: Use AI agents (OpenAI/Anthropic) to generate scores without needing Ableton open.
3. **Batch Rendering**: Render 50+ unique songs sequentially from JSON files.
4. **Deterministic Deployment**: Entire song structures are injected into Session View in one atomic call.

---

## Core Components

### 1. SongScore (`score_engine.py`)
A pure Python data model representing a song. No Ableton dependencies.
- **Meta**: Title, Tempo, Key, Gap Bars.
- **Structure**: Ordered list of sections (Intro, Chorus, etc.) with durations.
- **Tracks**: List of track definitions (Audio or MIDI).
- **Clips**: Clips mapped to specific sections.
- **Mixer**: Volume, Pan, EQ/Compressor presets, Return Sends.

### 2. ScoreRenderer (`score_renderer.py`)
Translates `SongScore` into TCP commands for Ableton Live.
- **Mapping**: Sections → Scenes | Tracks → Tracks | Clips → Clip Slots.
- **Sample Selection**: Resolver for `"auto"` samples based on BPM proximity.
- **MIDI Resolution**: Resolves pattern names (e.g., `dembow_standard`) into explicit MIDI notes before sending.
- **Mixer Application**: Configures devices (EQ Eight, Compressor) and sends.

### 3. AI Loop (`ai_loop.py`)
An autonomous production script compatible with Anthropic/OpenRouter/Local LLMs.
- Queries AI for valid `SongScore` JSON.
- Validates and saves to `mcp_server/scores/`.
- Optionally renders immediately to Ableton.

---

## Technical Mapping (Session View)

The system is strictly Session-View only to avoid Arrangement complexity and allow clip-based performance.

| SongScore Element | Ableton Element | Command Used |
|-------------------|-----------------|--------------|
| `SectionDef` | **Scene** | `create_scene`, `set_scene_name` |
| `TrackDef` | **Track** | `create_audio_track`, `create_midi_track` |
| `ClipDef` (Audio) | **Clip Slot** | `load_sample_to_clip` |
| `ClipDef` (MIDI) | **Clip Slot** | `create_clip`, `add_notes_to_clip` |
| `MixerDef` | **Devices** | `configure_eq`, `configure_compressor`, `set_track_send` |

---

## Available Tools (MCP)

### Composer Tools
- `new_score`: Initialize active score.
- `compose_structure`: Define sections and durations.
- `compose_audio_track`: Add audio tracks with sample references.
- `compose_midi_track`: Add MIDI tracks with instruments.
- `compose_pattern`: Apply predefined MIDI patterns (dembow, bass, etc.).
- `compose_mixer`: Set levels and FX presets.
- `compose_from_template`: Create full score from "reggaeton_basic", etc.

### Management & Rendering
- `save_score` / `load_score`: Persist JSON to `mcp_server/scores/`.
- `list_scores`: List all saved canciones.
- `render_score`: Inject active score into Ableton.
- `render_score_from_file`: Render a specific JSON file.
- `render_all_scores`: Sequentially render everything in the scores folder.

---

## MIDI Patterns Reference

The following patterns can be used in `compose_midi_track` or `compose_pattern`:

- **Drums**: `dembow_minimal`, `dembow_standard`, `dembow_double`.
- **Bass**: `bass_sub`, `bass_pluck`, `bass_octaves`, `bass_sustained`.
- **Harmony**: `chords_verse`, `chords_chorus`.
- **Melody**: `melody_simple`.

## Best Practices for AI Agents

1. **Always start with a Template**: Use `compose_from_template` first, then modify.
2. **Use "auto" samples**: Let the renderer pick the best file matching the BPM.
3. **Validate before Render**: Use `compose_validate` to catch ID mismatches.
4. **Iterate in JSON**: It's faster to tweak the JSON score via compose tools than to re-render everything.
