Control port API - CESNET/UltraGrid GitHub Wiki

Control port API allows runtime control of various UltraGrid parts. It opens a plain text TCP socket for the control (optionally can also connect to already opened socket).

Please note that the control port API is intended for internal UltraGrid purposes, not for the end users, so do not ask developers for any support.

• Table of Contents
• Command-line arguments
  • Common (UG & reflector)
  • UltraGrid
  • Reflector
• Control socket usage howto
  • Reflector
    • Receiver change
    • Transcoding mode change
    • Adding and removing output ports
  • Stat lines
  • Compression
  • FEC change
  • Rate limiter
  • Volume setting
  • Video Switcher
  • Video postprocess change (receiver only)
  • Capture filter change (sender only)
  • Audio filters (sender only)
  • Other - (currently in-)complete reference
    • Sender only
    • Receiver only
• Statistics and events
  • Statistics
    • Audio

--control-port <port>[:0|:1]

Defines control socket port to be opened. If :1 is appended (eg. --control-port 8000:1), it connects to previously opened socket on localhost as a client (:0, default, starts a server mode). If parameter is absent, dynamic port is opened in a server mode (number can be viewed by pressing 'i' in UltraGrid console).

--param control-accept-global

Allow remote control (by default disabled).

For reflector usage, please see here.

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

<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

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

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.

See below.

Compression can be changed with:

compresss <new_compression>

eg.:

compresss libavcodec:encoder=libx264:bitrate=10M

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.

Rate limiter may be changed with following message"

sender.transmit TX_msg rate 1M

You may also use following 2 special values:

sender.transmit TX_msg rate 0
sender.transmit TX_msg rate -1

for unlimited (0) and auto (-1).

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

volume up

and

volume down

Audio can be muted or unmuted on either sender or receiver with:

[un]mute-{sender|receiver}

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)

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

capture.filter mirror            # add capture filter
capture.filter blank:0:0:200:100 # add capture filter
capture.filter delete 0          # delete first capture filter
capture.filter flush             # flush all capture filters

An audio filter can be added using

audio.sender.filter <filter_name>:<config>

Individual filters can be then controlled using the audio.sender.filter.data[n] key. For example to adjust the delay to 5s for the delay filter:

audio.sender.filter.data[0] 5000

• restart stream SSRC (both audio and video):

  reset-ssrc

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

• set requested destination port (optionally specifying source port and ports for audio):

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

• set requested receiver address:

  receiver <address>

• set port for receiving video (audio)

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

• set AV delay in ms (positive - audio is delayed, negative - video is delayed

  av-delay <delay>

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

stats on

and

stats off

to disable it.

Format (receiver):

stats ARECV volrms0 <dBFS> volpeak0 <dBFS> volrms1 <dBFS> volpeak1 <dBFS>

Reports values for first and second channel. If mono is received, the values of first channel is copied to second channel.