Add Music and Voiceover to a Video

You built the picture yourself: custom-coded scenes, a screen recording, an animation rendered on your machine. Now it needs a music bed and narration. mux_video_audio does the mix on BlackOps' servers. You name the video, the track and the voiceover clips; BlackOps fetches every file itself, mixes them, and saves the result to your media library as a new video you can attach to a post or tweet.

Your agent never downloads or moves the audio. That matters for licensed music: the file goes from the source straight into your library.

The flow

1. Upload the silent video. Use upload_media (or get_media_upload_url and finalize_media_upload for a large file). Keep the asset_id. A video that is already on a public https link works too.
2. Make the narration. synthesize_speech turns lines of text into ElevenLabs MP3 clips and returns a URL and measured duration for each. Decide where each line starts in the video.
3. Add the music to your library. add_music_track with a file_url (see Connecting Artlist to your agent). BlackOps downloads the file, checks it really is an MP3 or WAV, and analyzes its BPM, beat grid and hook. Keep the track id.
4. Start the mix. mux_video_audio returns an asset_id straight away and runs the mix in the background, like render_video.
5. Wait for it. Poll get_video_audio_mix with that asset_id until status is ready. It reports a stage and a progress percentage while it runs.
6. Use it. The asset_id is a normal media library video. Attach it with attach_media_to_tweet or attach_media_to_post.

When the mix finishes with a library track, BlackOps records the use for you, the same as mark_music_used, so list_music_tracks steers your next video toward a different track.

A mix request

{
  "domain": "example.com",
  "video": { "asset_id": "7d1c…" },
  "music": {
    "track_id": "c42e…",
    "start_offset_ms": 78182,
    "volume": 0.6,
    "fade_in_ms": 500,
    "fade_out_ms": 1500
  },
  "voiceovers": [
    { "url": "https://…/line-1.mp3", "start_ms": 1200 },
    { "url": "https://…/line-2.mp3", "start_ms": 9800, "volume": 1.1 }
  ],
  "duck": { "enabled": true, "volume": 0.3, "attack_ms": 200, "release_ms": 500 },
  "output_length_ms": 45000,
  "title": "Launch video"
}

• video: an asset_id from your media library, or an https url. One of the two.
• music: a library track_id, an audio asset_id, or an https url. start_offset_ms skips into the track, so a mix can start on the hook rather than the intro (hook_start_seconds from get_music_track is a good starting point). volume runs from 0 to 2, default 0.6. The music fades in and out by default.
• voiceovers: up to 30 clips, each a BlackOps audio asset_id or an https url, with start_ms from the start of the video.
• duck: while any clip plays, the music drops to volume (default 0.3, so about 10 dB down) and comes back up after the clip ends. attack_ms and release_ms set how fast. On by default whenever there is narration.
• output_length_ms: optional. Trims the output to this length. It can't be longer than the video. Leave it out to keep the video's own length.

You can mix music only, narration only, or both.

What you get back

The output is an MP4 with the original picture copied as is, so there's no re-encode and no quality loss for H.264 or HEVC video. Anything else is re-encoded to H.264. The audio is AAC stereo at 48 kHz, with a limiter so the loudest moments don't clip. Any audio the video already had is replaced.

Connecting Artlist to your agent

BlackOps doesn't need your Artlist account. Your agent uses its own Artlist connection to find a track and get a download link for a track your plan licenses, then hands that link to BlackOps:

1. Connect Artlist to your agent (for example the Artlist connector in Claude).
2. Ask the agent to find a track (search_music) and get its download link (download_track).
3. The agent calls add_music_track with that link as file_url, plus title, artist, artlist_url and artlist_song_id so the library remembers where it came from.

Download links usually expire after a while. If add_music_track says the link answered with an error, get a fresh one and try again.

You can also add a file you already have: upload it with upload_media (MP3 and WAV are recorded as audio) and pass its asset_id to add_music_track.

Limits

• Video up to 150 MB, a music file up to 50 MB, each voiceover clip up to 25 MB and 50 MB of clips in total.
• A video that isn't H.264 or HEVC has to be re-encoded, which is slow. For a long video, export H.264 MP4 so the picture is copied instead.
• The output can be up to 10 minutes long.
• Every link is fetched with the same checks as other media links: https only, public hosts only, every redirect checked, and a size cap while downloading.
• A mix that fails says why in get_video_audio_mix (for example a link that answered 404, or a start time past the end of the video). Start a new mix once it's fixed.