If you already know the track
track_id is the Soundstripe song id. Pass one straight from your own catalog. There is no
need to call /v1/match first. Matching exists for picking a track when you do not know which one
you want. If you do, go straight to loop.
(video_id, track_id) pair builds the loop profile off the request
path. It returns 202 with a job_id and a poll of /v1/loop/jobs/{job_id}, and no plan. Poll
that until status is complete. Every later call for that same pair returns 200 with the plan
immediately.
The pair is what the cache is keyed on. Looping a track you have already built over a different
video is a cold call again, at the cold rate, so budget by pairing rather than by track.
Over MCP the same two steps are loop_music then check_job(job_id, "loop").
What the response contains
POST /v1/loop returns timings, never audio.
200
track identifies the recording. The two ids are not interchangeable: soundstripe_song_id
is the work, soundstripe_audio_file_id is the specific render to fetch. Both are returned in
every delivery mode, because identity is not content. Knowing which track this is tells you
nothing you could not read off a search result, and without it the plan is numbers with no
referent.
Assembling the loop
plan.segments is the authoritative playback path. Play each range of the song back to back,
in the order given. Everything else shapes the joins.
1
Resolve the audio
Fetch the file for
track.soundstripe_audio_file_id through your own catalog access.2
Cut the segments
For each entry, take the song from
song_from to song_to. The first segment is usually
the song’s own intro, and later ones repeat the loop body.3
Place it against the video
The music starts at
plan.music_in. A segment’s start in video time is music_in plus the
total length of every segment before it. In the example above, segment 2 starts at
0.0 + 41.4 = 41.4s.4
Crossfade each splice
seam_fades[i] is the crossfade length in seconds for the join between segment i and
i+1. seam_curves[i] is the gain exponent for that same join, anywhere from 0.5
(equal power, for this song’s weakest seam) to 1.0 (linear, for its best). Values in
between are real and should be applied as given. The arrays are parallel and one shorter
than segments.5
Apply per-segment gain
gain_db, when present, is a small loudness correction for that segment. With
gain_in_db and gain_glide_seconds the segment ramps between the two instead of
stepping.seam_curves varies per splice rather than being a constant.
Where the music ends
music_out is the video’s end. music_end is where the music resolves, which can be earlier
when the plan exits the loop into a come-down outro. tail_seconds is the sub-bar residual
between them. Fade out across the tail rather than cutting at music_out.
When there is no loop
applicable: false means no loop was worth making. hint says why in plain language and
retryable says whether calling again can change it. It is true when the analysis timed out or
came back incomplete, and false when the video is simply not longer than the track.
Preview audio
No audio is attached to any response by default. Nopreview object on match results, no
audio URL on a loop plan. You get catalog identifiers and timings.
This is deliberate. The only audio Cue is able to serve is watermarked, which cannot go into a
finished video, so it is never a deliverable. The identifiers in track are how you reach the
real file, under whatever catalog access you hold.
If you are evaluating tracks and don’t yet license a catalog, ask us to enable preview on your
account. That attaches a short-lived watermarked link for judging a track before licensing it.
It changes only what audio is attached. The plans, sync points, and metering are identical.
The MCP server
loop_music returns the same plan, and its tool description carries these assembly rules so an
agent can act on the response without reading this page. One difference: over MCP the plan drops
plan.options, the full copies of every alternative loop region, and carries a summary of each in
plan.alternates instead. REST keeps options in full. See MCP tools.