Contents
Muting a video sounds like one job. In practice it is three different jobs: silence the original sound, remove the audio track from the file, or swap the sound for something else. Each one is a different setting in the Edit API, and each one leaves a different file behind.
This guide covers all three, plus a fourth that comes up just as often, mixing music under the original audio. One Python script renders each version, and the probe endpoint reads back what the finished file contains. The numbers in the tables come from those renders.
TL;DR
- Set
volume: 0on the video asset to silence it. The output keeps a silent audio track. - Set
output.mute: trueto remove the audio track from the file entirely. - To replace the sound, silence the video and add an
audioasset on its own track. - To mix, leave the video at full volume and add the music at a low volume, 0.2 in this test.
- The script below does all four with the standard library, no SDK needed.
Where the sound lives in a render
An Edit API render is a JSON timeline of tracks and clips. Sound comes from two places, and there is a third setting that acts on the finished file.
- The video asset’s own audio. Every
videoasset has avolumebetween 0 and 1, where 0 is muted and 1 is full volume. The API reference gives 1 as the default. - Audio assets. An
audioasset is a clip like any other. It takes asrcURL, atrimpoint, avolume, aspeedand a fadeeffect. Put it on its own track so it does not compete for time with the video clips. output.mute. A boolean on the output block that mutes the audio track of the whole output video.
Some older tutorials put music in a timeline.soundtrack field. The examples below follow the API reference and put music in an audio asset on its own track.
Mute a video
There are two ways to do it, and they are not the same.
Setting volume: 0 on the video asset silences that clip. The output still has an audio track, it is just silent. Setting output.mute: true goes further and drops the audio track from the file. The probe endpoint shows the difference below.
Use volume: 0 when other clips on the timeline still need their sound, or when you plan to add music. Use output.mute when the file must have no audio at all, for example a background loop on a web page.
For feed video the choice costs little either way, because most of the audience never hears it. In LinkedIn’s 2017 survey of its members, 56% of people watching video on a laptop or desktop typically listen to it as well, but only 37% of those watching on mobile do.
Replace the audio
Replacing means two changes in one edit: the video asset at volume: 0, and an audio asset on a second track starting at the same time. In the script this is the replace mode.
Two details matter:
- Length. Audio plays until the file ends or the clip length is reached. Set the audio clip’s
lengthto match the video, or pass"end"to run it to the end of the timeline. A music file shorter than the clip leaves silence after it. - Fades. The audio asset’s
effecttakesfadeIn,fadeOutorfadeInFadeOut. The test usesfadeOutso the music does not stop dead at ten seconds.
Replacing is the right call when the original sound carries the meaning and you are swapping in a voiceover or a narration track.
Meta’s guidance for video ads makes the point: in one study of Facebook video ads, 41% of videos were basically meaningless without sound, and captioned ads increased view time by an average of 12%. If that describes your video, replace the audio or burn in captions rather than muting it.
Mix music under the original
Keep the video asset at volume: 1 and add the music at a low volume. The test uses 0.2 and the dialogue stays clear over it.
Watch the headroom. The mixed output in this test peaked at 0.0 dB, which is full scale. If your source is already loud, bring the video volume down to 0.8 or the music to 0.15 before the peaks clip. The audio multiple volumes template shows the same idea with several tracks at different levels.
The script
The script renders a ten second section of the Sintel trailer, an open movie by the Blender Foundation under CC BY 3.0, with a music track from the Shotstack sample library.
It needs an API key, which you can get by signing up for a free account, set as SHOTSTACK_API_KEY. Each render uses credits from your plan, as listed on the pricing page.
"""Mute a video, replace its audio, or mix music under it with the Shotstack Edit API.
Usage: SHOTSTACK_API_KEY=... python audio_modes.py <mode> mode = mute | output-mute | replace | mix | all
Renders a 10 second clip of the Sintel trailer (Blender Foundation, CC BY 3.0) and prints the output URL.
"""
import json
import os
import sys
import time
import urllib.parse
import urllib.request
API_KEY = os.environ.get("SHOTSTACK_API_KEY") or sys.exit("Set SHOTSTACK_API_KEY first.")
BASE = "https://api.shotstack.io/edit/v1"
VIDEO = "https://download.blender.org/durian/trailer/sintel_trailer-720p.mp4"
MUSIC = "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/music/unminus/lit.mp3"
START_IN_SOURCE = 20 # seconds into the trailer, where the dialogue is
LENGTH = 10
def call(method, path, body=None):
data = json.dumps(body).encode() if body else None
req = urllib.request.Request(BASE + path, data=data, method=method, headers={
"x-api-key": API_KEY, "Content-Type": "application/json", "Accept": "application/json"})
with urllib.request.urlopen(req, timeout=30) as r:
return json.load(r)["response"]
def video_clip(volume):
return {"asset": {"type": "video", "src": VIDEO, "trim": START_IN_SOURCE, "volume": volume}, "start": 0, "length": LENGTH}
def music_clip(volume):
return {"asset": {"type": "audio", "src": MUSIC, "volume": volume, "effect": "fadeOut"}, "start": 0, "length": LENGTH}
def edit(mode):
tracks = {
"mute": [[video_clip(0)]], # original sound off, nothing added
"output-mute": [[video_clip(1)]], # same, done at output level (see below)
"replace": [[video_clip(0)], [music_clip(1)]], # original off, music on its own track
"mix": [[video_clip(1)], [music_clip(0.2)]], # keep the dialogue, music under it at 20 per cent
}[mode]
output = {"format": "mp4", "resolution": "hd"}
if mode == "output-mute":
output["mute"] = True
return {"timeline": {"tracks": [{"clips": clips} for clips in tracks]}, "output": output}
def render(mode):
render_id = call("POST", "/render", edit(mode))["id"]
while True:
r = call("GET", f"/render/{render_id}")
if r["status"] == "done":
return render_id, r["url"]
if r["status"] == "failed":
sys.exit(f"{mode}: render {render_id} failed: {r.get('error')}")
time.sleep(3)
def audio_streams(url):
"""What the finished file actually contains, read back through the API's probe endpoint (ffprobe, no download)."""
meta = call("GET", "/probe/" + urllib.parse.quote(url, safe=""))["metadata"]
return [s for s in meta["streams"] if s["codec_type"] == "audio"]
modes = ["mute", "output-mute", "replace", "mix"] if sys.argv[1:] == ["all"] else sys.argv[1:2]
for mode in modes:
render_id, url = render(mode)
audio = audio_streams(url)
summary = ", ".join(f"{s['codec_name']} {int(s.get('bit_rate', 0)) // 1000} kbps" for s in audio) or "no audio stream"
print(f"{mode:<12} {render_id} audio: {summary}")
print(f"{'':<12} {url}")Three things the script does that are worth copying into your own code:
- One function per clip type.
video_clipandmusic_cliptake a volume and return a clip, so each mode is one line in theeditfunction. - One track per simultaneous clip. The video and the music start at the same time, so they sit on separate tracks. Two clips that overlap in time on one track do not render the way you expect.
- Read the file back. The probe endpoint runs ffprobe on the hosted output and returns its streams, so the script can say what the file contains without downloading it. The media metadata guide covers the rest of that response.
What each mode left in the file
This is the output of python audio_modes.py all:
mute f3689458-88ad-4fb6-9cb2-04db2f4a752e audio: aac 2 kbps
https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/35tqpmb0ya/f3689458-88ad-4fb6-9cb2-04db2f4a752e.mp4
output-mute 93d266ca-8578-4e4f-8d9a-c872bc0fc55a audio: no audio stream
https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/35tqpmb0ya/93d266ca-8578-4e4f-8d9a-c872bc0fc55a.mp4
replace b4d7d9d0-8a99-43e8-8168-7950191f943a audio: aac 129 kbps
https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/35tqpmb0ya/b4d7d9d0-8a99-43e8-8168-7950191f943a.mp4
mix d9a05aa8-ea40-4d94-8d66-2bddbd45d60b audio: aac 128 kbps
https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/35tqpmb0ya/d9a05aa8-ea40-4d94-8d66-2bddbd45d60b.mp4We then downloaded the four files and measured their loudness with FFmpeg’s volumedetect filter:
| Mode | What you set | Audio stream in the output | Loudness, mean and peak | File size |
|---|---|---|---|---|
mute | video volume: 0 | AAC stereo, 2 kbps | silent, -91 dB | 3.13 MB |
output-mute | output.mute: true | none | no audio | 3.12 MB |
replace | video volume: 0 + music at 1 | AAC stereo, 129 kbps | -20.2 dB, peak -0.1 dB | 3.29 MB |
mix | video volume: 1 + music at 0.2 | AAC stereo, 128 kbps | -13.5 dB, peak 0.0 dB | 3.29 MB |
Two findings worth knowing before you pick a mode.
- A muted clip still carries a track. The
muteoutput has a stereo AAC stream at 2 kbps. Players show an audio track, and some platforms’ checks will see one. Onlyoutput.muteproduces a file with no audio stream, and it saves 8 KB on a ten second clip, so size is not the reason to choose it. - Mixing can hit full scale. The
mixoutput peaked at 0.0 dB with the music at 0.2. The replace mode, music alone, peaked at -0.1 dB. If you mix over a loud source, pull one of the two volumes down.
The video below is the mix render.
One edit, the sound you want, nothing to re-encode locally
Muting, stripping, replacing and mixing are four settings on the same timeline. Set them in the edit, submit it, and the API returns a file with exactly the audio you asked for. The probe endpoint confirms it without a download.
Sign up for a free API key and run the script on your own footage. If this is your first render, the first video guide walks through the submit and poll loop.
Frequently asked questions (FAQs)
Can I fade the original sound out instead of cutting it?
Yes. The video asset has a volumeEffect field that takes fadeIn, fadeOut or fadeInFadeOut. For a custom curve, such as ducking the original under a voiceover for a few seconds, volume also accepts an array of tween objects that change the level over time. Our audio ducking guide builds those tweens from each voice-over line’s start and length.
Can I mute only part of a clip?
Split it into two clips on the same track, the first with volume: 1 and the second with volume: 0, using trim and start so they run back to back. Or keep one clip and use a volume tween to drop the level at the point you want.
How do I replace the audio on many videos?
Use one edit for every video and change only the video URL. Put a merge field such as {{VIDEO_URL}} in the video asset’s src, then send one render per video with its own merge value. The merging data guide shows the format.