http: Improve options descriptions
[ffmpeg.git] / doc / protocols.texi
1 @chapter Protocols
2 @c man begin PROTOCOLS
3
4 Protocols are configured elements in Libav which allow to access
5 resources which require the use of a particular protocol.
6
7 When you configure your Libav build, all the supported protocols are
8 enabled by default. You can list all available ones using the
9 configure option "--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 av* tools will display the list of
18 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 if they were
27 a unique resource.
28
29 A 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 @command{avplay} use the
40 command:
41 @example
42 avplay 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 @command{avconv}
55 use the command:
56 @example
57 avconv -i file:input.mpeg output.mpeg
58 @end example
59
60 The av* tools default to the file protocol, that is a resource
61 specified with the name "FILE.mpeg" is interpreted as the URL
62 "file:FILE.mpeg".
63
64 @section gopher
65
66 Gopher protocol.
67
68 @section hls
69
70 Read Apple HTTP Live Streaming compliant segmented stream as
71 a uniform one. The M3U8 playlists describing the segments can be
72 remote HTTP resources or local files, accessed using the standard
73 file protocol.
74 The nested protocol is declared by specifying
75 "+@var{proto}" after the hls URI scheme name, where @var{proto}
76 is either "file" or "http".
77
78 @example
79 hls+http://host/path/to/remote/resource.m3u8
80 hls+file://path/to/local/resource.m3u8
81 @end example
82
83 Using this protocol is discouraged - the hls demuxer should work
84 just as well (if not, please report the issues) and is more complete.
85 To use the hls demuxer instead, simply use the direct URLs to the
86 m3u8 files.
87
88 @section http
89
90 HTTP (Hyper Text Transfer Protocol).
91
92 This protocol accepts the following options:
93
94 @table @option
95 @item chunked_post
96 If set to 1 use chunked Transfer-Encoding for posts, default is 1.
97
98 @item headers
99 Set custom HTTP headers, can override built in default headers. The
100 value must be a string encoding the headers.
101
102 @item multiple_requests
103 Use persistent connections if set to 1, default is 0.
104
105 @item post_data
106 Set custom HTTP post data.
107
108 @item user_agent
109 Override the User-Agent header. If not specified a string of the form
110 "Lavf/<version>" will be used.
111
112 @item mime_type
113 Export the MIME type.
114
115 @item icy
116 If set to 1 request ICY (SHOUTcast) metadata from the server. If the server
117 supports this, the metadata has to be retrieved by the application by reading
118 the @option{icy_metadata_headers} and @option{icy_metadata_packet} options.
119 The default is 0.
120
121 @item icy_metadata_headers
122 If the server supports ICY metadata, this contains the ICY-specific HTTP reply
123 headers, separated by newline characters.
124
125 @item icy_metadata_packet
126 If the server supports ICY metadata, and @option{icy} was set to 1, this
127 contains the last non-empty metadata packet sent by the server. It should be
128 polled in regular intervals by applications interested in mid-stream metadata
129 updates.
130
131 @item offset
132 Set initial byte offset.
133
134 @item end_offset
135 Try to limit the request to bytes preceding this offset.
136 @end table
137
138 @section mmst
139
140 MMS (Microsoft Media Server) protocol over TCP.
141
142 @section mmsh
143
144 MMS (Microsoft Media Server) protocol over HTTP.
145
146 The required syntax is:
147 @example
148 mmsh://@var{server}[:@var{port}][/@var{app}][/@var{playpath}]
149 @end example
150
151 @section md5
152
153 MD5 output protocol.
154
155 Computes the MD5 hash of the data to be written, and on close writes
156 this to the designated output or stdout if none is specified. It can
157 be used to test muxers without writing an actual file.
158
159 Some examples follow.
160 @example
161 # Write the MD5 hash of the encoded AVI file to the file output.avi.md5.
162 avconv -i input.flv -f avi -y md5:output.avi.md5
163
164 # Write the MD5 hash of the encoded AVI file to stdout.
165 avconv -i input.flv -f avi -y md5:
166 @end example
167
168 Note that some formats (typically MOV) require the output protocol to
169 be seekable, so they will fail with the MD5 output protocol.
170
171 @section pipe
172
173 UNIX pipe access protocol.
174
175 Allow to read and write from UNIX pipes.
176
177 The accepted syntax is:
178 @example
179 pipe:[@var{number}]
180 @end example
181
182 @var{number} is the number corresponding to the file descriptor of the
183 pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr).  If @var{number}
184 is not specified, by default the stdout file descriptor will be used
185 for writing, stdin for reading.
186
187 For example to read from stdin with @command{avconv}:
188 @example
189 cat test.wav | avconv -i pipe:0
190 # ...this is the same as...
191 cat test.wav | avconv -i pipe:
192 @end example
193
194 For writing to stdout with @command{avconv}:
195 @example
196 avconv -i test.wav -f avi pipe:1 | cat > test.avi
197 # ...this is the same as...
198 avconv -i test.wav -f avi pipe: | cat > test.avi
199 @end example
200
201 Note that some formats (typically MOV), require the output protocol to
202 be seekable, so they will fail with the pipe output protocol.
203
204 @section rtmp
205
206 Real-Time Messaging Protocol.
207
208 The Real-Time Messaging Protocol (RTMP) is used for streaming multimedia
209 content across a TCP/IP network.
210
211 The required syntax is:
212 @example
213 rtmp://[@var{username}:@var{password}@@]@var{server}[:@var{port}][/@var{app}][/@var{instance}][/@var{playpath}]
214 @end example
215
216 The accepted parameters are:
217 @table @option
218
219 @item username
220 An optional username (mostly for publishing).
221
222 @item password
223 An optional password (mostly for publishing).
224
225 @item server
226 The address of the RTMP server.
227
228 @item port
229 The number of the TCP port to use (by default is 1935).
230
231 @item app
232 It is the name of the application to access. It usually corresponds to
233 the path where the application is installed on the RTMP server
234 (e.g. @file{/ondemand/}, @file{/flash/live/}, etc.). You can override
235 the value parsed from the URI through the @code{rtmp_app} option, too.
236
237 @item playpath
238 It is the path or name of the resource to play with reference to the
239 application specified in @var{app}, may be prefixed by "mp4:". You
240 can override the value parsed from the URI through the @code{rtmp_playpath}
241 option, too.
242
243 @item listen
244 Act as a server, listening for an incoming connection.
245
246 @item timeout
247 Maximum time to wait for the incoming connection. Implies listen.
248 @end table
249
250 Additionally, the following parameters can be set via command line options
251 (or in code via @code{AVOption}s):
252 @table @option
253
254 @item rtmp_app
255 Name of application to connect on the RTMP server. This option
256 overrides the parameter specified in the URI.
257
258 @item rtmp_buffer
259 Set the client buffer time in milliseconds. The default is 3000.
260
261 @item rtmp_conn
262 Extra arbitrary AMF connection parameters, parsed from a string,
263 e.g. like @code{B:1 S:authMe O:1 NN:code:1.23 NS:flag:ok O:0}.
264 Each value is prefixed by a single character denoting the type,
265 B for Boolean, N for number, S for string, O for object, or Z for null,
266 followed by a colon. For Booleans the data must be either 0 or 1 for
267 FALSE or TRUE, respectively.  Likewise for Objects the data must be 0 or
268 1 to end or begin an object, respectively. Data items in subobjects may
269 be named, by prefixing the type with 'N' and specifying the name before
270 the value (i.e. @code{NB:myFlag:1}). This option may be used multiple
271 times to construct arbitrary AMF sequences.
272
273 @item rtmp_flashver
274 Version of the Flash plugin used to run the SWF player. The default
275 is LNX 9,0,124,2. (When publishing, the default is FMLE/3.0 (compatible;
276 <libavformat version>).)
277
278 @item rtmp_flush_interval
279 Number of packets flushed in the same request (RTMPT only). The default
280 is 10.
281
282 @item rtmp_live
283 Specify that the media is a live stream. No resuming or seeking in
284 live streams is possible. The default value is @code{any}, which means the
285 subscriber first tries to play the live stream specified in the
286 playpath. If a live stream of that name is not found, it plays the
287 recorded stream. The other possible values are @code{live} and
288 @code{recorded}.
289
290 @item rtmp_pageurl
291 URL of the web page in which the media was embedded. By default no
292 value will be sent.
293
294 @item rtmp_playpath
295 Stream identifier to play or to publish. This option overrides the
296 parameter specified in the URI.
297
298 @item rtmp_subscribe
299 Name of live stream to subscribe to. By default no value will be sent.
300 It is only sent if the option is specified or if rtmp_live
301 is set to live.
302
303 @item rtmp_swfhash
304 SHA256 hash of the decompressed SWF file (32 bytes).
305
306 @item rtmp_swfsize
307 Size of the decompressed SWF file, required for SWFVerification.
308
309 @item rtmp_swfurl
310 URL of the SWF player for the media. By default no value will be sent.
311
312 @item rtmp_swfverify
313 URL to player swf file, compute hash/size automatically.
314
315 @item rtmp_tcurl
316 URL of the target stream. Defaults to proto://host[:port]/app.
317
318 @end table
319
320 For example to read with @command{avplay} a multimedia resource named
321 "sample" from the application "vod" from an RTMP server "myserver":
322 @example
323 avplay rtmp://myserver/vod/sample
324 @end example
325
326 To publish to a password protected server, passing the playpath and
327 app names separately:
328 @example
329 avconv -re -i <input> -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@@myserver/
330 @end example
331
332 @section rtmpe
333
334 Encrypted Real-Time Messaging Protocol.
335
336 The Encrypted Real-Time Messaging Protocol (RTMPE) is used for
337 streaming multimedia content within standard cryptographic primitives,
338 consisting of Diffie-Hellman key exchange and HMACSHA256, generating
339 a pair of RC4 keys.
340
341 @section rtmps
342
343 Real-Time Messaging Protocol over a secure SSL connection.
344
345 The Real-Time Messaging Protocol (RTMPS) is used for streaming
346 multimedia content across an encrypted connection.
347
348 @section rtmpt
349
350 Real-Time Messaging Protocol tunneled through HTTP.
351
352 The Real-Time Messaging Protocol tunneled through HTTP (RTMPT) is used
353 for streaming multimedia content within HTTP requests to traverse
354 firewalls.
355
356 @section rtmpte
357
358 Encrypted Real-Time Messaging Protocol tunneled through HTTP.
359
360 The Encrypted Real-Time Messaging Protocol tunneled through HTTP (RTMPTE)
361 is used for streaming multimedia content within HTTP requests to traverse
362 firewalls.
363
364 @section rtmpts
365
366 Real-Time Messaging Protocol tunneled through HTTPS.
367
368 The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used
369 for streaming multimedia content within HTTPS requests to traverse
370 firewalls.
371
372 @section librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte
373
374 Real-Time Messaging Protocol and its variants supported through
375 librtmp.
376
377 Requires the presence of the librtmp headers and library during
378 configuration. You need to explicitly configure the build with
379 "--enable-librtmp". If enabled this will replace the native RTMP
380 protocol.
381
382 This protocol provides most client functions and a few server
383 functions needed to support RTMP, RTMP tunneled in HTTP (RTMPT),
384 encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and tunneled
385 variants of these encrypted types (RTMPTE, RTMPTS).
386
387 The required syntax is:
388 @example
389 @var{rtmp_proto}://@var{server}[:@var{port}][/@var{app}][/@var{playpath}] @var{options}
390 @end example
391
392 where @var{rtmp_proto} is one of the strings "rtmp", "rtmpt", "rtmpe",
393 "rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and
394 @var{server}, @var{port}, @var{app} and @var{playpath} have the same
395 meaning as specified for the RTMP native protocol.
396 @var{options} contains a list of space-separated options of the form
397 @var{key}=@var{val}.
398
399 See the librtmp manual page (man 3 librtmp) for more information.
400
401 For example, to stream a file in real-time to an RTMP server using
402 @command{avconv}:
403 @example
404 avconv -re -i myfile -f flv rtmp://myserver/live/mystream
405 @end example
406
407 To play the same stream using @command{avplay}:
408 @example
409 avplay "rtmp://myserver/live/mystream live=1"
410 @end example
411
412 @section rtp
413
414 Real-Time Protocol.
415
416 @section rtsp
417
418 RTSP is not technically a protocol handler in libavformat, it is a demuxer
419 and muxer. The demuxer supports both normal RTSP (with data transferred
420 over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with
421 data transferred over RDT).
422
423 The muxer can be used to send a stream using RTSP ANNOUNCE to a server
424 supporting it (currently Darwin Streaming Server and Mischa Spiegelmock's
425 @uref{http://github.com/revmischa/rtsp-server, RTSP server}).
426
427 The required syntax for a RTSP url is:
428 @example
429 rtsp://@var{hostname}[:@var{port}]/@var{path}
430 @end example
431
432 The following options (set on the @command{avconv}/@command{avplay} command
433 line, or set in code via @code{AVOption}s or in @code{avformat_open_input}),
434 are supported:
435
436 Flags for @code{rtsp_transport}:
437
438 @table @option
439
440 @item udp
441 Use UDP as lower transport protocol.
442
443 @item tcp
444 Use TCP (interleaving within the RTSP control channel) as lower
445 transport protocol.
446
447 @item udp_multicast
448 Use UDP multicast as lower transport protocol.
449
450 @item http
451 Use HTTP tunneling as lower transport protocol, which is useful for
452 passing proxies.
453 @end table
454
455 Multiple lower transport protocols may be specified, in that case they are
456 tried one at a time (if the setup of one fails, the next one is tried).
457 For the muxer, only the @code{tcp} and @code{udp} options are supported.
458
459 Flags for @code{rtsp_flags}:
460
461 @table @option
462 @item filter_src
463 Accept packets only from negotiated peer address and port.
464 @item listen
465 Act as a server, listening for an incoming connection.
466 @end table
467
468 When receiving data over UDP, the demuxer tries to reorder received packets
469 (since they may arrive out of order, or packets may get lost totally). This
470 can be disabled by setting the maximum demuxing delay to zero (via
471 the @code{max_delay} field of AVFormatContext).
472
473 When watching multi-bitrate Real-RTSP streams with @command{avplay}, the
474 streams to display can be chosen with @code{-vst} @var{n} and
475 @code{-ast} @var{n} for video and audio respectively, and can be switched
476 on the fly by pressing @code{v} and @code{a}.
477
478 Example command lines:
479
480 To watch a stream over UDP, with a max reordering delay of 0.5 seconds:
481
482 @example
483 avplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4
484 @end example
485
486 To watch a stream tunneled over HTTP:
487
488 @example
489 avplay -rtsp_transport http rtsp://server/video.mp4
490 @end example
491
492 To send a stream in realtime to a RTSP server, for others to watch:
493
494 @example
495 avconv -re -i @var{input} -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
496 @end example
497
498 To receive a stream in realtime:
499
500 @example
501 avconv -rtsp_flags listen -i rtsp://ownaddress/live.sdp @var{output}
502 @end example
503
504 @section sap
505
506 Session Announcement Protocol (RFC 2974). This is not technically a
507 protocol handler in libavformat, it is a muxer and demuxer.
508 It is used for signalling of RTP streams, by announcing the SDP for the
509 streams regularly on a separate port.
510
511 @subsection Muxer
512
513 The syntax for a SAP url given to the muxer is:
514 @example
515 sap://@var{destination}[:@var{port}][?@var{options}]
516 @end example
517
518 The RTP packets are sent to @var{destination} on port @var{port},
519 or to port 5004 if no port is specified.
520 @var{options} is a @code{&}-separated list. The following options
521 are supported:
522
523 @table @option
524
525 @item announce_addr=@var{address}
526 Specify the destination IP address for sending the announcements to.
527 If omitted, the announcements are sent to the commonly used SAP
528 announcement multicast address 224.2.127.254 (sap.mcast.net), or
529 ff0e::2:7ffe if @var{destination} is an IPv6 address.
530
531 @item announce_port=@var{port}
532 Specify the port to send the announcements on, defaults to
533 9875 if not specified.
534
535 @item ttl=@var{ttl}
536 Specify the time to live value for the announcements and RTP packets,
537 defaults to 255.
538
539 @item same_port=@var{0|1}
540 If set to 1, send all RTP streams on the same port pair. If zero (the
541 default), all streams are sent on unique ports, with each stream on a
542 port 2 numbers higher than the previous.
543 VLC/Live555 requires this to be set to 1, to be able to receive the stream.
544 The RTP stack in libavformat for receiving requires all streams to be sent
545 on unique ports.
546 @end table
547
548 Example command lines follow.
549
550 To broadcast a stream on the local subnet, for watching in VLC:
551
552 @example
553 avconv -re -i @var{input} -f sap sap://224.0.0.255?same_port=1
554 @end example
555
556 Similarly, for watching in avplay:
557
558 @example
559 avconv -re -i @var{input} -f sap sap://224.0.0.255
560 @end example
561
562 And for watching in avplay, over IPv6:
563
564 @example
565 avconv -re -i @var{input} -f sap sap://[ff0e::1:2:3:4]
566 @end example
567
568 @subsection Demuxer
569
570 The syntax for a SAP url given to the demuxer is:
571 @example
572 sap://[@var{address}][:@var{port}]
573 @end example
574
575 @var{address} is the multicast address to listen for announcements on,
576 if omitted, the default 224.2.127.254 (sap.mcast.net) is used. @var{port}
577 is the port that is listened on, 9875 if omitted.
578
579 The demuxers listens for announcements on the given address and port.
580 Once an announcement is received, it tries to receive that particular stream.
581
582 Example command lines follow.
583
584 To play back the first stream announced on the normal SAP multicast address:
585
586 @example
587 avplay sap://
588 @end example
589
590 To play back the first stream announced on one the default IPv6 SAP multicast address:
591
592 @example
593 avplay sap://[ff0e::2:7ffe]
594 @end example
595
596 @section tcp
597
598 Trasmission Control Protocol.
599
600 The required syntax for a TCP url is:
601 @example
602 tcp://@var{hostname}:@var{port}[?@var{options}]
603 @end example
604
605 @table @option
606
607 @item listen
608 Listen for an incoming connection
609
610 @example
611 avconv -i @var{input} -f @var{format} tcp://@var{hostname}:@var{port}?listen
612 avplay tcp://@var{hostname}:@var{port}
613 @end example
614
615 @end table
616
617 @section tls
618
619 Transport Layer Security (TLS) / Secure Sockets Layer (SSL)
620
621 The required syntax for a TLS url is:
622 @example
623 tls://@var{hostname}:@var{port}
624 @end example
625
626 The following parameters can be set via command line options
627 (or in code via @code{AVOption}s):
628
629 @table @option
630
631 @item ca_file
632 A file containing certificate authority (CA) root certificates to treat
633 as trusted. If the linked TLS library contains a default this might not
634 need to be specified for verification to work, but not all libraries and
635 setups have defaults built in.
636
637 @item tls_verify=@var{1|0}
638 If enabled, try to verify the peer that we are communicating with.
639 Note, if using OpenSSL, this currently only makes sure that the
640 peer certificate is signed by one of the root certificates in the CA
641 database, but it does not validate that the certificate actually
642 matches the host name we are trying to connect to. (With GnuTLS,
643 the host name is validated as well.)
644
645 This is disabled by default since it requires a CA database to be
646 provided by the caller in many cases.
647
648 @item cert_file
649 A file containing a certificate to use in the handshake with the peer.
650 (When operating as server, in listen mode, this is more often required
651 by the peer, while client certificates only are mandated in certain
652 setups.)
653
654 @item key_file
655 A file containing the private key for the certificate.
656
657 @item listen=@var{1|0}
658 If enabled, listen for connections on the provided port, and assume
659 the server role in the handshake instead of the client role.
660
661 @end table
662
663 @section udp
664
665 User Datagram Protocol.
666
667 The required syntax for a UDP url is:
668 @example
669 udp://@var{hostname}:@var{port}[?@var{options}]
670 @end example
671
672 @var{options} contains a list of &-separated options of the form @var{key}=@var{val}.
673 Follow the list of supported options.
674
675 @table @option
676
677 @item buffer_size=@var{size}
678 set the UDP buffer size in bytes
679
680 @item localport=@var{port}
681 override the local UDP port to bind with
682
683 @item localaddr=@var{addr}
684 Choose the local IP address. This is useful e.g. if sending multicast
685 and the host has multiple interfaces, where the user can choose
686 which interface to send on by specifying the IP address of that interface.
687
688 @item pkt_size=@var{size}
689 set the size in bytes of UDP packets
690
691 @item reuse=@var{1|0}
692 explicitly allow or disallow reusing UDP sockets
693
694 @item ttl=@var{ttl}
695 set the time to live value (for multicast only)
696
697 @item connect=@var{1|0}
698 Initialize the UDP socket with @code{connect()}. In this case, the
699 destination address can't be changed with ff_udp_set_remote_url later.
700 If the destination address isn't known at the start, this option can
701 be specified in ff_udp_set_remote_url, too.
702 This allows finding out the source address for the packets with getsockname,
703 and makes writes return with AVERROR(ECONNREFUSED) if "destination
704 unreachable" is received.
705 For receiving, this gives the benefit of only receiving packets from
706 the specified peer address/port.
707
708 @item sources=@var{address}[,@var{address}]
709 Only receive packets sent to the multicast group from one of the
710 specified sender IP addresses.
711
712 @item block=@var{address}[,@var{address}]
713 Ignore packets sent to the multicast group from the specified
714 sender IP addresses.
715 @end table
716
717 Some usage examples of the udp protocol with @command{avconv} follow.
718
719 To stream over UDP to a remote endpoint:
720 @example
721 avconv -i @var{input} -f @var{format} udp://@var{hostname}:@var{port}
722 @end example
723
724 To stream in mpegts format over UDP using 188 sized UDP packets, using a large input buffer:
725 @example
726 avconv -i @var{input} -f mpegts udp://@var{hostname}:@var{port}?pkt_size=188&buffer_size=65535
727 @end example
728
729 To receive over UDP from a remote endpoint:
730 @example
731 avconv -i udp://[@var{multicast-address}]:@var{port}
732 @end example
733
734 @section unix
735
736 Unix local socket
737
738 The required syntax for a Unix socket URL is:
739
740 @example
741 unix://@var{filepath}
742 @end example
743
744 The following parameters can be set via command line options
745 (or in code via @code{AVOption}s):
746
747 @table @option
748 @item timeout
749 Timeout in ms.
750 @item listen
751 Create the Unix socket in listening mode.
752 @end table
753
754 @c man end PROTOCOLS