1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
|
sydra-rtp(8)
============
NAME
----
sydra-rtp - tool for RTP based streams
SYNOPSIS
--------
....
sydra-rtp
[ -h|--help ]
[ -D|--nodaemonize ]
[ -u|--username <username> ]
[ -g|--groupname <groupname> ]
[ -C|--chroot <path> ]
[ -P|--write-pid <filename> ]
[ -L|--log <target>:<level>[,<param1>[,<param2>[..]]] ]
[ -U|--debug ]
[ -n|--appname <name> ]
[ -m|--mode (sender|reciever) ]
[ --source <bin description> ]
[ --video-encoder <bin description> ]
[ --video-payloader <element> ]
[ --previewsink <bin description> ]
[ --audio-encoder <bin description> ]
[ --audio-payloader <element> ]
[ --video-caps <caps> ]
[ --video-depayloader <element> ]
[ --video-decoder <bin description> ]
[ --audio-caps <caps> ]
[ --audio-depayloader <element> ]
[ --audio-decoder <bin description> ]
[ --sink <bin description> ]
[ -a|--rtp-host <host> ]
[ -o|--rtp-port-base <port> ]
[ -A|--rtp-addr-local <address> ]
[ -O|--rtp-port-base-local <port> ]
[ --rtp-host-reflector <host> ]
[ --rtp-port-base-reflector <port> ]
[ -c|--no-auto-client ]
[ -t|--timeout <timeout> ]
[ -k|--keepalive-interval <interval> ]
[ --rec-video-encoder <bin description> ]
[ --rec-audio-encoder <bin description> ]
[ --rec-mux <element> ]
[ --rec-name-format <formatstring> ]
....
DESCRIPTION
-----------
*sydra* is a toolbox which allows you to set up multiple bidirectional
Video/Audio streams from external locations.
*sydra* has been written to be used for the Elevate Festival in Graz
Austria in order to involve external locations to present themselves
at the festival.
This manpage describes *sydra-rtp* the basic utility for the task which is
based on GStreamer and is written in C.
The *sydra-rtp* utility creates a gstreamer pipeline to send or receive
RTP-based Audio/Video streams. For a bidirectional connection 2 instances
of *sydra-rtp* are required on both sides of the communication. *sydra-rtp* has
automatic client detection capabilities in the form of keep alive messages.
These message are sent out by receivers to request RTP packets from a sender.
The sender will send RTP packets to one or more receivers which request
the stream. It also uses the keep alive messages to remove stale client
'connections'. A receiver can also request to be removed from the list of
receivers. This ensures a fast and clean shutdown.
The keepalive messages are also a simple way to work around NAT and
firewalls (UDP hole punching).
OPTIONS
-------
The following options can be passed to the *sydra-rtp* daemon:
*global options*
*-D, --nodaemonize*::
This option instructs *sydra-rtp* to run in foreground
instead of becoming a daemon which is the default.
*-u, --username <username>*::
run as this user. If no group is specified (*-g*) the default group of
the user is used. The default is to not drop privileges.
*-g, --groupname <groupname>*::
run as this group. If no username is specified (*-u*) this gets ignored.
The default is to not drop privileges.
*-C, --chroot <path>*::
Instruct *sydra-rtp* to run in a chroot jail. The default is
to not run in chroot.
*-P, --write-pid <filename>*::
Instruct *sydra-rtp* to write it's pid to this file. The default is
to not create a pid file.
*-L, --log <target>:<level>[,<param1>[,<param2>[..]]]*::
add log target to logging system. This can be invoked several times
in order to log to different targets at the same time. Every target
has its own log level which is a number between 0 and 5. Where 0 means
disabling log and 5 means debug messages are enabled. +
The file target can be used more than once with different levels.
If no target is provided at the command line a single target with the
config *syslog:3,sydra-rtp,daemon* is added. +
The following targets are supported:
*syslog*;; log to syslog daemon, parameters <level>[,<logname>[,<facility>]]
*file*;; log to file, parameters <level>[,<path>]
*stdout*;; log to standard output, parameters <level>
*stderr*;; log to standard error, parameters <level>
*-U, --debug*::
This option instructs *sydra-rtp* to run in debug mode. It implicits *-D*
(don't daemonize) and adds a log target with the configuration
*stdout:5* (logging with maximum level). In future releases there might
be additional output when this option is supplied.
*-n, --appname <name>*::
This set the application name using 'g_set_prgname()'. It will be used for example
by xvimagesink for window title.
*-m, --mode (sender|reciever)*::
This sets the main mode of *sydra-rtp*. The sender will read raw video and audio
from the source bin and send it via RTP to one or more receivers.
*sender-mode only options*
*--source <bin description>*::
A gst-launch-style description for the raw video and audio bin. This bin must contain
an element called 'videosrc' and an element called 'audiosrc' which should each
contain a pad called 'src'. Theses pads will get connected to the encoder bins.
Example:
'v4l2src ! videoconvert ! videoscale ! video/x-raw,format=I420,width=864,height=480 ! identity name="videosrc"
autoaudiosrc ! audio/x-raw,format=S16LE,channels=1,rate=48000 ! identity name="audiosrc"'
*--video-encoder <bin description>*::
Bin description for the video encoder. Example: 'videoconvert ! vp8enc'
*--video-payloader <element>*::
A RTP payloader element for the video codec in use. Example: 'rtpvp8pay'
*--previewsink <bin description>*::
A video sink element for local preview. Example: 'videoconvert ! textoverlay test="preview" ! xvimagesink'
*--audio-encoder <bin description>*::
Bin description for the audio encoder. Example: 'audioconvert ! opusenc'
*--audio-payloader <element>*::
A RTP payloader element for the audio codec in use. Example: 'rtpopuspay'
*receiver-mode only options*
*--video-caps <caps>*::
These caps will get assigned to incoming RTP packets for video. Example:
'application/x-rtp,media=video,clock-rate=90000,encoding-name=VP8-DRAFT-IETF-01,caps="video/x-vp8"'
*--video-depayloader <element>*::
A RTP depayloader element for the video codec in use. Example: 'rtpvp8depay'
*--video-decoder <bin description>*::
Bin description for the video decoder. Example: 'vp8dec'
*--audio-caps <caps>*::
These caps will get assigned to incoming RTP packets for audio. Example:
'application/x-rtp,media=audio,clock-rate=48000,encoding-name=X-GST-OPUS-DRAFT-SPITTKA-00,caps="audio/x-opus"'
*--audio-depayloader <element>*::
A RTP depayloader element for the audio codec in use. Example: 'rtpopusdepay'
*--audio-decoder <bin description>*::
Bin description for the audio decoder. Example: 'opusdec'
*--sink <bin description>*::
A gst-launch-style description for the raw video and audio bin. This bin must contain
an element called 'videosink' and an element called 'audiosink' which should each
contain a pad called 'sink'. Theses pads will get connected to the decoder bins.
Example:
'videoconvert name="videosink" ! videoscale add-borders=true ! xvimagesink
audioconvert name="audiosink" ! autoaudiosink'
*options for RTP*
*-a, --rtp-host <host>*::
In 'sender' mode this sets the address or hostname of the remote RTP receiver. Please
mind that the remote RTP host is always added as a receiver and it shouldn't be
configured to send keepalives. This would re-add the receiver to the list of clients
and as a result duplicate packages will be sent.
Also the remote RTP host is excluded from client timeout handling and remove requests
from it will get ignored.
When you omit this in sender mode the automatic client detection will be used to add
receivers.
In 'receiver' mode keepalive messages will be sent to this host. Leave empty to disable
keepalive messages.
*-o, --rtp-port-base <port>*::
The base number for remote ports. *sydra-rtp* will send the RTP/RTCP packets using the following
mapping:
* rtp-port-base + 0: RTP Video
* rtp-port-base + 1: RTCP Video
* rtp-port-base + 2: RTP Audio
* rtp-port-base + 3: RTCP Audio
*-A, --rtp-addr-local <address>*::
The local address to wait for incoming UDP messages. Leave empty to listen on any address.
*-O, --rtp-port-base-local <port>*::
The base number for local ports to bind to. The same mapping as for the remote port-base is
used to map incoming RTP packets to the RTP bin.
*--rtp-host-reflector <host>*::
When in receiver mode the incoming RTP packets will get reflected to this host. Leave empty
to disable RTP packet reflection.
*--rtp-port-base-reflector <port>*::
When a reflector-host gets specified using the option above the RTP packets will get sent to
the ports based on this. The same mapping as with the other port-base options is used.
*-c, --no-auto-client*::
This disables auto-detection for clients in 'sender' mode. Mind that if you disable the
automatic client detection and also omit the rtp-host option *sydra-rtp* won't send any RTP
messages. If configured recording will work but this is most probably not what you want.
*-t, --timeout <timeout>*::
This sets the client timeout in seconds in 'sender' mode. A value of 0 disables client
timeouts. This is not recommended.
*-k, --keepalive-interval <interval>*::
This sets the interval in seconds for sending out keepalive messages in 'receiver' mode.
A value of 0 disables keepalive messages and therefor the client auto detection won't
work for this client.
*options for recording*
*--rec-video-encoder <bin description>*::
A bin description for the video encoder used for recording. If you leave this empty the
output from the RTP video encoder is used. Example: 'videoconvert ! jpegenc'
*--rec-audio-encoder <bin description>*::
A bin description for the audio encoder used for recording. If you leave this empty the
output from the RTP audio encoder is used. Example: 'audioconvert ! vorbisenc'
*--rec-mux <element>*::
A gstreamer muxer element used for recording. If you leave this empty recording will be
disabled. Example: 'matroskamux'
*--rec-name-format <formatstring>*::
A 'strftime' based format string which will be used to create the name for the
recorded file. Example: ./recordings/%Y-%m-%d_%H-%M-%S.mkv
BUGS
----
Most likely there are some bugs in *sydra-rtp*. If you find a bug, please let
the developers know at equinox@spreadspace.org. Of course, patches are preferred.
SEE ALSO
--------
*strftime*(3), *gst-launch*(1)
AUTHORS
-------
Christian Pointner <equinox@spreadspace.org>
COPYING
-------
Copyright \(C) 2014 Christian Pointner. This program is free
software: you can redistribute it and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or any later version.
|
