Running UltraGrid

💡 Tip: There is a nice tutorial for UltraGrid by Jisc that can be used as a good starting point.

UltraGrid is a command line application which is run by a command called uv (from "UltraGrid video").

Table of Contents

• Invoking
  • Auxiliary tools
• Basics
• Sending/receiving
  • Sender settings
  • Reciever settings
• Advanced sender/reciever settings
  • Duplex
  • Bidirectional simplex
• Advanced Settings
• Use Cases
• GUI
  • Invoking the GUI
  • UltraGrid GUI Usage

Invoking

If it is not in system paths, you may need to use a relative path inside the UltraGrid folder:

./uv [arguments]

On macOS, you can also run UltraGrid from the application bundle. Bundle creation is described here. If running from bundle, use whole path to the binary inside the bundle:

/Volumes/ULTRAGRID/uv-qt.app/Contents/MacOS/uv
# or
./uv-qt.app/Contents/MacOS/uv

Path may be '.' (a dot) only or any absolute/relative path to the bundle (Disk Images are usually mounted in Volumes) .

To run an AppImage on Linux, make sure you make it executable. Then you can run it:

./UltraGrid-continuous-x86_64.AppImage [args] <receiver>

Last but not least option is to use the UltraGrid GUI.

Auxiliary tools

You may also want to run other executables distributed with UltraGrid, like reflectors. This is usually quite analogous to running the actual UltraGrid executable, eg.:

/Volumes/ULTRAGRID/uv-qt.app/Contents/MacOS/hd-rum-transcode     # macOS
.\hd-rum-transcode.exe                                           # Windows (PowerShell)

There is only a slight difference in case of AppImage where the actual file is all-in-one binary and individual executables are hidden inside. Therefore you need to use slightly different form:

./UltraGrid-continuous-x86_64.AppImage --tool hd-rum-transcode [args]
# Available tools can be listed in help:
./UltraGrid-continuous-x86_64.AppImage -h

Basics

Any specific sender-receiver connection can be established by appending parameters to the ./uv command.

To establish a connection between two remote machines you need to run a 'Sender' and a 'Receiver' Ultragrid on the respective machines.

Help for print help dialogue

./uv --help

Help for video capture and then e.g., uv -t testcard:help for particular parameters

./uv -t help

Help for displaying and then e.g., uv -d gl:help for particular parameters

./uv -d help

Help for compression and then e.g., uv -c libavcodec:help

./uv -c help

Help for audio capture and playback

./uv -s help (capture)

or

./uv -r help (playback)

You may also care about:

• audio
• traffic shaping (rate limiter) -l
• FEC -f
• MTU size -m (Jumbo frames; see also OS Setup)
• port number -P

Sending/receiving

Sender settings

A command to start the sender version of ultragrid should look something like this:

./uv -t somecard:0:4:RGB example.com

Now this command can be split into three parts. -t is a parameter that tells ultragrid you are setting the sender (capTure). example.com here represents the IP of the receiver.

Finally, the cryptic colon separated command is the sender card setting. Currently it is not mandatory for most capture devices - if unset, the values are detected from input format.

To determine your sender card setting, first use:

./uv -t help

To get a list of devices. After choosing a device, you can obtain further device options by:

./uv -t <yourdevice>:help

You can now fill the rest of the information according to the list received. Note that different cards require different numbers of parameters.

Note: The above command will send uncompressed video which will result in a huge stream. If not desired, look at Compression Settings.

Reciever settings

You can now apply almost the same procedure to set the receiver, the difference is that you use -d (Display) parameter instead of -t e.g.:

./uv -d decklink example.com

Note that on sender, you are required to fill in less options.

If you want to use gl, run this command

./uv -d gl <sourceIP>

Advanced sender/reciever settings

Duplex

It is also possible to use one machine for both sending and receiving via UltraGrid. This is viable either for synchronous communication (Videoconferencing...) or testing purposes (Later).

To use ultragrid as both, simply use both sender and receiver parameters.

Either with the same card as sender and receiver (please note that not all models support duplex operation):

./uv -d somecard -t somecard:0:4:RGB example.com

Or with a different card for different actions.

./uv -d somecard -t someothercard:0:4:RGB example.com

If you need just to test UltraGrid locally - you can use it as a self-loop - one machine can act as a sender and receiver of the SAME DATA. This way, you can test whether your machine is capable of handling UltraGrid without having to hassle with actual network link.

This is done simply by inserting the testing machine IP in place of the remote IP:

./uv -d gl -t somecard:0:4:RGB <this_machine_IP>

Bidirectional simplex

In this setup, you will use two Ultragrid instances, one for transmission, second for receiving. You can start UltraGrid simply by entering devices' individual configurations. The thing that needs to be kept in mind is that you have to specify explicitly ports at least for one instance. By default, UltraGrid uses RTP port 5006 for audio and 5004 for video. Thus, the pair of source ports of the transmitter need to be changed (otherwise, you will need to change TX ports also on the remote machine), eg. to:

computer1$ ./bin/uv -t decklink:1:8 -s analog -c jpeg:90 -l 500M 147.251.240.74 -P 5104:5004:5106:5006 # capture
computer1$ ./bin/uv -d decklink:2:5 -r embedded 147.251.240.74 # display

Please notice the ports 5104 and 5106 are substitutes for the default ones, the syntax is <video_rx>:<video_tx>:<audio_rx>:<audio_tx>.

Advanced Settings

You should now be able to establish a basic non-HD connection. For Audio, HD, 4K, Stereoscopic 3D and other features, please consult the corresponding sections:

• 4K Video Settings
• Audio Settings
• Capture filters
• Compression Settings
  • Libavcodec Compression
    • Hw. acceleration support
• FEC Settings
• Encryption
• iHDTV Settings
• Interlaced Input
• IPv6
• Multipoint Setup
• NDI
• Recording and Playback
• Reflector settings
• RTSP Server, SDP
• SAGE Settings
• Screen Capture
• Spout and Syphon
• Stereoscopic 3D Video Settings
• SW Video Mix
• Traffic shaping
• Video Postprocessors
• Video Switcher
• Videoconferencing Mode

Use Cases

Page Use Cases presents some useful Use Cases, including:

• Live web streaming with Nginx
• NAT traversal

GUI

Invoking the GUI

First step is to invoke the UltraGrid GUI. This differs whether or not you are running it from a command prompt or a OS GUI (usually a file manager).

When run from a command prompt you will need to specify the path for the executable, this is usually something like:

$ gui/QT/uv-qt                                      # running from UltraGrid build directory
$ gui/QT/uv-qt.app/Contents/MacOS/uv-qt             # ditto, in macOS
$ .\uv-qt.exe                                       # Windows PowerShell, UltraGrid Windows distribution
$ ./UltraGrid.AppImage                              # Linux AppImage
$ /Volumes/ULTRAGRID/uv-qt.app/Contents/MacOS/uv-qt # downloaded and mounted macOS DMG

When you compiled UltraGrid with GUI by yourself and don't have UltraGrid binary available in a system-wide path, you will need to pass the path with --with-uv parameter:

$ gui/QT/uv-qt --with-uv bin/uv
$ gui/QT/uv-qt.app/Contents/MacOS/uv-qt --with-uv bin/uv   # in macOS

If running via a OS GUI (a file manager), you will perhaps invoke the UltraGrid GUI as usual (by double-clicking etc.). This requires either officially distributed UltraGrid, or refer to bundling for homemade builds.

UltraGrid GUI Usage

See UltraGrid GUI Usage.