为什么需要 ffmpeg-webCLI？
在内容创作、短视频剪辑、隐私敏感场景中，传统视频处理面临三大痛点：必须上传云端（隐私泄露风险）、依赖在线服务（网络不稳定、费用）、功能碎片化（不同工具切换麻烦）。
ffmpeg-webCLI（GitHub: tejaswigowda/ffmpeg-webCLI）完美解决这些问题。100% 浏览器端、本地处理、无任何数据上传的#视频编辑器，底层基于 ffmpeg.wasm（FFmpeg 的 WebAssembly 移植）。所有操作在用户设备内存中完成，支持 30+ 种实用功能，并以 Progressive Web App (PWA)形式提供离线体验和屏幕唤醒锁。
项目亮点：
●零服务器依赖，隐私至上
●离线优先 PWA（首次加载 ffmpeg.wasm 后完全离线）
●实时预览 + 输出大小估算
●Web Worker 后台处理，UI 始终响应
●支持 MP4/WebM/MKV/MOV/AVI/GIF + 多种音频/图片格式
●高级合成：拼接、画中画、Logo 水印、音频混音、字幕嵌入、Raw FFmpeg 命令行
●屏幕唤醒锁（长处理不息屏）
●GPL-3.0 开源，可自由研究、修改、分发
本文覆盖所有功能点、高效实用用法、完整安装/源码运行方法、技术原理与架构实现**（含 worker.js 关键代码逻辑、COI 机制、Emscripten FS、命令构建等），提供可直接落地的深度指南。
一、完整功能
项目 UI 通过可点击的 Operation Tiles（4 列网格）切换不同面板，所有操作共享全局 Trim 控件（开始/结束滑块，自动填充视频时长）。Trim 应用于大多数操作（Loop 除外）。处理后输出可预览并下载为 Blob。
1. 基础转换与压缩类
●Convert Format：一键转 MP4 (H.264+AAC)、WebM (VP9+Opus，约小 45%)、MKV、MOV、AVI。底层用对应 -c:v/ -c:a+ 容器。
●Resize & Compress：同时缩放 + 压缩。宽度/高度自动填充源分辨率，支持保持宽高比；CRF 滑块 (18 近无损 ~ 51 极致压缩) + preset (ultrafast ~ veryslow) 实时更新大小估算。结合 scalefilter + H.264 编码。
●Pad / Letterbox：添加黑/白/灰色边框适配目标比例（16:9、9:16、1:1、4:3、4:5、21:9）。视频等比缩放居中填充，不裁剪不拉伸。Re-encode H.264/AAC。
●Strip Metadata：-map_metadata -1彻底移除 GPS、相机型号、时间戳等元数据。
2. 剪辑与时长控制类
●Trim（全局）：任意操作前设置起止点，-ss+ -t实现精确裁剪。
●Speed Change(0.25× ~ 4×)：同时调整视频 PTS 和音频 atempo链（超出 0.5-2.0 范围自动多级 atempo），音调与同步保留。
●Reverse：reverse+ areverse实现视频+音频倒放。
●Fade In/Out：独立设置淡入/淡出时长（秒），filter 链在 trim 之后应用。
●Boomerang：前向 + 立即反向拼接成循环。使用 concat+ reverse，音频移除（反向音频通常无意义）。
●Loop / Repeat(2~50 次)：-stream_loop+ stream copy，无重编码，输出文件按倍数增大（Trim 不生效）。
3. 视觉调整与特效类
●Rotate / Flip：90° CW/CCW、180°、水平/垂直/双向翻转。
●Crop：X/Y 偏移 + 宽高，自动预填源尺寸，支持精确区域裁剪。
●Adjust (Brightness/Contrast/Saturation)：eqfilter，三滑块 + Grayscale 复选框（饱和度归零）。
●Denoise：hqdn3d(高品质 3D 降噪)，Light/Medium/Heavy 预设（参数 2:2:3:3 ~ 10:10:15:15）。适合低光/噪点素材。
●Sharpen / Blur：unsharp(轻/中/重 mask 参数) 或 boxblur。视频重编码，音频 copy。
●Thumbnail Extractor：指定时间戳提取单帧为 JPG/PNG（默认视频中点）。
4. 音频处理类
●Extract Audio：输出 MP3/AAC/WAV/OGG/FLAC。-vn剥离视频。
●Mute Video：移除音频流（保留视频）。
●Volume：0~4× 倍增，volumefilter，视频 stream copy（快速无损）。
●Normalize Audio：loudnorm(EBU R128)，目标 -14 LUFS (YouTube/Spotify)、-16 (播客)、-23 (广播)。视频 copy，音频处理。
●Mix Audio (Background Music)：第二音频文件（MP3/WAV 等）混入。原音频音量 + 音乐音量滑块 (0-2)。音乐短于视频时自动 -stream_loop -1，amixfilter (duration=first)。
5. 合成与高级类
●To GIF：双通道调色板生成 (palettegen + paletteuse)，设置 FPS + 宽度（高度自动保持比例），最佳色彩质量。
●Embed Subtitles：上传 .srt/.vtt/.ass，软字幕嵌入（MP4 用 mov_text，MKV 原生 copy）。视频/音频 stream copy，零画质损失。硬烧录需 libass 支持，标准 wasm 构建暂不支持。
●Logo / Image Overlay：PNG/JPG/GIF/WebP 水印，位置（四角+中心）+ 宽度百分比缩放。overlay+ scalepre-pass，视频重编码，音频 copy。
●Concatenate (Join Clips)：第二视频追加到主视频后。concatfilter 自动处理不同分辨率/帧率/编码，H.264/AAC 重编码（Trim 只作用主视频）。
●Side by Side：水平 (hstack) 或垂直 (vstack) 并排。目标公共尺寸 + 音频来源选择（主/次/无）。重编码。
●Picture in Picture：第二视频作为小窗叠加（位置+宽度%）。短视频自动循环，Trim 作用主视频，音频保留主轨。重编码。
●Media Info：加载时浏览器 video 元素提取基础元数据（文件名、大小、时长、分辨率、码率、MIME）。点击 “Process Video” 执行 ffmpeg -hide_banner -i深度扫描，输出完整 codec/stream/pixel/container 信息到日志。
6. 终极灵活：Raw FFmpeg 模式
完整命令行访问！在文本区输入参数（插入 -i input之后、输出文件名之前）。支持：
●实时完整命令预览（正确处理带空格的引号值）
●可选 Bypass Trim
●第二输入文件选择器 → 写入虚拟 FS 为 input2.<ext>（Raw 示例库包含 “Replace audio track” 等需 input2 的场景）
●示例命令库（一键填充）：color-bar watermark、cap framerate、grayscale、loudnorm、lossless remux (-c copy)、letterbox、denoise (hqdn3d)、sharpen (unsharp)、stabilize (deshake)、vignette、extract audio WAV、extract first frame、replace audio 等。
几乎覆盖 #FFmpeg 所有能力。
功能覆盖总结：基础转换/压缩/剪辑/特效/音频/合成/自定义全具备，远超普通在线编辑器，且完全本地。
二、详细高效使用方法
标准工作流（UI 始终响应）：
1.访问页面 → 点击 Load ffmpeg（首次下载 ~31MB WASM，之后缓存）。
2.拖拽/选择视频文件 → 激活 Process 按钮，自动显示 Media Info。
3.（可选）拖动 Trim 滑块设置起止。
4.点击 Operation Tile → 对应面板出现，实时调整参数（多数触发 live size estimate 更新）。
5.点击 Process Video→ Web Worker 执行，进度条 + 日志实时更新，屏幕唤醒锁自动开启。
6.预览结果（视频/音频播放器或图片）→ Download。
高效技巧（基于项目实现）：
●组合操作：先 Trim + 任意 op 一次完成；处理后下载结果，再加载新文件继续（支持链式工作流）。
●性能优化：优先用 stream copy 的操作（Mute、Volume、Loop、部分 Mix/Concat 场景）速度极快且无损；重编码时选 ultrafast + 较高 CRF 快速预览；长视频用较低 preset 换更好压缩。
●GIF 质量：务必用内置 To GIF（双 pass 调色板），普通 convert 转 GIF 质量差。
●Raw 模式进阶：学习 filter_complex 实现复杂 graph；用 input2 实现音频替换、双视频处理；lossless remux (-c copy) 极快改容器。
●大小估算：实时更新帮助决策 CRF/preset/分辨率，避免试错。
●离线使用：首次在线加载 ffmpeg + 资源 → 安装 PWA → 完全离线处理（含缓存的 CDN ffmpeg 核心）。
●移动端：Chrome/Firefox/Samsung 良好；iOS Safari PWA 支持有限但可用。
●错误恢复：失败自动清理虚拟 FS，避免残留文件。
●最佳实践：大文件注意设备 RAM（WASM + 视频同时在内存）；用 Chrome/Edge 获得最佳 SharedArrayBuffer + pthread 性能。
三、安装方法与从源码运行
1. 在线最快使用（推荐新手）
直接访问 Live Demo → 浏览器安装为 PWA（地址栏 install 按钮或菜单）→ 离线可用。
2. 本地运行（推荐开发/自定义）
打开 http://127.0.0.1:5500
server.js 核心作用（源码 verbatim 分析）：Node http server，强制设置：
●Cross-Origin-Opener-Policy: same-origin
●Cross-Origin-Embedder-Policy: require-corp
●Cross-Origin-Resource-Policy: cross-origin（允许 CDN）
●智能 Cache-Control（service-worker/manifest 不缓存，JS/CSS 长期缓存等）
为什么必须这些 Header？ffmpeg.wasm 多线程版本依赖 SharedArrayBuffer，浏览器安全策略要求 Cross-Origin Isolation（COOP+COEP），否则 pthread 不可用，性能大幅下降。
3. 其他本地服务器方式
●npx serve docs（需手动配置相同 COOP/COEP headers）
●生产部署参考 vercel.json（项目已配置对应 headers）
●任何支持自定义响应的静态服务器均可
4. 从源码修改/构建
项目为纯静态前端（docs/ 目录即应用）：
●修改 docs/index.html（UI、命令构建逻辑）
●修改 docs/worker.js（ffmpeg 加载、FS、EXEC 桥接）
●修改 docs/service-worker.js/ manifest.json调整 PWA 缓存策略
●无需复杂构建工具，直接编辑后用 server.js serve 即可测试
●想贡献：Fork → 修改 → PR（GPL-3.0 要求修改后开源）
注意：README 中本地运行示例 clone URL 有笔误，应为 ffmpeg-webCLI而非 ffmpeg.wasm.editor。
四、技术原理与架构实现
核心技术栈
●ffmpeg.wasm：@ffmpeg/core@0.12.10 + @ffmpeg/ffmpeg@0.12.15 + @ffmpeg/util（pinned in service-worker cache）
●前端：原生 HTML/JS + Web Components 风格面板切换
●处理引擎：Web Worker（隔离重计算）
●文件系统：Emscripten FS（内存虚拟文件系统，input/output 全在 RAM）
●PWA：Service Worker + Manifest + Wake Lock API
关键架构组件详解
1. worker.js（处理核心，源码深度分析）
自定义 worker 解决跨域 worker + WASM 加载痛点：
●动态 import coreURL（绕过跨域 module worker 限制）
●预取 wasmBinary 为 ArrayBuffer→ 传给 createFFmpegCore({ wasmBinary, instantiateWasm: custom })
●custom instantiateWasm强制 WebAssembly.instantiate(new Uint8Array(wasmBinary)...)，彻底避免 Emscripten 内部 fetch/blob URL/range request 错误
●支持消息类型：LOAD / EXEC / FFPROBE / WRITE_FILE / READ_FILE / DELETE_FILE 等完整 FS 操作
●ffmpeg.setLogger/ setProgress→ postMessage 回主线程
●每次 EXEC 后 ffmpeg.reset()清理状态
这套加载机制是项目“可靠运行”的关键，远超 naive 的 ffmpeg.wasm 示例。
2. index.html 主逻辑
●响应式双栏布局（移动端折叠）
●Operation Tiles + 条件显示 panel-{mode}
●runProcess()大 switch(currentOp) 构建参数数组：
○全局 Trim → -ss-t
○多数 op 组合 -vf/ -affilter 链 + -c:v libx264 -preset ... -crf ...或 -c copy
○多输入场景额外 -i input2.xxx+ 对应 map/filter
●实时 size estimate（启发式或 probe）
●ffmpeg.writeFile()把用户文件写入虚拟 FS
●执行后 ffmpeg.readFile()取回 ArrayBuffer → Blob → 预览/下载
3. PWA 与离线（service-worker.js + manifest.json）
●三级缓存：STATIC_ASSETS（install 时预缓存）、RUNTIME_CACHE（network-first + fallback）、CDN_CACHE（cache-first jsDelivr @ffmpeg 资源）
●版本化 v3，便于更新
●特殊处理：JS 失败返回空模块避免 import 报错；导航请求 fallback index.html
●manifest：standalone display、深色主题、maskable icons、shortcuts
4. 跨源隔离 (COI) 机制
server.js + coi-serviceworker.js（fallback） + vercel.json 共同保障 SharedArrayBuffer 可用 → ffmpeg.wasm 能使用 pthread 加速部分 filter/编码。
5. 性能与限制
●优势：零网络延迟、隐私零泄露、Web Worker + pthread 高性能、stream copy 极致速度
●限制：受设备 RAM 约束（大视频+复杂 filter 可能 OOM）；标准 wasm 构建部分高级功能（如完整 libass 硬字幕）受限；iOS PWA 能力较弱
整个架构“浏览器即完整视频处理工作站”的设计哲学：通过 Web Worker + 定制 WASM 加载 + Emscripten FS + PWA 缓存，实现了接近原生 FFmpeg 的体验，同时保持极致隐私与离线能力。
ffmpeg-webCLI 是目前开源社区中功能最全面、实现最扎实的浏览器端 FFmpeg 视频编辑器之一。不仅提供了实用工具，更通过精心设计的 worker 加载机制、COI 支持、PWA 缓存策略，向开发者展示了如何在浏览器中可靠运行复杂原生工具链。
适用人群：
●隐私敏感的内容创作者（短视频、教学、内部素材）
●离线/低网络环境工作者
●想学习 FFmpeg filter + WebAssembly 的开发者
●需要快速原型或教育演示的场景
进阶建议：
●Fork 后扩展 Raw 模式示例库或增加新 filter 面板
●结合本地 MLX / 其他工具链打造完整创作 pipeline
●关注 ffmpeg.wasm 后续多线程与 SIMD 优化