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

You can modify the rendering pipeline in video-use to include custom metadata by extending the ffmpeg command lists in 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, 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:

# 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:

# 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 to accept and apply the metadata dictionary:

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:

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:

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:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}