Wan2.1-UMT5插件开发入门：为WebUI添加自定义视频后处理功能-编程阁

Wan2.1-UMT5插件开发入门：为WebUI添加自定义视频后处理功能

你是不是也觉得Wan2.1-UMT5的WebUI功能很强大，但偶尔会想：“要是能在这里直接给生成的视频加个水印，或者统一加个片头片尾就好了”？其实，这个想法完全可以实现，而且比你想象的要简单。

今天，我们就来聊聊怎么给这个WebUI“添砖加瓦”，开发一个属于你自己的插件。不需要你从零开始研究整个系统，只需要一点Python基础，跟着步骤走，你就能让WebUI多出一个实用的视频后处理功能。整个过程，就像给乐高玩具加装一个新模块，既有趣又有成就感。

1. 开始之前：你需要准备什么

在动手敲代码之前，我们先看看需要哪些“装备”。放心，大部分东西你可能已经有了。

首先，你得有一个已经能正常运行的Wan2.1-UMT5 WebUI环境。如果你还没部署好，可以先去它的项目主页看看部署指南。这里假设你已经能通过浏览器访问那个熟悉的界面，并且能正常生成视频了。

其次，你需要一点Python基础。不需要你是专家，但至少得知道怎么定义函数、使用类、导入模块，以及处理像字典、列表这样的基本数据结构。如果你写过一些简单的脚本，那就完全没问题。

开发工具方面，任何你顺手的代码编辑器都可以，比如VS Code、PyCharm，甚至记事本也行。关键是要有一个能让你舒服写代码的环境。

最后，也是最重要的一点：保持好奇心。插件开发本质上是在理解现有框架的基础上进行扩展，所以过程中你可能会需要查看WebUI本身的源代码。别怕，这就像是在看一份已经写好的说明书，目的是弄明白它哪里留了“接口”给我们用。

2. 理解WebUI的插件架构：它怎么工作的？

在造轮子之前，我们先看看车子是怎么跑的。Wan2.1-UMT5的WebUI采用了一种模块化的插件架构，这让扩展功能变得非常清晰。

简单来说，WebUI在启动时会主动去一个特定的目录（通常是extensions文件夹）里“寻找”插件。它会检查每个子文件夹，如果里面有一个符合要求的Python文件（比如script.py），就把它加载进来，并执行里面定义好的“挂钩”函数。

这些“挂钩”函数，就是插件和主程序对话的窗口。主程序会在不同的时机（比如界面加载时、用户点击生成按钮后）调用这些挂钩，我们的插件代码就在这些时机里被执行。

一个典型的插件结构长这样：

your_custom_plugin/ ├── script.py # 插件的核心代码，必须的文件 ├── requirements.txt # （可选）声明插件依赖的Python包 └── README.md # （可选）插件的说明文档

script.py是插件的灵魂。在这个文件里，我们主要通过几个关键函数来与WebUI交互：

ui()函数：负责在WebUI的界面上添加我们自己的控制组件，比如滑块、输入框、复选框。用户通过这里和我们插件互动。
处理函数：这不是一个固定名字的函数，而是我们定义的一个或多个函数，用来实现核心逻辑（比如给视频加水印）。它会被ui()函数里创建的组件所触发。
其他可选挂钩：例如，如果插件需要在WebUI启动时就做一些初始化工作，可以使用before_ui()函数。

理解了这个流程，我们就可以开始动手了。我们的目标是：在视频生成完成后，自动为其添加一个文字水印。

3. 第一步：创建插件的基本骨架

让我们从创建一个最简单的插件目录开始。在你的WebUI根目录下，找到或创建一个名为extensions的文件夹。然后，在里面新建一个文件夹，名字就是你的插件名，比如video_watermarker。

接下来，在video_watermarker文件夹里，创建最重要的script.py文件。我们先写一个最基础的版本，它什么都不做，只是证明自己能被加载。

