Running UltraGrid

Martin Pulec edited this page Feb 12, 2019 · 5 revisions

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

Ultragrid is a command line application, run either via command uv (if you installed it) or manually from the folder <Your-Ultragrid-Folder>/bin.


On Mac OS X, 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:


where <path_to> may be '.' (a dot) only or any absolute/relative path to the bundle.

Table of Contents


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)


 ./uv -r help (playback)

You may also care about:


Sender settings

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

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

Now this command can be split into three parts. -t is a parameter that tells ultragrid you are setting the sender (capTure). here represents the IP of the receiver. Finally, the cryptic colon separated command is the sender card setting.

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.

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

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


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

Or with a different card for different actions.

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

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 -P 5104:5004:5106:5006 # capture
 computer1$ ./bin/uv -d decklink:2:5 -r embedded # 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:

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.