Control port API

Command-line arguments

Common

--control-port

Defines control port socket to be opened, if you append :1 parameter (eg. --control-port 8000:1), it connects to previously opened socket as a client.

UltraGrid

--start-paused

Starts UltraGrid sender paused.

Reflector

For reflector usage, please see here.

Control socket usage howto

Reflector

Note: In new UltraGrid there can be also identifier in format : instead of numerical IDs.

Receiver change

<hostA> and <hostB> have indices 0 and 1. Therefore, if you want to change target from <hostA> to X, you would use following message:

port 0  receiver X

Transcoding mode change

Reflector works in 2 modes - packet reflector and transcoder. Here, for it acts like packet reflector and simply forwards incoming packets to it. For hostB it transcodes incoming stream and uses libavcodec (MJPEG) compression.

To transit from one mode to another (first is for packet reflector), use following commands:

port[0] sock

and

port[0] recompress

Thereafter, if you change first port to a transcoder, you can change compression by message:

port 0 compress JPEG

Adding and removing output ports

You can also add and remove hosts to reflector by commands:

 root delete-port <id>
 root create-port <host>:<tx_port> <compression>
 root create-port <host>:<tx_port>

• First command removes port with index . Keep in mind that after that, ports' indices of +1 and higher are decremented by one.
• Second command appends new output port to the list. By default it is in transcoding mode with compression (can be "none").
• The third command creates new output port that retransmits incoming packets to (aka packet reflector).

Note: In older UltraGrid versions, the delimiter between and <tx_port> was a space instead of the colon.

Stat lines

See below.

SSRC reset

SSRC reset of RTP stream can be done with following command:

reset-ssrc

or

port <n> reset-ssrc

for transcoding reflector's port

First command resets SSRC both for audio and video stream of the producent (this is not true for distributor by now since it does not support audio yet).

FEC change

FEC can be changed by following command:

fec video <new_fec_config_string>

Format of <new_fec_config_string> is exactly the same as passed to -f commandline argument.

Note: To disable FEC, simply use FEC none.

Volume setting

You can increase/decrease volume of the received audio stream with following commands:

volume up

and

volume down

You can also use

mute

to toggle output audio off and on.

Note: These commands work on receiver only.

Video Switcher

UltraGrid can be started in a mode when multiple inputs are connected and UltraGrid is run with a switcher metacapture as described here. Then, control command is this:

capture.data 0

to select first input (indexed from zero)

Video postprocess change (receiver only)

UltraGrid can change video postprocessor on fly with following command:

postprocss <new_video_postprocess>

eg.

postprocess border:width=10:color=#ff0000

to border.the video with 10 px red border.

When you do not want to use any video postprocessor, use following command

postprocess flush

Other - (currently in-)complete reference

Sender only

Following commands will work on sender only and should not be send to receiver or combined sender/receiver:

sender-port <TXport> | <videoRXport>:<videoTXport>|<videoRXport>:<videoTXport>:<audioRXport>:<audioTXport>

Sets requested destination port (optionally specifying source port and ports for audio).

receiver <address>

Sets requested receiver address.

Receiver only

receiver-port <RXport>|<videoRXport>:<audioRXport>

Sets source port for received video (audio).

Statistics and events

Statistics

Statistics are not reported by default. To enable statistics reporting, use command:

stats on

and

stats off

to disable it.

UltraGrid and transcoding reflector

Statistics are reported per frame and cumulatively.

Format (sender): stats SEND <port_id> bufferId <num> droppedFrames <num> nanoPerFrameActual <num> nanoPerFrameExpected <num> sendBytesTotal <num> timestamp <millis_since_unix_epoch> compressMillis <num>

where

<port_id>

is identifier of output port - *default* for UltraGrid, *:* for every output port of transcoding reflector.

timestamp

timestamp when the statistic was generated (therefore usually the latest timestamp in processing workflow)

TODO

rest of the keywords

Format (receiver):

stats RECV bufferId <num> expectedPackets <num> receivedPackets <num> expectedBytes <num> receivedBytes <num> isCorrupted <num> isDisplayed <num> timestamp <millis_since_unix_epoch> nanoPerFrameDecompress <num> nanoPerFrameErrorCorrection <num> nanoPerFrameExpected <num> reportedFrames <num>

where (excluding keywords explained above):

nanoPerFrameErrorCorrection

deFECation time (cumulative)

TODO

the rest of the keywords

Packet reflector

Statistics are reported in 5 second interval.

Format

stats FWD receivedBytes <num> receivedPackets <num> timestamp <millis_since_unix_epoch>[ portList <port_list>]

where <port_list> is a comma separated list of output ports in format <host>:<port>. E.g., h1.example.org:5004,h2.example.com:8000. If <port_list> is empty (no active output ports), the keyword portList is omitted from the line.

Audio

Format (receiver):

stats ARECV volrms <double> volpeak <double>

Reported volumes are of first channel and are in dBFS.

Events

TODO