PHP调用ffmpeg写入MP4元数据必须使用-metadata参数，因MP4采用udta/ilst结构而非ID3；需逐项拼接、UTF-8编码、双引号包裹并转义特殊字符，且须加-movflags +faststart优化首帧加载。
PHP调用ffmpeg写入MP4元数据时，必须用-metadata参数
FFmpeg本身不支持通过PHP内置函数直接修改MP4的元数据（如title、artist、album），只能靠命令行参数注入。PHP只是拼接并执行命令，真正写入动作由ffmpeg完成。常见错误是误以为用file_put_contents()或修改ID3就能改MP4标签——MP4用的是udta和ilst box结构，ID3只适用于MP3。
正确做法是把所有元数据项拼进-metadata参数，每项独立写，不能合并成一个字符串：
-metadata title="我的课程视频"-metadata artist="讲师张三"-metadata comment="2026年夏季更新版"-
-metadata year="2026"（注意：MP4规范中推荐用date而非year）
完整示例命令：
ffmpeg -i input.mp4 -c:v copy -c:a copy -metadata title="PHP转码实战" -metadata artist="TechLab" -metadata date="2026-08-12" -y output.mp4
其中-c:v copy -c:a copy表示不重编码，仅复制流+写入元数据，速度快且无画质损失。
中文元数据乱码？关键在UTF-8编码与ffmpeg版本
Linux下ffmpeg默认按系统locale解析元数据，若服务器locale不是en_US.UTF-8或zh_CN.UTF-8，中文会变成乱码或被截断。不要用iconv提前转码，ffmpeg 4.0+原生支持UTF-8输入，但需确保：
- PHP脚本文件本身保存为UTF-8无BOM格式
- 所有传入
escapeshellarg()的中文字符串，必须在调用前确认是UTF-8编码（可用mb_detect_encoding($str) === 'UTF-8'校验） - 避免在命令里混用单引号和双引号包裹中文——统一用双引号，并确保shell环境支持UTF-8
验证是否写入成功，用ffprobe检查：
ffprobe -v quiet -show_entries format_tags=title,artist,date -of default=nw=1 input.mp4
如果输出为空或显示N/A，说明元数据未写入或格式不被识别。
PHP中动态拼接-metadata参数容易漏转义
元数据值里含空格、括号、&、$等shell特殊字符时，仅靠escapeshellarg()不够——它只处理单层引号包裹，而ffmpeg要求每个-metadata值仍需独立引号。错误写法：
$title = "PHP教程 (2026版)"; // 含空格和括号 $cmd = "ffmpeg -i in.mp4 -metadata title=" . escapeshellarg($title) . " out.mp4"; // ❌ 生成 -metadata title='PHP教程 (2026版)' → ffmpeg报错
正确写法是手动加双引号，并对内部双引号做转义：
$title = str_replace('"', '\"', $title);
$cmd = "ffmpeg -i in.mp4 -metadata title="$title" -y out.mp4";
更稳妥的做法是封装一个安全拼接函数，对每个元数据键值对单独处理，而不是拼成一长串再escapeshellarg()。
MP4元数据写入后moov位置偏移，影响HLS/点播首帧加载
用-metadata参数重写MP4时，ffmpeg默认会把新moov box放在文件末尾（除非加-movflags +faststart）。这会导致浏览器点开视频时卡顿几秒——因为播放器要先读到文件末尾才能拿到索引信息。
必须显式加上-movflags +faststart，且该参数要放在输出文件名之前：
ffmpeg -i input.mp4 -c:v copy -c:a copy -metadata title="Demo" -movflags +faststart -y output.mp4
注意：+faststart会重排整个文件，耗时随文件大小线性增长；大文件（>500MB）建议异步执行，否则Web请求超时。验证是否生效：
ffprobe -v quiet -show_entries format=format_name -of default=nw=1 output.mp4
返回含mov,mp4,m4a,3gp,3g2,mj2即正常；若用hexdump -C output.mp4 | head -20查，应看到moov在前4KB内。
元数据本身不增加体积，但+faststart会触发全量重写，这是最容易被忽略的性能代价。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
