-
Notifications
You must be signed in to change notification settings - Fork 58
Control port API
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
- Control socket usage howto
- Statistics and events
- --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.
If you have any technical or non-technical question or suggestion please feel free to contact us at