Viz Engine Administrator Guide

Version 5.1 | Published November 09, 2023 ©

Matrox Stream

Viz Engine can send MPEG-TS over RTP and receive MPEG-TS over RTP/UDP, SRT, RTSP, RTMP streams by using DSX.Core or any Matrox board that has an RTP / RTP2 / STMP upgrade.

images/download/attachments/105087567/license.png

Important: MPEG-TS over RTP/UDP, SRT, RTSP, RTMP streaming require a Mezzanine IP license. Progressive formats are supported for output only. However, both progressive and interlaced formats are supported for input.
Also note, that RTP/UDP, SRT, RTSP, RTMP streaming inputs require Video I/O Mode Version 3 (Configuration/Video Board).

Features

Input

Output

Progressive

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/check.svg

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/check.svg

Interlaced

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/check.svg

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/error.svg

MPEG-TS over RTP

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/check.svg

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/check.svg

MPEG-TS over UDP

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/check.svg

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/error.svg

RTSP

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/check.svg

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/error.svg

RTMP

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/check.svg

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/error.svg

SRT

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/check.svg

images/s/-3kz4ly/8804/1yuue1v/_/images/icons/emoticons/error.svg

Note: Only H.264 video and AAC audio are supported. Moreover, only audio with two channels is supported. If a different audio characteristic is detected in the stream, the audio is ignored and only video is displayed.

Note: Since only broadcast resolution is supported and there is no framerate conversion between input and output, input and output framerates must match.

Matrox License

An RTP / RTP2 / STMP Matrox license is required in order to be able to receive any kind of stream. Which license is required depends on your existing license.

Important: The main board, the first one appearing in Matrox. Devices in the Viz Engine configuration file, must have decoding capabilities. A board has decoding capabilities if it is /500 or /550, or if it has any of the following upgrades: U50, U55 or STMP.

In order to receive a stream, one of the following streaming licenses is also required for the board:

  • RTP: Lets you receive any kind of stream except RTMP and MPEG-TS, since it lacks a demuxer.

  • RTP2: Lets you receive any kind of stream except MPEG-TS, since it lacks a demuxer.

  • STMP: Lets you receive any kind of stream.

Note: To be able to receive a stream, the license can be installed in a secondary board, it does not need to be installed in the main board.

