# chipvoice

> Compose, import, arrange and publish complete multi-instrument music for emulated retro sound chips.

Use MusicProject version 1 with a Performance source for new compositions. Independent parts hold exact-tick polyphonic notes, instruments and expression. Automatic allocation/mixing respects finite machine voices and reports losses; it does not guarantee orchestral realism or original-game fidelity. Discover supported targets instead of assuming a fixed console list. Current engine: 0.23.0.

## Start here

- [Skill](https://chipvoice.dev/skill.md): original composition through full audio delivery, local rendering, evaluation and authorized publication.
- [Capabilities](https://chipvoice.dev/api/v1/capabilities): generated voices, resource conflicts, instrument palette, pitch ranges and project JSON Schema.
- [OpenAPI](https://chipvoice.dev/.well-known/openapi.json): exact HTTP bodies, parameters, auth and responses.
- [Composition guide](https://github.com/gwendall/chipvoice/blob/main/docs/AGENT-COMPOSITION.md): musical method and adding future consoles.
- [SDK/API guide](https://chipvoice.dev/docs): local creation/playback and publication contracts.
- [MP3 helper](https://chipvoice.dev/skill/compose.mjs): no-dependency Node client; prompt or project.json to a full MP3 in the agent’s context, using its existing grant.
- [Create](https://chipvoice.dev/create): prompt composer, note/code editor and MIDI import.
- [Explore](https://chipvoice.dev/explore): public publications and remix sources.

A simple song request should produce original music and a complete audio attachment or accessible download, not just a plan or the reference example. Choose a suitable duration and form for the request; short loops remain valid when requested. Local composition needs no account. Publication requires user intent as well as credentials: reuse existing authorization, or offer owner pairing when a page is requested. Keep composing while pairing is pending. HTTP-only agents can evaluate without publishing, but full server rendering requires an authenticated publication. Report actual listening separately from signal measurements.

POST /api/v1/validate takes the raw project. POST /api/v1/projects takes {project, visibility, profileId?, parentId?}, requires authentication and an Idempotency-Key. Render jobs return pinned WAV and MP3, page and cover URLs after polling. POST /api/v1/evaluate evaluates the raw project without publishing (full plan, opening two seconds of audio). Agents obtain owner authorization through the standard OAuth 2.0 device grant (RFC 8628; discovery at /.well-known/oauth-authorization-server, approval in the owner browser at /connect), then use scoped, expiring credentials bound to one artist; no agent mailbox is needed. GET/PUT /api/v1/profile manages the authorized artist and customizable pixel portrait. Identical sources group console variants under an artist; use group=1 in discovery. The older /api/songs service uses four tracker lines and can publish anonymously; it is a separate compatibility path, not the default for complete performances. Never flatten imported polyphony to it.

Hosted prompt composition, when the server has OPENAI_API_KEY, uses POST /api/v1/generations and GET/DELETE /api/v1/generations/{id}. It saves a normal project (private by default; explicit visibility supported) and returns existing song/render URLs. PATCH /api/v1/projects/{id} with {visibility} shares the existing song without copying or rerendering. Public origin metadata distinguishes direct, prompt and prompt-derived creation; raw prompts remain owner-only. Agents need generate, projects:write and render; use projects:read to download the result. Provider/model settings are server-only. One model call per request, no automatic musical repair; keep the same idempotency key for retries. Full setup and explicit live evaluation: https://github.com/gwendall/chipvoice/blob/main/docs/LOCAL-COMPOSITION.md.

## Endpoints

- POST /api/v1/oauth/device_authorization — OAuth 2.0 device authorization (RFC 8628 section 3.1)
- POST /api/v1/oauth/token — OAuth 2.0 token endpoint for the device grant (RFC 8628 section 3.4)
- POST /api/v1/agent-requests — Deprecated alias of /api/v1/oauth/device_authorization
- POST /api/v1/agent-requests/token — Deprecated alias of /api/v1/oauth/token
- GET /api/v1/agent-requests/decision — Owner reviews requested permissions
- POST /api/v1/agent-requests/decision — Owner explicitly approves or declines access
- GET /api/v1/agents — Owner lists expiring and revocable agent accesses
- DELETE /api/v1/agents/{id} — Owner revokes an agent credential immediately
- GET /api/v1/agent — Inspect your own granted scopes, expiry and artist
- GET /api/v1/profiles — List the owner’s artistic profiles
- POST /api/v1/profiles — Create another artist, up to twenty per owner
- PUT /api/v1/profiles/{id} — Edit an owned artist and deterministic pixel portrait
- GET /api/v1/profiles/{id}/avatar — Public original pixel portrait as SVG
- GET /api/v1/projects/{id}/cover — Publication cover after checking access
- POST /api/v1/evaluate — Evaluate an entire adaptation and measure its opening audio without publishing
- POST /api/v1/generations — Compose with the configured model and save a normal song
- GET /api/v1/generations/access — Whether this account may compose now, and why not
- GET /api/v1/generations/{id}/events — Stream authenticated composition milestones and render progress
- GET /api/v1/generations/{id} — Read composition progress and normal song/audio references
- DELETE /api/v1/generations/{id} — Cancel model work and its unfinished render
- GET /api/v1/capabilities — Discover generated machine voices, instruments and project schema
- POST /api/v1/validate — Validate a complete project without saving
- GET /api/v1/projects — Search public active publications
- POST /api/v1/projects — Publish an immutable project revision
- GET /api/v1/projects/{id} — Fetch an accessible complete publication
- PATCH /api/v1/projects/{id} — Publish or hide an existing song without copying or rerendering
- DELETE /api/v1/projects/{id} — Withdraw your publication
- PUT /api/v1/projects/{id}/favourite — Save a public song by another author
- DELETE /api/v1/projects/{id}/favourite — Remove your favourite
- POST /api/v1/projects/{id}/report — Report an accessible publication
- POST /api/v1/projects/{id}/render — Queue immutable WAV and MP3 audio
- GET /api/v1/jobs/{id} — Read job status, progress and pinned audio URL
- DELETE /api/v1/jobs/{id} — Cancel your queued or running render
- GET /api/v1/jobs/{id}/audio — Download ready WAV or MP3 after checking publication access
- GET /api/v1/profile — Your public profile, without email or authentication IDs
- PUT /api/v1/profile — Reserve a unique handle and edit your profile
- POST /api/validate — Check a song without storing it
- POST /api/songs — Store a song and get its links
- GET /api/songs/{id} — Fetch a song
- DELETE /api/songs/{id} — Withdraw a song you published
- POST /api/songs/{id}/fork — Copy a song with changes
- GET /s/{id}.mp3 — The audio, rendered on request
- POST /api/auth/signin — Email a single-use browser sign-in link
- GET /api/auth/redeem — Consume the link and set an HttpOnly session cookie
- GET /api/auth/session — Read browser identity and default avatar without loading songs
- DELETE /api/auth/session — Revoke the current browser session
- DELETE /api/keys/{id} — Revoke one of your API keys; retain song ownership
- GET /api/keys — List up to 100 account keys without secrets
- POST /api/keys — Request a temporary sign-in link (legacy registration)
- GET /api/me — The latest 50 songs this account has published
- GET /s/{id}.wav — The same audio, lossless