转码
TubePress 如何借助分布式 FFmpeg 工作进程，将上传文件转换为适合网页播放的多清晰度版本。
转码将单个上传文件转换为多个适合网络播放的 MP4 版本，让观看者无论上传的是什么格式，都能获得清晰度选择菜单、快速启动的播放体验以及统一的编解码器。此外，它还会嵌入可选的附加功能—水印和片头/片尾片段—并生成播放器所需的进度预览缩略图。
此处所有内容均在 /admin/settings?tab=transcode 下配置，分布在 格式、队列、服务器、水印、片头 和 时间轴 子标签中。转码可以在 CMS 服务器本身上运行，也可以分发到专用的工作节点。
为什么要转码
原始上传文件可以是任意分辨率、编解码器或容器格式。转码将其标准化为带有 +faststart 标志的 MP4/H.264 版本，使播放在文件完全下载前就能开始，同时生成多种尺寸（例如 720p 和 480p），以便 播放器 能够提供清晰度选择器，并为小屏幕设备提供较小的文件。水印和片头/片尾片段也在同一处理流程中应用，因为它们必须编码进每个版本。
转码流水线
当视频准备好处理时，TubePress 会为每个输出在 transcode_jobs 表中创建一个任务并依次处理：
- 排队。为全分辨率源层级和所有低于源高度的活跃格式各创建一个任务，如果启用了预览，则额外创建一个时间轴任务。
- 领取。工作节点—本服务器或远程服务器—认领下一个待处理任务，从源层级开始。
- 下载。远程工作节点通过 HTTP 拉取源文件（一个经过密钥认证的直接 URL，可绕过签名媒体链接）。
- 转码。FFmpeg 对版本进行编码，按配置应用剪裁、水印和片头，并实时报告进度百分比。
- 上传与回调。结果以分块方式上传回服务器，回调标记任务完成。
视频状态跟踪此流程：任务运行时处于 处理中 状态，源层级完成后立即切换为 已发布，只有当源层级永远无法生成时才变为 错误。较低分辨率版本在发布后继续生成。
版本与格式
输出格式可在 格式 标签中完整编辑，并存储在 video_formats 表中。每种格式包含名称、文件后缀（例如 _720p.mp4）、目标分辨率、原始 FFmpeg 选项、保持宽高比 标志和激活开关。内置默认值为：
| 格式 | 分辨率 |
|---|---|
| 720p | 1280 × 720 |
| 480p | 854 × 480 |
| 360p | 640 × 360 |
两条规则确保质量合理。TubePress 从不进行放大：任何等于或高于源高度的格式将被跳过。并且 原始最高质量始终保留—如果启用了水印或剪裁，将重新编码为全分辨率 源 版本（在队列中显示为星号），否则直接提供源文件。开始剪裁 选项（0–300 秒）可以去掉每个视频的开头几秒；与水印一样，它会应用于包括源文件在内的每种格式。
任务队列
队列 标签（/admin/settings?tab=transcode&sub=queue）按视频分组显示任务，并支持按 全部 / 待处理 / 处理中 / 已完成 / 失败 筛选。每个视频为每个层级显示一个徽章—带星号的源层级，然后是各分辨率，最后是 TIMELINE—以任务状态着色：
每个视频的控制台（终端图标）实时流式传输任务列表、处理每个层级的工作节点、已用时间和任何错误信息。重试失败任务 按钮一键将所有当前失败的任务重新排队。
远程转码服务器
转码是 CPU 密集型操作，因此可以将其从 Web 服务器中卸载。在 服务器 标签中，本服务器 设置本地同时运行的 FFmpeg 任务数量（1–4，或设为 0 以仅使用远程工作节点），并允许覆盖 FFmpeg 路径。在其下方可注册远程工作节点；任务会自动分配给负载最低的节点，每个节点都有 最大并发任务数 限制（推荐每两个 CPU 核心对应一个任务）。
- 添加服务器。点击 添加服务器，输入名称和 URL（例如
http://YOUR-IP:8090），然后保存。API 密钥和启动命令将立即显示。 - 安装 FFmpeg + PHP。在工作节点机器上运行
sudo apt install ffmpeg php-cli php-curl。 - 部署工作节点。下载
transcode-worker.php（从/api/transcode-worker-download或临时wget链接获取），上传并使用sudo ufw allow 8090/tcp开放端口。 - 启动。使用您的密钥运行工作节点：
php transcode-worker.php --port=8090 --key=YOUR_API_KEY- 验证。点击 检查；健康的工作节点将报告 在线，并显示检测到的编码器和实时 CPU/GPU 使用情况。
GPU 加速（NVIDIA、AMD、Intel 或 Apple）会被自动检测并使用。工作节点拉取源文件、转码、报告进度并以分块方式将结果上传回 CMS—分块上传的目的是将每次请求保持在 Cloudflare 100 MB 限制以内。对于无人值守的主机，安装指南包含一个 systemd 单元，以便工作节点在启动时自动重启。
监控与重试
系统的设计确保视频永远不会被静默放弃。编码失败后会以递增的退避间隔自动重试—从大约半分钟到几小时不等—因为大多数失败都是暂时性的（CDN 缓慢或不稳定）。除此之外，每小时的恢复任务会重新排队所有仍标记为失败的任务，持续尝试直到版本成功生成。无需手动点击，但如果需要强制重试，重试失败任务 按钮随时可用。
如果源层级本身永久失败，其依赖的子格式任务将被取消（没有源文件无法继续），视频将被标记为 错误；恢复机制仍会尝试修复。当源层级最终完成时，视频将自动发布。
系统要求
FFmpeg 必须在转码运行的任何位置可用：
- 本地处理：在 CMS 服务器上安装 FFmpeg（
sudo apt install ffmpeg）。转码 页面安装后将显示检测到的版本。 - 远程处理：每个工作节点需要 FFmpeg 以及
php-cli和php-curl，至少 2 个 CPU 核心和 2 GB 内存，并开放工作节点端口。