# script.py - 插件骨架 import modules.scripts as scripts from modules import script_callbacks import gradio as gr class Script(scripts.Script): # 插件标题，会在WebUI的插件列表里显示 def title(self): return “视频水印工具” # 插件展示的位置，返回一个列表 # 通常我们让它显示在主要生成区域 def show(self, is_img2img): return scripts.AlwaysVisible # 最重要的部分：创建UI组件 def ui(self, is_img2img): with gr.Accordion(“视频后处理 - 添加水印”, open=False): enabled = gr.Checkbox(label=“启用水印”, value=False) watermark_text = gr.Textbox(label=“水印文字”, placeholder=“例如：© My Studio 2024”) position = gr.Dropdown(label=“水印位置”, choices=[“左上角”, “右上角”, “左下角”, “右下角”, “居中”], value=“右下角”) font_size = gr.Slider(label=“字体大小”, minimum=10, maximum=100, value=24, step=1) # 将我们创建的UI组件返回，这样它们的状态才能被主程序记录 return [enabled, watermark_text, position, font_size] # 处理函数：这里先留空，下一步实现 def process(self, p, enabled, watermark_text, position, font_size): # p 是主程序传递过来的处理对象，包含了本次生成的所有参数和上下文 # 后面的参数对应 ui() 函数返回的组件列表 if not enabled: # 如果用户没启用插件，直接返回，什么都不做 return # 水印逻辑将在这里实现 print(f“水印插件被调用，参数：{watermark_text}, {position}”) # 暂时只是打印信息，证明插件被正确调用了

保存这个文件。现在，重启你的WebUI。如果一切正常，在WebUI的界面里（可能在某个选项卡或折叠面板里），你应该能看到一个名为“视频后处理 - 添加水印”的区域，里面有我们刚刚定义的复选框、输入框、下拉菜单和滑块。

虽然现在点击生成视频，插件还不会真的加水印（只会在控制台打印一行字），但我们已经成功迈出了第一步：创建了一个能被WebUI识别和加载的插件界面。

4. 第二步：实现核心后处理逻辑

现在我们来填上最关键的“坑”：如何给视频加上水印。这里我们需要用到视频处理库。Python里最常用的是opencv-python（也就是cv2）和moviepy。为了简单起见，我们这里用moviepy，因为它对视频、音频、文字的处理API更友好。

首先，确保你的环境里安装了moviepy。如果没有，可以在插件目录下创建一个requirements.txt文件，里面写上moviepy，WebUI可能会在加载时自动安装。或者你也可以手动在终端运行pip install moviepy。

让我们修改script.py中的process函数，加入实际的水印逻辑。

# script.py - 完善process函数 import modules.scripts as scripts from modules import script_callbacks import gradio as gr import os import tempfile # 注意：moviepy.editor导入可能较慢，放在函数内部按需导入是更好的实践 # from moviepy.editor import VideoFileClip, TextClip, CompositeVideoClip class Script(scripts.Script): # ... title(), show(), ui() 函数保持不变 ... def process(self, p, enabled, watermark_text, position, font_size): if not enabled or not watermark_text: # 如果未启用或水印文字为空，直接返回 return # 延迟导入，避免影响WebUI启动速度 try: from moviepy.editor import VideoFileClip, TextClip, CompositeVideoClip except ImportError: print(“错误：未找到moviepy库，请运行 ‘pip install moviepy’ 进行安装。”) return # 假设主程序将生成的视频文件路径放在 p 对象的某个属性中 # 实际情况中，你需要根据Wan2.1-UMT5的具体实现来获取视频路径 # 这里是一个示例逻辑，你需要适配： # 1. 如何获取本次生成输出的视频文件路径？ # 2. 处理完成后，如何替换或通知主程序使用新文件？ print(“[水印插件] 开始处理视频...”) # 示例：假设我们通过某种方式知道了输出视频的路径 # 这通常需要研究主程序的源代码，找到视频保存的变量或钩子 # 这里我们用一个伪代码表示： # original_video_path = p.output_video_path # 这行需要你根据实际情况修改 # 由于直接获取路径可能复杂，另一种思路是使用回调（callback） # 我们稍后在第五步讨论更优雅的集成方式。 # --- 以下是假设我们已经获得视频路径后的处理逻辑 --- # 我们创建一个临时函数来演示水印添加过程 def add_watermark_to_video(input_path, output_path): # 加载视频 video = VideoFileClip(input_path) # 创建文字水印 txt_clip = (TextClip(watermark_text, fontsize=font_size, color=‘white’) .set_duration(video.duration) .set_opacity(0.7)) # 设置透明度 # 根据选择的位置放置水印 video_w, video_h = video.size txt_w, txt_h = txt_clip.size margin = 10 # 边距 position_map = { “左上角”: (margin, margin), “右上角”: (video_w - txt_w - margin, margin), “左下角”: (margin, video_h - txt_h - margin), “右下角”: (video_w - txt_w - margin, video_h - txt_h - margin), “居中”: ((video_w - txt_w) // 2, (video_h - txt_h) // 2) } pos = position_map.get(position, position_map[“右下角”]) txt_clip = txt_clip.set_position(pos) # 将文字水印合成到视频上 final_video = CompositeVideoClip([video, txt_clip]) # 输出到文件 final_video.write_videofile(output_path, codec=‘libx264’, audio_codec=‘aac’) # 释放资源 video.close() final_video.close() print(f“[水印插件] 演示逻辑：将为视频添加水印 ‘{watermark_text}’ 到 {position}”) # 注意：此时 original_video_path 并未真正定义，以上函数暂未执行。 # 真正的调用需要在获取真实视频路径后。

