> 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/restore-video-and-stream/.

# Restore a video and stream it

Restore the speech in a video, download the restored MP4, and stream the result in a browser with hls.js.

## How it works

1. Your code → Diffio API: `POST /projects`, talk.mp4, generation
2. Your code → Media host: `upload.requests`, the SDK sends the parts
3. Diffio API → Your code: `generation complete`, files.video (MP4)
4. Your code → Diffio API: `GET /projects/{id}`, video_preview_status: "ready"
5. Your code → Diffio API: `GET …/media`, files.hls_master, 6 hour URLs
6. Your code → Browser: `player.html`, hls_master URL
7. Browser → Media host: `GET hls_master`, playlists and segments, any origin

**The browser streams straight from the media host; your API key never reaches it.**

## Build it

### 1. Restore the video

Upload MP4, MOV, WebM, AVI, MKV, 3GP or 3G2 (up to 2 GB; see [Video support](https://diffio.ai/docs/overview/capabilities/video-support/)) like any recording. The finished generation has `files.video`: the same video with the restored speech, as an MP4. `file="video"` (`downloadFile: "video"` in Node) saves it.

### 2. Wait for the picture stream

The picture for streaming is prepared from the upload: the project's `video_preview_status` goes `preparing` → `ready`. Until then, `files.hls_master` plays sound only; if it ends `failed`, `files.video` still works.

### 3. Stream it

`files.hls_master` plays the restored sound with the picture. Safari plays HLS itself; other browsers use hls.js. The media host answers these URLs from any origin, and they stop working at `expires_at` (6 hours): in production, your server asks for a fresh grant each time someone opens the player.

### The complete script

Pass a video file; it writes `restored.mp4` and `player.html`.

**video.py**

```python
"""Restore the speech in a video, save the restored MP4, and write player.html that streams it with hls.js.

python video.py talk.mp4
"""
import sys
import time

from diffio import DiffioClient, DiffioTimeoutError, GenerationFailedError

PLAYER = """<!doctype html>
<title>Restored video</title>
<video id="player" controls playsinline style="width: 100%; max-width: 960px"></video>
<script src="https://cdn.jsdelivr.net/npm/hls.js@1.5.17/dist/hls.min.js"></script>
<script>
  const source = "HLS_MASTER_URL"; // files.hls_master; works until the grant's expires_at
  const video = document.getElementById("player");
  if (video.canPlayType("application/vnd.apple.mpegurl")) video.src = source; // Safari plays HLS itself
  else if (Hls.isSupported()) { const hls = new Hls(); hls.loadSource(source); hls.attachMedia(video); }
</script>
"""

path = sys.argv[1]
client = DiffioClient()  # reads DIFFIO_API_KEY

# 1. Restore; files.video is the video with the restored speech.
try:
    result = client.restore_audio(path, file="video", output_path="restored.mp4", timeout=3600)
except (GenerationFailedError, DiffioTimeoutError) as error:
    sys.exit(f"restore did not finish: {error}")
project_id, generation_id = result.project.id, result.generation.id

# 2. The picture stream for HLS (bounded wait).
deadline = time.monotonic() + 600
project = client.projects.get(project_id)
while project.video_preview_status == "preparing" and time.monotonic() < deadline:
    time.sleep(3)
    project = client.projects.get(project_id)
if not project.has_video or project.video_preview_status != "ready":
    sys.exit(f"no picture stream (has_video {project.has_video}, video_preview_status {project.video_preview_status})")

# 3. A playback grant: hls_master plays the restored sound with the picture.
media = client.generations.media(project_id, generation_id)
with open("player.html", "w") as page:
    page.write(PLAYER.replace("HLS_MASTER_URL", media.files["hls_master"]))
print("saved restored.mp4 and player.html; the stream works until", media.expires_at)
```

**video.mjs**

```javascript
// Restore the speech in a video, save the restored MP4, and write player.html that streams it with hls.js.
// node video.mjs talk.mp4
import { writeFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";
import { DiffioClient } from "diffio";

const PLAYER = `<!doctype html>
<title>Restored video</title>
<video id="player" controls playsinline style="width: 100%; max-width: 960px"></video>
<script src="https://cdn.jsdelivr.net/npm/hls.js@1.5.17/dist/hls.min.js"></script>
<script>
  const source = "HLS_MASTER_URL"; // files.hls_master; works until the grant's expires_at
  const video = document.getElementById("player");
  if (video.canPlayType("application/vnd.apple.mpegurl")) video.src = source; // Safari plays HLS itself
  else if (Hls.isSupported()) { const hls = new Hls(); hls.loadSource(source); hls.attachMedia(video); }
</script>
`;

const path = process.argv[2];
const client = new DiffioClient(); // reads DIFFIO_API_KEY

// 1. Restore; files.video is the video with the restored speech (a failure throws with its error code).
const result = await client.restoreAudio({ file: path, downloadFile: "video", outputPath: "restored.mp4", timeout: 3600 });
const projectId = result.project.id;

// 2. The picture stream for HLS (bounded wait).
const deadline = Date.now() + 600_000;
let project = await client.projects.get(projectId);
while (project.video_preview_status === "preparing" && Date.now() < deadline) {
  await sleep(3000);
  project = await client.projects.get(projectId);
}
if (!project.has_video || project.video_preview_status !== "ready") {
  throw new Error(`No picture stream (has_video ${project.has_video}, video_preview_status ${project.video_preview_status})`);
}

// 3. A playback grant: hls_master plays the restored sound with the picture.
const media = await client.generations.media(projectId, result.generation.id);
await writeFile("player.html", PLAYER.replace("HLS_MASTER_URL", media.files.hls_master));
console.log("saved restored.mp4 and player.html; the stream works until", media.expires_at);
```

## What you get

![A restored downtown street interview in the Diffio app: the video picture above the waveform, the Restored switch and the Background amount slider at 25%](https://diffio.ai/media/remove-background-noise-from-video/app-video-result.webp)

Soundtrack as uploaded

[Soundtrack as uploaded (MP3)](https://diffio.ai/media/remove-background-noise-from-video/downtown-traffic-original.mp3)

Restored by Diffio 4.7 Pro

[Restored by Diffio 4.7 Pro (MP3)](https://diffio.ai/media/remove-background-noise-from-video/downtown-traffic-speech.mp3)

**A street interview in Kansas City with traffic passing: its soundtrack as uploaded, the speech restored by Diffio 4.7 Pro, and the restored video in the Diffio app. Video by Kansas City, Mo. City Communications, CC BY 3.0. [More restored videos](https://diffio.ai/remove-background-noise-from-video/).**

- `restored.mp4`: the video with the restored speech.
- `player.html`: the HLS stream with the picture, playable in any modern browser for 6 hours.

**Output of `python video.py talk.mp4`**

**Terminal**

```bash
saved restored.mp4 and player.html; the stream works until 2026-11-13T06:33:47Z
```

## API reference

- POST [Create a project](https://diffio.ai/docs/api-reference/create-project/) (`/projects`): Upload a video like any recording.
- GET [Get a project](https://diffio.ai/docs/api-reference/get-project/) (`/projects/{project_id}`): has_video and video_preview_status.
- GET [Get a playback grant](https://diffio.ai/docs/api-reference/get-generation-media/) (`/projects/{project_id}/generations/{generation_id}/media`): video, hls_master, video_hls and the other files.

## Related pages

- Previous: [Share a restored result](https://diffio.ai/docs/developers/guides/share-a-result/): Publish → public read → revoke
- Next: [Compare Flash and Pro](https://diffio.ai/docs/developers/guides/compare-flash-and-pro/): One project → two generations
