MpegEncoder
Class· Source
enc = mpegCoder.MpegEncoder()
帧尺度的视频编码器，用于混流并编码视频文件。
该编码器实例可以被看做是一个文件写入器，其支持：
- 将
np.ndarray编码成视频帧。 - 设置编码器的种类以及视频参数。
- 将输入的矩阵缩放为指定大小的视频帧。
MpegEncoder要求用户在写入视频帧之前，初始化视频编码器，并确保在一切工作结束后，关闭编码器。如果编码器没有被手动（显式地）关闭，则会在实例析构的时候，自动检查、并调用关闭视频的方法。在析构过程中，如果手动触发Ctrl+C中止析构，会导致输出的视频损坏。
参数
该类不提供初始化参数。
方法
clear
enc.clear()
清除包括默认视频路径之外的所有设置、参数。如果该方法调用的时候，该编码器已经打开了一个视频，clear()就会自动关闭该视频。
tip
就像使用其他的文件写入类一样，建议用户总是手动调用clear()。
resetPath
enc.resetPath(videoPath)
将默认的视频路径重置为给定的值。该方法仅仅用于设置参数，不会打开视频。
输入
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
videoPath | str或bytes | 待写入视频的路径。 |
getParameter
param = enc.getParameter(paramName=None)
获取视频参数或设置值。每次调用时，paramName仅能接受一个参数名。
输入
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
paramName | str或bytes | 待检查的参数名字。如果没有给定，则所有的重要参数（包括一小部分私有参数）会被收集并返回成一个dict。 |
接下来列出可以被索引的paramName:
| 参数 | 类型 | 说明 |
|---|---|---|
videoPath | str | 当前写入的视频路径。若视频尚未打开，则会返回默认视频路径。 |
codecName | str | 编码器(codec)的名字，所有可用的FFMpeg编码器列表参见此文档。需要特别注意的是，并非所有的编码器都是可用的，实际哪些编码器可用，取决于当前使用的FFMpeg依赖库的编译情况。 |
nthread | int | 编码用的线程数。 |
bitRate | float | 所写入视频的比特率（单位为Kb/s）。该值可以直接决定输出视频的文件大小。 |
width | int | 所写入视频的宽度。该值主要由用户设置所决定。 |
height | int | 所写入视频的高度。该值主要由用户设置所决定。 |
widthSrc | int | 给定的原始输入帧的宽度。该值必须和写入的矩阵np.ndarray大小保持一致。如果没有指定，则会使用width。 |
heightSrc | int | 给定的原始输入帧的高度。该值必须和写入的矩阵np.ndarray大小保持一致。如果没有指定，则会使用height。 |
GOPSize | int | 每个画面组(GOP)的大小。 |
maxBframe | int | 在每个画面组内，所出现的连续的B帧的帧数的最大值。在绝大多数情况下，该值无法超过16。 |
frameRate | float | 所写入视频的目标帧率（单位为FPS）。 |
输出
| 参数 | 类型 | 说明 |
|---|---|---|
param | 由paramName决定 | 返回的参数值。若函数调用时未提供paramName，则会收集所有重要的参数。 |
setParameter
enc.setParameter(
decoder=None, configDict=None, videoPath=None, codecName=None,
nthread=None, bitRate=None, width=None, height=None, widthSrc=None, heightSrc=None,
GOPSize=None, maxBframe=None, frameRate=None
)
设置编码器。该方法仅当调用于FFmpegSetup()之前才会生效。
输入
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
decoder | MpegDecoder或MpegClient | 若设置该值，则必要的参数会从给定的解码器或客户端实例里拷贝。如果同次调用里还重复指定了其他参数，这些拷贝所得的参数优先级低于用户特别指定的参数。该参数在转码视频的时候特别有用。 | |
configDict | dict | 当参数需要跨越子进程从其他编码器或客户端传递给此实例时，用于替代decoder参数的方案。使用形如configDict=decoder.getParameter()的方式等价于使用decoder=decoder参数。 | |
videoPath | str | 当前正在写入视频的路径。如果视频文件没有打开，则相当于默认视频路径。 | |
codecName | str | 编码器(codec)的名字，所有可用的FFMpeg编码器列表参见此文档。需要特别注意的是，并非所有的编码器都是可用的，实际哪些编码器可用，取决于当前使用的FFMpeg依赖库的编译情况。 | |
nthread | int | 编码用的线程数。 | |
bitRate | float | 所写入视频的比特率（单位为Kb/s）。该值可以直接决定输出视频的文件大小。 | |
width | int | 所写入视频的宽度。 | |
height | int | 所写入视频的高度。 | |
widthSrc | int | 给定的原始输入帧的宽度。该值必须和写入的矩阵np.ndarray大小保持一致。如果没有指定，则会使用width。 | |
heightSrc | int | 给定的原始输入帧的高度。该值必须和写入的矩阵np.ndarray大小保持一致。如果没有指定，则会使用height。 | |
GOPSize | int | 每个画面组(GOP)的大小。 | |
maxBframe | int | 在每个画面组内，所出现的连续的B帧的帧数的最大值。在绝大多数情况下，该值无法超过16。 | |
frameRate | tuple | 所写入视频的目标帧率。该值需要是一个由两个int构成的tuple： (分子, 分母)。 此格式是为了和AVRational保持一致。 |
FFmpegSetup
enc.FFmpegSetup(videoPath=None)
打开视频文件，并初始化编码器。编码器初始化的过程中，所用编码方式(codec)和视频格式(例如mp4,flv)将会从用户利用setParameter()指定的参数设置、以及文件名称检出。如果调用该方法时，已经打开了一个视频文件，则该文件会先被关闭，然后再以相同设置开启由该方法打开的视频。
输入
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
videoPath | str或bytes | 当前写入的视频路径。若该值没有给定，则会使用resetPath()所设置的默认视频路径。设置该参数同时也会使得默认视频路径改变。 |
dumpFile
enc.dumpFile()
将视频元数据的概览显示在标准输出上。
caution
该方法的显示基于C的标准输出。因此，这些输出无法被python抓取或重定向。
EncodeFrame
is_success = enc.EncodeFrame(PyArrayFrame)
将一帧编码到视频中。在绝大多数情况下，该帧将不会被马上写入到文件里，而是先存放在编码器(codec)管理的底层缓存里。只有在FFmpegClose()被调用的时候，缓存内的帧才会刷入（flush）到视频之内。
输入
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
PyArrayFrame | np.ndarray | 一个形状为(H, W, C)的数组，其中(H, W)分别为源帧的高度（heightSrc）和宽度（widthSrc）。 C代表3个RGB通道。 |
输出
| 参数 | 类型 | 说明 |
|---|---|---|
is_success | bool | 帧编码的状态。如果给定的帧成功地编码到视频之内，则返回True，否则，返回False。 |
FFmpegClose
enc.FFmpegClose()
关闭视频文件，调用该方法会使得所有缓存内的帧被编码、并刷入（flush）到视频文件中。此后，编码器会为视频写入文件尾（video tail）。如果用户没有显式调用该方法，则会被clear()隐式调用，或者在编码器实例析构的时候隐式调用。
操作符
__str__
info = str(enc)
返回当前编码器状态的简要报告。
输出
| 参数 | 类型 | 说明 |
|---|---|---|
info | str | 当前编码器状态的简报。编码器的设置和参数会以格式化字符串的形式展示。 |
范例
参见教程中的转码一节。接下来展示几种常用参数设置：
优化视频编码
...
dec = mpegCoder.MpegDecoder()
...
enc = mpegCoder.MpegEncoder()
enc.setParameter(decoder=dec, codecName='libx265', videoPath='test-video-x265.mp4', GOPSize=24, maxBframe=16)
...
缩放、并重采样视频
...
enc = mpegCoder.MpegEncoder()
enc.setParameter(width=1280, height=720, frameRate=(5, 1), codecName='libx265', videoPath='test-video-x265.mp4')
...
使用AV1编码器
...
enc = mpegCoder.MpegEncoder()
enc.setParameter(width=1280, height=720, codecName='libsvtav1', videoPath='test-video-av1.mp4')
...
多线程编码
...
enc = mpegCoder.MpegEncoder()
enc.setParameter(nthread=8)
...