Add video metadata preservation and save_first_image option to VideoCombine

[cooldplay]

Summary

This PR adds two new features to the VideoCombine node:

1. Metadata Preservation: Ability to preserve and transplant video metadata (workflow, prompt, etc.) from input videos to output videos
2. Save First Image Option: Adds a configurable option for saving the first frame as PNG (previously always enabled)

Changes

New Features

1. Metadata Preservation

• Metadata Extraction: Added get_video_metadata() function in utils.py that extracts metadata from video files using ffmpeg

  • Supports two extraction methods: stderr parsing and FFMETADATA format parsing
  • Properly handles ffmpeg's metadata format with individual key=value pairs
  • Implements correct escaping/unescaping for special characters (=, ;, #, \, newlines)
  • Automatically parses JSON values in metadata fields

• LoadVideo Nodes Enhancement: All LoadVideo nodes now extract and return metadata

  • Added new output type VHS_METADATA
  • Added new output metadata to all LoadVideo variants:
    • LoadVideoUpload
    • LoadVideoPath
    • LoadVideoFFmpegUpload
    • LoadVideoFFmpegPath

• VideoCombine Enhancement: VideoCombine now accepts optional video metadata input

  • Added optional input video_metadata (type: VHS_METADATA)
  • When metadata is provided, uses it instead of current workflow metadata
  • Maintains backward compatibility - uses current workflow if no metadata input is connected

2. Save First Image Option

• Added save_first_image boolean parameter to VideoCombine (default: True)
• Previously, the first frame was always saved as PNG - now this behavior is configurable
• When enabled, saves the first frame of the video as a PNG file with full metadata
• Purpose: While videos can store metadata, extracting and viewing that metadata requires specific tools or loading the entire video. A PNG file with embedded metadata can be simply dragged into ComfyUI to instantly load the workflow, making it much easier to inspect or reuse the generation settings.
• The PNG file includes:
  • Complete workflow information in metadata
  • Prompt data
  • Creation timestamp
  • All extra PNG info from the workflow
• Filename format: {filename}_{counter:05}.png

Other Improvements

• Added -movflags "+faststart+write_colr" to several video formats (h264-mp4, h265-mp4, nvenc variants) for better compatibility and faster streaming
• Updated ffv1-mkv format configuration

Use Cases

Metadata Preservation: This feature enables workflows where you want to:

1. Load a video that was generated with specific workflow settings
2. Process/modify the video (apply effects, resize, etc.)
3. Save the output video while preserving the original generation metadata

This feature is particularly useful when you want to perform interpolation or other post-processing on generated videos at a later time while preserving the original workflow metadata.

 

Save First Image:

• Easy workflow inspection: Simply drag and drop the PNG into ComfyUI to load the complete workflow, without needing to extract metadata from the video file
• Workflow archival: Keep a visual reference alongside the video that also contains all generation parameters
• Compatibility: Not all video players or tools can display embedded video metadata, but PNG metadata is widely supported in image viewers and ComfyUI
• Quick reference: See the first frame as a thumbnail while having instant access to all generation settings
• Now optional: Users can disable this feature if they don't need the PNG output

Example Workflow

LoadVideoPath → [video output] → VideoCombine (save_first_image=True)
             → [metadata output] ↗

The metadata flows from LoadVideo to VideoCombine, ensuring the output video contains the same workflow/prompt information as the input video. With save_first_image enabled (default), you also get a PNG that can be dragged directly into ComfyUI to load the workflow.

Technical Details

• The metadata extraction correctly handles ffmpeg's behavior of splitting comment fields into individual metadata keys
• Multi-line metadata values are properly supported
• JSON values are automatically parsed when appropriate
• Error handling ensures the feature degrades gracefully if metadata extraction fails
• First image is saved before video processing begins, ensuring metadata is preserved even if video encoding fails
• PNG metadata format is identical to ComfyUI's standard image output, ensuring full compatibility with workflow loading

Backward Compatibility

✅ Fully backward compatible:

• The video_metadata input is optional and defaults to using current workflow metadata when not connected
• The save_first_image parameter defaults to True, maintaining the existing behavior of always saving the first frame as PNG
• Users who want to disable the first image PNG can now set save_first_image to False

[xbelda]

I was facing this issue when I found your PR.
Just tested the option to save the first image and it works just as expected.

Great work, hope this gets merged soon.