Add protocols.texi.
[ffmpeg.git] / 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