Running UltraGrid - CESNET/UltraGrid GitHub Wiki
💡 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").
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.
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
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
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.
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>
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>
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>.
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
- FEC Settings
- Encryption
- iHDTV Settings
- Interlaced Input
- IPv6
- Multipoint Setup
- Recording and Playback
- Reflector settings
- RTSP Server, SDP
- SAGE Settings
- Screen Capture
- Stereoscopic 3D Video Settings
- SW Video Mix
- Syphon, Spout and NDI
- Traffic shaping
- Video Postprocessors
- Video Switcher
- Videoconferencing Mode
Page Use Cases presents some useful Use Cases, including:
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.
See UltraGrid GUI Usage.