subc/viperfish repository overview

⁠Introduction (project Viperfish)

Combining the examples:

• MediaLooks sender and receiver (from the MediaLooks SDK)
• SimpleWebRTC sender and receiver example (https://github.com/simplewebrtc/SimpleWebRTC/tree/master/test⁠)

We were able to write a working browser based WebRTC based sender and receiver.

Now we have the SubC WebRTC web streamer (codename Viperfish) and receiver that worked with the modified and existing WebRTC signaling server (that was based on Signal Master).

⁠Installation

The system has several parts to it. The ones this document will focus on are:

• NodeJS server
• Usage of the NodeJS server (see Usage section)
• Usage of the individual sender and receiver html pages if ported to another web server (see Usage section)

The system also has a Blazer page with allows for viewing of the stream and an Android app based on usage of a webview.

⁠NodeJS server

Currently, we have a custom NodeJS server that can host the pages, sender.html and receiver.html. Depending on usage installation can vary.

You will need:

• Port 443 available (if you need to change the port number, see the folder config and modify the default.json file section named port)
• NodeJS installed on the operating system
• (Linux) Access to sudo or root user (usage of port 443 is limited sometimes to admin's)

⁠From from Windows or Linux Console

Steps:

1. Change directory to the beta folder
2. Type "npm i" (*)

⁠From Docker image

Prebuild docker images are available at https://hub.docker.com/repository/docker/subc/viperfish⁠. You have the options of running the docker image using:

• Docker-compose
• startDocker.bat file
• docker run -p 443:443 --name viperfish:dev-1.0 -d subc/viperfish
• docker run -p 443:443 --name viperfish:main-1.0 -d subc/viperfish
• docker run -p 443:443 --name viperfish:debug-1.0 -d subc/viperfish

⁠Available Images

⁠Usage

⁠Starting the NodeJS Server

Steps:

1. Download a copy of the repo
2. Change directory to the beta folder
3. Type "npm start" or "node server_beta.js"

⁠Running on a Non-NodeJS solution

You can also use this system from something like Apache.

See the Folder structure section for a breakdown of how all the folders are files are available, but the sender.html and receiver.html files are what makes everything work in a non-NodeJS setup.

However, to enable this option you need to do a minor edit. See instructions below.

1. Open the file sender.html and change: i. var room = undefined; to var room = location.search && location.search.split('&')[1]; ii. var vidEncoder = undefined; to var vidEncoder = location.search && location.search.split('&')[2]; iii. var vidBitrate = undefined; to var vidBitrate = location.search && location.search.split('&')[3]; iv. var signalingServer = undefined; to var signalingServer = location.search && location.search.split('&')[4];
2. Open the file receiver.html and change: i. var room = undefined; to var room = location.search && location.search.split('&')[1]; ii. var signalingServer = undefined; to var signalingServer = location.search && location.search.split('&')[2];

IMPORTANT NOTES:

• You can hardcode the signaling server into the .html files as well.
• You can move the signaling server var to the /js/common.js file.
• You can move the collection of data from the address var to the /js/common.js file. (It is setup inside of the .html files for NodeJS to do a replacement operation on the read in html string data.)
• When you call the sender.html and receiver.html files from the browser, use the format:
  • https://{domain}:{port}/{path}/{receiver.html}?{receiver}&{stream_name}
  • https://{domain}:{port}/{path}/{sender.html}?{sender}&{stream_name}&{video_encoder}&{video_bitrate}

⁠Streaming A Video

The web server will start listening on the provided port. From the console, it will show possible addresses you can use to access the server.

The format you need to follow is:

https://{domain}:{port}/sender/{stream_name}/{video_encoder}/{video_bitrate}

Steps

1. Determine the domain you have the server installed on
2. Open the browser to that domain with needed options of /sender and /{stream_name}. For example, https://www.someserver.com/sender/sample_stream⁠.
3. When prompted to allow access to your camera and microphone, click Allow
4. Now your streaming that camera out

⁠Allowed Video Encoders

⁠Allowed Video BitRates

Bit rate (bitrate or as a variable R) is the number of bits that are conveyed or processed per unit of time.

When quantifying large or small bit rates, SI prefixes (also known as metric prefixes or decimal prefixes) are used, thus:

• 0.001 bit/s = 1 mbit/s (one millibit per second, i.e., one bit per thousand seconds)
• 1,000 bit/s = 1 kbit/s (one kilobit per second, i.e., one thousand bits per second)
• 1,000,000 bit/s = 1 Mbit/s (one megabit per second, i.e., one million bits per second)
• 1,000,000,000 bit/s = 1 Gbit/s (one gigabit per second, i.e., one billion bits per second)

⁠Stream Name

The stream name but be only numbers or letters. All other characters will be removed by the server upon sending the data to the sender.html or receiver.html pages.

⁠Opening A Video from the Browser

To view a stream, you will need to know the domain name and the name of the stream.

The format you need to follow is:

https://{domain}:{port}/receiver/{stream_name}

⁠Stream Name

The stream name but be only numbers or letters. All other characters will be removed by the server upon sending the data to the sender.html or receiver.html pages.

⁠Troubleshooting

⁠Streaming appears ok, but unable to view the stream.

Just because you can get access to your camera and have what appears to be a valid stream outgoing, does not mean it is working.

Checking if able to view it from a browser is helpful, but using the formatted url, https://{domain}:{port}/receiver/{stream_name}. But some it's not working try checking the below.

1. Open up Dev tools by pressing F12, click on the sources tab and choose (index) from the list. Inside the source code, there are globals defined, make sure none of them are showing = undefined. If you see this issue, there is something mis-configured in the /config/defaults.json file or the server needs to be restarted from the console.

// Set room (will be assign by server)
var room = "bob";
// Set the signaling server.
var signalingServer = "https://testserver.subcservices.com/";

// Set room (will be assign by server)
var room = "bob";
// Set video encoder.
var vidEncoder = "h264";
// Set video bitrate.
var vidBitrate = "64000";
// Set the signaling server.
var signalingServer = "https://testserver.subcservices.com/";

⁠Technical Breakdown

Below is a full technical breakdown of the sender and receiver files and how they work. These include code samples and research links for further reading.

⁠Folder Structure

graph TD;
    ROOT-->./js;
    ./js-->receiver.js;
    ./js-->common.js;
    ./js-->sender.js;
    ./js-->simplewebrtc-with-adapter.bundle.js;
    ROOT-->./css;
    ./css-->common.css;
    ROOT-->./ssl;
    ./ssl-->cert.pem;
    ./ssl-->key.pem;
    ROOT-->./sender.html;
    ROOT-->./receiver.html;
    ROOT-->./204.html;
    ROOT-->./404.html;
    ROOT-->./server_beta.js;
    ROOT-->./startServer.bat;
    ROOT-->./startServer.sh;