diff options
Diffstat (limited to 'doc/sydra-rtp.8.txt')
| -rw-r--r-- | doc/sydra-rtp.8.txt | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/doc/sydra-rtp.8.txt b/doc/sydra-rtp.8.txt new file mode 100644 index 0000000..4fd87b0 --- /dev/null +++ b/doc/sydra-rtp.8.txt @@ -0,0 +1,272 @@ +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> ] + [ -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: 'audioconveert ! 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,payload=96,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. + +*-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. |