> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/developers/guides/separate-speech-and-background/.

# 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. 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_status` is `ready`, or act on the `generation.stems_ready` webhook (`generation.stems_failed` when they never will be).

### 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 `409` `revision_conflict` ([Errors](https://diffio.ai/docs/api-reference/errors/)); read again and decide.

### 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. Download it

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

### The complete script

**tracks.py**

```python
"""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)
```

**tracks.mjs**

```javascript
// Restore interview.mp3, turn its background down to 20%, and save that mix as an MP3.
// node tracks.mjs
import { writeFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";
import { DiffioApiError, DiffioClient } from "diffio";

const client = new DiffioClient(); // reads DIFFIO_API_KEY

// 1. A finished restore.
const result = await client.restoreAudio({ file: "interview.mp3", outputPath: "interview-restored.mp3" });
const projectId = result.project.id;
let generation = result.generation;

// 2. The separated tracks can finish after the restore.
const deadline = Date.now() + 600_000;
while (generation.stems_status !== "ready") {
  if (generation.stems_status === "failed" || Date.now() > deadline) {
    throw new Error(`No separated tracks (stems_status ${generation.stems_status})`);
  }
  await sleep(3000);
  generation = await client.generations.get(projectId, generation.id);
}

// 3. Save the balance (0 is speech only, 1 keeps all of the background) on the mix you read.
const current = await client.mix.get(projectId, generation.id);
let mix;
try {
  mix = await client.mix.save(projectId, generation.id, { background_gain: 0.2, revision: current.revision });
} catch (error) {
  if (error instanceof DiffioApiError && error.code === "revision_conflict") {
    throw new Error(`Someone saved the mix since you read it (${JSON.stringify(error.details)}); read it again first`);
  }
  throw error;
}
console.log("saved mix", mix.background_gain, "revision", mix.revision);

// 4. Render the saved mix as an MP3 and wait for it.
let rendered = await client.exports.create(projectId, generation.id, { artifact: "mix", format: "mp3" });
rendered = await client.exports.wait(projectId, generation.id, rendered.id);

// 5. Download it.
const response = await fetch(rendered.url);
if (!response.ok) throw new Error(`Download failed (${response.status})`);
await writeFile("interview-mix.mp3", Buffer.from(await response.arrayBuffer()));
console.log("saved interview-mix.mp3 from export", rendered.id);
```

## What you get

As uploaded

[As uploaded (MP3)](https://diffio.ai/media/remove-background-noise-from-video/outdoor-wind-original.mp3)

Speech track (background_gain 0)

[Speech track (background_gain 0) (MP3)](https://diffio.ai/media/remove-background-noise-from-video/outdoor-wind-speech.mp3)

Background track

[Background track (MP3)](https://diffio.ai/media/remove-background-noise-from-video/outdoor-wind-background.mp3)

**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](https://diffio.ai/remove-background-noise-from-video/).**

- `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**

```bash
saved mix 0.2 revision 4014a8c299444bbb866971bbb7b657ca:1
saved interview-mix.mp3 from export 7c2e9b41d0a84f6e9a3b5c1d2e8f4a60
```

## API reference

- GET [Get a generation](https://diffio.ai/docs/api-reference/get-generation/) (`/projects/{project_id}/generations/{generation_id}`): stems_status of the restore.
- GET [Get the saved mix](https://diffio.ai/docs/api-reference/get-generation-mix/) (`/projects/{project_id}/generations/{generation_id}/mix`): The saved balance and its revision.
- PUT [Save the mix](https://diffio.ai/docs/api-reference/save-generation-mix/) (`/projects/{project_id}/generations/{generation_id}/mix`): Save background_gain and leveling.
- POST [Create an export](https://diffio.ai/docs/api-reference/create-generation-export/) (`/projects/{project_id}/generations/{generation_id}/exports`): Artifacts, formats and limits.
- GET [Get an export](https://diffio.ai/docs/api-reference/get-generation-export/) (`/projects/{project_id}/generations/{generation_id}/exports/{export_id}`): Export status and a fresh url.

## Related pages

- Previous: [Let users edit by asking](https://diffio.ai/docs/developers/guides/edit-by-asking/): Ask → proposals → edit
- Next: [Share a restored result](https://diffio.ai/docs/developers/guides/share-a-result/): Publish → public read → revoke
