Skip to main content
Version: 3.2.x

MpegServer

Class· Source

sev = mpegCoder.MpegServer()

The frame-level video stream service used for pushing an online video stream.

This service instance is integrated with the features of MpegEncoder. Like the FFMpeg CLI usages, MpegServer could not be run independently. A server program is required to be launched before the instance getting set up. We recommend some server programs here.

In practice, we recommend to split this instance into a sub-process, and use the multiprocessing to feed the served data. See the tutorial to find the example. Although this class also provides a non-blocking style API, we do not recommend users to use that.

Arguments

This class does not has initialization arguments.

Methods

clear

sev.clear()

Clear all configurations including the default video address. If a video is being pushed by the server, clear() will close the video automatically, and release the connection to the server.

tip

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


resetPath

sev.resetPath(videoAddress)

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

Requires

ArgumentTypeRequired
Description
videoAddressstr or bytesThe address of the video stream to be pushed.

getParameter

param = sev.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
videoAddressstrThe current address of the pushed video. If the video is not being pushed, will return the default video address.
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.
formatNamestrThe video format name guessed from videoAddress.
nthreadintThe number of encoder threads.
bitRatefloatThe bit rate of the pushed video stream (Kb/s). This value determines the served stream size directly.
widthintThe width of the pushed video stream. This value is mainly determined by the user configurations.
heightintThe height of the pushed video stream. 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 pushed video stream. The unit is FPS.
waitReffloatA wait reference with the unit of second. This value represents how long users need to wait from this moment before pushing the next video frame. This value is required to be used with the non-blocking API ServeFrame().
ptsAheadintThe target ahead time duration in the unit of time stamp. This value is used for controlling the amount of waitRef and the waiting time of the blocking API. It is converted from the configuration frameAhead.

Returns

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

setParameter

sev.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, frameAhead=None
)

Set the configurations of the server. 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.
videoAddressstrThe current address of the pushed video. If the video is not being pushed, will return the default video address.
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.
formatNamestrThe video format name guessed from videoAddress.
nthreadintThe number of encoder threads.
bitRatefloatThe bit rate of the pushed video stream (Kb/s). This value determines the served stream size directly.
widthintThe width of the pushed video stream.
heightintThe height of the pushed video stream.
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 pushed video stream. This value should be a tuple of two ints: (numerator, denominator). This format is consistent with AVRational.
frameAheadintThe target ahead frame number. This value is used for controlling the number of served frames. For example, waitRef is calculated by the equation: Nw=T×max(NpushedNplayedNahead, 0)N_w = T \times \max(N_{pushed} - N_{played} - N_{ahead},~ 0), where NpushedN_{pushed}, NplayedN_{played} and NaheadN_{ahead} are the number of pushed frames, the number of played frames and frameAhead respectively. TT is the time base. By this way, the waitRef and the waiting time of the blocking API ServeFrameBlock() will be controlled by this value. Users do not need to specify it explicitly, because it could be calculated from the configured GOPSize.

FFmpegSetup

sev.FFmpegSetup(videoAddress=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 protocol used by the serving address and the user configurations set by setParameter(). If an video is being pushed by the server now, this video will be disconnected and released first, then the new video will be pushed with the same configurations.

Requires

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

dumpFile

sev.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.


ServeFrame

is_success = sev.ServeFrame(PyArrayFrame)

Push one frame to the video stream. Note that in most cases, the frame will not be pushed 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 stream. But the writting to the codec buffer will be finished instantly.

This is the non-blocking API, which means the current thread will be only blocked by the frame encoding operations. Users need to use this API with getParameter('waitRef') to control the number of served frames. Otherwise, serving too many frames will make the data to be dropped or cause the video server to collapse. The example about how to correctly use this API could be found here.

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 pushing. If the given frame succeeds to be encoded and pushed, will return True; Otherwise, will return False.

ServeFrameBlock

is_success = sev.ServeFrameBlock(PyArrayFrame)

Push one frame to the video stream. Note that in most cases, the frame will not be pushed 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 stream. The writting and pushing speeds to the codec buffer are controlled by user configurations.

This is the recommended blocking API, which means the method will cause the current thread blocked if the served frames are ahead of the playing time too much. In this case, the method will wait until the playing time catch the half of the served but not played frames. This method will ensure the safety of the video server.

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 pushing. If the given frame succeeds to be encoded and pushed, will return True; Otherwise, will return False.

FFmpegClose

sev.FFmpegClose()

Close the video stream and release the connection. Calling this method will flush all buffered frames into the video stream. In some cases, the video tail will be writen to the stream. If users does not call this method explicitly, it will be called when clear() is called or when the server is destructed.

Operators

__str__

info = str(sev)

Return a brief report of the current stream encoder status.

Returns

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

Examples

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

Optimize the video encoding

...
dec = mpegCoder.MpegDecoder()
...
sev = mpegCoder.MpegServer()
sev.setParameter(decoder=dec, codecName='libx265', videoAddress='rtsp://localhost:8554/video', GOPSize=24, maxBframe=16)
...

Rescale and resample the video

...
sev = mpegCoder.MpegServer()
sev.setParameter(width=1280, height=720, frameRate=(5, 1), GOPSize=12, codecName='libx265', videoAddress='rtsp://localhost:8554/video')
...

Use multi-thread encoding

...
sev = mpegCoder.MpegServer()
sev.setParameter(width=1280, height=720, GOPSize=12, nthread=8, videoAddress='rtsp://localhost:8554/video')
...

Configure the ahead frame number manually

...
sev = mpegCoder.MpegServer()
sev.setParameter(decoder=d, codecName='libx265', videoAddress='rtsp://localhost:8554/video', GOPSize=24, frameAhead=48)
...