musical-core

Cross-project shared audio + MIDI + PWA core. Forked from BeatForge at commit 86c1b88c92fdd86ac40ee1e1ee88fa3f08765ca2 as the canonical home for the framework-free "control plane" plus master-bus FX modules and PWA glue used across BeatForge and (forthcoming) makam_studio.

Status

• Experimental. No published versions, no semver guarantee, no GitHub remote yet. Local-only by design — see ~/lab/CLAUDE.md and CONTRIBUTING.md for the rationale.
• Vendored, not linked. Consuming projects copy modules from this repo into their own src/ tree (or pull via path/fileference if a package manager is added later). No npm publish, no workspace.
• MIT licensed. See LICENSE.

What's in here

Subtree	Purpose
src/audio/events/	Typed pub/sub bus (makeEventBus, TriggerEvent/ParamEvent/...). Synchronous, framework-free.
src/audio/router/	Address-keyed dispatch. UI knobs, MIDI CCs, automation lanes all funnel through here.
src/audio/audio-graph/	AudioModule + ControllableModule contracts + composition helpers (chain/tap/parallel).
src/audio/machines/shared/	Tiny Web Audio helpers — createOsc, ampEnvelope, dcBlocker, createNoise.
src/audio/effects/	Master/insert FX as ControllableModules — reverb, delay, filter, overdrive, bitcrush.
src/audio/scheduler-worker.ts	Dedicated Web Worker the engine ticks against.
src/midi/	Web MIDI bridge (input mapping, output sink, clock I/O). Plus use-midi-bridge.ts (React lifecycle owner) and midi-panel.tsx (reference panel UI to fork).
src/lib/	db, storage, urlState, log, errors, pwa — vendor-copy targets, all parameterized away from BeatForge specifics.
templates/	vite.config.ts.template, manifest.webmanifest.template — copy + edit, do not import.
docs/REFERENCES.md	Pointers back to BeatForge's reference docs.

What's NOT here

• BeatForge's drum-voice machines (kick.ts, snare.ts, etc.).
• BeatForge's pattern schema, sequencer, world-rhythm map, kit registry, step grid components, world map.
• BeatForge brand assets (icons, colors, manifest names) and cultural-positioning manifestos.
• Any react-router, Tailwind, sample-asset bundling.
• Tests (yet) — the originals live in BeatForge; ports follow when this repo grows beyond "vendor copy".

Consuming this repo

Until a package-manager workflow is decided, the workflow is:

# In a consuming project (e.g. makam_studio):
rsync -av --delete ~/lab/musical-core/src/audio/events/ \
  ./src/modules/events/
# ... and so on per module.

See PORT_LOG.md for the per-file source/destination mapping when this repo was first populated, and CONTRIBUTING.md for the sync discipline ("backport, don't drift").

Why this exists

BeatForge and makam_studio share a "control plane" abstraction (events

• router + audio-graph), MIDI bridge, PWA scaffold, and IndexedDB plumbing. Re-deriving any of those for makam_studio would burn weeks; vendoring directly from BeatForge tangles two unrelated products in one repo. This is the third path: a brand-neutral canonical home both can pull from, with attribution headers in every file pointing back to the BeatForge commit that originated it.

The full rationale is in ~/lab/makam_studio/research/beatforge-reusable-research-mining.md and ~/lab/makam_studio/MANIFESTO.md.