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
| Argument | Type | Required | Description |
|---|---|---|---|
videoAddress | str or bytes | The 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
| 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 |
|---|---|---|
videoAddress | str or bytes | The current address of the read video. If the video stream is not opened, will return the default video address. |
width | int | The width of the read video. This value is determined by the video stream. |
height | int | The height of the read video. This value is determined by the video stream. |
frameCount | int | The number of returned frames in the last frame extraction method. |
coderName | str | The name of the codec used for decoding the video. |
nthread | int | The number of decoder threads. |
duration | float | The total seconds of this video. |
estFrameNum | int | The estimated total frame number (may be not accurate). |
srcFrameRate | float | The average frame rate of the source video stream. The unit is FPS. The actual frame rate may be changed on client side. |
Returns
| Argument | Type | Description |
|---|---|---|
param | Determined by paramName | The 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
| Argument | Type | Required | Description |
|---|---|---|---|
widthDst | int | The 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. | |
heightDst | int | The 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. | |
cacheSize | int | The number of allocated avaliable frames in the cache. We recommend to configure this value as 2*readSize. | |
dstFrameRate | tuple | The 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. | |
nthread | int | The 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
| Argument | Type | Required | Description |
|---|---|---|---|
videoAddress | str or bytes | The 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
| Argument | Type | Required | Description |
|---|---|---|---|
readSize | int | The number of the frames to be read. If configured as <=0, will use the default readSize configured by setParameter(). |
Returns
| Argument | Type | Description |
|---|---|---|
frames | np.ndarray | An 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
| Argument | Type | Description |
|---|---|---|
info | str | A 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)
...