Skip to content

MpegEncoder.mdx

Latest commit

 

History

History
269 lines (189 loc) · 11.8 KB

MpegEncoder.mdx

File metadata and controls

269 lines (189 loc) · 11.8 KB
id MpegEncoder
title MpegEncoder
sidebar_label MpegEncoder
slug /apis/MpegEncoder
description This class has wrapped the C-API of FFMpeg encoder so that users could call its methods to encode frames by using numpy-data quickly.

import IconExternalLink from '@theme/IconExternalLink'; import InlineIcon from '@site/src/components/InlineIcon'; import vsiSymbolClass from '@iconify-icons/codicon/symbol-class'; import vsiCheckIcon from '@iconify-icons/codicon/check'; import octFileCode16 from '@iconify-icons/octicon/file-code-16'; import { SourceURL, Splitter } from '@site/src/envs/variables';

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 {#arguments}

This class does not has initialization arguments.

Methods {#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 {#requires}

Argument Type Required
Description
videoPath str or bytes The 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 {#requires}

Argument Type Required
Description
paramName str or bytes The 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:

Parameter Type
Description
videoPath str The current path of the written video. If the video is not opened, will return the default video path.
codecName str The 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.
nthread int The number of encoder threads.
bitRate float The bit rate of the written video (Kb/s). This value determines the output video size directly.
width int The width of the written video. This value is mainly determined by the user configurations.
height int The height of the written video. This value is mainly determined by the user configurations.
widthSrc int The width of the source frame. This value should be consistent with the size of the np.ndarray. If not given, will use width.
heightSrc int The height of the source frame. This value should be consistent with the size of the np.ndarray. If not given, will use height.
GOPSize int The size of one GOP.
maxBframe int The maximal number of consecutive B frames in a GOP. In most cases, this value could not be greater than 16.
frameRate float The target frame rate of the written video. The unit is FPS.

Returns {#returns}

Argument Type
Description
param Determined by paramName The 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 {#requires}

Argument Type Required
Description
decoder MpegDecoder or MpegClient When 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.
configDict dict An 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.
videoPath str The current path of the written video. If the video is not opened, will return the default video path.
codecName str The 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.
nthread int The number of encoder threads.
bitRate float The bit rate of the written video (Kb/s). This value determines the output video size directly.
width int The width of the written video.
height int The height of the written video.
widthSrc int The width of the source frame. This value should be consistent with the size of the np.ndarray. If not given, will use width.
heightSrc int The height of the source frame. This value should be consistent with the size of the np.ndarray. If not given, will use height.
GOPSize int The size of one GOP.
maxBframe int The maximal number of consecutive B frames in a GOP. In most cases, this value could not be greater than 16.
frameRate tuple The 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 {#requires}

Argument Type Required
Description
videoPath str or bytes The 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 {#requires}

Argument Type Required
Description
PyArrayFrame np.ndarray An 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 {#returns}

Argument Type
Description
is_success bool The 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 {#operators}

__str__

info = str(enc)

Return a brief report of the current encoder status.

Returns {#returns}

Argument Type
Description
info str A brief report of the encoder status, the configurations and parameters will be listed as formatted texts.

Examples {#examples}

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

Optimize the video encoding {#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 {#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 {#use-the-av1-encoder}

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

Use multi-thread encoding {#use-multi-thread-encoding}

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