上面的代码展示了核心的水印添加算法，但留下了一个关键问题：我们的插件如何拿到WebUI刚刚生成的那个视频文件？

5. 第三步：寻找“挂钩点”并优雅集成

直接去主程序的变量里“硬掏”路径不是好办法，而且容易因为版本更新而失效。更稳健的方式是利用WebUI框架提供的回调函数或事件钩子。

我们需要研究Wan2.1-UMT5的源代码，特别是视频生成完成后的那个时间点，看看它是否暴露了相应的回调接口。例如，常见的钩子名可能是on_video_processed、postprocess_video，或者在生成管道结束的某个阶段。

假设我们经过研究，发现可以通过script_callbacks模块注册一个在视频保存后被调用的函数。那么我们的集成方式将变得非常清晰。

# script.py - 使用回调进行集成 import modules.scripts as scripts from modules import script_callbacks import gradio as gr import os # 在类外部定义回调函数 def on_video_saved(video_path, p, enabled, watermark_text, position, font_size): """当视频被保存时，这个函数会被调用""" if not enabled or not watermark_text: return video_path # 不做处理，返回原路径 print(f“[水印插件] 检测到视频已保存: {video_path}”) # 现在我们有真实的视频路径了！ # 准备输出路径：在原文件名基础上加后缀 dir_name = os.path.dirname(video_path) base_name, ext = os.path.splitext(os.path.basename(video_path)) output_path = os.path.join(dir_name, f“{base_name}_watermarked{ext}”) try: from moviepy.editor import VideoFileClip, TextClip, CompositeVideoClip # 调用我们之前写好的水印函数 (需要稍作调整，使其接受参数) # 这里直接写处理逻辑... video = VideoFileClip(video_path) txt_clip = (TextClip(watermark_text, fontsize=font_size, color=‘white’, font=‘Arial’) .set_duration(video.duration) .set_opacity(0.7)) video_w, video_h = video.size txt_w, txt_h = txt_clip.size margin = 10 position_map = { ... } # 同上 pos = position_map.get(position, position_map[“右下角”]) txt_clip = txt_clip.set_position(pos) final_video = CompositeVideoClip([video, txt_clip]) final_video.write_videofile(output_path, codec=‘libx264’, audio_codec=‘aac’, verbose=False, logger=None) video.close() final_video.close() print(f“[水印插件] 水印视频已保存至: {output_path}”) # 返回处理后的新路径，这样其他流程可能会使用它 return output_path except Exception as e: print(f“[水印插件] 处理失败: {e}”) return video_path # 出错则返回原路径 class Script(scripts.Script): # ... title(), show() 保持不变 ... def ui(self, is_img2img): with gr.Accordion(“视频后处理 - 添加水印”, open=False): enabled = gr.Checkbox(label=“启用水印”, value=False) watermark_text = gr.Textbox(label=“水印文字”, placeholder=“例如：© My Studio 2024”) position = gr.Dropdown(label=“水印位置”, choices=[“左上角”, “右上角”, “左下角”, “右下角”, “居中”], value=“右下角”) font_size = gr.Slider(label=“字体大小”, minimum=10, maximum=100, value=24, step=1) self.infotext_fields = [(enabled, “video_watermark_enabled”), (watermark_text, “video_watermark_text”), (position, “video_watermark_position”), (font_size, “video_watermark_font_size”)] return [enabled, watermark_text, position, font_size] def process(self, p, enabled, watermark_text, position, font_size): # 这个函数在生成开始前被调用，我们可以在这里注册回调，并把参数传递过去 # 我们需要把插件的参数“绑定”到即将发生的视频保存事件上 # 一种方法是将参数存储在 p 对象中，供回调函数读取 if enabled and watermark_text: # 标记需要处理 p.watermark_params = { “enabled”: enabled, “text”: watermark_text, “position”: position, “font_size”: font_size } # 查找并注册回调（这里需要根据实际框架调整） # 例如：script_callbacks.register_video_postprocess_callback(my_callback) else: p.watermark_params = None

关键点：你需要仔细查阅Wan2.1-UMT5 WebUI的开发者文档或源代码，找到正确的回调注册方法。可能是script_callbacks.on_before_image_saved、script_callbacks.on_image_saved的变体，或者一个专门用于视频的钩子。将我们的on_video_saved函数注册进去，并确保它能接收到必要的参数（视频路径和我们的水印设置）。