Skip to main content
Version: 3.2.x

MpegClient

Class· Source

cln = mpegCoder.MpegClient()

The frame-level video stream client used for demuxing an online video stream.

This client instance is integrated with the features of MpegDecoder. The connection to the video server is established by FFmpegSetup(). When the client is working, it will manage a background sub-thread for fetching the remote frames consecutively. The fetched frames are saved in a circular buffer. The method ExtractFrame() always return the latest received frames. To learn more details, please review the description of the theory.

MpegClient requires users to initialize the decoding before reading frames, and close the video after finishing all works. If the video is not closed manually, an automatical closing would be performed when the client is destructed. MpegClient also supports threading control. When the client is connected to the server, users could use start() to keep the buffer synchronized with the video stream. Calling terminate() will force the buffer updating to stop. In this case, the method ExtractFrame() will always return the same results.

Arguments

This class does not has initialization arguments.

Methods

clear

cln.clear()

Clear all configurations except the default video address. If a video stream is alredy opened, clear() will release the connection automatically.

tip

We suggest that users should call clear() manually, like using other file readers. No matter when start() is called, this method could be used safely without calling terminate().


resetPath

cln.resetPath(videoAddress)

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

Requires

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

getParameter

param = cln.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
videoAddressstr or bytesThe current address of the read video. If the video stream is not opened, will return the default video address.
widthintThe width of the read video. This value is determined by the video stream.
heightintThe height of the read video. This value is determined by the video stream.
frameCountintThe number of returned frames in the last frame extraction method.
coderNamestrThe name of the codec used for decoding the video.
nthreadintThe number of decoder threads.
durationfloatThe total seconds of this video.
estFrameNumintThe estimated total frame number (may be not accurate).
srcFrameRatefloatThe average frame rate of the source video stream. The unit is FPS. The actual frame rate may be changed on client side.

Returns

ArgumentType
Description
paramDetermined by paramNameThe returned value of the parameter. If no paramName is given, will return all important parameters. These parameters could serve as configDict for MpegEncoder and MpegServer.

setParameter

cln.setParameter(widthDst=None, heightDst=None, cacheSize=None, readSize=None, dstFrameRate=None, nthread=None)

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

Requires

ArgumentTypeRequired
Description
widthDstintThe width of extracted frames. Configuring both widthDst and heightDst will cause the frames to be scaled. If a value <=0 is given, this value would take no effect.
heightDstintThe height of extracted frames. Configuring both widthDst and heightDst will cause the frames to be scaled. If a value <=0 is given, this value would take no effect.
cacheSizeintThe number of allocated avaliable frames in the cache. We recommend to configure this value as 2*readSize.
dstFrameRatetupleThe destination FPS of the stream. This value should be formatted as a factor defined as (numerator, denominator). Configuing this value will cause the received frames to be resampled.
nthreadintThe number of decoder threads.

FFmpegSetup

cln.FFmpegSetup(videoAddress=None)

Open the online video stream, and initialize the decoder. After the client initialized, the video parameters will be loaded, the video format will be parsed and the video codec will be detected automatically. If an video stream connection is established by the client now, this connection will be released first, then the new video stream will be opened.

Requires

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

dumpFile

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


start

cln.start()

Start the demuxing thread. The started sub-thread will keep receiving remote frames to ensure the client buffer is synchronized with the online video stream.

caution

This method must be called after FFmpegSetup(). Once this method is called, users are not allowed to call it again until terminate() is called or the client is restarted by FFmpegSetup().


terminate

cln.terminate()

Terminate the current demuxing thread. This method is required to be called after start(). It will stop the frame receiving, and make the played video to be "paused". In this case, the frame receiving could be started again by start().

caution

This method must be called after FFmpegSetup(). Calling this method will not cause the current connection aborted. Only clear() could release the connection explicitly.


ExtractFrame

frames = cln.ExtractFrame(readSize=0)

Read the latest several frames from the circular buffer.

This method is merely a reading method, and not decode frames. Instead, the decoding is managed by the sub-thread. ExtractFrame() always fetch the several frames that are latestly decoded. Even terminate() is called, this method could be still used safely.

Requires

ArgumentTypeRequired
Description
readSizeintThe number of the frames to be read. If configured as <=0, will use the default readSize configured by setParameter().

Returns

ArgumentType
Description
framesnp.ndarrayAn array with a shape of (N, H, W, C), where N is given by readSize (no matter whether the video reaches its end), (H, W) are the height and width of the returned frames respectively. C means the 3 RGB channel. If no valid frames are received, this method would return several frames that are totally black.

Operators

__str__

info = str(cln)

Return a brief report of the current client status.

Returns

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

Examples

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

Scale the decoded frame

...
cln = mpegCoder.MpegClient()
cln.setParameter(widthDst=720, heightDst=486)
...

Configure the cache size

...
cln = mpegCoder.MpegClient()
# Assume that the source frame rate is 29.997
cln.setParameter(readSize=30, cacheSize=60)
...

Use multi-thread decoding

...
cln = mpegCoder.MpegClient()
cln.setParameter(nthread=8)
...