macOS 无头运行

最近一次验证：2026 年 7 月，使用 melt 7.38.0 与 FFmpeg 8.1，在 Apple Silicon（macOS）上。

本指南介绍如何在 macOS 上没有图形会话的情况下运行 melt：包括环境搭建，以及对无人值守、批量和 CI 渲染真正重要的那些参数。文中描述的是 Apple Silicon 上的 Homebrew 安装方式，也就是作者每天运行的自动化视频管线所采用的环境。Dan 使用 MacPorts；对应的 port 都存在，命令可以直接对应转换。

在 macOS 上用 Homebrew 安装

Homebrew 提供有持续维护的 MLT formula，因此整套工具链只需一条命令：

brew install mlt

这会一并拉取 FFmpeg、Qt 模块以及其余运行时依赖。确认二进制文件以及它能看到的服务模块：

melt -version
melt -query "producers" | grep -E "avformat|pango|qtext"

如果你改为从源码构建，请让 configure 指向 Homebrew 的安装前缀，而不是硬编码某个路径，这样当前缀变化时本指南依然可用：

./configure --enable-gpl --prefix="$(brew --prefix)"

在无显示器的情况下运行 melt

最需要知道的一点是：不带 -consumer 参数的 melt 会打开交互式 SDL 预览，而这需要一个窗口和一个音频设备。在无头（headless）、批量或 CI 环境下，你应当始终显式指定 avformat 消费器并写入文件：

melt -profile atsc_1080p_25 \
  input.mp4 \
  -consumer avformat:output.mp4 \
  vcodec=libx264 acodec=aac

这样它会一直运行到结束并自行退出，不需要窗口，也不需要显示服务器。没有需要设置的 DISPLAY 变量，也不需要额外包裹它。选择与你的目标格式匹配的 -profile；melt -query "profiles" 会列出全部可用配置。

面向脚本与 CI 的进度上报

无人值守运行时请使用 -progress2。它每次更新打印一行进度，而不是覆盖同一行，因此在日志文件或 CI 控制台中读起来很清晰：

melt -progress2 -profile atsc_1080p_25 \
  input.mp4 \
  -consumer avformat:output.mp4 vcodec=libx264 acodec=aac

每一行都带有当前帧号和百分比，如果你想用包装脚本来驱动进度条，这很容易解析。

标题与文字叠加

这是最费时间摸索的部分，以下是 macOS 上的实际情况。

使用 qtext（Qt 文字生产器）。它在 macOS 上开箱即用支持无头运行。 macOS 上的 Qt 运行在 cocoa 平台，因此影响 Linux 无头环境的 DISPLAY / WAYLAND_DISPLAY 中止行为在这里不会出现。无需设置任何环境变量，而且 Qt 的文字选项比其他方案更丰富：

melt -profile atsc_1080p_25 \
  color:black out=125 \
  qtext:. text="Rendered headless" fgcolour=0xffffffff size=72 \
  -consumer avformat:titled.mp4 vcodec=libx264

对于跨平台脚本，请设置 QT_QPA_PLATFORM=offscreen。 在无头 Linux 上，正是它让 Qt 模块能在没有显示服务器的情况下运行（见 mlt#1069 (opens in a new tab)）。在 macOS 上它也无害，因此把它写进共用的渲染脚本，就能让同一条命令在两个平台上都工作：

QT_QPA_PLATFORM=offscreen melt -profile atsc_1080p_25 \
  color:black out=125 \
  qtext:. text="Portable across macOS and Linux" size=72 \
  -consumer avformat:titled.mp4 vcodec=libx264

pango 生产器是完全不依赖 Qt 或窗口服务器的兜底方案。 有两种情况下它是正确选择：一是以 launchd LaunchDaemon 运行、没有已登录的 Aqua 会话；二是原样的 Homebrew FFmpeg——自 FFmpeg 8 起不再附带 drawtext 滤镜，因此那里的 FFmpeg 文字路径不可用。pango 两者都不需要：

melt -profile atsc_1080p_25 \
  color:black out=125 \
  pango:. text="No Qt, no display" fgcolour=0xffffffff size=72 \
  -consumer avformat:titled.mp4 vcodec=libx264

简而言之：qtext 提供最丰富的文字效果、是 macOS 上的默认选择；对于同时在 Linux 上运行的脚本，在它前面加 QT_QPA_PLATFORM=offscreen；完全没有窗口服务器时用 pango。

一个完整的无头任务

综合起来，一个渲染带标题叠加的片段并记录进度的批处理任务：

#!/usr/bin/env bash
set -euo pipefail

melt -progress2 -profile atsc_1080p_25 \
  input.mp4 \
  qtext:. text="Draft" fgcolour=0xccffffff size=64 \
  -consumer avformat:output.mp4 \
    vcodec=libx264 acodec=aac \
  2>&1 | tee render.log

不需要显示器，不需要人工清理，并且有退出码和日志，可以由 cron、launchd 或 CI 据此采取行动。