ScoreReel

An opinionated, music-driven particle cinematics engine.

ScoreReel turns music into authored particle worlds. It is not a generic equalizer skin, a VJ node editor, or a bag of effects. Each built-in scene is a coherent visual composition with its own spatial model, camera language, musical bindings, and deterministic choreography.

The project starts from one reference user and serves people who share the same taste: cinematic scale, restrained motion, legible musical response, deep atmosphere, and images that feel composed rather than randomly generated.

Product contract

music observations + optional reel rule + seed
                         |
                         v
              deterministic show plan
                         |
                         v
                authored scene program
                         |
                         v
                    one canvas

• AI may write a bounded rule, but ScoreReel has no AI or network dependency.
• Rules select and tune complete built-in programs; they never contain shaders, executable code, arbitrary assets, or free-form scene graphs.
• The same compatible inputs and seed reproduce the same choreography.
• With no rule, ScoreReel still selects a coherent show instead of combining random effects.
• The first reference world is cosmos/ringed-voyage.

An intended rule is deliberately small:

schema_version: 1
seed: 42
preset: cosmos/ringed-voyage
mood: vast
drive: 0.72
camera: forward-glide

Status

The first executable vertical slice is complete:

• strict YAML and object validation for ScoreReel Show Protocol v1;
• deterministic rule-free planning from a music fingerprint and bounded traits;
• a reusable WebAudio spectrum adapter for energy, bass, onset, brightness, and optional trusted host mood axes;
• bounded feature-frame projection into authored visual controls;
• the cosmos/ringed-voyage Three.js particle world;
• explicit render-at-time, resize, context-loss, and disposal lifecycle;
• a capturable reference gallery with local-audio loading and fixed browser evidence;
• a publishable ESM library with TypeScript declarations and an exported JSON schema.

Pinned ScoreBench package consumption, an externally supplied semantic mood adapter, package registry publishing, and additional authored worlds remain open.

Run the reference gallery

npm install
npm run dev

Open the displayed local URL. Click LOAD SCORE to choose a local audio file; it stays on the machine and drives the world through WebAudio. Add ?test=1 to hold the authored show at its fixed reference timestamp.

Engine surface

import {
  AnalyserFeatureSource,
  ScoreReelRuntime,
  parseReelRule,
  planShow,
} from "./src/index";

const parsed = parseReelRule(ruleSource);
if (!parsed.ok) throw new Error(JSON.stringify(parsed.errors));

const runtime = new ScoreReelRuntime({
  canvas,
  plan: planShow({ rule: parsed.value }),
});

runtime.resize(width, height, devicePixelRatio);

const analyser = audioContext.createAnalyser();
hostPlaybackNode.connect(analyser);
const features = new AnalyserFeatureSource(analyser);

function draw() {
  const frame = features.sample(hostPlaybackTime(), {
    reducedMotion: matchMedia("(prefers-reduced-motion: reduce)").matches,
  });
  runtime.renderAt(frame.time, frame);
  requestAnimationFrame(draw);
}

draw();

// When the host tears down this view:
runtime.dispose();

The analyser adapter observes mixed audio only; it does not claim melody, harmony, sections, or stems. A host with trusted semantic analysis may pass bounded mood axes to sample(). The host still owns its audio graph, clock, request-animation-frame loop, and canvas.captureStream() lifecycle. The published machine contract is ScoreReel Show Protocol v1.

Build the reusable library with npm run build:lib; npm pack --dry-run shows the exact ESM, declarations, schema, README, and license that would be published.

Reference envelope

The current cosmos/ringed-voyage program contains 87,736 deterministic procedural points plus two planet meshes. The renderer caps device pixel ratio at 2. The checked visual reference is 1440 x 900 at DPR 1 in Chrome on macOS; other GPU pixels may differ within the review tolerance recorded by the browser test.

Quality and acceptance

The project profile, iron boundaries, direction, and capability coverage matrix live in docs/roadmap.md. Every first-class capability must ship with a happy-path end-to-end proof; risk, failure, permission, and recovery coverage follow the mandatory rules recorded there.

Agent contributors must also follow AGENTS.md.

npm run test:all

License

MIT