企业官网建设流程全解析

• 桌面应用
• 音视频
• 视频处理

FFmpegFreeUI（简称 3FUI）是运行在 Windows 上的 FFmpeg 专业交互外壳，面向懂基本参数的进阶编码人员，定位为"一整套可扩展平台"而非一键全自动软件。本文围绕仓库根目录的 README.md 展开，覆盖 3FUI 的设计定位与部署前提、启动参数与远程调用（含源码级实现细节）、插件开发协议与编码队列事件，以及 Agent 智能体的自定义模型配置；读完后你可以直接掌握 3FUI 的外壳集成能力与全部可外部配置的入口。

一、项目定位：只调用 FFmpeg，不内置任何编解码器

3FUI 与 HandBrake、ShanaEncoder、ShutterEncoder 属于同一桌的常规专业级压制转换软件，但它与这些产品的关键区别在于：3FUI 只使用 ffmpeg 来执行任务，没有内置任何编解码器。用户需要手动放置 ffmpeg 或将其添加到环境变量。从源码结构看，这使 3FUI 的参数体系不必随 ffmpeg 更新而频繁变动——ffmpeg 更新后直接替换即可使用，性能始终跟随 ffmpeg 本身的最新水平。

核心运行规格如下（来自 README 与工程配置）：

3FUI 专为国内环境设计，语言只有简体中文，不计划多语言功能。主要特点包括：全自由转码与任意自写参数、底层逻辑基于预设方便分享方案、多数界面直接标出参数名、实时计算剩余时间与预估最终大小且可暂停任务、专为批量处理设计且无任务数量限制、不会擅自向输出文件写入软件信息、不碰注册表、不收集任何信息，以及完整的色彩管理、大量烧字幕选项、对 AviSynth/VapourSynth 的便捷调用、简易混流与合并、性能监控（基于 LibreHardwareMonitorLib）、ffprobe/ffplay 调用、质量评测、外部/远程调用和插件支持。

概念基础：封装格式 ≠ 编码格式

这是使用 3FUI 前必须澄清的广泛误区：mp4 是封装格式而不是编码格式，不存在"mp4 这种编码"。x264 才是编码格式，严格来讲 AVC/H.264 是实现标准，libx264 是 CPU 编码器，mp4 只是外面的壳，其内部可以塞 x264、x265、av1 等主流编码；而 mkv 所支持的编码最为广泛。

关于硬件编解码规格，README 给出了几点关键结论（NVIDIA 规格以其官方 GPU 支持矩阵为准，Intel QSV 与 AMD AMF 见各自官方文档）：

• NVIDIA：编解码核心只有代数和个数的差距，没有"规模差距"。单任务场景下高端卡并不比同代低端卡快（README 原文以 3090/3060、5090/5050 类比），且 ffmpeg 无法在一个任务中正确调用多个编解码核心。若只为编解码买 N 卡，买当代最低型号即可。
• 游戏卡并发限制：游戏卡对同时调用的数量有限制，一般是 8 个（约可同时启动 8 个调用 N 卡编码的 ffmpeg 进程），专业卡没有此限制。

二、外部调用：与 FFmpeg 一致的启动参数

3FUI 具有和 FFmpeg 一样的参数调用方式：可以在终端中启动、在外部程序中传递，也可以用快捷方式测试。README 说明这些功能在原理上走的是插件功能（需要 5.0 及以上版本）。

规则要点（README 原文）：

• -i和-3fui_file必须一起用，表示"使用指定预设文件对指定媒体文件进行任务"；预设文件可以直接指定为 Preset 文件夹（即方案管理）中的预设名称。
• -ffmpeg是纯命令模式，后面的所有内容都会给 ffmpeg；既可传入参数列表，也可传入以ffmpeg、ffmpeg.exe或其完整路径开头的完整 FFmpeg 命令行，程序会自动忽略其中的可执行文件部分。
• 另外可用-3fuiVideoHelperInPointTime和-3fuiVideoHelperOutPointTime传递剪辑区间参数。

源码实现：参数解析与预设解析

参数处理集中在 启动参数响应_v6.vb。从源码可以看到几个 README 未展开的实现细节：

