Mercurial > hg > pmhd
diff ffmpeg/doc/ffmpeg-protocols.1 @ 10:6840f77b83aa
commit
| author | Yading Song <yading.song@eecs.qmul.ac.uk> |
|---|---|
| date | Sun, 21 Apr 2013 10:55:35 +0200 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ffmpeg/doc/ffmpeg-protocols.1 Sun Apr 21 10:55:35 2013 +0200 @@ -0,0 +1,918 @@ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "FFMPEG-PROTOCOLS 1" +.TH FFMPEG-PROTOCOLS 1 "2013-04-21" " " " " +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +ffmpeg\-protocols \- FFmpeg protocols +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This document describes the input and output protocols provided by the +libavformat library. +.SH "PROTOCOLS" +.IX Header "PROTOCOLS" +Protocols are configured elements in FFmpeg which allow to access +resources which require the use of a particular protocol. +.PP +When you configure your FFmpeg build, all the supported protocols are +enabled by default. You can list all available ones using the +configure option \*(L"\-\-list\-protocols\*(R". +.PP +You can disable all the protocols using the configure option +\&\*(L"\-\-disable\-protocols\*(R", and selectively enable a protocol using the +option "\-\-enable\-protocol=\fI\s-1PROTOCOL\s0\fR\*(L", or you can disable a +particular protocol using the option +\&\*(R"\-\-disable\-protocol=\fI\s-1PROTOCOL\s0\fR". +.PP +The option \*(L"\-protocols\*(R" of the ff* tools will display the list of +supported protocols. +.PP +A description of the currently available protocols follows. +.SS "bluray" +.IX Subsection "bluray" +Read BluRay playlist. +.PP +The accepted options are: +.IP "\fBangle\fR" 4 +.IX Item "angle" +BluRay angle +.IP "\fBchapter\fR" 4 +.IX Item "chapter" +Start chapter (1...N) +.IP "\fBplaylist\fR" 4 +.IX Item "playlist" +Playlist to read (\s-1BDMV/PLAYLIST/\s0?????.mpls) +.PP +Examples: +.PP +Read longest playlist from BluRay mounted to /mnt/bluray: +.PP +.Vb 1 +\& bluray:/mnt/bluray +.Ve +.PP +Read angle 2 of playlist 4 from BluRay mounted to /mnt/bluray, start from chapter 2: +.PP +.Vb 1 +\& \-playlist 4 \-angle 2 \-chapter 2 bluray:/mnt/bluray +.Ve +.SS "concat" +.IX Subsection "concat" +Physical concatenation protocol. +.PP +Allow to read and seek from many resource in sequence as if they were +a unique resource. +.PP +A \s-1URL\s0 accepted by this protocol has the syntax: +.PP +.Vb 1 +\& concat:<URL1>|<URL2>|...|<URLN> +.Ve +.PP +where \fI\s-1URL1\s0\fR, \fI\s-1URL2\s0\fR, ..., \fI\s-1URLN\s0\fR are the urls of the +resource to be concatenated, each one possibly specifying a distinct +protocol. +.PP +For example to read a sequence of files \fIsplit1.mpeg\fR, +\&\fIsplit2.mpeg\fR, \fIsplit3.mpeg\fR with \fBffplay\fR use the +command: +.PP +.Vb 1 +\& ffplay concat:split1.mpeg\e|split2.mpeg\e|split3.mpeg +.Ve +.PP +Note that you may need to escape the character \*(L"|\*(R" which is special for +many shells. +.SS "data" +.IX Subsection "data" +Data in-line in the \s-1URI\s0. See <\fBhttp://en.wikipedia.org/wiki/Data_URI_scheme\fR>. +.PP +For example, to convert a \s-1GIF\s0 file given inline with \fBffmpeg\fR: +.PP +.Vb 1 +\& ffmpeg \-i "data:image/gif;base64,R0lGODdhCAAIAMIEAAAAAAAA//8AAP//AP///////////////ywAAAAACAAIAAADF0gEDLojDgdGiJdJqUX02iB4E8Q9jUMkADs=" smiley.png +.Ve +.SS "file" +.IX Subsection "file" +File access protocol. +.PP +Allow to read from or read to a file. +.PP +For example to read from a file \fIinput.mpeg\fR with \fBffmpeg\fR +use the command: +.PP +.Vb 1 +\& ffmpeg \-i file:input.mpeg output.mpeg +.Ve +.PP +The ff* tools default to the file protocol, that is a resource +specified with the name \*(L"\s-1FILE\s0.mpeg\*(R" is interpreted as the \s-1URL\s0 +\&\*(L"file:FILE.mpeg\*(R". +.SS "gopher" +.IX Subsection "gopher" +Gopher protocol. +.SS "hls" +.IX Subsection "hls" +Read Apple \s-1HTTP\s0 Live Streaming compliant segmented stream as +a uniform one. The M3U8 playlists describing the segments can be +remote \s-1HTTP\s0 resources or local files, accessed using the standard +file protocol. +The nested protocol is declared by specifying +"+\fIproto\fR" after the hls \s-1URI\s0 scheme name, where \fIproto\fR +is either \*(L"file\*(R" or \*(L"http\*(R". +.PP +.Vb 2 +\& hls+http://host/path/to/remote/resource.m3u8 +\& hls+file://path/to/local/resource.m3u8 +.Ve +.PP +Using this protocol is discouraged \- the hls demuxer should work +just as well (if not, please report the issues) and is more complete. +To use the hls demuxer instead, simply use the direct URLs to the +m3u8 files. +.SS "http" +.IX Subsection "http" +\&\s-1HTTP\s0 (Hyper Text Transfer Protocol). +.PP +This protocol accepts the following options. +.IP "\fBseekable\fR" 4 +.IX Item "seekable" +Control seekability of connection. If set to 1 the resource is +supposed to be seekable, if set to 0 it is assumed not to be seekable, +if set to \-1 it will try to autodetect if it is seekable. Default +value is \-1. +.IP "\fBchunked_post\fR" 4 +.IX Item "chunked_post" +If set to 1 use chunked transfer-encoding for posts, default is 1. +.IP "\fBheaders\fR" 4 +.IX Item "headers" +Set custom \s-1HTTP\s0 headers, can override built in default headers. The +value must be a string encoding the headers. +.IP "\fBcontent_type\fR" 4 +.IX Item "content_type" +Force a content type. +.IP "\fBuser-agent\fR" 4 +.IX Item "user-agent" +Override User-Agent header. If not specified the protocol will use a +string describing the libavformat build. +.IP "\fBmultiple_requests\fR" 4 +.IX Item "multiple_requests" +Use persistent connections if set to 1. By default it is 0. +.IP "\fBpost_data\fR" 4 +.IX Item "post_data" +Set custom \s-1HTTP\s0 post data. +.IP "\fBtimeout\fR" 4 +.IX Item "timeout" +Set timeout of socket I/O operations used by the underlying low level +operation. By default it is set to \-1, which means that the timeout is +not specified. +.IP "\fBmime_type\fR" 4 +.IX Item "mime_type" +Set \s-1MIME\s0 type. +.IP "\fBcookies\fR" 4 +.IX Item "cookies" +Set the cookies to be sent in future requests. The format of each cookie is the +same as the value of a Set-Cookie \s-1HTTP\s0 response field. Multiple cookies can be +delimited by a newline character. +.PP +\fI\s-1HTTP\s0 Cookies\fR +.IX Subsection "HTTP Cookies" +.PP +Some \s-1HTTP\s0 requests will be denied unless cookie values are passed in with the +request. The \fBcookies\fR option allows these cookies to be specified. At +the very least, each cookie must specify a value along with a path and domain. +\&\s-1HTTP\s0 requests that match both the domain and path will automatically include the +cookie value in the \s-1HTTP\s0 Cookie header field. Multiple cookies can be delimited +by a newline. +.PP +The required syntax to play a stream specifying a cookie is: +.PP +.Vb 1 +\& ffplay \-cookies "nlqptid=nltid=tsn; path=/; domain=somedomain.com;" http://somedomain.com/somestream.m3u8 +.Ve +.SS "mmst" +.IX Subsection "mmst" +\&\s-1MMS\s0 (Microsoft Media Server) protocol over \s-1TCP\s0. +.SS "mmsh" +.IX Subsection "mmsh" +\&\s-1MMS\s0 (Microsoft Media Server) protocol over \s-1HTTP\s0. +.PP +The required syntax is: +.PP +.Vb 1 +\& mmsh://<server>[:<port>][/<app>][/<playpath>] +.Ve +.SS "md5" +.IX Subsection "md5" +\&\s-1MD5\s0 output protocol. +.PP +Computes the \s-1MD5\s0 hash of the data to be written, and on close writes +this to the designated output or stdout if none is specified. It can +be used to test muxers without writing an actual file. +.PP +Some examples follow. +.PP +.Vb 2 +\& # Write the MD5 hash of the encoded AVI file to the file output.avi.md5. +\& ffmpeg \-i input.flv \-f avi \-y md5:output.avi.md5 +\& +\& # Write the MD5 hash of the encoded AVI file to stdout. +\& ffmpeg \-i input.flv \-f avi \-y md5: +.Ve +.PP +Note that some formats (typically \s-1MOV\s0) require the output protocol to +be seekable, so they will fail with the \s-1MD5\s0 output protocol. +.SS "pipe" +.IX Subsection "pipe" +\&\s-1UNIX\s0 pipe access protocol. +.PP +Allow to read and write from \s-1UNIX\s0 pipes. +.PP +The accepted syntax is: +.PP +.Vb 1 +\& pipe:[<number>] +.Ve +.PP +\&\fInumber\fR is the number corresponding to the file descriptor of the +pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr). If \fInumber\fR +is not specified, by default the stdout file descriptor will be used +for writing, stdin for reading. +.PP +For example to read from stdin with \fBffmpeg\fR: +.PP +.Vb 3 +\& cat test.wav | ffmpeg \-i pipe:0 +\& # ...this is the same as... +\& cat test.wav | ffmpeg \-i pipe: +.Ve +.PP +For writing to stdout with \fBffmpeg\fR: +.PP +.Vb 3 +\& ffmpeg \-i test.wav \-f avi pipe:1 | cat > test.avi +\& # ...this is the same as... +\& ffmpeg \-i test.wav \-f avi pipe: | cat > test.avi +.Ve +.PP +Note that some formats (typically \s-1MOV\s0), require the output protocol to +be seekable, so they will fail with the pipe output protocol. +.SS "rtmp" +.IX Subsection "rtmp" +Real-Time Messaging Protocol. +.PP +The Real-Time Messaging Protocol (\s-1RTMP\s0) is used for streaming multimedia +content across a \s-1TCP/IP\s0 network. +.PP +The required syntax is: +.PP +.Vb 1 +\& rtmp://<server>[:<port>][/<app>][/<instance>][/<playpath>] +.Ve +.PP +The accepted parameters are: +.IP "\fBserver\fR" 4 +.IX Item "server" +The address of the \s-1RTMP\s0 server. +.IP "\fBport\fR" 4 +.IX Item "port" +The number of the \s-1TCP\s0 port to use (by default is 1935). +.IP "\fBapp\fR" 4 +.IX Item "app" +It is the name of the application to access. It usually corresponds to +the path where the application is installed on the \s-1RTMP\s0 server +(e.g. \fI/ondemand/\fR, \fI/flash/live/\fR, etc.). You can override +the value parsed from the \s-1URI\s0 through the \f(CW\*(C`rtmp_app\*(C'\fR option, too. +.IP "\fBplaypath\fR" 4 +.IX Item "playpath" +It is the path or name of the resource to play with reference to the +application specified in \fIapp\fR, may be prefixed by \*(L"mp4:\*(R". You +can override the value parsed from the \s-1URI\s0 through the \f(CW\*(C`rtmp_playpath\*(C'\fR +option, too. +.IP "\fBlisten\fR" 4 +.IX Item "listen" +Act as a server, listening for an incoming connection. +.IP "\fBtimeout\fR" 4 +.IX Item "timeout" +Maximum time to wait for the incoming connection. Implies listen. +.PP +Additionally, the following parameters can be set via command line options +(or in code via \f(CW\*(C`AVOption\*(C'\fRs): +.IP "\fBrtmp_app\fR" 4 +.IX Item "rtmp_app" +Name of application to connect on the \s-1RTMP\s0 server. This option +overrides the parameter specified in the \s-1URI\s0. +.IP "\fBrtmp_buffer\fR" 4 +.IX Item "rtmp_buffer" +Set the client buffer time in milliseconds. The default is 3000. +.IP "\fBrtmp_conn\fR" 4 +.IX Item "rtmp_conn" +Extra arbitrary \s-1AMF\s0 connection parameters, parsed from a string, +e.g. like \f(CW\*(C`B:1 S:authMe O:1 NN:code:1.23 NS:flag:ok O:0\*(C'\fR. +Each value is prefixed by a single character denoting the type, +B for Boolean, N for number, S for string, O for object, or Z for null, +followed by a colon. For Booleans the data must be either 0 or 1 for +\&\s-1FALSE\s0 or \s-1TRUE\s0, respectively. Likewise for Objects the data must be 0 or +1 to end or begin an object, respectively. Data items in subobjects may +be named, by prefixing the type with 'N' and specifying the name before +the value (i.e. \f(CW\*(C`NB:myFlag:1\*(C'\fR). This option may be used multiple +times to construct arbitrary \s-1AMF\s0 sequences. +.IP "\fBrtmp_flashver\fR" 4 +.IX Item "rtmp_flashver" +Version of the Flash plugin used to run the \s-1SWF\s0 player. The default +is \s-1LNX\s0 9,0,124,2. +.IP "\fBrtmp_flush_interval\fR" 4 +.IX Item "rtmp_flush_interval" +Number of packets flushed in the same request (\s-1RTMPT\s0 only). The default +is 10. +.IP "\fBrtmp_live\fR" 4 +.IX Item "rtmp_live" +Specify that the media is a live stream. No resuming or seeking in +live streams is possible. The default value is \f(CW\*(C`any\*(C'\fR, which means the +subscriber first tries to play the live stream specified in the +playpath. If a live stream of that name is not found, it plays the +recorded stream. The other possible values are \f(CW\*(C`live\*(C'\fR and +\&\f(CW\*(C`recorded\*(C'\fR. +.IP "\fBrtmp_pageurl\fR" 4 +.IX Item "rtmp_pageurl" +\&\s-1URL\s0 of the web page in which the media was embedded. By default no +value will be sent. +.IP "\fBrtmp_playpath\fR" 4 +.IX Item "rtmp_playpath" +Stream identifier to play or to publish. This option overrides the +parameter specified in the \s-1URI\s0. +.IP "\fBrtmp_subscribe\fR" 4 +.IX Item "rtmp_subscribe" +Name of live stream to subscribe to. By default no value will be sent. +It is only sent if the option is specified or if rtmp_live +is set to live. +.IP "\fBrtmp_swfhash\fR" 4 +.IX Item "rtmp_swfhash" +\&\s-1SHA256\s0 hash of the decompressed \s-1SWF\s0 file (32 bytes). +.IP "\fBrtmp_swfsize\fR" 4 +.IX Item "rtmp_swfsize" +Size of the decompressed \s-1SWF\s0 file, required for SWFVerification. +.IP "\fBrtmp_swfurl\fR" 4 +.IX Item "rtmp_swfurl" +\&\s-1URL\s0 of the \s-1SWF\s0 player for the media. By default no value will be sent. +.IP "\fBrtmp_swfverify\fR" 4 +.IX Item "rtmp_swfverify" +\&\s-1URL\s0 to player swf file, compute hash/size automatically. +.IP "\fBrtmp_tcurl\fR" 4 +.IX Item "rtmp_tcurl" +\&\s-1URL\s0 of the target stream. Defaults to proto://host[:port]/app. +.PP +For example to read with \fBffplay\fR a multimedia resource named +\&\*(L"sample\*(R" from the application \*(L"vod\*(R" from an \s-1RTMP\s0 server \*(L"myserver\*(R": +.PP +.Vb 1 +\& ffplay rtmp://myserver/vod/sample +.Ve +.SS "rtmpe" +.IX Subsection "rtmpe" +Encrypted Real-Time Messaging Protocol. +.PP +The Encrypted Real-Time Messaging Protocol (\s-1RTMPE\s0) is used for +streaming multimedia content within standard cryptographic primitives, +consisting of Diffie-Hellman key exchange and \s-1HMACSHA256\s0, generating +a pair of \s-1RC4\s0 keys. +.SS "rtmps" +.IX Subsection "rtmps" +Real-Time Messaging Protocol over a secure \s-1SSL\s0 connection. +.PP +The Real-Time Messaging Protocol (\s-1RTMPS\s0) is used for streaming +multimedia content across an encrypted connection. +.SS "rtmpt" +.IX Subsection "rtmpt" +Real-Time Messaging Protocol tunneled through \s-1HTTP\s0. +.PP +The Real-Time Messaging Protocol tunneled through \s-1HTTP\s0 (\s-1RTMPT\s0) is used +for streaming multimedia content within \s-1HTTP\s0 requests to traverse +firewalls. +.SS "rtmpte" +.IX Subsection "rtmpte" +Encrypted Real-Time Messaging Protocol tunneled through \s-1HTTP\s0. +.PP +The Encrypted Real-Time Messaging Protocol tunneled through \s-1HTTP\s0 (\s-1RTMPTE\s0) +is used for streaming multimedia content within \s-1HTTP\s0 requests to traverse +firewalls. +.SS "rtmpts" +.IX Subsection "rtmpts" +Real-Time Messaging Protocol tunneled through \s-1HTTPS\s0. +.PP +The Real-Time Messaging Protocol tunneled through \s-1HTTPS\s0 (\s-1RTMPTS\s0) is used +for streaming multimedia content within \s-1HTTPS\s0 requests to traverse +firewalls. +.SS "rtmp, rtmpe, rtmps, rtmpt, rtmpte" +.IX Subsection "rtmp, rtmpe, rtmps, rtmpt, rtmpte" +Real-Time Messaging Protocol and its variants supported through +librtmp. +.PP +Requires the presence of the librtmp headers and library during +configuration. You need to explicitly configure the build with +\&\*(L"\-\-enable\-librtmp\*(R". If enabled this will replace the native \s-1RTMP\s0 +protocol. +.PP +This protocol provides most client functions and a few server +functions needed to support \s-1RTMP\s0, \s-1RTMP\s0 tunneled in \s-1HTTP\s0 (\s-1RTMPT\s0), +encrypted \s-1RTMP\s0 (\s-1RTMPE\s0), \s-1RTMP\s0 over \s-1SSL/TLS\s0 (\s-1RTMPS\s0) and tunneled +variants of these encrypted types (\s-1RTMPTE\s0, \s-1RTMPTS\s0). +.PP +The required syntax is: +.PP +.Vb 1 +\& <rtmp_proto>://<server>[:<port>][/<app>][/<playpath>] <options> +.Ve +.PP +where \fIrtmp_proto\fR is one of the strings \*(L"rtmp\*(R", \*(L"rtmpt\*(R", \*(L"rtmpe\*(R", +\&\*(L"rtmps\*(R", \*(L"rtmpte\*(R", \*(L"rtmpts\*(R" corresponding to each \s-1RTMP\s0 variant, and +\&\fIserver\fR, \fIport\fR, \fIapp\fR and \fIplaypath\fR have the same +meaning as specified for the \s-1RTMP\s0 native protocol. +\&\fIoptions\fR contains a list of space-separated options of the form +\&\fIkey\fR=\fIval\fR. +.PP +See the librtmp manual page (man 3 librtmp) for more information. +.PP +For example, to stream a file in real-time to an \s-1RTMP\s0 server using +\&\fBffmpeg\fR: +.PP +.Vb 1 +\& ffmpeg \-re \-i myfile \-f flv rtmp://myserver/live/mystream +.Ve +.PP +To play the same stream using \fBffplay\fR: +.PP +.Vb 1 +\& ffplay "rtmp://myserver/live/mystream live=1" +.Ve +.SS "rtp" +.IX Subsection "rtp" +Real-Time Protocol. +.SS "rtsp" +.IX Subsection "rtsp" +\&\s-1RTSP\s0 is not technically a protocol handler in libavformat, it is a demuxer +and muxer. The demuxer supports both normal \s-1RTSP\s0 (with data transferred +over \s-1RTP\s0; this is used by e.g. Apple and Microsoft) and Real-RTSP (with +data transferred over \s-1RDT\s0). +.PP +The muxer can be used to send a stream using \s-1RTSP\s0 \s-1ANNOUNCE\s0 to a server +supporting it (currently Darwin Streaming Server and Mischa Spiegelmock's +<\fBhttp://github.com/revmischa/rtsp\-server\fR>). +.PP +The required syntax for a \s-1RTSP\s0 url is: +.PP +.Vb 1 +\& rtsp://<hostname>[:<port>]/<path> +.Ve +.PP +The following options (set on the \fBffmpeg\fR/\fBffplay\fR command +line, or set in code via \f(CW\*(C`AVOption\*(C'\fRs or in \f(CW\*(C`avformat_open_input\*(C'\fR), +are supported: +.PP +Flags for \f(CW\*(C`rtsp_transport\*(C'\fR: +.IP "\fBudp\fR" 4 +.IX Item "udp" +Use \s-1UDP\s0 as lower transport protocol. +.IP "\fBtcp\fR" 4 +.IX Item "tcp" +Use \s-1TCP\s0 (interleaving within the \s-1RTSP\s0 control channel) as lower +transport protocol. +.IP "\fBudp_multicast\fR" 4 +.IX Item "udp_multicast" +Use \s-1UDP\s0 multicast as lower transport protocol. +.IP "\fBhttp\fR" 4 +.IX Item "http" +Use \s-1HTTP\s0 tunneling as lower transport protocol, which is useful for +passing proxies. +.PP +Multiple lower transport protocols may be specified, in that case they are +tried one at a time (if the setup of one fails, the next one is tried). +For the muxer, only the \f(CW\*(C`tcp\*(C'\fR and \f(CW\*(C`udp\*(C'\fR options are supported. +.PP +Flags for \f(CW\*(C`rtsp_flags\*(C'\fR: +.IP "\fBfilter_src\fR" 4 +.IX Item "filter_src" +Accept packets only from negotiated peer address and port. +.IP "\fBlisten\fR" 4 +.IX Item "listen" +Act as a server, listening for an incoming connection. +.PP +When receiving data over \s-1UDP\s0, the demuxer tries to reorder received packets +(since they may arrive out of order, or packets may get lost totally). This +can be disabled by setting the maximum demuxing delay to zero (via +the \f(CW\*(C`max_delay\*(C'\fR field of AVFormatContext). +.PP +When watching multi-bitrate Real-RTSP streams with \fBffplay\fR, the +streams to display can be chosen with \f(CW\*(C`\-vst\*(C'\fR \fIn\fR and +\&\f(CW\*(C`\-ast\*(C'\fR \fIn\fR for video and audio respectively, and can be switched +on the fly by pressing \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`a\*(C'\fR. +.PP +Example command lines: +.PP +To watch a stream over \s-1UDP\s0, with a max reordering delay of 0.5 seconds: +.PP +.Vb 1 +\& ffplay \-max_delay 500000 \-rtsp_transport udp rtsp://server/video.mp4 +.Ve +.PP +To watch a stream tunneled over \s-1HTTP:\s0 +.PP +.Vb 1 +\& ffplay \-rtsp_transport http rtsp://server/video.mp4 +.Ve +.PP +To send a stream in realtime to a \s-1RTSP\s0 server, for others to watch: +.PP +.Vb 1 +\& ffmpeg \-re \-i <input> \-f rtsp \-muxdelay 0.1 rtsp://server/live.sdp +.Ve +.PP +To receive a stream in realtime: +.PP +.Vb 1 +\& ffmpeg \-rtsp_flags listen \-i rtsp://ownaddress/live.sdp <output> +.Ve +.IP "\fBstimeout\fR" 4 +.IX Item "stimeout" +Socket \s-1IO\s0 timeout in micro seconds. +.SS "sap" +.IX Subsection "sap" +Session Announcement Protocol (\s-1RFC\s0 2974). This is not technically a +protocol handler in libavformat, it is a muxer and demuxer. +It is used for signalling of \s-1RTP\s0 streams, by announcing the \s-1SDP\s0 for the +streams regularly on a separate port. +.PP +\fIMuxer\fR +.IX Subsection "Muxer" +.PP +The syntax for a \s-1SAP\s0 url given to the muxer is: +.PP +.Vb 1 +\& sap://<destination>[:<port>][?<options>] +.Ve +.PP +The \s-1RTP\s0 packets are sent to \fIdestination\fR on port \fIport\fR, +or to port 5004 if no port is specified. +\&\fIoptions\fR is a \f(CW\*(C`&\*(C'\fR\-separated list. The following options +are supported: +.IP "\fBannounce_addr=\fR\fIaddress\fR" 4 +.IX Item "announce_addr=address" +Specify the destination \s-1IP\s0 address for sending the announcements to. +If omitted, the announcements are sent to the commonly used \s-1SAP\s0 +announcement multicast address 224.2.127.254 (sap.mcast.net), or +ff0e::2:7ffe if \fIdestination\fR is an IPv6 address. +.IP "\fBannounce_port=\fR\fIport\fR" 4 +.IX Item "announce_port=port" +Specify the port to send the announcements on, defaults to +9875 if not specified. +.IP "\fBttl=\fR\fIttl\fR" 4 +.IX Item "ttl=ttl" +Specify the time to live value for the announcements and \s-1RTP\s0 packets, +defaults to 255. +.IP "\fBsame_port=\fR\fI0|1\fR" 4 +.IX Item "same_port=0|1" +If set to 1, send all \s-1RTP\s0 streams on the same port pair. If zero (the +default), all streams are sent on unique ports, with each stream on a +port 2 numbers higher than the previous. +VLC/Live555 requires this to be set to 1, to be able to receive the stream. +The \s-1RTP\s0 stack in libavformat for receiving requires all streams to be sent +on unique ports. +.PP +Example command lines follow. +.PP +To broadcast a stream on the local subnet, for watching in \s-1VLC:\s0 +.PP +.Vb 1 +\& ffmpeg \-re \-i <input> \-f sap sap://224.0.0.255?same_port=1 +.Ve +.PP +Similarly, for watching in \fBffplay\fR: +.PP +.Vb 1 +\& ffmpeg \-re \-i <input> \-f sap sap://224.0.0.255 +.Ve +.PP +And for watching in \fBffplay\fR, over IPv6: +.PP +.Vb 1 +\& ffmpeg \-re \-i <input> \-f sap sap://[ff0e::1:2:3:4] +.Ve +.PP +\fIDemuxer\fR +.IX Subsection "Demuxer" +.PP +The syntax for a \s-1SAP\s0 url given to the demuxer is: +.PP +.Vb 1 +\& sap://[<address>][:<port>] +.Ve +.PP +\&\fIaddress\fR is the multicast address to listen for announcements on, +if omitted, the default 224.2.127.254 (sap.mcast.net) is used. \fIport\fR +is the port that is listened on, 9875 if omitted. +.PP +The demuxers listens for announcements on the given address and port. +Once an announcement is received, it tries to receive that particular stream. +.PP +Example command lines follow. +.PP +To play back the first stream announced on the normal \s-1SAP\s0 multicast address: +.PP +.Vb 1 +\& ffplay sap:// +.Ve +.PP +To play back the first stream announced on one the default IPv6 \s-1SAP\s0 multicast address: +.PP +.Vb 1 +\& ffplay sap://[ff0e::2:7ffe] +.Ve +.SS "tcp" +.IX Subsection "tcp" +Trasmission Control Protocol. +.PP +The required syntax for a \s-1TCP\s0 url is: +.PP +.Vb 1 +\& tcp://<hostname>:<port>[?<options>] +.Ve +.IP "\fBlisten\fR" 4 +.IX Item "listen" +Listen for an incoming connection +.IP "\fBtimeout=\fR\fImicroseconds\fR" 4 +.IX Item "timeout=microseconds" +In read mode: if no data arrived in more than this time interval, raise error. +In write mode: if socket cannot be written in more than this time interval, raise error. +This also sets timeout on \s-1TCP\s0 connection establishing. +.Sp +.Vb 2 +\& ffmpeg \-i <input> \-f <format> tcp://<hostname>:<port>?listen +\& ffplay tcp://<hostname>:<port> +.Ve +.SS "tls" +.IX Subsection "tls" +Transport Layer Security/Secure Sockets Layer +.PP +The required syntax for a \s-1TLS/SSL\s0 url is: +.PP +.Vb 1 +\& tls://<hostname>:<port>[?<options>] +.Ve +.IP "\fBlisten\fR" 4 +.IX Item "listen" +Act as a server, listening for an incoming connection. +.IP "\fBcafile=\fR\fIfilename\fR" 4 +.IX Item "cafile=filename" +Certificate authority file. The file must be in OpenSSL \s-1PEM\s0 format. +.IP "\fBcert=\fR\fIfilename\fR" 4 +.IX Item "cert=filename" +Certificate file. The file must be in OpenSSL \s-1PEM\s0 format. +.IP "\fBkey=\fR\fIfilename\fR" 4 +.IX Item "key=filename" +Private key file. +.IP "\fBverify=\fR\fI0|1\fR" 4 +.IX Item "verify=0|1" +Verify the peer's certificate. +.PP +Example command lines: +.PP +To create a \s-1TLS/SSL\s0 server that serves an input stream. +.PP +.Vb 1 +\& ffmpeg \-i <input> \-f <format> tls://<hostname>:<port>?listen&cert=<server.crt>&key=<server.key> +.Ve +.PP +To play back a stream from the \s-1TLS/SSL\s0 server using \fBffplay\fR: +.PP +.Vb 1 +\& ffplay tls://<hostname>:<port> +.Ve +.SS "udp" +.IX Subsection "udp" +User Datagram Protocol. +.PP +The required syntax for a \s-1UDP\s0 url is: +.PP +.Vb 1 +\& udp://<hostname>:<port>[?<options>] +.Ve +.PP +\&\fIoptions\fR contains a list of &\-separated options of the form \fIkey\fR=\fIval\fR. +.PP +In case threading is enabled on the system, a circular buffer is used +to store the incoming data, which allows to reduce loss of data due to +\&\s-1UDP\s0 socket buffer overruns. The \fIfifo_size\fR and +\&\fIoverrun_nonfatal\fR options are related to this buffer. +.PP +The list of supported options follows. +.IP "\fBbuffer_size=\fR\fIsize\fR" 4 +.IX Item "buffer_size=size" +Set the \s-1UDP\s0 socket buffer size in bytes. This is used both for the +receiving and the sending buffer size. +.IP "\fBlocalport=\fR\fIport\fR" 4 +.IX Item "localport=port" +Override the local \s-1UDP\s0 port to bind with. +.IP "\fBlocaladdr=\fR\fIaddr\fR" 4 +.IX Item "localaddr=addr" +Choose the local \s-1IP\s0 address. This is useful e.g. if sending multicast +and the host has multiple interfaces, where the user can choose +which interface to send on by specifying the \s-1IP\s0 address of that interface. +.IP "\fBpkt_size=\fR\fIsize\fR" 4 +.IX Item "pkt_size=size" +Set the size in bytes of \s-1UDP\s0 packets. +.IP "\fBreuse=\fR\fI1|0\fR" 4 +.IX Item "reuse=1|0" +Explicitly allow or disallow reusing \s-1UDP\s0 sockets. +.IP "\fBttl=\fR\fIttl\fR" 4 +.IX Item "ttl=ttl" +Set the time to live value (for multicast only). +.IP "\fBconnect=\fR\fI1|0\fR" 4 +.IX Item "connect=1|0" +Initialize the \s-1UDP\s0 socket with \f(CW\*(C`connect()\*(C'\fR. In this case, the +destination address can't be changed with ff_udp_set_remote_url later. +If the destination address isn't known at the start, this option can +be specified in ff_udp_set_remote_url, too. +This allows finding out the source address for the packets with getsockname, +and makes writes return with \s-1AVERROR\s0(\s-1ECONNREFUSED\s0) if \*(L"destination +unreachable\*(R" is received. +For receiving, this gives the benefit of only receiving packets from +the specified peer address/port. +.IP "\fBsources=\fR\fIaddress\fR\fB[,\fR\fIaddress\fR\fB]\fR" 4 +.IX Item "sources=address[,address]" +Only receive packets sent to the multicast group from one of the +specified sender \s-1IP\s0 addresses. +.IP "\fBblock=\fR\fIaddress\fR\fB[,\fR\fIaddress\fR\fB]\fR" 4 +.IX Item "block=address[,address]" +Ignore packets sent to the multicast group from the specified +sender \s-1IP\s0 addresses. +.IP "\fBfifo_size=\fR\fIunits\fR" 4 +.IX Item "fifo_size=units" +Set the \s-1UDP\s0 receiving circular buffer size, expressed as a number of +packets with size of 188 bytes. If not specified defaults to 7*4096. +.IP "\fBoverrun_nonfatal=\fR\fI1|0\fR" 4 +.IX Item "overrun_nonfatal=1|0" +Survive in case of \s-1UDP\s0 receiving circular buffer overrun. Default +value is 0. +.IP "\fBtimeout=\fR\fImicroseconds\fR" 4 +.IX Item "timeout=microseconds" +In read mode: if no data arrived in more than this time interval, raise error. +.PP +Some usage examples of the \s-1UDP\s0 protocol with \fBffmpeg\fR follow. +.PP +To stream over \s-1UDP\s0 to a remote endpoint: +.PP +.Vb 1 +\& ffmpeg \-i <input> \-f <format> udp://<hostname>:<port> +.Ve +.PP +To stream in mpegts format over \s-1UDP\s0 using 188 sized \s-1UDP\s0 packets, using a large input buffer: +.PP +.Vb 1 +\& ffmpeg \-i <input> \-f mpegts udp://<hostname>:<port>?pkt_size=188&buffer_size=65535 +.Ve +.PP +To receive over \s-1UDP\s0 from a remote endpoint: +.PP +.Vb 1 +\& ffmpeg \-i udp://[<multicast\-address>]:<port> +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIffmpeg\fR\|(1), \fIffplay\fR\|(1), \fIffprobe\fR\|(1), \fIffserver\fR\|(1), \fIlibavformat\fR\|(3) +.SH "AUTHORS" +.IX Header "AUTHORS" +The FFmpeg developers. +.PP +For details about the authorship, see the Git history of the project +(git://source.ffmpeg.org/ffmpeg), e.g. by typing the command +\&\fBgit log\fR in the FFmpeg source directory, or browsing the +online repository at <\fBhttp://source.ffmpeg.org\fR>. +.PP +Maintainers for the specific components are listed in the file +\&\fI\s-1MAINTAINERS\s0\fR in the source code tree.