Skip to main content
Version: 3.1.0

MpegEncoder

Class· Source

enc = mpegCoder.MpegEncoder()

The frame-level video encoder used for muxing a video file.

This encoder instance serves as a video file writer. It supports:

  • Encode a 3D np.ndarray as a video frame.
  • Configure the codec type and the video parameters.
  • Scaling the encoded video frames to a specific size.

MpegEncoder requires users to initialize the encoder before writing frames, and close the video after finishing all works. If the video is not closed manually, an automatical closing would be performed when the encoder is destructed. During the distruction, hitting Ctrl+C will cause the written video to break.

Arguments

This class does not has initialization arguments.

Methods

clear

enc.clear()

Clear all configurations including the default video path. If a video is opened by the encoder, clear() will close the video automatically.

tip

We suggest that users should call clear() manually, like using other file writers.


resetPath

enc.resetPath(videoPath)

Reset the default video path to a specific value. Configuring this value will not cause the video to be opened. This method is merely used as a configuration.

Requires

ArgumentTypeRequired
Description
videoPathstr or bytesThe path of the video to be written.

getParameter

param = enc.getParameter(paramName=None)

Get the video parameter or configuration value. Each time paramName only accepts one parameter name.

Requires

ArgumentTypeRequired
Description
paramNamestr or bytesThe name of the parameter to be checked. If not give, all important parameters, including some private parameters will be returned as a dict.

Here is a list of checkable paramName:

ParameterType
Description
videoPathstrThe current path of the written video. If the video is not opened, will return the default video path.
codecNamestrThe name of the encoder. See here to view a list of FFMpeg encoders. Note that not all encoders could be used, the avaliable encoders depends on the current FFMpeg built libraries.
nthreadintThe number of encoder threads.
bitRatefloatThe bit rate of the written video (Kb/s). This value determines the output video size directly.
widthintThe width of the written video. This value is mainly determined by the user configurations.
heightintThe height of the written video. This value is mainly determined by the user configurations.
widthSrcintThe width of the source frame. This value should be consistent with the size of the np.ndarray. If not given, will use width.
heightSrcintThe height of the source frame. This value should be consistent with the size of the np.ndarray. If not given, will use height.
GOPSizeintThe size of one GOP.
maxBframeintThe maximal number of consecutive B frames in a GOP. In most cases, this value could not be greater than 16.
frameRatefloatThe target frame rate of the written video. The unit is FPS.

Returns

ArgumentType
Description
paramDetermined by paramNameThe returned value of the parameter. If no paramName is given, will return all important parameters.

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
)

Set the configurations of the encoder. To make the configurations take effects, these parameters need to be configured before FFmpegSetup().

Requires

ArgumentTypeRequired
Description
decoderMpegDecoder or MpegClientWhen configure this argument, the required configurations will be copied from a decoder or a client. If users also provide duplicated arguments in the same call, these copied parameters have a lower preference than those specified by users. This argument is useful when trancoding a video.
configDictdictAn alternative of the argument decoder when the parameters need to be passed through different processes. Using configDict=decoder.getParameter() is equivalent to using decoder=decoder.
videoPathstrThe current path of the written video. If the video is not opened, will return the default video path.
codecNamestrThe name of the encoder. See here to view a list of FFMpeg encoders. Note that not all encoders could be used, the avaliable encoders depends on the current FFMpeg built libraries.
nthreadintThe number of encoder threads.
bitRatefloatThe bit rate of the written video (Kb/s). This value determines the output video size directly.
widthintThe width of the written video.
heightintThe height of the written video.
widthSrcintThe width of the source frame. This value should be consistent with the size of the np.ndarray. If not given, will use width.
heightSrcintThe height of the source frame. This value should be consistent with the size of the np.ndarray. If not given, will use height.
GOPSizeintThe size of one GOP.
maxBframeintThe maximal number of consecutive B frames in a GOP. In most cases, this value could not be greater than 16.
frameRatetupleThe target frame rate of the written video. This value should be a tuple of two ints: (numerator, denominator). This format is consistent with AVRational.

FFmpegSetup

enc.FFmpegSetup(videoPath=None)

Open the video file, and initialize the encoder. During the encoder initialization, the codec and the video format will be configured according to the file name and the user configurations set by setParameter(). If an video is being opened by the encoder now, this video will be closed first, then the new video will be opened with the same configurations.

Requires

ArgumentTypeRequired
Description
videoPathstr or bytesThe path of the video to be written. If not given, will use the default path configured by resetPath(). Setting this argument will also cause the default video path to change.

dumpFile

enc.dumpFile()

Print out a brief preview of the video meta-data to the standard output.

caution

This method is based on C stdout. Therefore, these results could not be redirected or catched by python.


EncodeFrame

is_success = enc.EncodeFrame(PyArrayFrame)

Encode one frame into the video. Note that in most cases, the frame will not be written to the file instantly. Instead of, the frames will be saved in a low-level buffer of the codec. Only when FFmpegClose() is called, the frames in the buffer will be flushed into the file.

Requires

ArgumentTypeRequired
Description
PyArrayFramenp.ndarrayAn array with a shape of (H, W, C), where (H, W) are the source height (heightSrc) and source width (widthSrc) respectively. C means the 3 RGB channel.

Returns

ArgumentType
Description
is_successboolThe status of the frame encoding. If the given frame succeeds to be encoded, will return True; Otherwise, will return False.

FFmpegClose

enc.FFmpegClose()

Close the video file. Calling this method will flush all buffered frames into the file. Then the video tail will be writen to the file. If users does not call this method explicitly, it will be called when clear() is called or when the encoder is destructed.

Operators

__str__

info = str(enc)

Return a brief report of the current encoder status.

Returns

ArgumentType
Description
infostrA brief report of the encoder status, the configurations and parameters will be listed as formatted texts.

Examples

See Transcoding in the tutorial. Here we also show some specific configurations:

Optimize the video encoding

...
dec = mpegCoder.MpegDecoder()
...
enc = mpegCoder.MpegEncoder()
enc.setParameter(decoder=dec, codecName='libx265', videoPath='test-video-x265.mp4', GOPSize=24, maxBframe=16)
...

Rescale and resample the video

...
enc = mpegCoder.MpegEncoder()
enc.setParameter(width=1280, height=720, frameRate=(5, 1), codecName='libx265', videoPath='test-video-x265.mp4')
...

Use the AV1 encoder

...
enc = mpegCoder.MpegEncoder()
enc.setParameter(width=1280, height=720, codecName='libsvtav1', videoPath='test-video-av1.mp4')
...

Use multi-thread encoding

...
enc = mpegCoder.MpegEncoder()
enc.setParameter(nthread=8)
...