doc/protocols.texi

   1 @chapter Protocols
   2 @c man begin PROTOCOLS
   3
   4 Protocols are configured elements in FFmpeg which allow to access
   5 resources which require the use of a particular protocol.
   6
   7 When you configure your FFmpeg build, all the supported protocols
   8 are enabled by default. You can list them using the configure option
   9 "--list-protocols".
  10
  11 You can disable all the protocols using the configure option
  12 "--disable-protocols", and selectively enable a protocol using the
  13 option "--enable-protocol=@var{PROTOCOL}", or you can disable a
  14 particular protocol using the option
  15 "--disable-protocol=@var{PROTOCOL}".
  16
  17 The option "-protocols" of the ff* tools will display the list of
  18 the supported protocols.
  19
  20 A description of the currently available protocols follows.
  21
  22 @section concat
  23
  24 Physical concatenation protocol.
  25
  26 Allow to read and seek from many resource in sequence as they were an
  27 unique resource.
  28
  29 An url accepted by this protocol has the syntax:
  30 @example
  31 concat:@var{URL1}|@var{URL2}|...|@var{URLN}
  32 @end example
  33
  34 where @var{URL1}, @var{URL2}, ..., @var{URLN} are the urls of the
  35 resource to be concatenated, each one possibly specifying a distinct
  36 protocol.
  37
  38 For example to read a sequence of files @file{split1.mpeg},
  39 @file{split2.mpeg}, @file{split3.mpeg} with @file{ffplay} use the
  40 command:
  41 @example
  42 ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg
  43 @end example
  44
  45 Note that you may need to escape the character "|" which is special for
  46 many shells.
  47
  48 @section file
  49
  50 File access protocol.
  51
  52 Allow to read from or read to a file.
  53
  54 For example to read from a file @file{input.mpeg} with @file{ffmpeg}
  55 use the command:
  56 @example
  57 ffmpeg -i file:input.mpeg output.mpeg
  58 @end example
  59
  60 Note that if not specified otherwise, the ff* tools will use the file
  61 protocol by default, that is a resource specified with the name
  62 "FILE.mpeg" is interpreted as it were the url "file:FILE.mpeg".
  63
  64 @section gopher
  65
  66 Gopher protocol.
  67
  68 @section http
  69
  70 HTTP (Hyper Text Trasfer Protocol).
  71
  72 @section mmst
  73
  74 MMS (Microsoft Media Server) protocol over TCP.
  75
  76 @section md5
  77
  78 MD5 output protocol.
  79
  80 Computes the MD5 hash of data written, and on close writes this to the
  81 designated output or stdout if none is specified. It can be used to
  82 test muxers without writing an actual file.
  83
  84 Some examples follow.
  85 @example
  86 # write the MD5 hash of the encoded AVI file in the file output.avi.md5
  87 ffmpeg -i input.flv -f avi -y md5:output.avi.md5
  88
  89 # write the MD5 hash of the encoded AVI file to stdout
  90 ffmpeg -i input.flv -f avi -y md5:
  91 @end example
  92
  93 Note that some formats (typically mov) require the output protocol to
  94 be seekable, so they will fail with the MD5 output protocol.
  95
  96 @section pipe
  97
  98 UNIX pipe access protocol.
  99
 100 Allow to read and write from UNIX pipes.
 101
 102 The accepted syntax is:
 103 @example
 104 pipe:[@var{number}]
 105 @end example
 106
 107 @var{number} is the number corresponding to the file descriptor of the
 108 pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr).
 109 If @var{number} is not specified will use by default stdout if the
 110 protocol is used for writing, stdin if the protocol is used for
 111 reading.
 112
 113 For example to read from stdin with @file{ffmpeg}:
 114 @example
 115 cat test.wav | ffmpeg -i pipe:0
 116 # this is the same as
 117 cat test.wav | ffmpeg -i pipe:
 118 @end example
 119
 120 For writing to stdout with @file{ffmpeg}:
 121 @example
 122 ffmpeg -i test.wav -f avi pipe:1 | cat > test.avi
 123 # this is the same as
 124 ffmpeg -i test.wav -f avi pipe: | cat > test.avi
 125 @end example
 126
 127 Note that some formats (typically mov), require the output protocol to
 128 be seekable, so they will fail with the pipe output protocol.
 129
 130 @section rtmp
 131
 132 Real-Time Messaging Protocol.
 133
 134 The Real-Time Messaging Protocol (RTMP) is used for streaming multime‐
 135 dia content across a TCP/IP network.
 136
 137 The required syntax is:
 138 @example
 139 rtmp://@var{server}[:@var{port}][/@var{app}][/@var{playpath}]
 140 @end example
 141
 142 Follows the description of the accepted parameters.
 143 @table @option
 144
 145 @item server
 146 It is the address of the RTMP server.
 147
 148 @item port
 149 It is the number of the TCP port to use (by default is 1935).
 150
 151 @item app
 152 It is the name of the application to acces. It usually corresponds to
 153 the the path where the application is installed on the RTMP server
 154 (e.g. @file{/ondemand/}, @file{/flash/live/}, etc.).
 155
 156 @item playpath
 157 It is the path or name of the resource to play with reference to the
 158 application specified in @var{app}, may be prefixed by "mp4:".
 159
 160 @end table
 161
 162 For example to read with @file{ffplay} a multimedia resource named
 163 "sample" from the application "vod" from an RTMP server "myserver":
 164 @example
 165 ffplay rtmp://myserver/vod/sample
 166 @end example
 167
 168 @section rtmp, rtmpe, rtmps, rtmpt, rtmpte
 169
 170 Real-Time Messaging Protocol and its variants supported through
 171 librtmp.
 172
 173 Require the presence of the headers and library of librtmp during
 174 configuration. You need to explicitely configure the build with
 175 "--enable-librtmp". If enabled this will replace the native RTMP
 176 protocol.
 177
 178 This protocol provides most client functions and a few server
 179 functions needed to support RTMP, RTMP tunneled in HTTP (RTMPT),
 180 encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and tunneled
 181 variants of these encrypted types (RTMPTE, RTMPTS).
 182
 183 The required syntax is:
 184 @example
 185 @var{rtmp_proto}://@var{server}[:@var{port}][/@var{app}][/@var{playpath}] @var{options}
 186 @end example
 187
 188 where @var{rtmp_proto} is one of the strings "rtmp", "rtmpt", "rtmpe",
 189 "rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and
 190 @var{server}, @var{port}, @var{app} and @var{playpath} have the same
 191 meaning has specified for the RTMP native protocol.
 192 @var{options} contains a list of space-separated options of the form
 193 @var{key}=@var{val}.
 194
 195 See the manual page of librtmp (man 3 librtmp) for more information.
 196
 197 For example, to stream a file in real-time to an RTMP server using
 198 @file{ffmpeg}:
 199 @example
 200 ffmpeg -re -i myfile -f flv rtmp://myserver/live/mystream
 201 @end example
 202
 203 To play the same stream using @file{ffplay}:
 204 @example
 205 ffplay "rtmp://myserver/live/mystream live=1"
 206 @end example
 207
 208 @section rtp
 209
 210 Real-Time Protocol.
 211
 212 @section tcp
 213
 214 Trasmission Control Protocol.
 215
 216 @section udp
 217
 218 User Datagram Protocol.
 219
 220 @c man end PROTOCOLS