From a0d2eedec53284d81132ae3f34d3357af527ce9c Mon Sep 17 00:00:00 2001 From: Christian Pointner Date: Thu, 2 Oct 2014 04:53:47 +0200 Subject: added alle options to the manpage --- doc/sydra.8 | 254 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/sydra.8.txt | 154 ++++++++++++++++++++++++++++++++++ src/options.c | 2 +- 3 files changed, 409 insertions(+), 1 deletion(-) diff --git a/doc/sydra.8 b/doc/sydra.8 index d8b3337..6e875d4 100644 --- a/doc/sydra.8 +++ b/doc/sydra.8 @@ -41,6 +41,32 @@ sydra \- toolbox for RTP based streams [ \fB\-P|\-\-write\-pid\fR ] [ \fB\-L|\-\-log\fR :[,[,[\&.\&.]]] ] [ \fB\-U|\-\-debug\fR ] + [ \fB\-n|\-\-appname\fR ] + [ \fB\-m|\-\-mode\fR (sender|reciever) ] + [ \fB\-\-source\fR ] + [ \fB\-\-video\-encoder\fR ] + [ \fB\-\-video\-payloader\fR ] + [ \fB\-\-previewsink\fR ] + [ \fB\-\-audio\-encoder\fR ] + [ \fB\-\-audio\-payloader\fR ] + [ \fB\-\-video\-caps\fR ] + [ \fB\-\-video\-depayloader\fR ] + [ \fB\-\-video\-decoder\fR ] + [ \fB\-\-audio\-caps\fR ] + [ \fB\-\-audio\-depayloader\fR ] + [ \fB\-\-audio\-decoder\fR ] + [ \fB\-\-sink\fR ] + [ \fB\-a|\-\-rtp\-host\fR ] + [ \fB\-o|\-\-rtp\-port\-base\fR ] + [ \fB\-A|\-\-rtp\-addr\-local\fR
] + [ \fB\-O|\-\-rtp\-port\-base\-local\fR ] + [ \fB\-c|\-\-no\-auto\-client\fR ] + [ \fB\-t|\-\-timeout\fR ] + [ \fB\-k|\-\-keepalive\-interval\fR ] + [ \fB\-\-rec\-video\-encoder\fR ] + [ \fB\-\-rec\-audio\-encoder\fR ] + [ \fB\-\-rec\-mux\fR ] + [ \fB\-\-rec\-name\-format\fR ] .fi .SH "DESCRIPTION" .sp @@ -48,6 +74,8 @@ sydra \- toolbox for RTP based streams .SH "OPTIONS" .sp The following options can be passed to the \fBsydra\fR daemon: +.sp +\fBglobal options\fR .PP \fB\-D, \-\-nodaemonize\fR .RS 4 @@ -121,6 +149,232 @@ to run in debug mode\&. It implicits \fBstdout:5\fR (logging with maximum level)\&. In future releases there might be additional output when this option is supplied\&. .RE +.PP +\fB\-n, \-\-appname \fR +.RS 4 +This set the application name using +\fIg_set_prgname()\fR\&. It will be used for example by xvimagesink for window title\&. +.RE +.PP +\fB\-m, \-\-mode (sender|reciever)\fR +.RS 4 +This sets the main mode of +\fBsydra\fR\&. The sender will read raw video and audio from the source bin and send it via RTP to one or more receivers\&. +.RE +.sp +\fBsender\-mode only options\fR +.PP +\fB\-\-source \fR +.RS 4 +A gst\-launch\-style description for the raw video and audio bin\&. This bin must contain an element called +\fIvideosrc\fR +and an element called +\fIaudiosrc\fR +which should each contain a pad called +\fIsrc\fR\&. Theses pads will get connected to the encoder bins\&. Example: +\fIv4l2src ! 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"\fR +.RE +.PP +\fB\-\-video\-encoder \fR +.RS 4 +Bin description for the video encoder\&. Example: +\fIvideoconvert ! vp8enc\fR +.RE +.PP +\fB\-\-video\-payloader \fR +.RS 4 +A RTP payloader element for the video codec in use\&. Example: +\fIrtpvp8pay\fR +.RE +.PP +\fB\-\-previewsink \fR +.RS 4 +A video sink element for local preview\&. Example: +\fIvideoconvert ! textoverlay test="preview" ! xvimagesink\fR +.RE +.PP +\fB\-\-audio\-encoder \fR +.RS 4 +Bin description for the audio encoder\&. Example: +\fIaudioconveert ! opusenc\fR +.RE +.PP +\fB\-\-audio\-payloader \fR +.RS 4 +A RTP payloader element for the audio codec in use\&. Example: +\fIrtpopuspay\fR +.RE +.sp +\fBreceiver\-mode only options\fR +.PP +\fB\-\-video\-caps \fR +.RS 4 +These caps will get assigned to incoming RTP packets for video\&. Example: +\fIapplication/x\-rtp,media=video,clock\-rate=90000,encoding\-name=VP8\-DRAFT\-IETF\-01,caps="video/x\-vp8"\fR +.RE +.PP +\fB\-\-video\-depayloader \fR +.RS 4 +A RTP depayloader element for the video codec in use\&. Example: +\fIrtpvp8depay\fR +.RE +.PP +\fB\-\-video\-decoder \fR +.RS 4 +Bin description for the video decoder\&. Example: +\fIvp8dec\fR +.RE +.PP +\fB\-\-audio\-caps \fR +.RS 4 +These caps will get assigned to incoming RTP packets for audio\&. Example: +\fIapplication/x\-rtp,media=audio,clock\-rate=48000,payload=96,encoding\-name=X\-GST\-OPUS\-DRAFT\-SPITTKA\-00,caps="audio/x\-opus"\fR +.RE +.PP +\fB\-\-audio\-depayloader \fR +.RS 4 +A RTP depayloader element for the audio codec in use\&. Example: +\fIrtpopusdepay\fR +.RE +.PP +\fB\-\-audio\-decoder \fR +.RS 4 +Bin description for the audio decoder\&. Example: +\fIopusdec\fR +.RE +.PP +\fB\-\-sink \fR +.RS 4 +A gst\-launch\-style description for the raw video and audio bin\&. This bin must contain an element called +\fIvideosink\fR +and an element called +\fIaudiosink\fR +which should each contain a pad called +\fIsink\fR\&. Theses pads will get connected to the decoder bins\&. Example: +\fIvideoconvert name="videosink" ! videoscale add\-borders=true ! xvimagesink audioconvert name="audiosink" ! autoaudiosink\fR +.RE +.sp +\fBoptions for RTP\fR +.PP +\fB\-a, \-\-rtp\-host \fR +.RS 4 +In +\fIsender\fR +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\(cqt 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 +\fIreceiver\fR +mode keepalive messages will be sent to this host\&. Leave empty to disable keepalive messages\&. +.RE +.PP +\fB\-o, \-\-rtp\-port\-base \fR +.RS 4 +The base number for remote ports\&. +\fBsydra\fR +will send the RTP/RTCP packets using the following mapping: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +rtp\-port\-base + 0: RTP Video +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +rtp\-port\-base + 1: RTCP Video +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +rtp\-port\-base + 2: RTP Audio +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +rtp\-port\-base + 3: RTCP Audio +.RE +.RE +.PP +\fB\-A, \-\-rtp\-addr\-local
\fR +.RS 4 +The local address to wait for incoming UDP messages\&. Leave empty to listen on any address\&. +.RE +.PP +\fB\-O, \-\-rtp\-port\-base\-local \fR +.RS 4 +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\&. +.RE +.PP +\fB\-c, \-\-no\-auto\-client\fR +.RS 4 +This disables auto\-detection for clients in +\fIsender\fR +mode\&. Mind that if you disable the automatic client detection and also omit the rtp\-host option +\fBsydra\fR +won\(cqt send any RTP messages\&. If configured recording will work but this is most probably not what you want\&. +.RE +.PP +\fB\-t, \-\-timeout \fR +.RS 4 +This sets the client timeout in seconds in +\fIsender\fR +mode\&. A value of 0 disables client timeouts\&. This is not recommended\&. +.RE +.PP +\fB\-k, \-\-keepalive\-interval \fR +.RS 4 +This sets the interval in seconds for sending out keepalive messages in +\fIreceiver\fR +mode\&. A value of 0 disables keepalive messages and therefor the client auto detection won\(cqt work for this client\&. +.RE +.sp +\fBoptions for recording\fR +.PP +\fB\-\-rec\-video\-encoder \fR +.RS 4 +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: +\fIvideoconvert ! jpegenc\fR +.RE +.PP +\fB\-\-rec\-audio\-encoder \fR +.RS 4 +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: +\fIaudioconvert ! vorbisenc\fR +.RE +.PP +\fB\-\-rec\-mux \fR +.RS 4 +A gstreamer muxer element used for recording\&. If you leave this empty recording will be disabled\&. Example: +\fImatroskamux\fR +.RE +.PP +\fB\-\-rec\-name\-format \fR +.RS 4 +A +\fIstrftime\fR +based format string which will be used to create the name for the recorded file\&. Example: \&./recordings/%Y\-%m\-%d_%H\-%M\-%S\&.mkv +.RE .SH "BUGS" .sp Most likely there are some bugs in \fBsydra\fR\&. If you find a bug, please let the developers know at equinox@spreadspace\&.org\&. Of course, patches are preferred\&. diff --git a/doc/sydra.8.txt b/doc/sydra.8.txt index 6330b71..532f6de 100644 --- a/doc/sydra.8.txt +++ b/doc/sydra.8.txt @@ -20,6 +20,32 @@ sydra [ -P|--write-pid ] [ -L|--log :[,[,[..]]] ] [ -U|--debug ] + [ -n|--appname ] + [ -m|--mode (sender|reciever) ] + [ --source ] + [ --video-encoder ] + [ --video-payloader ] + [ --previewsink ] + [ --audio-encoder ] + [ --audio-payloader ] + [ --video-caps ] + [ --video-depayloader ] + [ --video-decoder ] + [ --audio-caps ] + [ --audio-depayloader ] + [ --audio-decoder ] + [ --sink ] + [ -a|--rtp-host ] + [ -o|--rtp-port-base ] + [ -A|--rtp-addr-local
] + [ -O|--rtp-port-base-local ] + [ -c|--no-auto-client ] + [ -t|--timeout ] + [ -k|--keepalive-interval ] + [ --rec-video-encoder ] + [ --rec-audio-encoder ] + [ --rec-mux ] + [ --rec-name-format ] .... @@ -38,6 +64,8 @@ OPTIONS The following options can be passed to the *sydra* daemon: +*global options* + *-D, --nodaemonize*:: This option instructs *sydra* to run in foreground instead of becoming a daemon which is the default. @@ -79,6 +107,132 @@ The following options can be passed to the *sydra* daemon: *stdout:5* (logging with maximum level). In future releases there might be additional output when this option is supplied. +*-n, --appname *:: + 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*. 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 *:: + 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 for the video encoder. Example: 'videoconvert ! vp8enc' + +*--video-payloader *:: + A RTP payloader element for the video codec in use. Example: 'rtpvp8pay' + +*--previewsink *:: + A video sink element for local preview. Example: 'videoconvert ! textoverlay test="preview" ! xvimagesink' + +*--audio-encoder *:: + Bin description for the audio encoder. Example: 'audioconveert ! opusenc' + +*--audio-payloader *:: + A RTP payloader element for the audio codec in use. Example: 'rtpopuspay' + + +*receiver-mode only options* + +*--video-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 *:: + A RTP depayloader element for the video codec in use. Example: 'rtpvp8depay' + +*--video-decoder *:: + Bin description for the video decoder. Example: 'vp8dec' + +*--audio-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 *:: + A RTP depayloader element for the audio codec in use. Example: 'rtpopusdepay' + +*--audio-decoder *:: + Bin description for the audio decoder. Example: 'opusdec' + +*--sink *:: + 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 *:: + 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 *:: + The base number for remote ports. *sydra* 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
*:: + The local address to wait for incoming UDP messages. Leave empty to listen on any address. + +*-O, --rtp-port-base-local *:: + 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* won't send any RTP + messages. If configured recording will work but this is most probably not what you want. + +*-t, --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 *:: + 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 *:: + 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 *:: + 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 *:: + A gstreamer muxer element used for recording. If you leave this empty recording will be + disabled. Example: 'matroskamux' + +*--rec-name-format *:: + 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 ---- diff --git a/src/options.c b/src/options.c index 354b3be..89c55fc 100644 --- a/src/options.c +++ b/src/options.c @@ -190,7 +190,7 @@ static GOptionGroup* options_get_rec_group(options_t* opt) { "rec-audio-encoder", 0, 0, G_OPTION_ARG_STRING, &opt->audio_enc_rec_, "pipeline for audio encoder for recording (i.e. audioconvert ! vorbisenc) - leave empty to use same as for RTP", "BIN DESCRIPTION" }, { "rec-mux", 0, 0, G_OPTION_ARG_STRING, &opt->rec_mux_, - "muxer elemenent for recording (i.e. matroskamux) - leave empty to disable recording", "ELEMENT" }, + "muxer element for recording (i.e. matroskamux) - leave empty to disable recording", "ELEMENT" }, { "rec-name-format", 0, 0, G_OPTION_ARG_STRING, &opt->rec_name_format_, "the recording file name format string, see manpage of strftime for the syntax", "FORMATSTRING" }, { NULL } -- cgit v1.2.3