Developer platform · 0.2 alpha

Casset Apps

Casset Apps are interactive experiences that live inside an artist profile.

Build a profile room, interactive discography, visualizer, game, or collector experience. Start locally with a downloadable project and sample Casset data—no credentials required.

Build your first app Download React starter

The local SDK and starters work today. Production Casset Apps are reviewed and code-owned by Casset; third-party submission is not open.

curl -LO https://casset.fm/downloads/casset-apps/casset-minimal-profile-app-v0.2.0-alpha.0.zip
unzip casset-minimal-profile-app-v0.2.0-alpha.0.zip
cd casset-minimal-profile-app
pnpm install
pnpm test
pnpm dev

Choose your path

Start with the thing you want to build.

Use Headless when you own the website and need public artist data. Use Casset Apps when the experience should live inside Casset. Skip to the reference when you already know the model.

I want public artist dataBuild a website, catalog browser, or public-data tool with the separate Headless API.Headless API · build beyond Casset I want to build inside CassetDownload a native starter and build an interactive experience for an artist profile.Casset Apps · local alpha I need the full technical referenceLook up manifest fields, permissions, host commands, data states, and troubleshooting.Reference · exact contracts

Five-minute start

Build your first app.

Download the smallest starter, install it, and run it against sample Casset data. Every ZIP includes the local SDK, tests, and build instructions. No Casset credential is required.

Unpack

Choose a Profile or Track starter and enter its root folder.

Run it

Install dependencies, start the local app, and explore its sample states.

Make it yours

Change the manifest and interface, then run the included tests and build.

Open the full quickstart Compare all starters Open the agent brief Inspect download checksums

What you can build

Choose where your experience runs.

Profile Apps can use artist identity, approved catalog and release data, and narrow playback requests. Track experiences can follow playback time supplied by Casset, but cannot control the player.

Profile experiencesCreate an interactive profile room, release home, discography, game, or collector experience around an existing Casset purchase.Profile Surface · local alpha Track experiencesBuild a visualizer or release ritual that follows playback time supplied by Casset without owning audio or creating another clock.Track Runtime · read only Catalog experiencesUse the artist and approved Catalog supplied by Casset to build a listening index or release artifact. Lyrics are not part of this alpha contract.Profile data · permission checked Campaign and audience dataThese permission names exist, but the data adapters do not. Moments, Campaigns, and Audience data remain unavailable.Unavailable

How it works

Use the local SDK included with every starter.

The @casset/apps alpha validates your manifest, supplies typed artist context, and lets the App make a small set of requests to Casset. It is included in every ZIP as a local dependency, not published to npm.

@casset/appsvendored host contract

typescriptcontract checking

vitelocal build

vitestfixture and state tests

reactReact starter only

Manifest

Identity and version
Profile or Track context
Placements and permissions
Track kinds when applicable

Context

Short-lived launch lifecycle
Minimized public data
Explicit Profile data states
URL-free Track resource references

Host

Capability detection
Profile-only PLAY_TRACK request
Lifecycle subscriptions
Fail-closed close and invalid requests

import {
  hasCassetPermission,
  hostSupports,
  isCassetDataReady,
  type CassetAppHost,
} from "@casset/apps"

export async function playFirstTrack(host: CassetAppHost) {
  const { context } = host.getSnapshot()
  if (context.kind !== "PROFILE_SURFACE") return
  if (!isCassetDataReady(context.catalog)) return
  if (!hasCassetPermission(context, "playback.control")) return
  if (!hostSupports(host, "PROFILE_PLAY_TRACK")) return

  const track = context.catalog.data.tracks[0]
  if (track) await host.request({ type: "PLAY_TRACK", trackId: track.id })
}

{
  "schema": "casset.app-manifest.v1",
  "id": "studio.afterglow-room",
  "slug": "afterglow-room",
  "name": "Afterglow Room",
  "shortDescription": "A quiet release room inside the Profile World.",
  "description": "Stages an approved release and requests playback through Casset.",
  "developer": { "name": "Your studio" },
  "version": "0.1.0",
  "icon": "/icon.svg",
  "screenshots": [],
  "category": "IDENTITY",
  "context": "PROFILE_SURFACE",
  "placements": ["ARTIST_APP_ROUTE"],
  "permissions": [
    "artist.profile.read",
    "artist.theme.read",
    "catalog.tracks.read",
    "playback.read",
    "playback.control"
  ],
  "supportedFanAccess": ["FREE"],
  "compatibility": { "mobile": true, "desktop": true, "pwa": true },
  "trackApplicability": null
}

@casset/apps is not published to npm. The starter ZIPs include the exact pre-release source and install it through a local file: dependency, so the imports above are real without implying an open package or marketplace.

One playback authorityYour App asks. Casset remains in control.repository local

Apps receive

Approved artist, theme, Catalog, and release data
Explicit loading, empty, denied, and unavailable states
Track time and lifecycle updates supplied by Casset
Checks for the requests the current host supports

Casset retains

