[Feature] Video Export Support with Source Image Embedding

[Gunther-Schulz]

All code and this PR description was generated by AI.

🎯 Key Benefit

Enable Complete i2v Generation Repeatability: This feature allows users to fully reproduce previous image-to-video (i2v) generations by storing source images alongside video files. When you drag a previously generated video back to the UI, not only will the generation settings and seed be restored, but also the original source image(s) used for i2v generation - enabling perfect reproduction and tweaking of previous generations.

🚀 Overview

This PR adds support for embedding source images into MP4 video files using the mutagen library, solving the challenge of preserving source images for i2v workflow repeatability.

✨ New Feature

MP4 Image Embedding

• Mutagen Integration: Embed source images as MP4 cover art using the mutagen library
• Universal Compatibility: MP4 files with embedded images work across all devices and media players
• Multiple Image Support: Embed start, end, and reference images when available
• Quality Preservation: Images stored byte-for-byte identical with no recompression

🔧 Implementation

• Added mutagen-based MP4 image embedding functionality
• Integrated with existing "Embed Source Images" checkbox in GUI
• Pure Python solution with no external dependencies for MP4 embedding

🎯 Benefits

• Complete Workflow Repeatability: Drag videos back to UI to restore both settings AND source images
• Wide Compatibility: MP4 format supported universally
• No Quality Loss: Original image quality preserved
• Easy Integration: Works with existing GUI controls
• Reliable Storage: Images embedded as standard MP4 metadata

📋 Usage

1. Generate videos with MP4 output
2. Enable "Embed Source Images" option in Outputs tab
3. Source images automatically embedded as cover art in MP4 files
4. Drag generated videos back to UI - settings, seed, AND source images are automatically restored
5. Tweak parameters and regenerate with identical or modified settings

This feature provides a modern, widely-compatible way to store source images alongside generated videos, enabling complete reproducibility of i2v generations.

[Tophness]

What's the purpose of including an image extractor for mvk specifically?
Also, when it comes to using images from video, over at #965 I have a whole UI for picking which frame you want to use. Much more useful than a separate command line argument to wgp.py (which isn't how people use WAN2GP anyway).

I'd much rather add mkv support to mutagen than use ffmpeg via command line and externally move metadata between temp file locations tbh. There's already a PR for it about a year ago, it just wasn't accepted yet. If there's anything left to do, that seems like a job where AI could really help.

[Gunther-Schulz]

Thanks for the comment. I will check out the other PR. I removed the terminal stuff. I saw ffmpeg is a dependency anyways (it's in requirements.txt) so i figured I'd use that.

P.S.: I can't seem to find the PR you are referring to. Can you point me to it?
P.P.S: Mutagen seems to be for audio files only? https://mutagen.readthedocs.io/en/latest/ I would prefer a solution that does not rely on external cli utilities as well but I can't seem to find any solution :(

[Tophness]

P.P.S: Mutagen seems to be for audio files only? https://mutagen.readthedocs.io/en/latest/ I would prefer a solution that does not rely on external cli utilities as well but I can't seem to find any solution :(

I used mutagen for the mp4 metadata reading/writing. It's right above where you do the ffmpeg commands. Went through a ton of libraries and that was the best by far. No mkv support though, so I'll see if I can add it

[Gunther-Schulz]

I used mutagen for the mp4 metadata reading/writing. It's right above where you do the ffmpeg commands. Went through a ton of libraries and that was the best by far. No mkv support though, so I'll see if I can add it

I switched to mutagen for embedding images into mp4 now. Thank you for that suggestion. I disabled mkv support. I am keeping the back-end code for mkv support however but do not expose it to the GUI frontend for now.

[Tophness]

I've added mkv support to mutagen. There wasn't much to use in that PR so I just built a new one from scratch.
We can always just use my fork.

quodlibet/mutagen#688

[Tophness]

I got why you were adding mkv support, but I don't understand the point of the embedding images into the mp4. Unless I'm missing something?

[Gunther-Schulz]

I got why you were adding mkv support, but I don't understand the point of the embedding images into the mp4. Unless I'm missing something?

As you know you can apply the generation settings from a previously generated video by dragging it to the UI. With this feature it is now possible to repeat/tweak a previous generation for i2v as well, because the image can be stored with the video and not only the settings metadata. So when you now drag a video to the UI not only will the settings and seed of the previous video be restored but also the image(s) used for the i2v generation.

[Gunther-Schulz]

I've added mkv support to mutagen. We can always just use my fork.

quodlibet/mutagen#688

Thank you! I think I will wait until this PR gets accepted/merged and then do a separate PR enabling mkv support.

[Tophness]

I got why you were adding mkv support, but I don't understand the point of the embedding images into the mp4. Unless I'm missing something?

As you know you can apply the generation settings from a previously generated video by dragging it to the UI. With this feature it is now possible to repeat/tweak a previous generation for i2v as well, because the image can be stored with the video and not only the settings metadata. So when you now drag a video to the UI not only will the settings and seed of the previous video be restored but also the image(s) used for the i2v generation.

Oh that's actually pretty useful. I was trying to do something like that a while back but dismissed doing it in metadata because I assumed cover art would be pretty low res and base64 would take up space

[Gunther-Schulz]

Oh that's actually pretty useful. I was trying to do something like that a while back but dismissed doing it in metadata because I assumed cover art would be pretty low res and base64 would take up space

yea turns out there is no quality loss and i tried attaching up to 16kx16kx images and even that works

[deepbeepmeep]

Thanx, this is a useful feature ! As few obsevations:

• please put as much new code in new external files (even if it means moving existing code with it), the wgp.py is already way too big and I am trying to slim it down.
• mkv support will require further testing : I am not sure mkv can contain all the output video codec that a user can choose. Also it shouldnt break the demux audio / remux audio when reusing audio tracks in the generate_video() function

[Tophness]

wgp.py is already way too big and I am trying to slim it down.

I was thinking about this the other day. Since we've split tabs into their own functions, we could always have them in separate modules. It would've been a bit annoying before, but at >500kb, that would probably just be more manageable. I've dumped a lot of random functions in there for the queue too, we can make those utility modules or something. It's much easier to do that and not trip something with the html-based queue.
Happy to do this myself, but lmk how you want to structure it if you wanted something different, and I guess I should wait till all these latest PRs have been merged 1st

[Gunther-Schulz]

Thanx, this is a useful feature ! As few obsevations:

• please put as much new code in new external files (even if it means moving existing code with it), the wgp.py is already way too big and I am trying to slim it down.
• mkv support will require further testing : I am not sure mkv can contain all the output video codec that a user can choose. Also it shouldnt break the demux audio / remux audio when reusing audio tracks in the generate_video() function

Yes, I have realized that wgp.py needs a refactor ;) I will refactor out my portion no problem.
I disabled (user-facing) mkv already and good pointer that codec support needs to be tested.

[Gunther-Schulz]

refactor done, ready to merge

[deepbeepmeep]

Many thanks for your work. I havent merged it directly as it seems the AI created a couple useless stuff (and missed some bugs) but it is now the v9 branch ! Congrats