[常用工具] Python视频解码库DeFFcode使用指北
DeFFcode是一种跨平台的高性能视频帧解码器，通过内部封装ffmpeg，提供GPU解码支持，几行python代码就能够快速解码视频帧，并具有强大的错误处理能力。DeFFcode的APIs支持多种媒体流作为输入源，例如IP摄像机、常规多媒体文件、屏幕录制、图像序列、网络协议（例如 HTTP(s)、RTP/RSTP）等。由于FFmpeg的学习曲线非常陡峭，封装FFmpeg后的DeFFcode提供类似OpenCV-Python编码语法来帮助用户，使得在Python中学习、创建和开发基于FFmpeg的应用程序变得更加容易。DeFFcode的官方代码仓库见：deffcode。DeFFcode的官方文档见deffcode_doc。
DeFFcode的作者专注于音视频流的处理，除了Deffcode，作者还开源了Python视频处理库VidGear。VidGear的具体使用见Python视频处理库VidGear使用指北。DeFFcode还处于快速发展阶段，许多功能还需要完善。VidGear提供了比DeFFcode更丰富的视频处理接口，但是DeFFcode提供了比VidGear更高效更专业的视频解码接口。如果想要从事音视频流解码相关工作，还是学习ffmpeg的C++代码使用。
入门ffmpeg使用或者想要对音视频处理有所了解推荐看看雷霄骅的博客。雷霄骅是视音频技术处理的专家，也是国内音视频领域无偿分享技术最多的程序员。但是很不幸雷霄骅因过度劳累于2016年与世长辞，所以大家还是多注意身体健康。身体才是革命的本钱，少加班，该休息就得休息，没有时间休息的人注定没有时间生病。
文章目录
- 1 前置知识
-
- 1.1 安装
- 1.2 DeFFcode功能预览
- 2 基础使用
-
- 2.1 解码视频文件
- 2.2 解码本地摄像头和屏幕截取
- 2.3 解码网络流
- 2.4 从图像序列捕获帧
- 2.5 保存视频
- 2.6 特定帧存储
- 3 进阶使用
-
- 3.1 虚拟源生成与解码
- 3.2 硬件加速视频解码
- 3.3 复杂效果添加
- 3.4 视频属性数据更改
- 4 参考
1 前置知识
1.1 安装
对于DeFFcode，python版本需要高于3.7。DeFFcode支持以下系统：
- 2016以后的linux版本，推荐使用linux系统运行VidGear
- Windows 7及以上版本
- MacOS 10.12.6及以上版本
Deffcode安装代码如下：
pip install -U deffcode
特别要注意的是DeFFcode必须要安装ffmpeg执行文件。安装ffmpeg，其它系统自行搜索安装方法，ubuntu下直接输入：
sudo apt install ffmpeg
1.2 DeFFcode功能预览
视频流解码
DeFFcode核心功能就是利用ffmpeg进行视频解码。相关公开测试视频流地址为：
- rtsp流：rtsp://wowzaec2demo.streamlock.net/vod/mp4:BigBuckBunny_115k.mp4，来源于https://www.wowza.com/developer/rtsp-stream-test
- http流：http://devimages.apple.com.edgekey.net/streaming/examples/bipbop_4x3/gear2/prog_index.m3u8，来源于苹果提供的测试源
- http流：https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1MB.mp4，来源于DeFFcode
from deffcode import FFdecoder
import cv2
# FFedecoder创建视频源和视频解码规则，formulate在ffmpeg中执行语句
# 本地视频
# decoder = FFdecoder("test.mp4").formulate()
# rtsp流
decoder = FFdecoder("rtsp://wowzaec2demo.streamlock.net/vod/mp4:BigBuckBunny_115k.mp4").formulate()
# 从decoder中抓取RGB图像
for frame in decoder.generateFrame():
print(frame.shape)
# 将rgb图像转换为bgr图像，送给opencv展示
frame_bgr = frame[:, :, ::-1]
cv2.imshow("Output Frame", frame_bgr)
key = cv2.waitKey(1) & 0xFF
if key == ord("q"):
break
# 安全关闭解码进程
decoder.terminate()
视频流属性识别
对于给定的输入源，DeFFcode使用各种方法识别视频流其中包含的文件所有属性，比如是否包含音频，图像分辨率，视频码率。不同的视频流返回的属性参数不同，具体按需要探索下就行了。
from deffcode import Sourcer
# sourcer设置定位视频流中的数据信息，probe_stream探测视频流的输出
sourcer = Sourcer("test.mp4").probe_stream()
# 解析为python字典数据
data = sourcer.retrieve_metadata()
# pretty_json表示解析为类似json.dump后的json字符串
print(sourcer.retrieve_metadata(pretty_json=True))
2 基础使用
2.1 解码视频文件
DeFFcode的FFdecoder API很容易支持多媒体视频文件路径作为其source参数的输入。通过它的frame_format参数，您可以轻松解码所有知名计算机视觉库（例如 OpenCV）都支持的任何像素格式的视频帧。FFdecoder API 的generateFrame()函数可用于多种方法来访问来自给定源的RGB帧，例如生成器（推荐方法）、调用with语句和迭代器。在下面示例中，我们将使用上述访问方法从给定的视频文件中解码默认的RGB24视频帧。
生成器调用
from deffcode import FFdecoder
decoder = FFdecoder("test.mp4").formulate()
# 读取RGB24图像
for frame in decoder.generateFrame():
if frame is None:
break
print(frame.shape)
decoder.terminate()
with调用
调用with语句方法可用于使代码更简单、更清晰、更易读。这种方法还自动处理FFdecoder API 中的formulate()和terminate()方法的管理，因此不需要显式调用它们。
from deffcode import FFdecoder
import cv2
# 不需要调用formulate和terminate
with FFdecoder("test.mp4") as decoder:
for frame in decoder.generateFrame():
if frame is None:
break
print(frame.shape)
迭代器调用
迭代器的调用方式类似于OpenCV-Python读取视频的方式。
from deffcode import FFdecoder
decoder = FFdecoder("test.mp4").formulate()
while True:
# next返回迭代器的下一个项目
frame = next(decoder.generateFrame(), None)
if frame is None:
break
print(frame.shape)
decoder.terminate()
参数设置
# 设置解码后的图像为bgr24，可以直接给opencv使用
FFdecoder("test.mp4", frame_format="bgr24")
# 设置解码后的图像为灰度图像，verbose输出解码的详细统计信息
FFdecoder("test.mp4", frame_format="gray", verbose=True)
# 设置解码后的图像为yuv420p格式，verbose输出解码的详细统计信息
FFdecoder("test.mp4", frame_format="yuv420p", verbose=True)
2.2 解码本地摄像头和屏幕截取
这部分不同平台使用方法不同，而且涉及到很多参数的使用和软件安装，所以这里推荐自行阅读Decoding Live Feed Devices。
2.3 解码网络流
与解码视频文件类似，DeFFcode 的 FFdecoder API直接支持具有特定协议（如RTSP/RTP、HTTP(s)、MPEG-TS 等）的网络流作为其source参数的输入。以下示例用的都是网络上的公开视频流，由于网速问题有可能连接不上。
http流解码
from deffcode import FFdecoder
import cv2
# 获得BGR24图像
# decoder = FFdecoder("ttp://devimages.apple.com.edgekey.net/streaming/examples/bipbop_4x3/gear2/prog_index.m3u8", frame_format="bgr24").formulate()
decoder = FFdecoder("https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1MB.mp4", frame_format="bgr24").formulate()
for frame in decoder.generateFrame():
if frame is None:
break
cv2.imshow("Output", frame)
key = cv2.waitKey(1) & 0xFF
if key == ord("q"):
break
cv2.destroyAllWindows()
decoder.terminate()
RTSP/RTP流解码
from deffcode import FFdecoder
import cv2
# 设置传输协议为tcp
ffparams = {"-rtsp_transport": "tcp"}
# 取流
decoder = FFdecoder("rtsp://wowzaec2demo.streamlock.net/vod/mp4:BigBuckBunny_115k.mp4", frame_format="bgr24", verbose=True, **ffparams).formulate()
for frame in decoder.generateFrame():
if frame is None:
break
cv2.imshow("Output", frame)
key = cv2.waitKey(1) & 0xFF
if key == ord("q"):
break
cv2.destroyAllWindows()
decoder.terminate()
2.4 从图像序列捕获帧
特定命名图像序列读取
下面的代码展示了如何带有特定数字标记的图像序列逐帧读取图像。您可以使用以下FFmpeg命令从视频文件中提取时间长度为2s的图像序列，注意图像保存的文件夹路径应该要预先创建。
ffmpeg -t 2 -i test.mp4 imgs/image%02d.png
from deffcode import FFdecoder
import cv2
# 设置特定数字开始读图，在本例为img01.png
ffparams = {"-ffprefixes":["-start_number", "1"]}
# 注意图像数大于三张
# img%02d.png: 格式化输出文件名，本示例中输出img00.png，img01.png, img02.png等
# 如果是jpeg图像序列，图像后缀名应该为jpeg而不是jpg
decoder = FFdecoder("imgs/img%02d.png", frame_format="bgr24", verbose=True, **ffparams).formulate()
for frame in decoder.generateFrame():
if frame is None:
break
cv2.imshow("Output", frame)
key = cv2.waitKey(1) & 0xFF
if key == ord("q"):
break
cv2.destroyAllWindows()
decoder.terminate()
glob 模式
如果图像是连续的，但不一定是数字顺序，则通配符（*表示任意数量的任意字符）很有用，但是以下代码无法在windows下使用。
from deffcode import FFdecoder
import cv2
# glob模式抓取图像
# glob模式在 Windows FFmpeg 版本上不可用。
ffparams = {"-ffprefixes":["-pattern_type", "glob"]}
decoder = FFdecoder("imgs/img*.png", frame_format="bgr24", verbose=True, **ffparams).formulate()
for frame in decoder.generateFrame():
if frame is None:
break
cv2.imshow("Output", frame)
key = cv2.waitKey(1) & 0xFF
if key == ord("q"):
break
cv2.destroyAllWindows()
decoder.terminate()
循环读取图像
下面的设置展示了从单个或者多个图像循环读取的示例。注意jpg图像都以jpeg后缀命名。
# `-loop 1` 表示循环读取,loop是bool类型
ffparams = {"-ffprefixes":["-loop", "1"]}
# 设置单张图像循环读取
decoder = FFdecoder("imgs/img01.png", frame_format="bgr24", verbose=True, **ffparams).formulate()
# 设置多张图像循环读取
decoder = FFdecoder("imgs/img%02d.png", frame_format="bgr24", verbose=True, **ffparams).formulate()
2.5 保存视频
通过OpenCV保存视频
from deffcode import FFdecoder
import json, cv2
decoder = FFdecoder("test.mp4", frame_format="bgr24").formulate()
# decoder.metadata读取视频属性json数据，并转码为字典
metadata_dict = json.loads(decoder.metadata)
FOURCC = cv2.VideoWriter_fourcc("M", "J", "P", "G")
FRAMERATE = metadata_dict["source_video_framerate"]
FRAMESIZE = tuple(metadata_dict["source_video_resolution"])
writer = cv2.VideoWriter("output.avi", FOURCC, FRAMERATE, FRAMESIZE)
for frame in decoder.generateFrame():
if frame is None:
break
writer.write(frame)
cv2.imshow("Output", frame)
key = cv2.waitKey(1) & 0xFF
if key == ord("q"):
break
cv2.destroyAllWindows()
decoder.terminate()
writer.release()
通过VidGear保存视频（推荐）
使用这种方式保存视频，视频文件压缩率更高，保存速度更快，但是也CPU利用率也更高。
from deffcode import FFdecoder
from vidgear.gears import WriteGear
import json
decoder = FFdecoder("test.mp4", frame_format="bgr24", verbose=True).formulate()
output_params = {
"-input_framerate": json.loads(decoder.metadata)["source_video_framerate"]
}
writer = WriteGear(output_filename="output.mp4", **output_params)
for frame in decoder.generateFrame():
if frame is None:
break
writer.write(frame)
decoder.terminate()
writer.close()
参数设置
以下是各种ffmpeg参数的设置方法，ffparams设置参数后，然后传入FFdecoder。
# 截取前3s视频，按倒序保存
ffparams = {
"-vf": "trim=end=7,reverse"
}
# 裁剪中央输入区域，宽高都为输入视频的2/3，然后拉伸为原图像尺寸
ffparams = {
"-vf": "crop=2/3*in_w:2/3*in_h"
}
# 逆时针旋转图像30度，用绿色填充旋转图像未覆盖的区域
ffparams = {
"-vf": "trim=end=7,rotate=angle=-30*PI/180:fillcolor=green"
}
# 保存前7秒视频，逆时针旋转90度，保持纵向布局
# dir为旋转方向，具体可以搜搜ffmpeg transpose
ffparams = {
"-vf": "trim=end=7,transpose=dir=2:passthrough=portrait"
}
# 水平翻转，然后缩放图像到其原始大小的一半
ffparams = {
"-vf": "hflip,scale=w=iw/2:h=ih/2"
}
# 设置参数
decoder = FFdecoder(
"test.mp4", frame_format="bgr24", verbose=True, **ffparams
).formulate()
2.6 特定帧存储
DeFFcode的FFdecoder API使用FFmpeg参数-ss提供轻松且精确的帧搜索，使我们能够从输入源的特定部分保存图像。
from deffcode import FFdecoder
from PIL import Image
# 定义FFmpeg参数以查找00:00:01.45处图像，并获得一帧图像
ffparams = {"-ss": "00:00:01.45", "-frames:v": 1}
# 初始化参数
decoder = FFdecoder("test.mp4", **ffparams).formulate()
# 读取图像
frame = next(decoder.generateFrame(), None)
# 保存图像
if not (frame is None):
im = Image.fromarray(frame)
im.save("test.png")
else:
raise ValueError("Something is wrong!")
decoder.terminate()
3 进阶使用
3.1 虚拟源生成与解码
DeFFcode提供各种创建虚拟视频流的示例，具体使用见Decoding Live Virtual Sources，这里只列出两个经典的案例。
从测试源模式生成和解码帧
testsrc图生成一个测试视频模式，显示颜色模式、滚动渐变和时间戳。这对于测试目的很有用。
from deffcode import FFdecoder
import cv2
# 定义参数
ffparams = {
# 播放时间为10秒
"-ffprefixes": ["-t", "10"],
}
# 生成尺寸为1280x720，帧率30的testsrc测试图像
decoder = FFdecoder(
"testsrc=size=1280x720:rate=30",
source_demuxer="lavfi",
frame_format="bgr24",
**ffparams
).formulate()
for frame in decoder.generateFrame():
if frame is None:
break
cv2.imshow("Output", frame)
key = cv2.waitKey(1) & 0xFF
if key == ord("q"):
break
cv2.destroyAllWindows()
decoder.terminate()
使用自定义文本效果从渐变生成和解码帧
from deffcode import FFdecoder
import cv2
ffparams = {
"-ffprefixes": ["-t", "15"], # 15秒播放
"-vf": "drawtext=" # 绘制文本
+ "text='%{localtime\:%X}':" # 时间 (HH::MM::SS)
+ "fontfile='c\:\/windows\/fonts\/arial.ttf':" # 字体
+ "x=(w-text_w)/2:y=h-40*t:" # 向上滚动效果
+ "fontsize=50:" # 字体大小
+ "fontcolor=white", # 字体颜色
}
decoder = FFdecoder(
"gradients=n=3",
source_demuxer="lavfi",
frame_format="bgr24",
**ffparams
).formulate()
for frame in decoder.generateFrame():
if frame is None:
break
cv2.imshow("Output", frame)
key = cv2.waitKey(1) & 0xFF
if key == ord("q"):
break
cv2.destroyAllWindows()
decoder.terminate()
3.2 硬件加速视频解码
FFmpeg 提供对不同平台上不同支持的专用硬件的访问，以执行一系列与视频相关的任务，以更快地完成或使用更少的其他资源（特别是 CPU)。使用ffmpeg -decoders终端命令列出所有 FFmpeg 支持的解码器。可以看看具体ffmpeg支持本机哪种硬件解码。
比如判断ffmpeg是否可以通过依赖于gpu cuda的h264_cuvid解码，可以输入以下指令。如果输出包含了h264_cuvid那么就是支持的，可以通过gpu加速解码。
linux系统：ffmpeg -hide_banner -decoders | grep h264
windows系统：ffmpeg -hide_banner -decoders | findstr h264
如果支持h264_cuvid加速解码，可以尝试以下示例代码。
from deffcode import FFdecoder
import cv2
ffparams = {
"-vcodec": "h264_cuvid", # CUVID H.264加速视频解码
"-ffprefixes": ["-vsync", "0"], # 视频同步方法，一般都是自动，这里设置为0
}
decoder = FFdecoder(
"test.mp4", frame_format="bgr24", verbose=True, **ffparams
).formulate()
for frame in decoder.generateFrame():
if frame is None:
break
cv2.imshow("Output", frame)
key = cv2.waitKey(1) & 0xFF
if key == ord("q"):
break
cv2.destroyAllWindows()
decoder.terminate()
3.3 复杂效果添加
添加水印
以下代码展示了如何在读取的视频中添加图像，并保存视频到本地。
from deffcode import FFdecoder
from vidgear.gears import WriteGear
import json, cv2
# 定义带有复杂水印的视频过滤器
ffparams = {
"-ffprefixes": ["-t", "5"], # 视频总长度为5秒
"-clones": [
"-i",
"watermark.png",
],
"-filter_complex": "[1]format=rgba," # 设置水印图像输入格式
+ "colorchannelmixer=aa=0.7[logo];" # 设置水印透明度，数值越小越透明
+ "[0][logo]overlay=W-w-{pixel}:H-h-{pixel}:format=auto,".format(
pixel=5 # 设置水印图片在距离输入视频右下角5个像素处
)
+ "format=bgr24", # 设置输出格式
}
decoder = FFdecoder(
"test.mp4", frame_format="bgr24", verbose=True, **ffparams
).formulate()
output_params = {
"-input_framerate": json.loads(decoder.metadata)["source_video_framerate"],
}
# 保存视频
writer = WriteGear(output_filename="output.mp4", **output_params)
for frame in decoder.generateFrame():
if frame is None:
break
writer.write(frame)
decoder.terminate()
writer.close()
图像效果混合
下面的代码展示了如何往图像序列中混合虚拟效果。
from deffcode import FFdecoder
from vidgear.gears import WriteGear
import cv2, json
ffparams = {
"-ffprefixes": [
"-t", "10", # 视频长度为10s
"-f", "lavfi", # 使用输入虚拟数据
"-i", "mandelbrot=rate=25", # 视频帧率
],
"-custom_resolution": (1280, 720), # 重新设置图像 1280x720
"-filter_complex":"[1:v]format=yuv444p[v1];"
+ "[0:v]format=gbrp10le[v0];"
+ "[v1][v0]scale2ref[v1][v0];"
+ "[v0][v1]blend=all_mode='heat',"
+ "format=yuv422p10le[v]",
"-map": "[v]",
}
# 设置图像序列路径
decoder = FFdecoder(
"./imgs/image-%03d.png", frame_format="bgr24", verbose=True, **ffparams
).formulate()
output_params = {
"-input_framerate": 25,
}
writer = WriteGear(output_filename="output.mp4", **output_params)
for frame in decoder.generateFrame():
if frame is None:
break
writer.write(frame)
decoder.terminate()
writer.close()
此外Deffcode还支持添加各种艺术效果，具体方法可以阅读transcode-art-filtergraphs
3.4 视频属性数据更改
添加新属性
下面代码展示了读取视频后，往读取的属性数据中添加新的属性，注意该操作并不更改视频的实际属性数据。
from deffcode import FFdecoder
import json
decoder = FFdecoder("test.mp4", verbose=True)
# 设置字典数据
data = dict(
mystring="abcd",
myint=1234,
mylist=[1, "Rohan", ["inner_list"]],
mytuple=(1, "John", ("inner_tuple")),
mydict={"anotherstring": "hello"},
myjson=json.loads('{"name": "John", "age": 30, "city": "New York"}'),
)
# 分配视频的属性数据
decoder.metadata = data
decoder.formulate()
print(decoder.metadata)
decoder.terminate()
修改已有视频属性
在视频流解码前，可以设置视频流的属性数据，那么就会以更改后的属性解码图像。
from deffcode import FFdecoder
import cv2
decoder = FFdecoder("test.mp4", verbose=True)
# 替换属性数据，会以当前属性解码视频
decoder.metadata = {
"output_frames_pixfmt": "gray", # 灰度图
"source_video_resolution": [352, 288], # 宽高更改为352，288
}
decoder.formulate()
print(decoder.metadata)
for frame in decoder.generateFrame():
if frame is None:
break
cv2.imshow("Output gray", frame)
key = cv2.waitKey(1) & 0xFF
if key == ord("q"):
break
cv2.destroyAllWindows()
decoder.terminate()
4 参考
- deffcode
- deffcode_doc
- VidGear
- 雷霄骅
- Decoding Live Feed Devices
- Decoding Live Virtual Sources
- transcode-art-filtergraphs