# How to Modify the Rendering to Include Specific Metadata in the Output Video

> Learn how to modify video rendering to include custom metadata in the output. Extend ffmpeg commands in video-use helpers/render.py with -metadata flags for key-value pairs.

- Repository: [Browser Use/video-use](https://github.com/browser-use/video-use)
- Tags: how-to-guide
- Published: 2026-06-30

---

**You can modify the rendering pipeline in `video-use` to include custom metadata by extending the ffmpeg command lists in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) with `-metadata` flags, passing a dictionary of key-value pairs through the `extract_segment` and `build_final_composite` functions.**

The `video-use` library from browser-use handles video assembly through a multi-stage ffmpeg pipeline. If you need to modify the rendering to include specific metadata in the output video—such as titles, artists, or descriptions—you must intercept the command construction in the rendering helpers and append the appropriate metadata flags.

## Understanding the Three-Stage Rendering Pipeline

According to the source code in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), `video-use` builds the final video through three distinct stages:

1. **Per-segment extraction** – Each EDL range is converted into an individual MP4 file via the `extract_segment` function (lines 61-70 and 98-106).
2. **Lossless concatenation** – Segment files are stitched together using `concat_segments` (lines 67-78).
3. **Final compositing** – Overlays and subtitles are applied through `build_final_composite` (lines 55-67).

Since ffmpeg accepts arbitrary metadata via the repeated `-metadata key=value` option, you can modify the rendering to include specific metadata by extending the command lists (`cmd = [...]`) in the extraction and compositing functions.

## Adding CLI Support for Custom Metadata

To expose this functionality to users, add a `--metadata` argument to the CLI and parse it into a dictionary:

```python

# In your main entry point (around line 75)

ap.add_argument(
    "--metadata",
    nargs="+",
    metavar="KEY=VALUE",
    help="Custom FFmpeg metadata to embed (e.g. title='My Video' artist='Me')",
)

# Parse function (after line 104)

def parse_metadata(pairs: list[str] | None) -> dict[str, str]:
    out = {}
    if not pairs:
        return out
    for pair in pairs:
        if "=" not in pair:
            continue
        k, v = pair.split("=", 1)
        out[k] = v.strip("'\"")
    return out

metadata = parse_metadata(args.metadata)

```

Pass this dictionary to the rendering functions:

```python

# Around lines 115-120

segment_paths = extract_all_segments(
    edl, edit_dir, preview=args.preview, draft=args.draft, metadata=metadata
)

# ...

build_final_composite(
    base_path, overlays, subs_path, out_path, edit_dir, metadata=metadata
)

```

## Modifying extract_segment to Include Metadata

Update the `extract_segment` function in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) to accept and apply the metadata dictionary:

```python
def extract_segment(..., metadata: dict[str, str] | None = None):
    cmd = [
        "ffmpeg", "-y",
        "-ss", f"{seg_start:.3f}",
        "-i", str(source),
        "-t", f"{duration:.3f}",
        "-vf", vf,
        "-af", af,
        "-c:v", "libx264", "-preset", preset, "-crf", crf,
        "-pix_fmt", "yuv420p", "-r", "24",
        "-c:a", "aac", "-b:a", "192k", "-ar", "48000",
        "-movflags", "+faststart",
    ]

    # Append user-supplied metadata

    if metadata:
        for k, v in metadata.items():
            cmd += ["-metadata", f"{k}={v}"]
    cmd.append(str(out_path))
    subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)

```

This ensures every extracted segment MP4 contains your custom metadata before concatenation.

## Modifying build_final_composite to Include Metadata

Similarly, update `build_final_composite` to embed metadata in the final output:

```python
def build_final_composite(..., metadata: dict[str, str] | None = None):
    cmd = [
        "ffmpeg", "-y",
        *inputs,
        "-filter_complex", filter_complex,
        "-map", out_label,
        "-map", "0:a",
        "-c:v", "libx264", "-preset", "fast", "-crf", "18",
        "-pix_fmt", "yuv420p",
        "-c:a", "copy",
        "-movflags", "+faststart",
    ]

    # Append user-supplied metadata

    if metadata:
        for k, v in metadata.items():
            cmd += ["-metadata", f"{k}={v}"]
    cmd.append(str(out_path))
    subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)

```

## Complete Usage Example

With these modifications in place, run the rendering script with your custom metadata:

```bash
python helpers/render.py my_edl.json -o final.mp4 \
    --metadata title='My Demo Video' artist='Jane Doe' comment='Generated with video-use'

```

This command modifies the rendering to include specific metadata in both the intermediate segment files and the final composite video.

## Verifying Embedded Metadata

Confirm the metadata was successfully embedded using ffprobe:

```bash
ffprobe -show_entries format_tags -of default=noprint_wrappers=1:nokey=0 final.mp4

```

The output displays the key-value pairs passed through the `--metadata` flag.

## Summary

- **Architecture-aware approach**: The `video-use` pipeline constructs ffmpeg commands as Python lists, making it safe to extend them with `-metadata` flags.
- **Consistent metadata**: By passing the same dictionary to both `extract_segment` and `build_final_composite`, your metadata appears in every output file.
- **No dependencies**: This modification uses ffmpeg's built-in capabilities—no additional packages required.
- **Key files**: [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) contains the `extract_segment` (lines 98-106) and `build_final_composite` (lines 55-67) functions that require modification.

## Frequently Asked Questions

### How does ffmpeg handle the metadata flags in video-use?

ffmpeg processes `-metadata` flags by embedding the key-value pairs directly into the output file's container metadata. When you modify the rendering to include specific metadata in the output video, the flags are appended to the command list before `subprocess.run` executes the ffmpeg process, ensuring atomic inclusion in the rendered file.

### Will metadata persist through the concatenation stage?

When you include metadata in the `extract_segment` function, each individual segment MP4 retains those tags. However, to ensure metadata appears in the final deliverable, you must also pass the dictionary to `build_final_composite`, as the concatenation stage creates new files that may not inherit metadata from intermediate segments.

### Can I include special characters or spaces in metadata values?

Yes, but you must handle quoting carefully. The `parse_metadata` function strips surrounding single or double quotes from values, allowing you to pass values like `title='My Video'` or `description="A longer text"`. Avoid unescaped equals signs within keys, as the split operation uses the first `=` character as the delimiter.

### Do I need to modify the concat_segments function?

No, `concat_segments` (lines 67-78) performs lossless concatenation of already-encoded segments and typically uses the `concat` demuxer or protocol. Since metadata embedding must occur during encoding rather than during file stitching, you only need to modify `extract_segment` and `build_final_composite` to include the `-metadata` flags.