Get Started
spideriq
Get Started

Docs / video/add-narration-captions-and-ducked-music

Add narration, captions and ducked music to a video

Who this is for: Anyone submitting SpiderVideo stitching jobs, through the API or through an agent, who wants a finished video instead of one that still needs an editing pass.

What this does: Lays a narration track over your stitched scenes, drops the background music while the voice speaks, and burns word-by-word captions into the picture. The three are independent, and each is optional.

Before you begin

  • A SpiderIQ client token that can submit jobs.

  • Your scenes at http(s) URLs, as for any stitching job.

  • A narration audio file at an http(s) URL. SpiderVideo plays audio you already have and does not generate speech, so record or synthesise the voice first.

  • Background music at an http(s) URL, if you want ducking.

  • Word timings, if you want captions: every word with a start and an end in milliseconds.

  • To drive this from an agent, @spideriq/mcp 1.93.0 or @spideriq/mcp-leads 1.17.0 or newer. Older installs drop these fields without telling you.

Steps

  1. Add the narration. voiceUrl takes the URL, and voiceVolume sets its level between 0 and 1 (1.0 by default).

curl -X POST "https://spideriq.ai/api/v1/jobs/spiderVideo/submit" \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "projectName": "launch-clip",
      "scenes": [
        {"videoUrl": "https://cdn.example.com/scene1.mp4", "durationInSeconds": 5},
        {"videoUrl": "https://cdn.example.com/scene2.mp4", "durationInSeconds": 3}
      ],
      "voiceUrl": "https://cdn.example.com/voiceover.mp3",
      "voiceVolume": 1.0
    }
  }'

  1. Drop the music under the voice. Set duckMusic to true. It needs both musicUrl and voiceUrl, and it stays off unless you ask for it.

  "musicUrl": "https://cdn.example.com/music.mp3",
  "voiceUrl": "https://cdn.example.com/voiceover.mp3",
  "duckMusic": true

  1. Burn in the captions. Each entry carries the word and the span it occupies, and the word is highlighted across that span.

  "captions": [
    {"text": "Welcome", "startMs": 500, "endMs": 1046},
    {"text": "to", "startMs": 1166, "endMs": 1321}
  ]

  1. Submit the job and keep the job_id it returns. From an agent, call the create_video tool with voice_url, voice_volume, duck_music and captions instead.

Verify it worked

Poll GET /api/v1/jobs/{job_id}/status until the status is completed, then play the rendered file and check all three:

  • The narration is audible over the scenes.

  • The music is quieter while the voice speaks and comes back in the pauses.

  • Each caption word highlights as it is spoken, and nothing shows in the silences.

A voice track that could not be used never reaches this point. Rather than rendering a silent video, the job fails, so a completed job means the audio was really there.

Troubleshoot

  • The job failed instead of rendering. The voice file must be reachable over http(s) and contain an audio stream. A URL that 404s, or a file with no audio in it, fails the job by design. Open the URL yourself before resubmitting.

  • 422, duckMusic requires both musicUrl and voiceUrl. Ducking needs something to duck and something to duck under. Send both URLs, or drop duckMusic.

  • 422 on voiceVolume. It is a fraction between 0 and 1, not a decibel value and not a percentage.

  • The captions are out of step with the voice. Captions are drawn exactly as timed, and nothing listens to the audio. Timings from a speech-recognition service mark when each word was heard, so if you have the script, align it to those timings before sending them.

  • An agent submitted the job and the audio is missing. The older client packages accept these fields and never send them. Upgrade to @spideriq/mcp 1.93.0 or @spideriq/mcp-leads 1.17.0, then resubmit.

Related