1. 概述
本文描述了 MXMACA® 软件栈的FFmpeg命令行工具使用方法。
2. 编码参数
支持的编码参数，可通过ffmpeg -h查看帮助文档，如：
ffmpeg -h encoder=hevc_mxenc
支持的硬件编码器包含h264_mxenc、hevc_mxenc、mjpeg_mxenc。
h264_mxenc上查看编码参数，如下所示:
ffmpeg version n4.4.3-39-g1914aedcc1-VERSION--build_data:2025-04-04_04:56:43,branch:,commit_id:1914aedcc1 Copyright (c) 2000-2022 the FFmpeg developers
built with gcc 7 (Ubuntu 7.5.0-3ubuntu1~18.04)
configuration: --disable-asm --enable-metax --enable-shared --enable-cross-compile --enable-gpl --enable-libx264 --enable-libx265 --enable-libaom --enable-libdavs2 --enable-libxavs2 --enable-libopus --enable-libfreetype --enable-libvmaf --enable-version3 --enable-avresample --disable-sndio --disable-xlib --disable-alsa --disable-sdl2 --extra-version='VERSION--build_data:2025-04-04_04:56:43,branch:,commit_id:1914aedcc1' --extra-cflags=-I/workspace/out/Release/mxc500-2.32.0.1/linux/x86_64/include --extra-cflags=-I/workspace/out/Release/mxc500-2.32.0.1/linux/x86_64/include/mcr --extra-cflags=-I/workspace/out/Release/mxc500-2.32.0.1/linux/x86_64/ffmpeg/thirdparty/include --extra-ldflags=-L/workspace/out/Release/mxc500-2.32.0.1/linux/x86_64/lib --extra-ldflags=-L/workspace/out/Release/mxc500-2.32.0.1/linux/x86_64/ffmpeg/thirdparty/lib --extra-libs=-lmcruntime --extra-libs=-lmxkw --extra-libs=-lmxc-runtime64 --extra-libs=-lmcimage --prefix=/workspace/out/Release/mxc500-2.32.0.1/linux/x86_64/ffmpeg
libavutil 56. 70.100 / 56. 70.100
libavcodec 58.134.100 / 58.134.100
libavformat 58. 76.100 / 58. 76.100
libavdevice 58. 13.100 / 58. 13.100
libavfilter 7.110.100 / 7.110.100
libavresample 4. 0. 0 / 4. 0. 0
libswscale 5. 9.100 / 5. 9.100
libswresample 3. 9.100 / 3. 9.100
libpostproc 55. 9.100 / 55. 9.100
Encoder h264_mxenc [METAX VPUE H.264 encoder]:
General capabilities: delay hardware
Threading capabilities: none
Supported hardware devices: metax metax
Supported pixel formats: yuv420p yuv420p10le nv12 p010le metax
h264_mxenc AVOptions:
-preset <int> E..V....... Set the encoding preset (from 0 to 5) (default faster)
veryfast 0 E..V.......
faster 1 E..V.......
fast 2 E..V.......
medium 3 E..V.......
slow 4 E..V.......
slower 5 E..V.......
-profile <int> E..V....... Set the encoding profile (from -1 to 3) (default auto)
auto -1 E..V.......
baseline 0 E..V.......
main 1 E..V.......
high 2 E..V.......
high10 3 E..V.......
-level <int> E..V....... Set the encoding level restriction (from -1 to 99) (default auto)
auto -1 E..V.......
1 10 E..V.......
1.0 10 E..V.......
1b 99 E..V.......
1.0b 99 E..V.......
1.1 11 E..V.......
1.2 12 E..V.......
1.3 13 E..V.......
2 20 E..V.......
2.0 20 E..V.......
2.1 21 E..V.......
2.2 22 E..V.......
3 30 E..V.......
3.0 30 E..V.......
3.1 31 E..V.......
3.2 32 E..V.......
4 40 E..V.......
4.0 40 E..V.......
4.1 41 E..V.......
4.2 42 E..V.......
5 50 E..V.......
5.0 50 E..V.......
5.1 51 E..V.......
5.2 52 E..V.......
6 60 E..V.......
6.0 60 E..V.......
6.1 61 E..V.......
6.2 62 E..V.......
-tune <int> E..V....... Video quality for different target (from -1 to 0) (default auto)
auto -1 E..V.......
psnr 0 E..V.......
-rc <int> E..V....... Override the preset rate-control (from -1 to 4) (default auto)
auto -1 E..V.......
cbr 1 E..V....... Constant bitrate mode
vbr 2 E..V....... Variable bitrate mode
crf 3 E..V....... Constant rate factor mode
constqp 4 E..V....... Constant QP mode
.......
hevc_mxenc上查看编码参数，如下所示:
ffmpeg version n4.4.3-39-g1914aedcc1-VERSION--build_data:2025-04-04_04:56:43,branch:,commit_id:1914aedcc1 Copyright (c) 2000-2022 the FFmpeg developers
built with gcc 7 (Ubuntu 7.5.0-3ubuntu1~18.04)
configuration: --disable-asm --enable-metax --enable-shared --enable-cross-compile --enable-gpl --enable-libx264 --enable-libx265 --enable-libaom --enable-libdavs2 --enable-libxavs2 --enable-libopus --enable-libfreetype --enable-libvmaf --enable-version3 --enable-avresample --disable-sndio --disable-xlib --disable-alsa --disable-sdl2 --extra-version='VERSION--build_data:2025-04-04_04:56:43,branch:,commit_id:1914aedcc1' --extra-cflags=-I/workspace/out/Release/mxc500-2.32.0.1/linux/x86_64/include --extra-cflags=-I/workspace/out/Release/mxc500-2.32.0.1/linux/x86_64/include/mcr --extra-cflags=-I/workspace/out/Release/mxc500-2.32.0.1/linux/x86_64/ffmpeg/thirdparty/include --extra-ldflags=-L/workspace/out/Release/mxc500-2.32.0.1/linux/x86_64/lib --extra-ldflags=-L/workspace/out/Release/mxc500-2.32.0.1/linux/x86_64/ffmpeg/thirdparty/lib --extra-libs=-lmcruntime --extra-libs=-lmxkw --extra-libs=-lmxc-runtime64 --extra-libs=-lmcimage --prefix=/workspace/out/Release/mxc500-2.32.0.1/linux/x86_64/ffmpeg
libavutil 56. 70.100 / 56. 70.100
libavcodec 58.134.100 / 58.134.100
libavformat 58. 76.100 / 58. 76.100
libavdevice 58. 13.100 / 58. 13.100
libavfilter 7.110.100 / 7.110.100
libavresample 4. 0. 0 / 4. 0. 0
libswscale 5. 9.100 / 5. 9.100
libswresample 3. 9.100 / 3. 9.100
libpostproc 55. 9.100 / 55. 9.100
Encoder hevc_mxenc [METAX VPUE HEVC encoder]:
General capabilities: delay hardware
Threading capabilities: none
Supported hardware devices: metax metax
Supported pixel formats: yuv420p yuv420p10le nv12 p010le metax
hevc_mxenc AVOptions:
-preset <int> E..V....... Set the encoding preset (from 0 to 5) (default fast)
veryfast 0 E..V.......
faster 1 E..V.......
fast 2 E..V.......
medium 3 E..V.......
slow 4 E..V.......
slower 5 E..V.......
-profile <int> E..V....... Set the encoding profile (from -1 to 3) (default auto)
auto -1 E..V.......
main 0 E..V.......
mainstillpicture 1 E..V.......
main10 2 E..V.......
rext 3 E..V.......
-level <int> E..V....... Set the encoding level restriction (from -1 to 186) (default auto)
auto -1 E..V.......
1 30 E..V.......
1.0 30 E..V.......
2 60 E..V.......
2.0 60 E..V.......
2.1 63 E..V.......
3 90 E..V.......
3.0 90 E..V.......
3.1 93 E..V.......
4 120 E..V.......
4.0 120 E..V.......
4.1 123 E..V.......
5 150 E..V.......
5.0 150 E..V.......
5.1 153 E..V.......
5.2 156 E..V.......
6 180 E..V.......
6.0 180 E..V.......
6.1 183 E..V.......
6.2 186 E..V.......
-tune <int> E..V....... Video quality for different target (from -1 to 0) (default auto)
auto -1 E..V.......
psnr 0 E..V.......
-rc <int> E..V....... Override the preset rate-control (from -1 to 4) (default auto)
auto -1 E..V.......
cbr 1 E..V....... Constant bitrate mode
vbr 2 E..V....... Variable bitrate mode
crf 3 E..V....... Constant rate factor mode
constqp 4 E..V....... Constant QP mode
.......
3. 解码
目前解码只支持NV12像素格式输出，支持8-bit和10-bit位深。
可通过ffmpeg -h查看解码器支持的额外参数，如：
ffmpeg -h decoder=h264_mxvid
支持的解码器包含h264_mxvid、hevc_mxvid、av1_mxvid、avs2_mxvid、mjpeg_mxvid。
使用示例
解码h264
ffmpeg -c:v h264_mxvid -i input.mp4 -y output.yuv
4. 编码
4.1. 输入源YUV文件
使用示例
编码hevc
ffmpeg -r 50 -s 1280x720 -pix_fmt yuv420p -i input.yuv -c:v hevc_mxenc -b:v 30000000 -r 50 output.hevc
4.2. 输入源带封装文件（转码）
目前硬解硬编有2种模式可以选择，分别为host和device。
-device模式：解码后的图像数据一直保存在device内存上，供编码器或filters使用。
-host模式：解码器解码后yuv图像拷贝到系统内存上，供其他模块使用。性能低于device模式。
使用示例
device模式
ffmpeg -hwaccel metax -hwaccel_output_format metax -c:v hevc_mxvid -i input.ts -c:v hevc_mxenc -c:a copy -y output.mp4
ffmpeg -hwaccel metax -hwaccel_output_format metax -c:v hevc_mxvid -r 25 -b:v 3M -i input.ts -c:v hevc_mxenc -c:a copy -y output.mp4
host模式
ffmpeg -c:v hevc_mxvid -i input.ts -c:v hevc_mxenc -c:a copy -y output.mp4
ffmpeg -c:v hevc_mxvid -i input.ts -c:v hevc_mxenc -c:a copy -r 25 -b:v 3M -y output.mp4
4.3. 支持卡选择
可通过-init_hw_device选择设备，如：
-init_hw_device metax:0 //0代表第一张卡
使用示例
ffmpeg -init_hw_device metax:0 -hwaccel metax -hwaccel_output_format metax -c:v hevc_mxvid -i input.ts -c:v hevc_mxenc -c:a copy -y output.mp4
5. Filter
本章详细描述硬件支持的FFmpeg filter的参数及使用方法。
可以根据帮助文档查看当前版本的具体参数，使用方法如下：
ffmpeg -h filter=scale_metax
其中scale_metax为filter名称，可以替换成其他filter。
5.1. scale_metax
该filter用于转换图像格式和分辨率。支持的参数，参见表 5.1：
参数 |
说明 |
|---|---|
w |
输出的宽（默认iw） |
h |
输出的高（默认ih） |
format |
输出的格式（默认为输入格式） |
in_left |
输入图像中有效矩形的左上角横坐标（默认0） |
in_top |
输入图像中有效矩形的左上角纵坐标（默认0） |
in_right |
输入图像中有效矩形的右下角横坐标（默认iw） |
in_bottom |
输入图像中有效矩形的右下角纵坐标（默认ih） |
out_left |
输出图像中有效矩形的左上角横坐标（默认0） |
out_top |
输出图像中有效矩形的左上角纵坐标（默认0） |
out_right |
输出图像中有效矩形的右下角横坐标（默认ow） |
out_bottom |
输出图像中有效矩形的右下角纵坐标（默认ow） |
flags |
选择插值算法，可选值sync，blur，bicubic，bilinear（默认值） |
window_size |
窗口size，默认3（3*3），可选3、5 |
使用示例
host模式
ffmpeg -c:v h264_mxvid -i 1920x1080_24fps_h264_mm01.mp4 -vf hwupload_metax,scale_metax=w=960:h=540:format=yuv420p,hwdownload -c:v hevc_mxenc -y output.mp4
ffmpeg -c:v h264_mxvid -i 1920x1080_24fps_h264_mm01.mp4 -vf hwupload_metax,scale_metax_bsh=w=960:h=540:format=yuv420p,hwdownload -c:v hevc_mxenc -y output.mp4 //速度快，适用于缩放的宽高和原视频很接近
device模式
ffmpeg -hwaccel metax -hwaccel_output_format metax -c:v h264_mxvid -i 1920x1080_24fps_h264_mm01.mp4 -vf scale_metax=w=640:h=320:format=yuv420p -c:v hevc_mxenc -y output_device_scale.mp4
5.2. scale_metax_bsh
该filter用于转换图像格式和分辨率，速度较快。支持的参数，参见表 5.2：
参数 |
说明 |
|---|---|
w |
输出的宽（默认iw） |
h |
输出的高（默认ih） |
format |
输出的格式（默认为输入格式） |
in_left |
输入图像中有效矩形的左上角横坐标（默认0） |
in_top |
输入图像中有效矩形的左上角纵坐标（默认0） |
in_right |
输入图像中有效矩形的右下角横坐标（默认iw） |
in_bottom |
输入图像中有效矩形的右下角纵坐标（默认ih） |
out_left |
输出图像中有效矩形的左上角横坐标（默认0） |
out_top |
输出图像中有效矩形的左上角纵坐标（默认0） |
out_right |
输出图像中有效矩形的右下角横坐标（默认ow） |
out_bottom |
输出图像中有效矩形的右下角纵坐标（默认ow） |
使用示例
host模式
ffmpeg -c:v h264_mxvid -i 1920x1080_24fps_h264_mm01.mp4 -vf hwupload_metax,scale_metax_bsh=w=960:h=540:format=yuv420p,hwdownload -c:v hevc_mxenc -y output.mp4
device模式
ffmpeg -hwaccel metax -hwaccel_output_format metax -c:v h264_mxvid -i 1920x1080_24fps_h264_mm01.mp4 -vf scale_metax_bsh=w=640:h=320:format=yuv420p -c:v hevc_mxenc -y output_device_scale.mp4
5.3. overlay_metax
该filter用于图像叠加/融合。支持的参数，参见表 5.3：
参数 |
说明 |
|---|---|
x |
覆盖位置（x，y）中的x，默认0 |
y |
覆盖位置（x，y）中的y，默认0 |
b |
是否融合，默认0，不融合 |
使用示例
host模式
ffmpeg -c:v h264_mxvid -i 1920x1080_24fps_h264_mm01.mp4 -i 001_176x144_I420_b.jpeg -filter_complex "[0:v]hwupload_metax[base],[1:v]hwupload_metax[overlay],[base][overlay]overlay_metax=x=20:y=20" -c:v h264_mxenc -y output_jpeg.mp4
device模式
ffmpeg -hwaccel metax -hwaccel_output_format metax -c:v h264_mxvid -i 1920x1080_24fps_h264_mm01.mp4 -i 001_176x144_I420_b.jpeg -filter_complex "[0:v]scale_metax=w=960:h=540[base],[1:v]hwupload_metax[overlay],[base][overlay]overlay_metax=x=10:y=10" -c:v hevc_mxenc -y output_jpeg.mp4
ffmpeg -hwaccel metax -hwaccel_output_format metax -c:v h264_mxvid -i 1920x1080_24fps_h264_mm01.mp4 -i 001_176x144_I420_b.jpeg -filter_complex "[1:v]hwupload_metax[overlay],[0:v][overlay]overlay_metax=x=10:y=10" -c:v hevc_mxenc -y output_jpeg.mp4
5.4. drawbox_metax
该filter用于在图像上画框。支持的参数，参见表 5.4：
参数 |
说明 |
|---|---|
x |
画框的左上角横坐标，默认0 |
y |
画框的左上角纵坐标，默认0 |
w/width |
框的宽，默认0 |
h/height |
框的高，默认0 |
c/color |
框的颜色，默认black |
t/thickness |
框的厚度，默认3 |
使用示例
device模式
ffmpeg -hwaccel metax -hwaccel_output_format metax -c:v h264_mxvid -i 1920x1080_24fps_h264_mm01.mp4 -vf drawbox_metax=x=300:y=300:w=480:h=270:color=pink:t=2 -c:v hevc_mxenc -y output_device_drawbox.mp4
5.5. crop_metax
该filter用于裁剪图像。支持的参数，参见表 5.5：
参数 |
说明 |
|---|---|
w/out_w |
输出图像的宽，默认iw |
h/out_h |
输出图像的高，默认ih |
x |
裁剪时左上角横坐标，默认为(in_w-out_w)/2 |
y |
裁剪时左上角纵坐标，默认为(in_h-out_h)/2 |
使用示例
device模式
ffmpeg -hwaccel metax -hwaccel_output_format metax -c:v h264_mxvid -i 1920x1080_24fps_h264_mm01.mp4 -vf crop_metax=w=960:h=540:x=480:y=270 -c:v hevc_mxenc -y output_device_crop.mp4
5.6. hwupload_metax
该filter用于将图像从系统内存拷贝到设备内存，和其他filter一起使用。支持的参数参见表 5.6：
参数 |
说明 |
|---|---|
device |
硬件卡编号，默认值为0 |
-vf "hwupload_metax=device=1"
6. 复合型FFmpeg命令行
6.1. 多路视频合成一路
使用1080p的4图像，以2*2方式合成为一个1080p视频
ffmpeg -hwaccel mxvid -c:v h264_mxvid -i xxx0.mp4 -hwaccel mxvid -c:v h264_mxvid -i xxx1.mp4 -hwaccel mxvid -c:v h264_mxvid -i xxx2.mp4 -hwaccel mxvid -c:v h264_mxvid -i xxx3.mp4 -filter_complex "[0:v]scale_metax=w=1920:h=1080[base];[0:v]scale_metax=w=960:h=540[video_1];[1:v]scale_metax=w=960:h=540[video_2];[2:v]scale_metax=w=960:h=540[video_3];[3:v]scale_metax=w=960:h=540[video_4];[base][video_1]overlay_metax=x=0:y=0[overlay1];[overlay1][video_2]overlay_metax=x=960:y=0[overlay2];[overlay2][video_3]overlay_metax=x=0:y=540[overlay3];[overlay3][video_4]overlay_metax=x=960:y=540" -c:v h264_mxenc -y -f mp4 xxx4.mp4
6.2. 一路视频转码多路
将1路视频转码为4路
ffmpeg -i xxx0.mp4 -map 0 -c:v hevc_mxenc -preset faster -rc vbr -b:v 1M -y output1.mp4 -map 0 -c:v hevc_mxenc -preset fast -rc vbr -b:v 2M -y output2.mp4 -map 0 -c:v hevc_mxenc -preset medium -rc vbr -b:v 2M -y output3.mp4 -map 0 -c:v hevc_mxenc -preset fast -rc crf -qp 23 -y output4.mp4
6.3. 使用PNG添加水印
ffmpeg -hwaccel mxvid -c:v h264_mxvid -i Bosphorus.mp4 -i 0023.png -filter_complex "[0:v]scale_metax=format=bgra[in0];[1:v]hwupload_metax,scale_metax=format=bgra [in1];[in0][in1]overlay_metax=x=960:y=540:b=1[ov3];[ov3]scale_metax=format=nv12" -c:v h264_mxenc -f mp4 -y BrosOver.mp4
6.4. 多路解码
ffmpeg -hwaccel metax -c:v h264_mxvid -i xxx1.mp4 -hwaccel metax -c:v h264_mxvid -i xxx2.mp4 -hwaccel metax -c:v h264_mxvid -i xxx3.mp4 -map 0:v -y xxx1out.yuv -map 1:v -f rawvideo -y xxx2out.yuv -map 2:v -f rawvideo -y xxx3out.yuv
6.5. 多路转码
ffmpeg -s 1920x1080 -pix_fmt nv12 -i 1.yuv -s 1920x1080 -pix_fmt nv12 -i 2.yuv -map 0 -c:v hevc_mxenc -preset medium -rc vbr -b:v 2M -r 30 -y 1.mp4 -map 1 -c:v hevc_mxenc -preset medium -rc vbr -b:v 2M -r 25 -y 2.mp4
6.6. 多路转码
ffmpeg -hwaccel mxvid -c:v h264_mxvid -i xxx1.mp4 -hwaccel mxvid -c:v h264_mxvid -i xxx2.mp4 -hwaccel mxvid -c:v h264_mxvid -i xxx3.mp4 -map 0 -c:v hevc_mxenc -preset medium -rc vbr -b:v 2M -r 30 -y 1.mp4 -map 1 -c:v hevc_mxenc -preset medium -rc vbr -b:v 2M -r 25 -y 2.mp4 -map 2 -c:v hevc_mxenc -preset medium -rc vbr -b:v 2M -r 25 -y 3.mp4