Casperaki

Casperaki is being rebuilt as a modern pnpm/TypeScript monorepo for deterministic song generation, real audio rendering, and AI-assisted music production.

The current working app is the models layer: a local React + Express + Python server for downloading and running audio models such as ACE-Step, SAM-Audio, SoulX-Singer, and Matchering. It now lives at apps/models.

Workspace

apps/
  models/          # current AI model serving app
packages/
  song-schema/     # Phase 1 shell: canonical song contract
  music-theory/    # Phase 3 shell: chord/note/time primitives
  arrangement/     # Phase 3 shell: deterministic generators
docs/              # rebuild architecture and phase plans

Start with docs/README.md for the rebuild map.

Prerequisite: shared UI

@teamsuzie/ui lives in the sibling ../open_teamsuzie monorepo and is consumed through a local link: dependency. Build it once before running Casperaki:

cd ../open_teamsuzie
pnpm install --filter "@teamsuzie/ui..."
pnpm --filter "@teamsuzie/ui..." build

Re-run the build after pulling UI changes.

Setup

From this repo root:

pnpm install

Run the models app

pnpm dev:models

The API listens on http://localhost:16400 and the web UI on http://localhost:16401.

Useful commands:

pnpm typecheck
pnpm build
pnpm --filter @casperaki/models dev:server
pnpm --filter @casperaki/models dev:web

Configuration

The models app reads apps/models/.env (see apps/models/.env.example).

Docs

• docs/50-engineering-plan.md - master rebuild plan
• docs/51-phase1-song-schema-plan.md - next implementation phase
• docs/13-models-layer.md - current models app details