For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/developers/guides/separate-speech-and-background.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

Separate speech and background
Turn the background down under the restored speech, save that balance, and download it as an MP3.
How it works
- Your code → Diffio API:
POST /projects, restore, then wait for complete - Diffio API → Your code:
stems_status: "ready", or generation.stems_ready - Your code → Diffio API:
GET …/mix, revision - Your code → Diffio API:
PUT …/mix, background_gain 0.2, revision - Your code → Diffio API:
POST …/exports, artifact mix, format mp3 - Diffio API → Your code:
status: "ready", or export.ready, with url - Your code:
download url, interview-mix.mp3
Build it
- 1
Restore the recording
Any finished restore. The separated speech and background tracks are made from it.
- 2
Wait for the separated tracks
The tracks can finish after the restore. Poll until
stems_statusisready, or act on thegeneration.stems_readywebhook (generation.stems_failedwhen they never will be). - 3
Save the balance
background_gainruns from0(speech only) to1(all of the background). Read the mix first and send itsrevision: if someone saved since, the save is refused with409Conflict: see error.code for which one.revision_conflict(Errors); read again and decide. - 4
Render an export and wait
A
mixexport withoutbackground_gainuses the saved balance. Other recipes:speechorbackgroundalone, orbothas a zip. Wait forstatus: "ready"or theexport.readywebhook. Asking for the same recipe again returns the same export. - 5
Download it
A ready export carries a download
url;GET …/exports/{export_id}gives a fresh one later.
The complete script
"""Restore interview.mp3, turn its background down to 20%, and save that mix as an MP3.
python tracks.py
"""
import sys
import time
import urllib.request
from diffio import DiffioApiError, DiffioClient
client = DiffioClient() # reads DIFFIO_API_KEY
# 1. A finished restore.
result = client.restore_audio("interview.mp3", output_path="interview-restored.mp3")
project_id, generation = result.project.id, result.generation
# 2. The separated tracks can finish after the restore.
deadline = time.monotonic() + 600
while generation.stems_status != "ready":
if generation.stems_status == "failed" or time.monotonic() > deadline:
raise SystemExit(f"No separated tracks (stems_status {generation.stems_status})")
time.sleep(3)
generation = client.generations.get(project_id, generation.id)
# 3. Save the balance (0 is speech only, 1 keeps all of the background) on the mix you read.
current = client.mix.get(project_id, generation.id)
try:
mix = client.mix.save(project_id, generation.id, background_gain=0.2, revision=current.revision)
except DiffioApiError as error:
if error.code != "revision_conflict":
raise
sys.exit(f"Someone saved the mix since you read it (now {error.details}); read it again first")
print("saved mix", mix.background_gain, "revision", mix.revision)
# 4. Render the saved mix as an MP3 and wait for it.
rendered = client.exports.create(project_id, generation.id, artifact="mix", format="mp3")
rendered = client.exports.wait(project_id, generation.id, rendered.id)
# 5. Download it.
urllib.request.urlretrieve(rendered.url, "interview-mix.mp3")
print("saved interview-mix.mp3 from export", rendered.id)What you get
As uploaded
Speech track (background_gain 0)
Background track
interview-restored.mp3: the restored speech.interview-mix.mp3: the speech with 20% of the background under it.- The saved balance on the generation, for the next export or your own player.
Output of python tracks.py
saved mix 0.2 revision 4014a8c299444bbb866971bbb7b657ca:1
saved interview-mix.mp3 from export 7c2e9b41d0a84f6e9a3b5c1d2e8f4a60API reference
- GETGet a generation (
/projects/{project_id}/generations/{generation_id}): stems_status of the restore. - GETGet the saved mix (
/projects/{project_id}/generations/{generation_id}/mix): The saved balance and its revision. - PUTSave the mix (
/projects/{project_id}/generations/{generation_id}/mix): Save background_gain and leveling. - POSTCreate an export (
/projects/{project_id}/generations/{generation_id}/exports): Artifacts, formats and limits. - GETGet an export (
/projects/{project_id}/generations/{generation_id}/exports/{export_id}): Export status and a fresh url.