search

CESNET / UltraGrid

UltraGrid low-latency audio and video network transmission system
http://www.ultragrid.cz
Other
511 stars 54 forks source link

readme

UltraGrid - A High Definition Collaboratory

Facebook Follow Mastodon Follow Web Visit Coverity Scan Build Status C/C++ CI

UltraGrid Logo

Contents

About UltraGrid

UltraGrid brought by CESNET's Laboratory of Advanced Networking Technologies (Sitola) is a software implementation of high-quality low-latency video and audio transmissions using commodity hardware. Supported resolutions range through HD (1920x1080) up to 8K (7680x2160) with up to 60 frames per second. Other features are listed here.

The high-quality is achieved either by using uncompressed streams or streams with very low compression ratio. End-to-end transmission latency (i.e., all the way from the camera to the display) is about 100ms, but it varies based on camera and capture cards being used. UltraGrid was originally a research project used to demonstrate the possibilities of 10Gbps networks and to study multi-point data distribution in such environments. Recent advances in the field of GPU-accelerated low-latency codecs extend its usability also to Gigabit networks. High compression ratio compressions allow further use of any commodity network connection including a shared Internet connection.

UltraGrid is supported on stations with Linux, Windows or macOS operating system. The software is open-source distributed under BSD license, i.e., we're interested in both research/academic and commercial applications. Nowadays, main application areas are collaborative environments, medical, cinematography and broadcasting applications, as well as various educational activities.

It is a fork of the original UltraGrid developed by Colin Perkins, Ladan Gharai, et al..

Our work is supported by CESNET research intents "Optical Network of National Research and Its New Applications" (MŠM 6383917201), CESNET Large Infrastructure (LM2010005), CESNET E-Infrastructure (LM2015042) and partially also by Masaryk University research intent "Parallel and Distributed Systems" (MŠM 0021622419).

The contents of this directory are as follows:

   bin/                  Compiled binaries
   data/                 Various assets used by UG that is not source code
   doc/                  Documentation
   ext-deps/             External dependencies that are required by UG
   gui/                  Sources for UltraGrid GUI
   hd-rum-multi/         Simple standalone packet reflector
   src/                  Source code for the UltraGrid system
   package_specs/        Specifications for OBS
   test/                 Source code and binaries for test routines
   tools/                Small standalone helper tools
   autogen.sh            Build script
   configure.ac          "       "
   Makefile.in           "       "
   CONTRIBUTING.md       Various information for contributors
   COPYRIGHT             Full license terms and conditions
   Doxyfile              Doxygen configuration
   INSTALL               Installation instructions
   NEWS                  Change log and modification history
   README.md             This file

There are also subdirectories cuda_dxt, dxt_compress and ldgm which contain libraries that are parts of UltraGrid but are relatively standalone and self-contained.

Hardware and Software Requirements

Recommended Hardware Setup:

Required Software Preliminaries

You will need this software (in brackets are optional features for which you'll need it):

Using the UltraGrid System

The INSTALL gives instructions for building the UltraGrid system. Once the system has been built, the uv binary will be present. This can be invoked as follows:

   uv -t <capture_device> -c <compression> hostname     (on the sender)
   uv -d <display_device> hostname                      (on the receiver)

The \<display_device> is one of the list viewed with -d help.

The \<capture_device> is one of the list viewed with -t help. Name of capture device usually follows with configuration of video mode, video input etc. All options can be interactively dispayed using built-in help, eg. -t decklink:help.

The \<compression> specifies the selected video compression to be used. Similarly as for other options, available options can be viewed by -c help. If compression is not specified, video is transmitted uncompressed (in that case consider setting MTU with -m <mtu>).

Further options follow UltraGrid command-line help (-h) or visit this wiki page for further information.

As an example, if a user on host "ormal" wishes to send audio and video captured using a BMD DeckLink card another user on host "curtis" with a display using the OpenGL driver and Portaudio audio playback, then the user on host "ormal" would run:

   uv -t decklink -c libavcodec:codec=H.264 -s embedded --audio-codec OPUS curtis

while the user on "curtis" would run:

   uv -d gl -r portaudio ormal

The system requires access to UDP ports 5004 and 5006: you should open these ports on any firewall on the network path. Uncompressed high definition video formats require approximately 1 Gigabit per second of network capacity. Using different supported compression schemes, the needed network capacity can be as low as 10 Megabits per second for a high definition video.

Documentation

Documentation can be found either offline (apart from this document) and online. The online documentation is more comprehensive and up-to-date, offline is rather complementary.

The online documentation is available in our GitHub wiki.

UltraGrid built-in documentation can be found in doc subdirectory, these documents are available: