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
| Argument | Type | Required | Description |
|---|---|---|---|
videoAddress | str or bytes | The 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
| 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 | The current address of the pushed video. If the video is not being pushed, will return the default video address. |
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. |
formatName | str | The video format name guessed from videoAddress. |
nthread | int | The number of encoder threads. |
bitRate | float | The bit rate of the pushed video stream (Kb/s). This value determines the served stream size directly. |
width | int | The width of the pushed video stream. This value is mainly determined by the user configurations. |
height | int | The height of the pushed video stream. 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 pushed video stream. The unit is FPS. |
waitRef | float | A 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(). |
ptsAhead | int | The 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
| Argument | Type | Description |
|---|---|---|
param | Determined by paramName | The 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
| 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. | |
videoAddress | str | The current address of the pushed video. If the video is not being pushed, will return the default video address. | |
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. | |
formatName | str | The video format name guessed from videoAddress. | |
nthread | int | The number of encoder threads. | |
bitRate | float | The bit rate of the pushed video stream (Kb/s). This value determines the served stream size directly. | |
width | int | The width of the pushed video stream. | |
height | int | The height of the pushed video stream. | |
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 pushed video stream. This value should be a tuple of two ints: (numerator, denominator). This format is consistent with AVRational. | |
frameAhead | int | The target ahead frame number. This value is used for controlling the number of served frames. For example, waitRef is calculated by the equation: , where , and are the number of pushed frames, the number of played frames and frameAhead respectively. 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
| Argument | Type | Required | Description |
|---|---|---|---|
videoAddress | str or bytes | The 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
| 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
| Argument | Type | Description |
|---|---|---|
is_success | bool | The 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
| 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
| Argument | Type | Description |
|---|---|---|
is_success | bool | The 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
| Argument | Type | Description |
|---|---|---|
info | str | A 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)
...