Boards with decoding capabilities also support muxing and demuxing. For example, if a board has decoding capabilities (if it's /500, has U50 upgrade, etc.) and has an RTP license, the board is also able to receive MPEG-TS.

Boards with STMP do not need to have any other upgrades to be able to receive and decode streams; this license is usually used with /100 boards and when clip playback is not needed.

To summarize:

  • RTP / RTP2: Are only for receiving and do not provide decoding. Additional upgrades are therefore needed, usually in the form of U50 or U55.

  • STMP: Offers everything and is therefore usually paired with a /100 board.

There are exception to the above rules:

  • DSX.Core: By default supports any kind of stream except RTMP. However, to support decoding, the license should be at least /500.

  • M264: By default supports only video decoding. However, to support streaming, either of the following receiving licenses must be added: RTP / RTP2.

Example Matrox License Configuration

For a machine that has the following boards:

DSX.LE4L/8/100F with UPG/100/U55

M264/100 with UPG/RTP2

  • Choosing the DSX.LE4 as main board and the M264 as secondary board, the machine can:

    • Use the following input types: SDI, MPEG-TS over RTP/UDP, SRT, RTSP, RTMP, NDI, Clip.

    • Have SDI as output.

    • Use H.264 hardware decoding to decode the incoming streams.

  • Choosing only DSX.LE4 as main board and no secondary board, the machine can:

    • Use the following input types: SDI, NDI, Clip.

    • Have SDI as output.

  • Choosing only M264 as main board and no secondary board, the machine can:

    • Use the following input types: SRT, RTSP, RTMP, NDI, Clip (only uncompressed clips).

    • Audio decoding is not supported.

Note: In the case of a M264 main board, the machine does NOT have any output since RTP requires a muxer, which is only provided in a board with /500 /550 or upgrades U50, U55 or STMP. The machine does NOT support audio decoding or receiving MPEG-TS over RTP/UDP for the same reason.

Output Mode

There are two different output modes: SDI or RTP. To enable output to SDI, a Matrox board supporting SDI is needed and must be chosen in the configuration file: Matrox.Devices = A520888.

If the SDI board does not support an RTP upgrade, another board must be installed and must be included as a secondary board: Matrox.Devices = A520888, A520898.

If the main board, the first one appearing in Matrox.Devices, has the corresponding Matrox license to support RTP, then RTP output can be enabled.
To do so, change the entry RtpOut1.Enable in the config file to 1.

RtpOut1.Enable = 1

Also specify a Time server in the config file

It is also recommended to set an NTP time server: ntp_server = 131.107.13.100

Info: SDI Out, NDI Out, RTP output can be enabled at the same time.

Configuring a Stream

A stream can now be configured using the GUI interface under Live Input:

images/download/attachments/105087567/Screenshot_2022-07-28_085536.png

The only thing that differentiates different type of streams are their URLs:

rtp://localhost:22404
udp://localhost:22200?pkt_size=1316
srt://localhost:2345
rtsp://localhost:8554/mystream
rtmp://localhost:30000/live/1

The best way to test the functionality of a stream is by using ffmpeg. ffmpeg supports the sending of simple pattern that allows us to do basic sanity test.

Note: Even if a stream is being sent on localhost it is advisable to use one of the NIC as IP since otherwise it could cause problems. This issue is only known to happen to RTP stream.

Example Sending MPEG-TS over RTP and Receiving with Viz Engine on localhost

The following command can be used to simulate a source:

ffmpeg.exe -f lavfi -re -i smptehdbars=s=1280x720:r=60[out0] -c:v libx264 -profile:v high422 -pix_fmt yuv422p -x264-params "nal-hrd=cbr" -b:v 2M -minrate 2M -maxrate 2M -bufsize 2M -f rtp_mpegts -bsf:v h264_mp4toannexb "rtp://10.251.2.32:22404"

Viz Engine can then be configured with:

live_type1 = STREAM
live_system1 = 720P_6000_SMPTE296
LiveIn1.Url = rtp://10.251.2.32:22404
LiveIn1.NICAddress = 10.251.2.32

In this case, since we are sending to localhost, NIC address can be any of the installed network adapter IP. As mentioned previously, this configuration can be done via GUI.

Example Receiving MPEG-TS over UDP on localhost

The following command can be used to simulate a source:

ffmpeg.exe -f lavfi -re -i smptehdbars=s=1280x720:r=60[out0] -c:v libx264 -profile:v high422 -pix_fmt yuv422p -x264-params "nal-hrd=cbr" -b:v 2M -minrate 2M -maxrate 2M -bufsize 2M -f mpegts -bsf:v h264_mp4toannexb "udp://10.251.2.32:22404?pkt_size=1316"

Viz Engine can then be configured with:

live_type1 = STREAM
live_system1 = 720P_6000_SMPTE296
LiveIn1.Url = udp://10.251.2.32:22404
LiveIn1.NICAddress = 10.251.2.32

In this case, since we are sending to localhost, NIC address can be any of the installed network adapter IP. As mentioned previously, this configuration can be done via GUI.

Example Receiving SRT on localhost

For this srt-live-transmit is needed to wrap a UDP stream. First, send the UDP stream as described in the example above and then run the following:

srt-live-transmit "udp://10.251.2.32:22200?pkt_size=1316" srt://10.251.2.32:2345

Viz Engine can then be configured with:

live_type1 = STREAM
live_system1 = 720P_6000_SMPTE296
LiveIn1.Url = srt://10.251.2.32:2345
LiveIn1.NICAddress = 10.251.2.32

In this case, since we are sending to localhost, NIC address can be any of the installed network adapter IP. As mentioned previously, this configuration can be done via GUI.

Example Receiving RTSP on localhost

For this an RTSP server is needed. rtsp-simple-server is probably easiest way to get an RTSP server. After running the server run the following:

ffmpeg.exe -f lavfi -re -stream_loop -1 -i smptehdbars=s=1280x720:r=60[out0] -c:v libx264 -profile:v high422 -pix_fmt yuv422p -x264-params "nal-hrd=cbr" -b:v 2M -maxrate 2M -minrate 2M -bufsize 2M -f rtsp rtsp://10.251.2.32:8554/mystream -rtsp_transport tcp

The URL and port depend on how nginx has been configured.

Viz Engine can then be configured with:

live_type1 = STREAM
live_system1 = 720P_6000_SMPTE296
LiveIn1.Url = srt://10.251.2.32:2345
LiveIn1.NICAddress = 10.251.2.32
LiveIn1.SrcUdpPort = 22200

In this case, since we are sending to localhost, NIC address can be any of the installed network adapter IP. As mentioned previously, this configuration can be done via GUI.

For receiving multiple RTSP stream the configuration SrcUdpPort must be different for each of them. This port number should also be separated by 4. In this example, the next live would be, LiveIn2.SrcUdpPort = 22204.

Example Receiving RTMP on localhost

For this an RTMP sever is needed. nginx is probably easiest way to get an RTMP server. After running the server run the following:

ffmpeg.exe -f lavfi -re -stream_loop -1 -i smptehdbars=s=1280x720:r=60[out0] -c:v libx264 -profile:v high422 -pix_fmt yuv422p -x264-params "nal-hrd=cbr" -b:v 2M -maxrate 2M -minrate 2M -bufsize 2M -f flv rtmp://10.251.2.32:30000/live/1

The URL and port depend on how nginx has been configured. Viz Engine can then be configured with:

live_type1 = STREAM
live_system1 = 720P_6000_SMPTE296
LiveIn1.Url = rtmp://10.251.2.32:30000/live/1
LiveIn1.NICAddress = 10.251.2.32

In this case, since we are sending to localhost, NIC address can be any of the installed network adapter IP. As mentioned previously, this configuration can be done via GUI.

For receiving multiple RTSP stream the configuration SrcUdpPort must be different for each of them. This port number should also be separated by 4. In this example, the next live would be, LiveIn2.SrcUdpPort = 22204.

More Advanced Example Using ffmpeg

It is possible to send clip content using ffmpeg and receive this on the Viz Engine. The clip must be first transcoded to a format that is supported by Viz Engine. This can be done in the following way:

ffmpeg.exe -i "clip_input.mp4" -filter:v "fps=fps=60,scale=1280:720,setdar=16/9"-minrate 2M -maxrate 2M -bufsize 2M -vcodec libx264 -preset slow -ac 2 -ab 320k -acodec aac -strict -2 -t 00:05:00 "clip_output.mp4"

The above command generates a clip that Viz Engine can support. It also makes sure that the audio is two channels and has a constant bit rate. The generated clip can then be send using the same commands as described in the previous sections.

It is also possible to use CUDA with ffmpeg to reduce the CPU usage in case testing multiple sources is needed:

ffmpeg -vsync 0 -c:v h264_cuvid -re -stream_loop -1 -i clip_output.mp4 -c:v h264_nvenc -profile:v high422 -pix_fmt yuv422p -x264-params "nal-hrd=cbr" -b:a 320k -acodec aac -strict -2 -b:v 2M -maxrate 2M -minrate 2M -bufsize 2M -f rtsp rtsp://10.251.2.32:8554/mystream -rtsp_transport tcp

When sending it is advice to force the audio bit rate to constant even if the clip itself is already.

Receiving Different Input Types

It is possible to combine different input types in the same scene. The possible input types are: SDI / IP 2110, MPEG-TS over RTP/UDP, SRT, RTSP, RTMP, NDI, Clip.

Limitations

There are a lot of factors that must be taken into account to know how many streams can be received into the engine. However the following hard limit is good to have in mind. The engine might be able to receive up to 16x1080p60 streams. To achieve this the Engine/system must have the following minimum requirements:

  • P6000 or superior.

  • M264S2 or superior.

  • threaded_io configuration must be enabled on the configuration.

  • Network must be free from congestion.

  • Stream must be 4:2:0 8-bit Long GOP.

  • The scene must be simple.

Receiving 16x1080p60 is the absolute upper limit and use most of the system resources. There is no guarantee that this can be achieved since there are too many variables in place.

Known Issues and Troubleshooting

  • Artifacts: This is usually due to the characteristics of the stream (decoding parameters such as GOP size, bandwidth size, buffer size, etc.). The best way to know if the stream or the network is the issue, is to use ffplay and try to receive the stream with it. ffplay usually throws a lot of errors and it also shows the stream with artifacts. If this is the case we know the issue is in the source.

  • Can not receive stream: Try to receive the stream first with ffplay.