j4zzcat / viewport

Display multiple, side-by-side Unifi Protect and RTSP/S video streams in an unattended web page.

Viewport

Viewport is a simple program to display multiple, side-by-side Unifi Protect and RTPS(S) video streams in an unattended web page. It is designed for passive, security cameras view-only scenarios (i.e., 'Kiosk'). Viewport is easy to use, uses little resources and has low latency.

Quickstart

To display the video streams of a Unify Protect Controller, first define a local Admin on that controller, with minimum privileges. This user is used by Viewport to access the livestream feeds. Follow the following procedure:

1. Open up Unifi Protect web application, select OS Settings from the top-level navigation bar.
2. Click Admins and Users, then click the + (plus) button in the top right corner to Add Admin.
3. In the Add Admin panel, check Restrict to local access only, then fill in the username and password.
4. Uncheck the Use a pre-defined role, and set Live only for Protect, and None for OS Settings.
5. Click Add and close the app.
6. Run the following in the terminal:

docker run -it --rm --network host viewport:1.2 \ 
  streams 'unifi://username:password@host/_all'

Replace username and password with those used above, replace host with the hostname or ip address of the Unifi Protect Controller. Once Viewport starts, use Google Chrome to navigate to http://localhost:8001.

Another example

Display cameras from several controllers and RTPS sources on a 4x4 grid:

docker run -it --rm --network host viewport:1.2 \ 
  streams \
    --layout grid:4x4 \
    'unifi://username1:password1@host1/_all' \
    'unifi://username2:password2@host2/camera name 5,camera name 3' \
    'rtsp://host3/ABCDEFG' \
    'rtsps://host3/HIJKLMNOP?nighmode=false'

Theory of operation

Viewport is based on a simple client-server architecture, and is made of several parts:

On the client side:

• Viewport Player which is a simple livestream video player written in TypeScript. This player uses Media Source Extension API to play the H.264 fMP4 livestream video from the Unifi Protect Controller through the Viewport Reflector Server.
• FLV Player which plays the FLV streams transcoded by the FFMpegServer from RTSP(S).
• index.html which is a simple web page that is rendered once by the server and binds all the views together.

On the server side:

• Viewport Reflector which is a simple livestream reflector server. This server uses the excellent node-based Unifi Protect library to reflect the livestream off of a Unifi Protect Controller and onto the Viewport Player, over Web Sockets.
• Viewport FFMpeg Server which is a simple transcoding server that uses FFMPEG to transcode the specified RTSP(S) streams into FLV and sends it the FLV Player over Web Sockets.
• Viewport which provides CLI and orchestrates the execution of all the parts. Run the program with the --verbose option to see the entire flow.

Build

To build the software locally, run the following command. You should have docker and buildkit installed.

docker buildx build -t viewport:latest -f build/Dockerfile .

Known issues

• Somewhat working on Safari and Firefox.
• Not working on iOS.

Todo

• Better error handling. Should exit cleanly on fatal.
• Better unit testing.
• Migrate away from FLV player to mpegts.js
• Investigate why is that RTPS(S) streams paused when focus is taken away.
• Explore ways to optimize the RTSP(S) transcoding.

viewport's Issues

Reduce viedo stream latency

Version 1 is using HLS to serve the streams to the browser.
While this simple approach works, HLS introduces a 10-15 seconds lag to the video stream.
This is unacceptable for users of this software.

Find a way to eliminate the lag:

• For Unifi cameras, perhaps use the fMPEG stream directly
• For RTSP(S) streams, perhaps transcode to FLV and serve via a media server

Sometimes a Viewport Player will freeze due to a MSE Buffer Full error

The player only works on Chrome