Skip to content

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

  1. Your code → Diffio API: POST /projects, restore, then wait for complete
  2. Diffio API → Your code: stems_status: "ready", or generation.stems_ready
  3. Your code → Diffio API: GET …/mix, revision
  4. Your code → Diffio API: PUT …/mix, background_gain 0.2, revision
  5. Your code → Diffio API: POST …/exports, artifact mix, format mp3
  6. Diffio API → Your code: status: "ready", or export.ready, with url
  7. Your code: download url, interview-mix.mp3
Speech and background are separate tracks; a mix and an export only change how they are combined.

Build it

  1. 1

    Restore the recording

    Any finished restore. The separated speech and background tracks are made from it.

  2. 2

    Wait for the separated tracks

    The tracks can finish after the restore. Poll until stems_status is ready, or act on the generation.stems_ready webhook (generation.stems_failed when they never will be).

  3. 3

    Save the balance

    background_gain runs from 0 (speech only) to 1 (all of the background). Read the mix first and send its revision: if someone saved since, the save is refused with 409Conflict: see error.code for which one. revision_conflict (Errors); read again and decide.

  4. 4

    Render an export and wait

    A mix export without background_gain uses the saved balance. Other recipes: speech or background alone, or both as a zip. Wait for status: "ready" or the export.ready webhook. Asking for the same recipe again returns the same export.

  5. 5

    Download it

    A ready export carries a download url; GET …/exports/{export_id} gives a fresh one later.

The complete script

What you get

Speech track (background_gain 0)

Background track

An outdoor interview with wind across the mic, split by Diffio 4.7 Pro into its two tracks; a mix is any balance of the two. The clip and its credit.
  • 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
Terminal
saved mix 0.2 revision 4014a8c299444bbb866971bbb7b657ca:1
saved interview-mix.mp3 from export 7c2e9b41d0a84f6e9a3b5c1d2e8f4a60

API 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.

Report an issue with this page