Installation, entitlement, and launch authority
The global player and canonical audio clock
Routes, runtime dispatch, and raw media delivery
Disablement, exit, and production integration

manifestCasset contextyour interface

Agent-ready Markdown

Give Codex or Claude a focused build brief.

Every starter includes AGENTS.md, CLAUDE.md, PROMPT.md, and a README. The included instructions preserve Casset's playback and permission rules; the prompt is where you describe what you want to make.

AGENTS.md

Canonical Casset doctrine
Files the agent may change
Runtime authority rules
Required validation commands

CLAUDE.md

The same host boundary
Sparse-state expectations
Mobile and reduced-motion rules
No second player or private data

PROMPT.md

A reusable task brief
Creative intent and interaction
Acceptance criteria
Test and build handoff

# Build brief for Codex or Claude Code

## Objective
Turn the artist's active release into a quiet afterglow room inside
the existing Profile World.

## Use
- The vendored `@casset/apps` package
- The provided fixture and host lifecycle
- The starter's existing test and build commands

## Preserve
- Casset owns artist identity, authorization, playback, and exit
- Request playback through the host; never mount an `<audio>` element
- Handle loading, empty, unavailable, and permission-denied states
- Keep the interface calm, mobile-first, and artist-specific

## Verify
- `pnpm test`
- `pnpm build`

Runnable projects

Choose the smallest starter that fits.

All three starters use the same local SDK. Pick plain TypeScript, React, or a read-only Track experience; each includes prompts for creating an original App instead of cloning the sample.

Minimal Profile AppDependency-light TypeScript and DOM. Exercises ready, loading, empty, unavailable, and permission-denied catalog states.ZIP · minimal React Profile AppTyped React surface with lifecycle updates, release data, responsive composition, and host-approved Track requests.ZIP · intermediate Track ExperienceRead-only playback time supplied by Casset, visual state changes, lifecycle cleanup, and one local interaction.ZIP · advanced Starter guideChoose a kit, copy an agent prompt, inspect every included file, and follow the supported local workflow.Docs · agent ready

Availability

What works today—and what does not.

The local SDK and downloadable projects are usable. Public submission, third-party production installation, npm publication, credentials, and arbitrary App execution are unavailable.

Use now

Repository-local @casset/apps
Three standalone starter ZIPs
Strict parsers and fixtures
Trusted production Track contract

Casset only

Registry and runtime keys
Installation and entitlement truth
Playback stores and MediaFooter
Raw media and server authorization

Not shipped

npm publication
Public submit or review API
Arbitrary bundle isolation
Live revocation and resource delivery

Current distributionBuild against the truth that exists today.Read distribution status

Casset Apps are interactive experiences that live inside an artist profile.

Build a profile room, interactive discography, visualizer, game, or collector experience. Start locally with a downloadable project and sample Casset data—no credentials required.

The local SDK and starters work today. Production Casset Apps are reviewed and code-owned by Casset; third-party submission is not open.

curl -LO https://casset.fm/downloads/casset-apps/casset-minimal-profile-app-v0.2.0-alpha.0.zip unzip casset-minimal-profile-app-v0.2.0-alpha.0.zip cd casset-minimal-profile-app pnpm install pnpm test pnpm dev

import { hasCassetPermission, hostSupports, isCassetDataReady, type CassetAppHost, } from "@casset/apps" export async function playFirstTrack(host: CassetAppHost) { const { context } = host.getSnapshot() if (context.kind !== "PROFILE_SURFACE") return if (!isCassetDataReady(context.catalog)) return if (!hasCassetPermission(context, "playback.control")) return if (!hostSupports(host, "PROFILE_PLAY_TRACK")) return const track = context.catalog.data.tracks[0] if (track) await host.request({ type: "PLAY_TRACK", trackId: track.id }) }

{ "schema": "casset.app-manifest.v1", "id": "studio.afterglow-room", "slug": "afterglow-room", "name": "Afterglow Room", "shortDescription": "A quiet release room inside the Profile World.", "description": "Stages an approved release and requests playback through Casset.", "developer": { "name": "Your studio" }, "version": "0.1.0", "icon": "/icon.svg", "screenshots": [], "category": "IDENTITY", "context": "PROFILE_SURFACE", "placements": ["ARTIST_APP_ROUTE"], "permissions": [ "artist.profile.read", "artist.theme.read", "catalog.tracks.read", "playback.read", "playback.control" ], "supportedFanAccess": ["FREE"], "compatibility": { "mobile": true, "desktop": true, "pwa": true }, "trackApplicability": null }

# Build brief for Codex or Claude Code ## Objective Turn the artist's active release into a quiet afterglow room inside the existing Profile World. ## Use - The vendored `@casset/apps` package - The provided fixture and host lifecycle - The starter's existing test and build commands ## Preserve - Casset owns artist identity, authorization, playback, and exit - Request playback through the host; never mount an `<audio>` element - Handle loading, empty, unavailable, and permission-denied states - Keep the interface calm, mobile-first, and artist-specific ## Verify - `pnpm test` - `pnpm build`