1. 预设解析优先级（解析预设文件路径）：传入值若不是完整路径，程序会补.json后缀后依次在"用户自定义""从社区下载"预设目录和旧版Preset目录中查找；查不到文件时还会尝试按名称匹配开发者内置预设（见 读取预设数据）。
2. -ffmpeg的引号与转义处理：处理FFmpeg参数 对完整命令行再次做 命令行拆分（支持引号与反斜杠转义），并把含空格或引号的参数按 WindowsProcessStartInfo.Arguments规则重新加引号，避免带空格路径在任务队列执行 ffmpeg 时被截断。
3. 剪辑区间行为：-i+-3fui_file同时给出入点/出点时，会覆盖预设中的剪辑区间并采用"粗剪"方法（见 添加预设任务）；若只给了区间参数而没有输入+预设，则把区间直接写入当前参数面板的剪辑区间控件。
4. -test直接弹出"哔哔"消息框，适合验证快捷方式传参是否成功；fullscreen则在 ApplicationEvents.vb 中检测命令行包含fullscreen时生效。

三、远程调用：UDP 端口监听，把 3FUI 变成局域网编码节点

在设置中打开"远程调用"后，3FUI 监听指定端口，收到消息即开始任务；消息数据内容与启动参数完全一致。这意味着 3FUI 可以部署在局域网中作为编码机，从局域网任意电脑通过其他程序发任务给它——只要 3FUI 能访问文件即可，远程访问同样成立（需要 5.0 及以上版本）。

注意：发起程序必须使用 UDP 协议发送，默认端口 10591。

源码实现位于 端口监听_v6.vb，几个可验证的细节：

• 默认端口定义在 设置_v6.vb：Public Property 监听的端口 As String = "10591"，设置页 Form_v6_设置_远程调用.vb 修改后调用设置远程监听/设置远程监听端口生效。
• 端口规范化 规则：解析失败、端口为 10590（被改写为 10591）、或超出 1–65535 范围时，一律回退到 10591。
• 监听循环用UdpClient接收消息（1 秒接收超时），把 UTF-8 文本切回 UI 线程后交给 启动参数响应_v6.处理接收的参数 解析——也就是说远程消息与启动参数走的是同一套解析器，README 中"消息数据内容与启动参数是一样的"在代码层面成立。
• 启动失败会弹窗提示并把监听开关复位（见 启动客户端）。

四、插件开发：反射加载 + 委托通信的宿主协议

插件通过反射加载，不需要引用 3FUI，只通过一组HostCall_委托与宿主通信。开发时创建一个 .NET 10 Windows 窗体（或 WPF）项目，并在程序集的Entry类中提供共享/静态的Entry方法：

Public Class Entry Public Shared Sub Entry() '初始化、注册界面和队列事件 End Sub End Class

