FreeCut无头渲染管线用CLIDocker搭建免浏览器视频渲染服务【免费下载链接】freecutFreeCut is a professional-grade video editor that runs entirely in your browser. Professional video editing, zero installation. Create stunning videos with multi-track editing, keyframe animations, real-time preview, and high-quality exports.项目地址: https://gitcode.com/gh_mirrors/free/freecutFreeCut 是一款完全运行在浏览器里的专业视频剪辑工具而它的无头渲染管线Headless Render Pipeline让 FreeCut 视频渲染能力彻底脱离图形界面——通过 CLI 命令行或 Docker 容器你可以把项目 JSON 直接变成成片视频适合 CI 流水线、批量出片和服务器渲染。本文将带你快速搭建一个免浏览器的 FreeCut 视频渲染服务。为什么选择 FreeCut 无头渲染管线在浏览器剪辑工具里渲染通常要手动点击导出并守着进度条。但很多场景需要无人值守CI 自动化代码合入后自动渲染演示视频批量出片一份模板生成 100 个个性化视频服务器渲染GPU 渲染节点 7x24 出片快速抽帧不编码整段视频只取一帧预览图FreeCut 的无头管线正是为此设计用 Playwright 驱动一个预热的无头 Chrome在页面内调用与界面完全相同的真实渲染引擎WebGPU 合成 WebCodecs 编码并通过 HTTP API 对外提供渲染、抽帧、剪辑等能力。核心代码集中在 headless/ 目录几个关键模块如下模块作用headless/serve.mjsHTTP 渲染服务常驻进程1 个预热浏览器页面headless/render.mjs单任务/批量渲染 CLIheadless/frame.mjs单帧抽帧 CLI默认全分辨率 PNGheadless/edit.mjs纯编辑 CLI加文字、切分、转场不渲染headless/lib/render-core.mjs渲染核心启动 harness、准备任务、下载成片headless/lib/operation-queue.mjs操作队列串行化任务避免 GPU 争抢快速上手3 步启动渲染服务第 1 步克隆代码并安装依赖git clone https://gitcode.com/gh_mirrors/free/freecut cd freecut npm ci第 2 步构建渲染 harness无头模式通过headless.html这个驱动页调用页面内的渲染引擎需要先构建一次npm run build第 3 步启动服务并做健康检查FreeCut 工作区是纯文件夹结构项目位于projects/{项目ID}/project.json媒体位于media/{媒体ID}/布局逻辑见 headless/lib/workspace.mjs。启动时指定这个目录npm run headless:serve -- --workspace /path/to/FreeCutProjects服务默认监听127.0.0.1:8787出于安全考虑服务本身无鉴权默认只绑回环地址跨网络部署请用 Docker 并在外层加网关鉴权。用健康接口确认服务与 GPU 状态curl localhost:8787/health # - {ok:true,apiVersion:...,gpu:{...},software:false,harnessUrl:...}启动时会自动探测 WebGPU 适配器并打印型号如果是 lavapipe/SwiftShader 等软件适配器控制台会警告GPU 特效项目会被拒绝渲染可能产生空白/损坏帧这类项目请换带真实 GPU 的主机。Docker 一键容器化部署项目自带 headless/Dockerfile镜像预装了 Node 24、Google Chrome专有 H.264/AAC 解码器支持、Mesa lavapipe软件 Vulkan用于无 GPU 环境的 WebGPU 探测和中文字体。构建镜像构建上下文是仓库根目录docker build -f headless/Dockerfile -t freecut-headless .运行容器并挂载工作区/workspace需要可写用于锁文件与原子写入docker run --rm -p 8787:8787 \ -v /path/to/FreeCutProjects:/workspace \ freecut-headless验证curl localhost:8787/health # - {ok:true,gpu:true,...}GPU 加速在带 NVIDIA 显卡的 Linux 主机上加--gpus all -e NVIDIA_DRIVER_CAPABILITIESall即可让 WebGPU 走真实 GPU此时 NVIDIA 的 Vulkan ICD 会被自动发现无需额外配置。Dockerfile 还内置了几个贴心细节--no-sandbox容器内以 root 跑 Chrome 所必需、FREECUT_HOST0.0.0.0容器端口需接受外部流量、exec 形式 CMD保证 SIGTERM 能触发优雅停机并释放工作区写锁。调用渲染任务从一条 curl 到成片单项目渲染POST /render直接返回视频文件attachment 下载常用参数curl -X POST localhost:8787/render \ -H content-type: application/json \ -d {project:my-video,codec:vp9,container:webm,quality:high} \ -o out.webm支持的参数见 headless/serve.mjs 头注释codech264 / h265 / vp9 / vp8 / av1默认 h264不可用时自动回退containermp4 / webm / mov / mkvresolution/fps覆盖项目元数据qualitylow / medium / high / ultrain/outSec/duration只渲染时间片段audioOnly只出音轨默认 mp3批量渲染不想起服务CLI 支持--batch一个 JSON 数组描述多个任务共享同一个预热浏览器避免逐个冷启动node headless/render.mjs --workspace /path/to/FreeCutProjects --batch jobs.json也可以直接渲染单个项目或列出工作区里的所有项目node headless/render.mjs --workspace ~/FreeCutProjects --list node headless/render.mjs --workspace ~/FreeCutProjects --project my-video --codec h264 --out out.mp4抽一帧预览比渲染快一个量级调试 project.json 时与其编码短片段再抽帧不如直接用POST /frame——不走编码器和混流器只合成一帧默认输出全分辨率 PNGcurl -X POST localhost:8787/frame \ -H content-type: application/json \ -d {project:my-video,at:12.5} -o shot.png响应头X-Freecut-Frame会告知帧号若项目引用了缺失的媒体文件X-Freecut-Missing-Media会列出对应 id。CLI 等价写法node headless/frame.mjs --workspace ~/FreeCutProjects --project my-video --at 12.5 --out shot.png不渲染的纯编辑ops 操作列表POST /edit或 headless/edit.mjs通过页面内真实的时间线动作模块应用编辑操作并返回编辑后的项目 JSON全程不需要媒体文件。常见 op 包括addText加文字、addItem/updateItem/moveItem/removeItems、split切分、trimStart/trimEnd、addTransition转场等格式示例[ { op: addText, text: Hello Headless, from: 0, durationInFrames: 90, fontSize: 140 } ]CLI 不加--out或--in-place时是dry run只打印结果摘要不落盘非常适合脚本化流水线先验证再生成。服务架构与可靠性设计理解几个设计点能帮你把无头服务用得更稳预热单页面 串行队列服务启动时打开一个常驻 harness 页面所有请求经 OperationQueue 串行执行避免 GPU/CPU 争抢队列深度可用--max-queue-depth调整默认 8。失败自愈某次操作失败后队列会自动重建浏览器页面并重新探测 GPU见 headless/lib/page-session.mjs服务不会因一次崩溃而瘫痪。契约校验所有请求体经 headless/lib/contract.mjs 校验非法输入返回 400 并给出字段级错误信息媒体缺失返回 422 mediaIds。安全边界默认只绑127.0.0.1--host或FREECUT_HOST可显式放开项目 id 强制单段路径杜绝路径穿越HTTP 层还有请求体大小与超时保护headless/lib/http-security.mjs。超时配置渲染默认 30 分钟--render-timeout-ms、编辑默认 2 分钟--edit-timeout-ms停机优雅排空队列--shutdown-timeout-ms。常见问题速查问题排查方法健康检查gpu.software: true无真实 GPU。普通项目可用软件 WebGPU 渲染含 GPU 特效的项目请上--gpus all的 NVIDIA 主机端口 8787 连不上确认-p 8787:8787已发布原生直跑时默认只监听 127.0.0.1渲染报MISSING_MEDIA项目 JSON 引用的媒体 id 在media/下找不到文件按 422 响应中的mediaIds补齐想要 H.264 但回退了容器内是 Google Chrome 而非 Chromium已带专有编解码仍失败时查看X-Freecut-Warnings响应头首次启动很慢加--build自动构建 harness后续可先npm run build缓存 dist/小结FreeCut 无头渲染管线把浏览器里剪辑升级成了命令行出片本地 CLInpm run headless:serve起服务render/frame/edit三条命令覆盖渲染、抽帧、纯编辑Docker 部署一条docker builddocker run自带 Chrome、字体与软件 VulkanGPU 主机透传即用面向自动化批量任务、dry run 编辑、字段级错误契约、失败自愈队列都是为 CI 与渲染节点准备的。结合工作区纯文件夹的projects/ media/布局你可以把 FreeCut 项目当作代码库来管理版本、跑测试、出成片——专业级视频渲染零安装图形界面。【免费下载链接】freecutFreeCut is a professional-grade video editor that runs entirely in your browser. Professional video editing, zero installation. Create stunning videos with multi-track editing, keyframe animations, real-time preview, and high-quality exports.项目地址: https://gitcode.com/gh_mirrors/free/freecut创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考