Artifacts

Generate adaptive soundtrack for a table read artifact.

(Re)generates the per-scene adaptive soundtrack for the read backing this table_read artifact, or updates soundtrack direction for the whole screenplay, one scene, or one entry/line when directive fields are provided. No new revision — the artifact id and share URLs stay stable, like a voice recast. Optionally tune how much of the read carries soundtrack via musicCoveragePercent (a fraction 0..1 or a whole percent 0..100; clamped into [0,1]). For directive edits, send { scope?, mode?, sceneIndex?, entryIndex?, prompt?, summary?, enabled?, weight? }, e.g. "make scene 2 heavier bass", "mute the cold open", or mode: "replace" to overwrite a stale palette when switching scoring styles. To change one scene's music direction field by field, send { sceneIndex, direction: { endTransition?, mix?, ducking?, bpm?, density?, brightness?, guidance?, temperature?, topK?, scale?, seed?, instruments?, summary?, enabled? } }: the same save as the Table Read page's scene console, which drops the scene's rendered bed so the next render plays the new direction. GET returns each scene's direction as music.sceneDirections. Full regeneration is async + queued: returns { status: "generating" }. Directive edits return { status: "ready" }. Poll GET /artifacts/{artifactId}/music until music.status is ready. Requires Idempotency-Key. Scope: artifact:publish.

post/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

Headers

Idempotency-Keystring required

Customer-generated stable identifier for safe retries of idempotent POST requests.

Request body

musicMode'defined_clips'

Switch the script-level music mode. defined_clips (the only mode) plays durable per-scene music clips and auto-queues a baseline coverage pass.

regenerateScenesinteger[]

Zero-based scene indexes whose defined clips should re-render with their current prompts.

soundtrackEnabledboolean

The read's "Scene Soundtrack Active" master switch. false silences every scene's music everywhere (live playback, the MP3 and the MP4); banked clips and coverage are kept. Used alone. Free — it never waits on the project gate.

musicCoveragePercentnumber

Soundscape coverage: how much of the read carries music. Accepts a fraction (0..1) or a whole percent (0..100); clamped into [0,1]. The same setting as the in-app coverage slider: it keeps the key scenes (opening, finale, the most intense) and silences the rest, saves the percent, and queues clips for kept scenes that have none. 0 silences every scene; banked clips are kept.

scope'screenplay' | 'scene' | 'entry'

Directive scope. Defaults to scene when sceneIndex is supplied, entry when entryIndex is supplied, otherwise screenplay.

mode'merge' | 'replace'

Directive mode. Defaults to merge, which appends to the existing weighted prompt palette. Use replace to overwrite the targeted palette, e.g. when switching the whole read to a new scoring style.

sceneIndexinteger

Zero-based scene index to update. Required for scope: "scene"; optional context for entry-level updates.

entryIndexinteger

Zero-based parsed script entry index for line/beat-level soundtrack steering. Required for scope: "entry".

promptstring

Optional adaptive soundtrack prompt, e.g. "a single piano tone, held, then released" or "heavier bass pulse, tense low strings".

summarystring

Optional plain-language soundtrack summary.

enabledboolean

Optional soundtrack toggle. false mutes soundtrack for this scope; true turns it back on.

weightnumber

Optional prompt weight; defaults to 1 and is clamped by the API.

Response

Adaptive soundtrack generation dispatched or scene soundtrack direction updated.

artifactIdstring required
status'generating' | 'ready' | 'ok' required
musicMode'defined_clips'

Present when the music mode was switched.

soundtrackEnabledboolean

Present when the scene soundtrack master switch was set: its value now.

sceneIndexesinteger[]

Present when specific defined clips were queued to re-render.

clipobject

Present when one scene's defined clip was edited — the updated clip record.

coveragePercentnumber nullable

The clamped coverage percent applied (null when none was supplied and none was previously set).

totalScenesinteger

Number of scenes the read was decomposed into.

scope'screenplay' | 'scene' | 'entry'

Present when a soundtrack directive update was applied.

sceneIndexinteger

Present when a scene-level or resolved entry-level soundtrack update was applied.

entryIndexinteger

Present when an entry-level soundtrack update was applied.

directiveobject

Hidden soundtrack directive that was stored for future adaptive-scene regeneration.

adaptiveSceneDirectionobject

Present when a concrete scene direction was updated. This is the live theater adaptive scene direction.

Changes

No recorded changes to this operation across all 1 revision of this API.