====== Using Live Video in Blocks ======

To use live video:

  - Create a Live Video root block, or…
  - Add Live Video as a child block to a Composition or other suitable type.
  - Chose the desired stream type and other settings.
  - Specify the URL to the camera/streaming box (does not apply to local video input).

===== Live Video Formats =====

The following formats are supported:

  - RTSP stream. Compatible with most players. Supports audio. Low delay. Supported by most video cameras and streaming boxes.
  - RTMP stream. Compatible with most players. Supports audio. Supported by most streaming programs and many streaming devices.
  - Local Video In. Compatible with Pixilab player v4.0. Supports audio. Very low latency. Suitable for live camera feeds.
  - HLS stream: Compatible with most players. Supports audio. Delay is several seconds. Supported by some streaming boxes and services.
  - MJPEG stream. Compatible with most players. No audio. Low delay. Supported by many video cameras.
  - JPEG polling. Compatible with all players. No audio. Low delay. Supported by some video cameras.

As you can see, there are pros and cons with the various formats, and it is sometimes not straightforward to find the ideal combination for a given source device and player combination.


==== RTSP Stream ====

This format is supported by most cameras and streaming boxes, and (since Blocks 4) by PIXILAB Player and most browsers. The Kiloview KV-E2 works well for converting HDMI inputs to RTSP.

https://www.streamingvalley.nl/product/kiloview-e2-hdmi-h264-srt-video-encoder/

A similar box from the same manufacturer accepts SDI instead of HDMI.

{{ :blocks:blocks:video:kiloview-e1-4.jpg?nolink |}}

To minimize latency, chose a small custom GOP size (for example 5 frames), or a single frame only (only I-frames). When choosing a smaller GOP structure, the bitrate may need to be increased to maintain video quality. However, keep in mind that a higher bitrate puts more load onto the Blocks server, as it re-packages and distributes the stream, as well as on the network for distributing it. This is especially true when using numerous players simultaneously. 

==== RTMP Stream ====

