Skip to content

SEQUENCER_PRD.md

Latest commit

 

History

History
244 lines (171 loc) · 4.53 KB

SEQUENCER_PRD.md

File metadata and controls

244 lines (171 loc) · 4.53 KB

Yes — ToneForge Sequencer absolutely belongs in the family, and it fills a very specific gap between Stack, Runtime, and Intelligence.

What you’ve built so far handles sound events brilliantly.
The Sequencer is about sound behavior over time.

Below is a clear, non‑overlapping definition of what ToneForge Sequencer is, why it exists, and how it fits without bloating the system.

⏱️ ToneForge Sequencer (Concept & PRD‑Level Definition)

1. What ToneForge Sequencer Is

ToneForge Sequencer is a deterministic, event‑driven scheduling engine for procedural audio behaviors.

It sequences when sound events occur, not how they sound.

Think:

  • footsteps over time
  • weapon fire patterns
  • ambient loops with variation
  • UI interaction rhythms
  • creature behavior cycles

It is not a DAW timeline and not a music sequencer.

2. Why Stack Is Not Enough

Module Responsibility
Stack How multiple sounds combine into one event
Sequencer How events repeat, vary, and evolve over time

Example:

  • Stack: one footstep
  • Sequencer: walking, running, stopping, turning

Stack is vertical (layers).
Sequencer is horizontal (time).

3. Core Responsibilities

ToneForge Sequencer handles:

  • Event scheduling
  • Temporal patterns
  • State‑driven variation
  • Deterministic randomness
  • Runtime‑safe execution

It does not:

  • generate sound
  • analyze audio
  • classify assets
  • store libraries

4. Core Concepts

4.1 Sequence

A sequence is a timeline of event triggers, not audio clips.

{
  "name": "footstep_walk",
  "tempo": 110,
  "events": [
    { "time": 0.0, "event": "footstep", "seedOffset": 0 },
    { "time": 0.5, "event": "footstep", "seedOffset": 1 }
  ]
}

4.2 Event Reference

Events reference:

  • a Stack
  • a Recipe
  • or a Library entry
{
  "event": "footstep_gravel",
  "variant": "soft",
  "seedOffset": 12
}

4.3 Deterministic Timing

Sequencer timing is:

  • absolute or relative
  • tempo‑aware
  • sample‑accurate
  • reproducible

Uses Tone.js Clock / Transport concepts internally.

5. Sequencing Modes

5.1 Fixed Pattern

  • UI clicks
  • weapon fire
  • machinery loops

5.2 Probabilistic Pattern

  • footsteps
  • ambient sounds
  • creature behaviors
{
  "event": "footstep",
  "probability": 0.85
}

5.3 State‑Driven Pattern

  • walk → run → sprint
  • idle → alert → attack

Sequencer responds to external state changes.

6. Runtime Integration

ToneForge Sequencer is runtime‑first.

sequencer.start("footstep_walk", {
  surface: "gravel",
  speed: "walk"
});
  • Uses ToneForge Runtime for playback
  • Uses Stack for event composition
  • Uses seeds for variation
  • Can fall back to baked assets

7. Intelligence Integration

ToneForge Intelligence can:

  • suggest better patterns
  • detect repetition fatigue
  • rebalance timing
  • adapt sequences to context

Example:

“This footstep sequence repeats too predictably — introduce ±8% timing jitter.”

8. CLI & Automation

toneforge sequence generate footsteps_walk.json
toneforge sequence simulate footsteps_walk.json

Used for:

  • testing
  • validation
  • offline preview
  • batch generation

9. What Sequencer Is NOT

Not This Why
DAW timeline Too heavy, wrong abstraction
Music sequencer Focused on SFX behavior
AI composer Intelligence assists, doesn’t replace
Animation system Audio‑only responsibility

10. Where It Fits in the System

Stack → Sequencer → Runtime
        ↑
   Intelligence
  • Stack defines what
  • Sequencer defines when
  • Runtime defines how it plays
  • Intelligence defines why it changes

11. Why This Module Matters

Without Sequencer:

  • footsteps feel robotic
  • ambient soundscapes feel static
  • procedural audio lacks behavior

With Sequencer:

  • sound reacts to time
  • variation feels intentional
  • procedural systems feel alive

12. Summary

ToneForge Sequencer is the missing behavioral layer.

It turns:

  • sound events into sound systems
  • variation into rhythm
  • procedural audio into lived experience

It completes ToneForge’s evolution from:

sound generator → sound‑event compiler → sound behavior engine

If you want next, the obvious follow‑ups are:

  • a full PRD for ToneForge Sequencer
  • a state‑machine integration spec
  • or a comparison against Wwise/FMOD event systems