public class Entry { public static void Entry() { // 初始化、注册界面和队列事件 } }

4.1 添加界面（WinForms / WPF 面板）

Public Shared Property HostCall_AddCustomWinformPanel As Action(Of String, Control) Public Shared Sub SetHost_AddCustomWinformPanel(action As Object) HostCall_AddCustomWinformPanel = CType(action, Action(Of String, Control)) End Sub Public Shared Property HostCall_AddCustomWpfPanel As Action(Of String, UIElement) Public Shared Sub SetHost_AddCustomWpfPanel(action As Object) HostCall_AddCustomWpfPanel = CType(action, Action(Of String, UIElement)) End Sub '调用示例 HostCall_AddCustomWinformPanel?.Invoke("我的插件", New MyUserControl()) 'WPF 使用：HostCall_AddCustomWpfPanel?.Invoke("我的插件", New MyWpfControl())

public static Action<string, Control> HostCall_AddCustomWinformPanel { get; set; } public static void SetHost_AddCustomWinformPanel(object action) => HostCall_AddCustomWinformPanel = (Action<string, Control>)action; public static Action<string, UIElement> HostCall_AddCustomWpfPanel { get; set; } public static void SetHost_AddCustomWpfPanel(object action) => HostCall_AddCustomWpfPanel = (Action<string, UIElement>)action; //调用示例 HostCall_AddCustomWinformPanel?.Invoke("我的插件", new MyUserControl());

宿主侧的实现见 插件管理.vb：WinForms 控件直接挂为主窗体的插件选项卡；WPF 的UIElement会被包进Integration.ElementHost再挂入，因此插件可以同时使用两种技术栈。

4.2 添加编码任务

Public Shared Property HostCall_AddMissionToQueueWithArgs As Action(Of String, String, String, String) Public Shared Sub SetHost_AddMissionToQueueWithArgs(action As Object) HostCall_AddMissionToQueueWithArgs = CType(action, Action(Of String, String, String, String)) End Sub Public Shared Property HostCall_AddMissionToQueueWith3fuiFile As Action(Of String, String, String, String) Public Shared Sub SetHost_AddMissionToQueueWith3fuiFile(action As Object) HostCall_AddMissionToQueueWith3fuiFile = CType(action, Action(Of String, String, String, String)) End Sub '参数依次为：ffmpeg 参数（不要以 ffmpeg 开头）、显示名称、输出路径、输入路径（可空） HostCall_AddMissionToQueueWithArgs?.Invoke(args, name, output, input) HostCall_AddMissionToQueueWith3fuiFile?.Invoke(presetPath, name, output, input)

public static Action<string, string, string, string> HostCall_AddMissionToQueueWithArgs { get; set; } public static void SetHost_AddMissionToQueueWithArgs(object action) => HostCall_AddMissionToQueueWithArgs = (Action<string, string, string, string>)action; public static Action<string, string, string, string> HostCall_AddMissionToQueueWith3fuiFile { get; set; } public static void SetHost_AddMissionToQueueWith3fuiFile(object action) => HostCall_AddMissionToQueueWith3fuiFile = (Action<string, string, string, string>)action; HostCall_AddMissionToQueueWithArgs?.Invoke(args, name, output, input); HostCall_AddMissionToQueueWith3fuiFile?.Invoke(presetPath, name, output, input);

宿主侧对应 使用命令行添加任务到编码队列 与 使用预设文件添加任务到编码队列；预设文件路径的解析直接复用了启动参数那套读取预设数据，所以插件里传预设名/路径的行为与-3fui_file一致。

4.3 编码队列事件（6.1.28 起）

插件实现SetHost_SubscribeQueueEvents，注册器类型是Action(Of String, Object)（C# 为Action<string, object>）。调用注册器时第一个参数是事件筛选器，第二个参数必须是Action(Of String, String)（C# 为Action<string, string>）回调；回调收到的第一个参数是事件名，第二个参数是 JSON 字符串。

Public Shared Property HostCall_SubscribeQueueEvents As Action(Of String, Object) Public Shared Sub SetHost_SubscribeQueueEvents(action As Object) HostCall_SubscribeQueueEvents = CType(action, Action(Of String, Object)) End Sub Public Shared Sub Entry() HostCall_SubscribeQueueEvents?.Invoke("*", AddressOf OnQueueEvent) '也可以只订阅一个事件：HostCall_SubscribeQueueEvents?.Invoke("task.completed", AddressOf OnQueueEvent) End Sub Private Shared Sub OnQueueEvent(eventName As String, json As String) '按需反序列化 json；不要在这里阻塞编码线程 Dim data = System.Text.Json.JsonDocument.Parse(json) Dim taskId = data.RootElement.GetProperty("task").GetProperty("id").GetString() End Sub

public static Action<string, object> HostCall_SubscribeQueueEvents { get; set; } public static void SetHost_SubscribeQueueEvents(object action) => HostCall_SubscribeQueueEvents = (Action<string, object>)action; public static void Entry() { HostCall_SubscribeQueueEvents?.Invoke("*", OnQueueEvent); //只订阅完成事件：HostCall_SubscribeQueueEvents?.Invoke("task.completed", OnQueueEvent); } private static void OnQueueEvent(string eventName, string json) { using var data = System.Text.Json.JsonDocument.Parse(json); var taskId = data.RootElement.GetProperty("task").GetProperty("id").GetString(); }

注意事项（README 与源码一致）：

• 回调可能来自后台线程，插件应自行切回 UI 线程；回调中的异常会被宿主隔离，不会中断编码队列——见 注册编码队列事件 中的逐回调Try/Catch与"插件回调异常不得影响编码队列"注释。
• 筛选器支持*与事件名精确匹配（不区分大小写），空筛选器等价于全部。

支持的事件名：

事件 JSON 的主要字段为eventName、timestamp、task和log。task包含id、name、inputPath、outputPath、status、statusCode、progress、progressText、currentStage、realtimeOutput和nonProgressOutput；task.log/task.progress额外提供log.sequence、log.time、log.text、log.category、log.categoryCode、log.isError与log.stage。事件序列化的字段结构可在 编码队列事件处理 中逐字段核对；task.log与task.progress的分流在 编码任务_v6.vb 中触发。进度日志经过宿主节流，普通日志不会触发task.progress，因此可按需选择低频的task.log或完整的task.progress。

4.4 媒体流选择器

参数依次为：文件路径、视频/音频/字幕结果目标对象、输入文件索引，以及三个已选流索引字符串。目标对象需要提供Text属性；所有参数均可传Nothing/null。

Public Shared Property HostCall_MediaStreamVisualSelector As Action(Of String, Object, Object, Object, String, String, String, String) Public Shared Sub SetHost_MediaStreamVisualSelector(action As Object) HostCall_MediaStreamVisualSelector = CType(action, Action(Of String, Object, Object, Object, String, String, String, String)) End Sub HostCall_MediaStreamVisualSelector?.Invoke(filePath, videoTarget, audioTarget, subtitleTarget, "0", "0", "0", "")

public static Action<string, object, object, object, string, string, string, string> HostCall_MediaStreamVisualSelector { get; set; } public static void SetHost_MediaStreamVisualSelector(object action) => HostCall_MediaStreamVisualSelector = (Action<string, object, object, object, string, string, string, string>)action; HostCall_MediaStreamVisualSelector?.Invoke(filePath, videoTarget, audioTarget, subtitleTarget, "0", "0", "0", "");

宿主侧会弹出 Form_v6_媒体流选择器 并把选中结果写回目标对象的Text属性（见 打开媒体流可视化选择器）。

4.5 插件的安装与发布、加载流程

生成项目后，将输出目录中与项目同名的.dll后缀改为.3fui.dll，放入 3FUI 程序目录的Plugin文件夹并重启（该文件夹可能需要手动创建）；插件依赖的其他程序集也要一起复制，但不要改它们的扩展名。

从 启动时加载插件 与 加载单个插件 可以看到加载协议的实际约束：

• 只扫描程序目录下Plugin/*.3fui.dll；
• 要求存在{程序集名}.Entry类，且其中有一个共享/静态的Entry方法（VB 用Shared，C# 用static），找不到会弹窗并跳过初始化；
• 宿主回调通过 注入宿主回调 按方法名（SetHost_AddCustomWinformPanel、SetHost_AddCustomWpfPanel、SetHost_AddMissionToQueueWithArgs、SetHost_AddMissionToQueueWith3fuiFile、SetHost_MediaStreamVisualSelector、SetHost_SubscribeQueueEvents）反射注入，因此插件无需引用 3FUI 的程序集即可通信；
• 单个插件加载失败只会弹窗提示，不会阻塞其他插件。

五、Agent 智能体：自定义模型、推理级别与上下文总量

3FUI Agent 是专属于 3FUI 的"副驾驶"：可接入任何兼容 OpenAI SDK 的端点来使用任何模型，能控制整个参数面板、协助管理任务，并具备联网能力、文件系统访问、读取文本文件和图片、使用 Windows PowerShell 终端的能力；对话支持中途切换模型，数据完全存于本地并与所有模型和端点共享，交互为纯本地渲染的流式展现，支持基础 Markdown 语法。

对于端点/models接口未返回的模型，或需要显式指定推理级别/上下文总量的场景，可手动创建并编辑Agent/CustomModels.json——3FUI 不会主动创建或覆盖这个文件；修改后在 Agent 页面点击"重载连接"即可重新读取。

{ "version": 1, "global": { "models": [ { "id": "global-custom-model", "reasoning_efforts": ["low", "medium", "high"], "context_window_tokens": 200000 } ] }, "endpoints": [ { "endpoint": "https://api.example.com/v1", "models": [ { "id": "endpoint-custom-model", "reasoning_efforts": ["none", "low", "medium", "high", "xhigh"], "context_window_tokens": 1000000 }, { "id": "model-with-default-efforts", "reasoning_efforts": [] } ] } ] }

字段与规则（README 与 Agent自定义模型配置_v6.vb 源码一致）：

• global.models应用到所有端点；endpoints中的配置只应用于endpoint与当前 Agent 端点地址一致的项目，比较时忽略地址末尾的/和大小写（见 端点匹配）。
• id是实际发送给接口的模型名称。
• 新增模型的reasoning_efforts可以省略或留空，此时使用 3FUI 的默认推理级别。
• context_window_tokens是该模型的上下文总量，单位为 token；省略或设为0时继续使用 3FUI 内置值，不能使用负数（源码中负数会直接抛出格式错误）。
• 自定义模型会与端点返回的模型合并并按id去重；同一模型在全局、指定端点或端点响应中重复出现时，推理级别合并去重，指定端点中大于0的上下文总量会覆盖同一模型的全局值（见 合并模型项）。
• 如果端点的/models接口不可用但当前配置提供了可用模型，Agent 会直接使用自定义模型列表；配置文件格式无效时不会影响端点原有模型，Agent 页面会显示对应提示。
• 源码中的额外约束：文件路径固定为程序目录下的Agent/CustomModels.json，version必须为1，文件大小上限 1 MB，JSON 解析允许注释与尾逗号（见 加载）。

补充一点源码级背景：3FUI 内置了一张推理级别能力表，在端点未显式返回能力时对已知模型追加额外的推理级别（当前规则为gpt前缀的模型额外支持xhigh），见 Agent推理级别能力表_v6.vb。因此reasoning_efforts中的xhigh并非只有自定义配置能给出，内置表同样会参与合并。

六、问题反馈的正确姿势

README 的"反馈渠道"一节给出了明确原则，这里同样值得强调：

• 3FUI 不针对"非正常操作"做预防，此类操作极易引发报错；故意卡 bug 造成的损失与开发者无关。
• 反馈问题请优先走 Q 群渠道（群号见 README 开头），不要在 B 站评论区汇报问题。
• 不要把错误信息发给"生活 AI"去算卦：ffmpeg 的输出并非所有情况都有具体原因，尤其是"功能未支持""参数不正确"这类情况，没有完整上下文时任何模型都难以猜准。
• 正确做法：把完整错误信息和命令行发给技术人员；不想暴露文件名可手动抹掉；如有条件，提供输入文件的详细参数（很多播放器可以查看）。

七、许可、引用与新手学习资源

• 3FUI 使用MIT开源许可（见 LICENSE.txt），可以自由使用和分发；README 声明仅在 GitHub 开源，其他平台的同源代码并非官方。
• 多语言需求可自行开仓库维护所有字符串，并在 MIT 许可范围内行使权利。

引用程序集及其许可证：

新手入门方面，README 建议先系统学习视频基础参数（分辨率、帧率、色深、色度采样、封装与编码的区别等），再学习 3FUI 专属教程；文中推荐了极客湾、影视飓风的科普视频以及终末诗的视频压缩教学与 3FUI v5/v6 入门教程（具体链接见 README 原文，随版本更新）。学习完基础概念后再使用 3FUI 的自由参数能力，能显著降低试错成本。

小结

3FUI v6 的技术面可以归纳为四条主线：其一，"纯 FFmpeg 外壳"的设计让它始终跟随 ffmpeg 的最新能力，代价是对使用者有基本参数要求；其二，与 FFmpeg 一致的启动参数加上 UDP 远程调用，使它既能作为命令行工作流的一环，也能作为局域网编码节点部署，两者共用同一套参数解析器；其三，插件协议以反射 + 委托实现，覆盖自定义界面、任务注入、队列事件订阅和媒体流选择四类宿主能力，且宿主对插件异常做了隔离；其四，Agent 智能体通过本地CustomModels.json提供了模型级的推理级别与上下文总量控制入口。以上所有行为均可在 FFmpegFreeUI/功能/ 目录下的对应源码文件中逐条核对。

• 桌面应用
• 音视频
• 视频处理