---
title: "Read adaptive soundtrack status for a table read artifact."
method: GET
path: "/artifacts/{artifactId}/music"
tags: ["Artifacts"]
---

# Read adaptive soundtrack status for a table read artifact.

`GET /artifacts/{artifactId}/music`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/artifacts/{artifactId}/music`
- Auth: HTTP bearer

Returns adaptive soundtrack readiness for the read backing this artifact. `music.status` is `none` (no active soundtrack, including intentional 0% coverage), `generating` (scoring is still in progress), or `ready` (at least one scene carries soundtrack).  Scope: `artifact:read`.

## Response `200`

Adaptive soundtrack status envelope.

- MusicStatusEnvelope: Adaptive soundtrack status envelope for a table read artifact.
  - `music` object, required
    - `artifactId` string, required
    - `musicMode` 'defined_clips', required: Script-level music mode. defined_clips = durable per-scene music beds (the only mode).
    - `status` 'none' | 'generating' | 'ready', required: Adaptive soundtrack readiness for a table read. `none` — no active soundtrack is present (including intentional 0% coverage); `generating` — scoring is still in progress; `ready` — at least one scene carries soundtrack.
    - `soundtrackEnabled` boolean, required: The read's "Scene Soundtrack Active" master switch. false: no scene plays music, `scenesWithMusic` is 0 and `status` is `none`.
    - `scenesWithMusic` integer, required: Scenes whose music the read plays. Defined clips: the soundtrack is on, the scene is on (not silenced by soundscape coverage), its clip is ready, and the clip is not muted.
    - `totalScenes` integer, required
    - `coveragePercent` number, nullable, required: The soundscape coverage applied to the read (0..1); null when none was applied.
    - `missingClipSceneIndexes` integer[], required: Scenes coverage keeps on that have no clip to play and none being made (never generated, or failed). Re-render them with `regenerateScenes`.
    - `definedClips` object[], required: Per-scene durable clips (empty for realtime scripts with no clips). Vocals are an explicit per-scene opt-in; clips render instrumental otherwise.
      - `sceneIndex` integer, required
      - `heading` string, required
      - `prompt` string, required
      - `vocals` boolean, required
      - `status` 'pending' | 'rendering' | 'ready' | 'failed', required
      - `soundUrl` string, nullable, required
      - `error` string, nullable, required
      - `disabled` boolean, required
      - `fadeInMs` integer, nullable, required: Clip fade-in, ms (null → default fade applies).
      - `fadeOutMs` integer, nullable, required: Clip fade-out, ms (null → default fade applies).
      - `playMode` 'once' | 'loop', required: Playback mode: `once` (default) plays the bed a single time; `loop` repeats it to fill the scene.
      - `durationMs` integer, nullable, required: Measured natural duration of the clip, in milliseconds, when known.
      - `anchor` 'start' | 'end', nullable, required: Play-once placement inside a longer scene. `end` makes an outro finish at the scene boundary; null defaults to start.
      - `postRollMs` integer, nullable, required: Music-only tail after the final spoken line, in milliseconds.
      - `volume` number, required: The authored level, 0..1 (the default 0.25 when none was set): a place in the mix, played after the bed is levelled by `levelGainDb`.
      - `levelGainDb` number, nullable, required: The gain the read applies to this bed's file before its level, dB, to a tenth; null when the bed has no current loudness reading (it then plays at unity).
      - `loudnessFlag` 'unmeasured', nullable, required: unmeasured: a ready bed nobody has levelled yet — it plays at its file's own loudness until it is measured.
      - `sceneEnabled` boolean, required: The scene's music switch. false when soundscape coverage, or a per-scene mute, silences the scene.
      - `playing` boolean, required: The read plays this clip: the soundtrack and the scene are on, the clip is ready, and the clip is not muted.
    - `sceneDirections` SceneMusicDirection[], required: Each scene's music direction (only scenes that have one), as the Table Read page's scene console sets it. Change one with `sceneIndex` + `direction` on POST.
      - `sceneIndex` integer, required
      - `heading` string, required
      - `enabled` boolean, required: The scene's music is on.
      - `endTransition` 'fadeOut' | 'cut', required: How the music ends at the scene's boundary: `fadeOut` eases it out, `cut` stops it hard.
      - `summary` string, nullable, required: One line on the music's mood.
      - `instruments` object[], required
        - `text` string, required
        - `weight` number, required
      - `mix` number, nullable, required: Music level.
      - `ducking` number, nullable, required: How much of its level the music keeps under dialogue: 1 = no dip, lower dips deeper (say it in percent and dB, e.g. 48% of its level = -6 dB).
      - `bpm` number, nullable, required
      - `density` number, nullable, required
      - `brightness` number, nullable, required
      - `guidance` number, nullable, required
      - `temperature` number, nullable, required
      - `topK` number, nullable, required
      - `scale` string, nullable, required
      - `seed` number, nullable, required

## Other responses

- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `404`: The story artifact does not exist or is owned by another account.
- `409`: The artifact is not in a state where this operation is valid yet (e.g. requesting an MP4 render before the share link exists).
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/4534f5d25540?raw)