RTMP, while similar in some ways to RTSP, works with other types of devices and programs such as [[https://obsproject.com|OBS]] and [[https://www.vmix.com|vMix]], as well as some hardware devices, like the popular [[blocks:live-video:atem-mini|ATEM Mini Pro]] from Blackmagic.

One notable caveat with RTMP, that makes it different from the other streaming formats supported by Blocks is the way the connection is made between the RTMP source and Blocks. RTMP expects the external device to make the connection to Blocks, and "push" the video to Blocks. This is the opposite of RTSP, where Blocks takes the initiative of connecting to the camera, essentially "pulling" the video stream from its source when it's requested by a Spot.

This difference means that some streaming sources may have trouble connecting to Blocks unless Blocks is already expecting the stream, as Blocks won't "listen" for the stream until requested by a Spot. Some devices, such as the ATEM Mini Pro and the [[https://www.streamingvalley.nl/product/kiloview-e2-hdmi-h264-srt-video-encoder/|Kiloview]] streaming box, is OK with that and will just keep attempting to connect until it succeeds. Other sources, such as OBS, will just display an error message when trying to connect unless the Blocks is actively listening for that connection.

Thus, to use a streaming source that expects the server to listen before it will try to connect, do one of the following:

  * Wait with starting the streaming source until you know there's at least one Spot requesting the video.
  * Keep an extra "monitor Spot" displaying the live feed all the time.

The second of these options essentially makes sure that Blocks is always actively listening for the stream, even if no other spot is yet showing it.

Finally, due to the direction the stream is flowing in, you need to set up the stream URL at the streaming //source//, pointing it to the Blocks server using its address. Thus, if Blocks runs on 10.2.0.10, your would use a stream URL like this on the streaming source:

<code>
rtmp://10.2.0.10
</code> 

In Blocks, you can typically leave this set to the default URL, which means that the Blocks server will listen for this stream on all its network interfaces (if it has more than one). The default URL is

<code>rtmp://0.0.0.0</code>

To use multiple RTMP streams at the same time, add a port number after the IP address, separated by a colon. The default port number used by RTMP is 1935.

==== Local Video In ====

Blocks 4 and later supports local video, captured by a [[https://en.wikipedia.org/wiki/USB_video_device_class|UVC]] adapter connected to a USB port of a PIXILAB Player (version 4 or later). THis method results in very low latency – at most a few frames. Not all adapters will work, however, so either go with one of the recommended devices listed below, or test the adapter well in advance. You can only use //one// such local adapter/camera, and the video fed through this adapter can only be shown on the player to which is connected.

Web browser have restrictions for accessing a local video camera/source, and require specific settings to allow this without user intervention. PIXILAB Player is pre-configured to allow this when used with the //pixi.guide// domain name and the Chrome browser. These settings are found in the browser policy settings. If you need to use another domain name or a raw IP address, follow [[blocks:porteus_kiosk#manage_pixilab_player_chrome_policies_from_the_blocks_server|this guide]].)

The following adapters hage been used successfully. 

  * Inogeni 4K HDMI to USB 3.0
  * Magwell USB Capture HDMI Gen 2


==== HLS Stream ====

HLS is generally a good format as far as players are concerned, with good quality, scalability and audio. In some applications, the rather long delay (often several to more than ten seconds) associated with this format may be problematic. Finally, support for HLS is  limited on cameras and streaming boxes.

The [[https://www.aja.com/products/helo |AJA HELO]] is one hardware option for bringing HLS into a Blocks system.

{{ :blocks:blocks:video:aja-helo-h264-streamer-recorder.jpg?nolink |}}

It accepts SDI, HDMI and analog audio as inputs (with passthrough), and converts it to various streaming formats, with the option of simultaneous recording of the stream to a memory card. More on HLS streaming and the Helo device below.

==== MJPEG Stream ====

This format is also supported by many players, and is commonly supported by cameras as well. It typically has very low delay, but doesn't support audio. Some cameras may protect the MJPEG url with authentication, which then needs to be disabled for Blocks to access the stream.

==== JPEG Polling ====

This format has many similarities with MJPEG in that it has low delay, good player compatibility and no audio. It incurs a higher overhead, in that each image is fetched separately. This may also occasionally result in dropped frames.

It is supported by some network cameras, such as the Unifi line of cameras (which do not support MJPEG). Like MJPEG, you may need to disable any authentication in the camera for Blocks to be able to read the URL.

{{ :blocks:blocks:video:unifi-video-g3-flex-camera.jpg?nolink |}}


===== HLS Streaming Options =====

HLS is one of the oldest, and best supported, web streaming formats. It's compatible with pretty much all players, has very scalable performance, full frame rate and includes audio. The downside, as mentioned above, is that the propagation delay through the complete chain can be significant – often in the range of 3 to 10 seconds. However, for many applications, this may still be quite acceptable, and then HLS is a good choice.

==== AJA Helo ====

Due to its self-contained design and wide signal compatibility, the AHA Helo interface is an attractive option for bringing video onto a network in a way that can be used by Blocks. HLS support was added in Helo version 2.1. Make sure your device has at least this version. If not, upgrade it by downloading new firmware from AJA.

Using the web interface for the Helo, configure it as shown below. Chose the desired input type (HDMI or SDI). Audio can optionally be sourced through an analog 3.5 mm jack. Make sure "Power Up State" is set to "Stream", so the streaming function will be restarted automatically if the device loses power. Set other options as desired.

{{ :blocks:blocks:video:config.png?nolink |}}

Then set the Streaming profile like what's shown below, paying specific attention to the "Stream Type" setting. Reducing the "i-Frame [GOP] Every" setting to a shorter value than the default, such as 25 frames, speeds up the initial start of the stream. To access this setting, you must first set "Advanced Settings" to "Show".

{{ :blocks:blocks:video:streaming-profile.png?nolink |}}

Once all settings are set, click the green streaming button at the top to start the stream. Chose the Status page to see the "Stream URL"  under which the stream is provided.

{{ :blocks:blocks:video:status.png?nolink |}}

Copy the "Stream URL", and paste it into a Live Video block in Blocks, and make sure the stream type is set to HLS.


==== Sample Streams ==== 

There are numerous live feed sources available publicly on the Internet. Here are a few examples:

  * **HLS** news feed http://livepull1.secure.footprint.net/antena3mpp/bitrate_4.m3u8
  * **HLS** on-demand stream http://qthttp.apple.com.edgesuite.net/1010qwoeiuryfg/sl.m3u8
  * **MJPEG** public webcam http://217.152.196.254/axis-cgi/mjpg/video.cgi?camera=1
  * **Polling JPEG** public webcam http://62.108.201.7/record/current.jpg

(Please note this is 3rd party links and may well come and go or even being removed permanently)

Some public cameras using the "polling jpeg" method may have rate limits, meaning that if you poll them too frequently, your feed may stop working. Public cameras come and go, so some of the above streams may no longer be available by the time you read this. A quick google search should turn up plenty of others.
==== Online Streaming Services ====

For streams sourced from (or available to) the Internet, there are a number of online streaming services that can provide stream distribution and conversion into a wide variety of formats. Here are some examples:

  * [[https://www.wowza.com/products/streaming-engine|Wowsa]].
  * [[https://bitmovin.com|Bitmovin]].
  * [[https://www.videoexpertsgroup.com|Streamland]].
==== Software-based Stream Conversion ====

In some cases, the stream you want to show is already on the network, but in a format that can't be directly used by Blocks, such as RTSP or NDI. Such formats can often be converted using software based solutions, such as [[https://www.ffmpeg.org|ffmpeg]]. Contact PIXILAB for further information on how this can be done, including information on your server environment and detailed information about the source stream.

If you want to learn more about video streaming in general [[https://en.wikipedia.org/wiki/Streaming_media#Protocols|Wikipedia]] has an excellent article, as usual.