Fix spelling errors in texi files: accomodate -> accommodate allows to -> allows...
[ffmpeg.git] / doc / protocols.texi
1 @chapter Protocols
2 @c man begin PROTOCOLS
3
4 Protocols are configured elements in FFmpeg that enable access to
5 resources that require specific protocols.
6
7 When you configure your FFmpeg 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 ff* tools will display the list of
18 supported protocols.
19
20 A description of the currently available protocols follows.
21
22 @section bluray
23
24 Read BluRay playlist.
25
26 The accepted options are:
27 @table @option
28
29 @item angle
30 BluRay angle
31
32 @item chapter
33 Start chapter (1...N)
34
35 @item playlist
36 Playlist to read (BDMV/PLAYLIST/?????.mpls)
37
38 @end table
39
40 Examples:
41
42 Read longest playlist from BluRay mounted to /mnt/bluray:
43 @example
44 bluray:/mnt/bluray
45 @end example
46
47 Read angle 2 of playlist 4 from BluRay mounted to /mnt/bluray, start from chapter 2:
48 @example
49 -playlist 4 -angle 2 -chapter 2 bluray:/mnt/bluray
50 @end example
51
52 @section cache
53
54 Caching wrapper for input stream.
55
56 Cache the input stream to temporary file. It brings seeking capability to live streams.
57
58 @example
59 cache:@var{URL}
60 @end example
61
62 @section concat
63
64 Physical concatenation protocol.
65
66 Allow to read and seek from many resource in sequence as if they were
67 a unique resource.
68
69 A URL accepted by this protocol has the syntax:
70 @example
71 concat:@var{URL1}|@var{URL2}|...|@var{URLN}
72 @end example
73
74 where @var{URL1}, @var{URL2}, ..., @var{URLN} are the urls of the
75 resource to be concatenated, each one possibly specifying a distinct
76 protocol.
77
78 For example to read a sequence of files @file{split1.mpeg},
79 @file{split2.mpeg}, @file{split3.mpeg} with @command{ffplay} use the
80 command:
81 @example
82 ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg
83 @end example
84
85 Note that you may need to escape the character "|" which is special for
86 many shells.
87
88 @section crypto
89
90 AES-encrypted stream reading protocol.
91
92 The accepted options are:
93 @table @option
94 @item key
95 Set the AES decryption key binary block from given hexadecimal representation.
96
97 @item iv
98 Set the AES decryption initialization vector binary block from given hexadecimal representation.
99 @end table
100
101 Accepted URL formats:
102 @example
103 crypto:@var{URL}
104 crypto+@var{URL}
105 @end example
106
107 @section data
108
109 Data in-line in the URI. See @url{http://en.wikipedia.org/wiki/Data_URI_scheme}.
110
111 For example, to convert a GIF file given inline with @command{ffmpeg}:
112 @example
113 ffmpeg -i "data:image/gif;base64,R0lGODdhCAAIAMIEAAAAAAAA//8AAP//AP///////////////ywAAAAACAAIAAADF0gEDLojDgdGiJdJqUX02iB4E8Q9jUMkADs=" smiley.png
114 @end example
115
116 @section file
117
118 File access protocol.
119
120 Allow to read from or write to a file.
121
122 A file URL can have the form:
123 @example
124 file:@var{filename}
125 @end example
126
127 where @var{filename} is the path of the file to read.
128
129 An URL that does not have a protocol prefix will be assumed to be a
130 file URL. Depending on the build, an URL that looks like a Windows
131 path with the drive letter at the beginning will also be assumed to be
132 a file URL (usually not the case in builds for unix-like systems).
133
134 For example to read from a file @file{input.mpeg} with @command{ffmpeg}
135 use the command:
136 @example
137 ffmpeg -i file:input.mpeg output.mpeg
138 @end example
139
140 This protocol accepts the following options:
141
142 @table @option
143 @item truncate
144 Truncate existing files on write, if set to 1. A value of 0 prevents
145 truncating. Default value is 1.
146
147 @item blocksize
148 Set I/O operation maximum block size, in bytes. Default value is
149 @code{INT_MAX}, which results in not limiting the requested block size.
150 Setting this value reasonably low improves user termination request reaction
151 time, which is valuable for files on slow medium.
152 @end table
153
154 @section ftp
155
156 FTP (File Transfer Protocol).
157
158 Allow to read from or write to remote resources using FTP protocol.
159
160 Following syntax is required.
161 @example
162 ftp://[user[:password]@@]server[:port]/path/to/remote/resource.mpeg
163 @end example
164
165 This protocol accepts the following options.
166
167 @table @option
168 @item timeout
169 Set timeout of socket I/O operations used by the underlying low level
170 operation. By default it is set to -1, which means that the timeout is
171 not specified.
172
173 @item ftp-anonymous-password
174 Password used when login as anonymous user. Typically an e-mail address
175 should be used.
176
177 @item ftp-write-seekable
178 Control seekability of connection during encoding. If set to 1 the
179 resource is supposed to be seekable, if set to 0 it is assumed not
180 to be seekable. Default value is 0.
181 @end table
182
183 NOTE: Protocol can be used as output, but it is recommended to not do
184 it, unless special care is taken (tests, customized server configuration
185 etc.). Different FTP servers behave in different way during seek
186 operation. ff* tools may produce incomplete content due to server limitations.
187
188 @section gopher
189
190 Gopher protocol.
191
192 @section hls
193
194 Read Apple HTTP Live Streaming compliant segmented stream as
195 a uniform one. The M3U8 playlists describing the segments can be
196 remote HTTP resources or local files, accessed using the standard
197 file protocol.
198 The nested protocol is declared by specifying
199 "+@var{proto}" after the hls URI scheme name, where @var{proto}
200 is either "file" or "http".
201
202 @example
203 hls+http://host/path/to/remote/resource.m3u8
204 hls+file://path/to/local/resource.m3u8
205 @end example
206
207 Using this protocol is discouraged - the hls demuxer should work
208 just as well (if not, please report the issues) and is more complete.
209 To use the hls demuxer instead, simply use the direct URLs to the
210 m3u8 files.
211
212 @section http
213
214 HTTP (Hyper Text Transfer Protocol).
215
216 This protocol accepts the following options.
217
218 @table @option
219 @item seekable
220 Control seekability of connection. If set to 1 the resource is
221 supposed to be seekable, if set to 0 it is assumed not to be seekable,
222 if set to -1 it will try to autodetect if it is seekable. Default
223 value is -1.
224
225 @item chunked_post
226 If set to 1 use chunked transfer-encoding for posts, default is 1.
227
228 @item headers
229 Set custom HTTP headers, can override built in default headers. The
230 value must be a string encoding the headers.
231
232 @item content_type
233 Force a content type.
234
235 @item user-agent
236 Override User-Agent header. If not specified the protocol will use a
237 string describing the libavformat build.
238
239 @item multiple_requests
240 Use persistent connections if set to 1. By default it is 0.
241
242 @item post_data
243 Set custom HTTP post data.
244
245 @item timeout
246 Set timeout of socket I/O operations used by the underlying low level
247 operation. By default it is set to -1, which means that the timeout is
248 not specified.
249
250 @item mime_type
251 Set MIME type.
252
253 @item icy
254 If set to 1 request ICY (SHOUTcast) metadata from the server. If the server
255 supports this, the metadata has to be retrieved by the application by reading
256 the @option{icy_metadata_headers} and @option{icy_metadata_packet} options.
257 The default is 0.
258
259 @item icy_metadata_headers
260 If the server supports ICY metadata, this contains the ICY specific HTTP reply
261 headers, separated with newline characters.
262
263 @item icy_metadata_packet
264 If the server supports ICY metadata, and @option{icy} was set to 1, this
265 contains the last non-empty metadata packet sent by the server.
266
267 @item cookies
268 Set the cookies to be sent in future requests. The format of each cookie is the
269 same as the value of a Set-Cookie HTTP response field. Multiple cookies can be
270 delimited by a newline character.
271 @end table
272
273 @subsection HTTP Cookies
274
275 Some HTTP requests will be denied unless cookie values are passed in with the
276 request. The @option{cookies} option allows these cookies to be specified. At
277 the very least, each cookie must specify a value along with a path and domain.
278 HTTP requests that match both the domain and path will automatically include the
279 cookie value in the HTTP Cookie header field. Multiple cookies can be delimited
280 by a newline.
281
282 The required syntax to play a stream specifying a cookie is:
283 @example
284 ffplay -cookies "nlqptid=nltid=tsn; path=/; domain=somedomain.com;" http://somedomain.com/somestream.m3u8
285 @end example
286
287 @section mmst
288
289 MMS (Microsoft Media Server) protocol over TCP.
290
291 @section mmsh
292
293 MMS (Microsoft Media Server) protocol over HTTP.
294
295 The required syntax is:
296 @example
297 mmsh://@var{server}[:@var{port}][/@var{app}][/@var{playpath}]
298 @end example
299
300 @section md5
301
302 MD5 output protocol.
303
304 Computes the MD5 hash of the data to be written, and on close writes
305 this to the designated output or stdout if none is specified. It can
306 be used to test muxers without writing an actual file.
307
308 Some examples follow.
309 @example
310 # Write the MD5 hash of the encoded AVI file to the file output.avi.md5.
311 ffmpeg -i input.flv -f avi -y md5:output.avi.md5
312
313 # Write the MD5 hash of the encoded AVI file to stdout.
314 ffmpeg -i input.flv -f avi -y md5:
315 @end example
316
317 Note that some formats (typically MOV) require the output protocol to
318 be seekable, so they will fail with the MD5 output protocol.
319
320 @section pipe
321
322 UNIX pipe access protocol.
323
324 Allow to read and write from UNIX pipes.
325
326 The accepted syntax is:
327 @example
328 pipe:[@var{number}]
329 @end example
330
331 @var{number} is the number corresponding to the file descriptor of the
332 pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr).  If @var{number}
333 is not specified, by default the stdout file descriptor will be used
334 for writing, stdin for reading.
335
336 For example to read from stdin with @command{ffmpeg}:
337 @example
338 cat test.wav | ffmpeg -i pipe:0
339 # ...this is the same as...
340 cat test.wav | ffmpeg -i pipe:
341 @end example
342
343 For writing to stdout with @command{ffmpeg}:
344 @example
345 ffmpeg -i test.wav -f avi pipe:1 | cat > test.avi
346 # ...this is the same as...
347 ffmpeg -i test.wav -f avi pipe: | cat > test.avi
348 @end example
349
350 This protocol accepts the following options:
351
352 @table @option
353 @item blocksize
354 Set I/O operation maximum block size, in bytes. Default value is
355 @code{INT_MAX}, which results in not limiting the requested block size.
356 Setting this value reasonably low improves user termination request reaction
357 time, which is valuable if data transmission is slow.
358 @end table
359
360 Note that some formats (typically MOV), require the output protocol to
361 be seekable, so they will fail with the pipe output protocol.
362
363 @section rtmp
364
365 Real-Time Messaging Protocol.
366
367 The Real-Time Messaging Protocol (RTMP) is used for streaming multimedia
368 content across a TCP/IP network.
369
370 The required syntax is:
371 @example
372 rtmp://[@var{username}:@var{password}@@]@var{server}[:@var{port}][/@var{app}][/@var{instance}][/@var{playpath}]
373 @end example
374
375 The accepted parameters are:
376 @table @option
377
378 @item username
379 An optional username (mostly for publishing).
380
381 @item password
382 An optional password (mostly for publishing).
383
384 @item server
385 The address of the RTMP server.
386
387 @item port
388 The number of the TCP port to use (by default is 1935).
389
390 @item app
391 It is the name of the application to access. It usually corresponds to
392 the path where the application is installed on the RTMP server
393 (e.g. @file{/ondemand/}, @file{/flash/live/}, etc.). You can override
394 the value parsed from the URI through the @code{rtmp_app} option, too.
395
396 @item playpath
397 It is the path or name of the resource to play with reference to the
398 application specified in @var{app}, may be prefixed by "mp4:". You
399 can override the value parsed from the URI through the @code{rtmp_playpath}
400 option, too.
401
402 @item listen
403 Act as a server, listening for an incoming connection.
404
405 @item timeout
406 Maximum time to wait for the incoming connection. Implies listen.
407 @end table
408
409 Additionally, the following parameters can be set via command line options
410 (or in code via @code{AVOption}s):
411 @table @option
412
413 @item rtmp_app
414 Name of application to connect on the RTMP server. This option
415 overrides the parameter specified in the URI.
416
417 @item rtmp_buffer
418 Set the client buffer time in milliseconds. The default is 3000.
419
420 @item rtmp_conn
421 Extra arbitrary AMF connection parameters, parsed from a string,
422 e.g. like @code{B:1 S:authMe O:1 NN:code:1.23 NS:flag:ok O:0}.
423 Each value is prefixed by a single character denoting the type,
424 B for Boolean, N for number, S for string, O for object, or Z for null,
425 followed by a colon. For Booleans the data must be either 0 or 1 for
426 FALSE or TRUE, respectively.  Likewise for Objects the data must be 0 or
427 1 to end or begin an object, respectively. Data items in subobjects may
428 be named, by prefixing the type with 'N' and specifying the name before
429 the value (i.e. @code{NB:myFlag:1}). This option may be used multiple
430 times to construct arbitrary AMF sequences.
431
432 @item rtmp_flashver
433 Version of the Flash plugin used to run the SWF player. The default
434 is LNX 9,0,124,2. (When publishing, the default is FMLE/3.0 (compatible;
435 <libavformat version>).)
436
437 @item rtmp_flush_interval
438 Number of packets flushed in the same request (RTMPT only). The default
439 is 10.
440
441 @item rtmp_live
442 Specify that the media is a live stream. No resuming or seeking in
443 live streams is possible. The default value is @code{any}, which means the
444 subscriber first tries to play the live stream specified in the
445 playpath. If a live stream of that name is not found, it plays the
446 recorded stream. The other possible values are @code{live} and
447 @code{recorded}.
448
449 @item rtmp_pageurl
450 URL of the web page in which the media was embedded. By default no
451 value will be sent.
452
453 @item rtmp_playpath
454 Stream identifier to play or to publish. This option overrides the
455 parameter specified in the URI.
456
457 @item rtmp_subscribe
458 Name of live stream to subscribe to. By default no value will be sent.
459 It is only sent if the option is specified or if rtmp_live
460 is set to live.
461
462 @item rtmp_swfhash
463 SHA256 hash of the decompressed SWF file (32 bytes).
464
465 @item rtmp_swfsize
466 Size of the decompressed SWF file, required for SWFVerification.
467
468 @item rtmp_swfurl
469 URL of the SWF player for the media. By default no value will be sent.
470
471 @item rtmp_swfverify
472 URL to player swf file, compute hash/size automatically.
473
474 @item rtmp_tcurl
475 URL of the target stream. Defaults to proto://host[:port]/app.
476
477 @end table
478
479 For example to read with @command{ffplay} a multimedia resource named
480 "sample" from the application "vod" from an RTMP server "myserver":
481 @example
482 ffplay rtmp://myserver/vod/sample
483 @end example
484
485 To publish to a password protected server, passing the playpath and
486 app names separately:
487 @example
488 ffmpeg -re -i <input> -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@@myserver/
489 @end example
490
491 @section rtmpe
492
493 Encrypted Real-Time Messaging Protocol.
494
495 The Encrypted Real-Time Messaging Protocol (RTMPE) is used for
496 streaming multimedia content within standard cryptographic primitives,
497 consisting of Diffie-Hellman key exchange and HMACSHA256, generating
498 a pair of RC4 keys.
499
500 @section rtmps
501
502 Real-Time Messaging Protocol over a secure SSL connection.
503
504 The Real-Time Messaging Protocol (RTMPS) is used for streaming
505 multimedia content across an encrypted connection.
506
507 @section rtmpt
508
509 Real-Time Messaging Protocol tunneled through HTTP.
510
511 The Real-Time Messaging Protocol tunneled through HTTP (RTMPT) is used
512 for streaming multimedia content within HTTP requests to traverse
513 firewalls.
514
515 @section rtmpte
516
517 Encrypted Real-Time Messaging Protocol tunneled through HTTP.
518
519 The Encrypted Real-Time Messaging Protocol tunneled through HTTP (RTMPTE)
520 is used for streaming multimedia content within HTTP requests to traverse
521 firewalls.
522
523 @section rtmpts
524
525 Real-Time Messaging Protocol tunneled through HTTPS.
526
527 The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used
528 for streaming multimedia content within HTTPS requests to traverse
529 firewalls.
530
531 @section libssh
532
533 Secure File Transfer Protocol via libssh
534
535 Allow to read from or write to remote resources using SFTP protocol.
536
537 Following syntax is required.
538
539 @example
540 sftp://[user[:password]@@]server[:port]/path/to/remote/resource.mpeg
541 @end example
542
543 This protocol accepts the following options.
544
545 @table @option
546 @item timeout
547 Set timeout of socket I/O operations used by the underlying low level
548 operation. By default it is set to -1, which means that the timeout
549 is not specified.
550
551 @item truncate
552 Truncate existing files on write, if set to 1. A value of 0 prevents
553 truncating. Default value is 1.
554
555 @item private_key
556 Specify the path of the file containing private key to use during authorization.
557 By default libssh searches for keys in the @file{~/.ssh/} directory.
558
559 @end table
560
561 Example: Play a file stored on remote server.
562
563 @example
564 ffplay sftp://user:password@@server_address:22/home/user/resource.mpeg
565 @end example
566
567 @section librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte
568
569 Real-Time Messaging Protocol and its variants supported through
570 librtmp.
571
572 Requires the presence of the librtmp headers and library during
573 configuration. You need to explicitly configure the build with
574 "--enable-librtmp". If enabled this will replace the native RTMP
575 protocol.
576
577 This protocol provides most client functions and a few server
578 functions needed to support RTMP, RTMP tunneled in HTTP (RTMPT),
579 encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and tunneled
580 variants of these encrypted types (RTMPTE, RTMPTS).
581
582 The required syntax is:
583 @example
584 @var{rtmp_proto}://@var{server}[:@var{port}][/@var{app}][/@var{playpath}] @var{options}
585 @end example
586
587 where @var{rtmp_proto} is one of the strings "rtmp", "rtmpt", "rtmpe",
588 "rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and
589 @var{server}, @var{port}, @var{app} and @var{playpath} have the same
590 meaning as specified for the RTMP native protocol.
591 @var{options} contains a list of space-separated options of the form
592 @var{key}=@var{val}.
593
594 See the librtmp manual page (man 3 librtmp) for more information.
595
596 For example, to stream a file in real-time to an RTMP server using
597 @command{ffmpeg}:
598 @example
599 ffmpeg -re -i myfile -f flv rtmp://myserver/live/mystream
600 @end example
601
602 To play the same stream using @command{ffplay}:
603 @example
604 ffplay "rtmp://myserver/live/mystream live=1"
605 @end example
606
607 @section rtp
608
609 Real-time Transport Protocol.
610
611 The required syntax for an RTP URL is:
612 rtp://@var{hostname}[:@var{port}][?@var{option}=@var{val}...]
613
614 @var{port} specifies the RTP port to use.
615
616 The following URL options are supported:
617
618 @table @option
619
620 @item ttl=@var{n}
621 Set the TTL (Time-To-Live) value (for multicast only).
622
623 @item rtcpport=@var{n}
624 Set the remote RTCP port to @var{n}.
625
626 @item localrtpport=@var{n}
627 Set the local RTP port to @var{n}.
628
629 @item localrtcpport=@var{n}'
630 Set the local RTCP port to @var{n}.
631
632 @item pkt_size=@var{n}
633 Set max packet size (in bytes) to @var{n}.
634
635 @item connect=0|1
636 Do a @code{connect()} on the UDP socket (if set to 1) or not (if set
637 to 0).
638
639 @item sources=@var{ip}[,@var{ip}]
640 List allowed source IP addresses.
641
642 @item block=@var{ip}[,@var{ip}]
643 List disallowed (blocked) source IP addresses.
644
645 @item write_to_source=0|1
646 Send packets to the source address of the latest received packet (if
647 set to 1) or to a default remote address (if set to 0).
648
649 @item localport=@var{n}
650 Set the local RTP port to @var{n}.
651
652 This is a deprecated option. Instead, @option{localrtpport} should be
653 used.
654
655 @end table
656
657 Important notes:
658
659 @enumerate
660
661 @item
662 If @option{rtcpport} is not set the RTCP port will be set to the RTP
663 port value plus 1.
664
665 @item
666 If @option{localrtpport} (the local RTP port) is not set any available
667 port will be used for the local RTP and RTCP ports.
668
669 @item
670 If @option{localrtcpport} (the local RTCP port) is not set it will be
671 set to the the local RTP port value plus 1.
672 @end enumerate
673
674 @section rtsp
675
676 Real-Time Streaming Protocol.
677
678 RTSP is not technically a protocol handler in libavformat, it is a demuxer
679 and muxer. The demuxer supports both normal RTSP (with data transferred
680 over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with
681 data transferred over RDT).
682
683 The muxer can be used to send a stream using RTSP ANNOUNCE to a server
684 supporting it (currently Darwin Streaming Server and Mischa Spiegelmock's
685 @uref{http://github.com/revmischa/rtsp-server, RTSP server}).
686
687 The required syntax for a RTSP url is:
688 @example
689 rtsp://@var{hostname}[:@var{port}]/@var{path}
690 @end example
691
692 Options can be set on the @command{ffmpeg}/@command{ffplay} command
693 line, or set in code via @code{AVOption}s or in
694 @code{avformat_open_input}.
695
696 The following options are supported.
697
698 @table @option
699 @item initial_pause
700 Do not start playing the stream immediately if set to 1. Default value
701 is 0.
702
703 @item rtsp_transport
704 Set RTSP trasport protocols.
705
706 It accepts the following values:
707 @table @samp
708 @item udp
709 Use UDP as lower transport protocol.
710
711 @item tcp
712 Use TCP (interleaving within the RTSP control channel) as lower
713 transport protocol.
714
715 @item udp_multicast
716 Use UDP multicast as lower transport protocol.
717
718 @item http
719 Use HTTP tunneling as lower transport protocol, which is useful for
720 passing proxies.
721 @end table
722
723 Multiple lower transport protocols may be specified, in that case they are
724 tried one at a time (if the setup of one fails, the next one is tried).
725 For the muxer, only the @samp{tcp} and @samp{udp} options are supported.
726
727 @item rtsp_flags
728 Set RTSP flags.
729
730 The following values are accepted:
731 @table @samp
732 @item filter_src
733 Accept packets only from negotiated peer address and port.
734 @item listen
735 Act as a server, listening for an incoming connection.
736 @item prefer_tcp
737 Try TCP for RTP transport first, if TCP is available as RTSP RTP transport.
738 @end table
739
740 Default value is @samp{none}.
741
742 @item allowed_media_types
743 Set media types to accept from the server.
744
745 The following flags are accepted:
746 @table @samp
747 @item video
748 @item audio
749 @item data
750 @end table
751
752 By default it accepts all media types.
753
754 @item min_port
755 Set minimum local UDP port. Default value is 5000.
756
757 @item max_port
758 Set maximum local UDP port. Default value is 65000.
759
760 @item timeout
761 Set maximum timeout (in seconds) to wait for incoming connections.
762
763 A value of -1 mean infinite (default). This option implies the
764 @option{rtsp_flags} set to @samp{listen}.
765
766 @item reorder_queue_size
767 Set number of packets to buffer for handling of reordered packets.
768
769 @item stimeout
770 Set socket TCP I/O timeout in micro seconds.
771
772 @item user-agent
773 Override User-Agent header. If not specified, it default to the
774 libavformat identifier string.
775 @end table
776
777 When receiving data over UDP, the demuxer tries to reorder received packets
778 (since they may arrive out of order, or packets may get lost totally). This
779 can be disabled by setting the maximum demuxing delay to zero (via
780 the @code{max_delay} field of AVFormatContext).
781
782 When watching multi-bitrate Real-RTSP streams with @command{ffplay}, the
783 streams to display can be chosen with @code{-vst} @var{n} and
784 @code{-ast} @var{n} for video and audio respectively, and can be switched
785 on the fly by pressing @code{v} and @code{a}.
786
787 @subsection Examples
788
789 The following examples all make use of the @command{ffplay} and
790 @command{ffmpeg} tools.
791
792 @itemize
793 @item
794 Watch a stream over UDP, with a max reordering delay of 0.5 seconds:
795 @example
796 ffplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4
797 @end example
798
799 @item
800 Watch a stream tunneled over HTTP:
801 @example
802 ffplay -rtsp_transport http rtsp://server/video.mp4
803 @end example
804
805 @item
806 Send a stream in realtime to a RTSP server, for others to watch:
807 @example
808 ffmpeg -re -i @var{input} -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
809 @end example
810
811 @item
812 Receive a stream in realtime:
813 @example
814 ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp @var{output}
815 @end example
816 @end itemize
817
818 @section sap
819
820 Session Announcement Protocol (RFC 2974). This is not technically a
821 protocol handler in libavformat, it is a muxer and demuxer.
822 It is used for signalling of RTP streams, by announcing the SDP for the
823 streams regularly on a separate port.
824
825 @subsection Muxer
826
827 The syntax for a SAP url given to the muxer is:
828 @example
829 sap://@var{destination}[:@var{port}][?@var{options}]
830 @end example
831
832 The RTP packets are sent to @var{destination} on port @var{port},
833 or to port 5004 if no port is specified.
834 @var{options} is a @code{&}-separated list. The following options
835 are supported:
836
837 @table @option
838
839 @item announce_addr=@var{address}
840 Specify the destination IP address for sending the announcements to.
841 If omitted, the announcements are sent to the commonly used SAP
842 announcement multicast address 224.2.127.254 (sap.mcast.net), or
843 ff0e::2:7ffe if @var{destination} is an IPv6 address.
844
845 @item announce_port=@var{port}
846 Specify the port to send the announcements on, defaults to
847 9875 if not specified.
848
849 @item ttl=@var{ttl}
850 Specify the time to live value for the announcements and RTP packets,
851 defaults to 255.
852
853 @item same_port=@var{0|1}
854 If set to 1, send all RTP streams on the same port pair. If zero (the
855 default), all streams are sent on unique ports, with each stream on a
856 port 2 numbers higher than the previous.
857 VLC/Live555 requires this to be set to 1, to be able to receive the stream.
858 The RTP stack in libavformat for receiving requires all streams to be sent
859 on unique ports.
860 @end table
861
862 Example command lines follow.
863
864 To broadcast a stream on the local subnet, for watching in VLC:
865
866 @example
867 ffmpeg -re -i @var{input} -f sap sap://224.0.0.255?same_port=1
868 @end example
869
870 Similarly, for watching in @command{ffplay}:
871
872 @example
873 ffmpeg -re -i @var{input} -f sap sap://224.0.0.255
874 @end example
875
876 And for watching in @command{ffplay}, over IPv6:
877
878 @example
879 ffmpeg -re -i @var{input} -f sap sap://[ff0e::1:2:3:4]
880 @end example
881
882 @subsection Demuxer
883
884 The syntax for a SAP url given to the demuxer is:
885 @example
886 sap://[@var{address}][:@var{port}]
887 @end example
888
889 @var{address} is the multicast address to listen for announcements on,
890 if omitted, the default 224.2.127.254 (sap.mcast.net) is used. @var{port}
891 is the port that is listened on, 9875 if omitted.
892
893 The demuxers listens for announcements on the given address and port.
894 Once an announcement is received, it tries to receive that particular stream.
895
896 Example command lines follow.
897
898 To play back the first stream announced on the normal SAP multicast address:
899
900 @example
901 ffplay sap://
902 @end example
903
904 To play back the first stream announced on one the default IPv6 SAP multicast address:
905
906 @example
907 ffplay sap://[ff0e::2:7ffe]
908 @end example
909
910 @section sctp
911
912 Stream Control Transmission Protocol.
913
914 The accepted URL syntax is:
915 @example
916 sctp://@var{host}:@var{port}[?@var{options}]
917 @end example
918
919 The protocol accepts the following options:
920 @table @option
921 @item listen
922 If set to any value, listen for an incoming connection. Outgoing connection is done by default.
923
924 @item max_streams
925 Set the maximum number of streams. By default no limit is set.
926 @end table
927
928 @section srtp
929
930 Secure Real-time Transport Protocol.
931
932 The accepted options are:
933 @table @option
934 @item srtp_in_suite
935 @item srtp_out_suite
936 Select input and output encoding suites.
937
938 Supported values:
939 @table @samp
940 @item AES_CM_128_HMAC_SHA1_80
941 @item SRTP_AES128_CM_HMAC_SHA1_80
942 @item AES_CM_128_HMAC_SHA1_32
943 @item SRTP_AES128_CM_HMAC_SHA1_32
944 @end table
945
946 @item srtp_in_params
947 @item srtp_out_params
948 Set input and output encoding parameters, which are expressed by a
949 base64-encoded representation of a binary block. The first 16 bytes of
950 this binary block are used as master key, the following 14 bytes are
951 used as master salt.
952 @end table
953
954 @section tcp
955
956 Transmission Control Protocol.
957
958 The required syntax for a TCP url is:
959 @example
960 tcp://@var{hostname}:@var{port}[?@var{options}]
961 @end example
962
963 @var{options} contains a list of &-separated options of the form
964 @var{key}=@var{val}.
965
966 The list of supported options follows.
967
968 @table @option
969 @item listen=@var{1|0}
970 Listen for an incoming connection. Default value is 0.
971
972 @item timeout=@var{microseconds}
973 Set raise error timeout, expressed in microseconds.
974
975 This option is only relevant in read mode: if no data arrived in more
976 than this time interval, raise error.
977
978 @item listen_timeout=@var{microseconds}
979 Set listen timeout, expressed in microseconds.
980 @end table
981
982 The following example shows how to setup a listening TCP connection
983 with @command{ffmpeg}, which is then accessed with @command{ffplay}:
984 @example
985 ffmpeg -i @var{input} -f @var{format} tcp://@var{hostname}:@var{port}?listen
986 ffplay tcp://@var{hostname}:@var{port}
987 @end example
988
989 @section tls
990
991 Transport Layer Security (TLS) / Secure Sockets Layer (SSL)
992
993 The required syntax for a TLS/SSL url is:
994 @example
995 tls://@var{hostname}:@var{port}[?@var{options}]
996 @end example
997
998 The following parameters can be set via command line options
999 (or in code via @code{AVOption}s):
1000
1001 @table @option
1002
1003 @item ca_file, cafile=@var{filename}
1004 A file containing certificate authority (CA) root certificates to treat
1005 as trusted. If the linked TLS library contains a default this might not
1006 need to be specified for verification to work, but not all libraries and
1007 setups have defaults built in.
1008 The file must be in OpenSSL PEM format.
1009
1010 @item tls_verify=@var{1|0}
1011 If enabled, try to verify the peer that we are communicating with.
1012 Note, if using OpenSSL, this currently only makes sure that the
1013 peer certificate is signed by one of the root certificates in the CA
1014 database, but it does not validate that the certificate actually
1015 matches the host name we are trying to connect to. (With GnuTLS,
1016 the host name is validated as well.)
1017
1018 This is disabled by default since it requires a CA database to be
1019 provided by the caller in many cases.
1020
1021 @item cert_file, cert=@var{filename}
1022 A file containing a certificate to use in the handshake with the peer.
1023 (When operating as server, in listen mode, this is more often required
1024 by the peer, while client certificates only are mandated in certain
1025 setups.)
1026
1027 @item key_file, key=@var{filename}
1028 A file containing the private key for the certificate.
1029
1030 @item listen=@var{1|0}
1031 If enabled, listen for connections on the provided port, and assume
1032 the server role in the handshake instead of the client role.
1033
1034 @end table
1035
1036 Example command lines:
1037
1038 To create a TLS/SSL server that serves an input stream.
1039
1040 @example
1041 ffmpeg -i @var{input} -f @var{format} tls://@var{hostname}:@var{port}?listen&cert=@var{server.crt}&key=@var{server.key}
1042 @end example
1043
1044 To play back a stream from the TLS/SSL server using @command{ffplay}:
1045
1046 @example
1047 ffplay tls://@var{hostname}:@var{port}
1048 @end example
1049
1050 @section udp
1051
1052 User Datagram Protocol.
1053
1054 The required syntax for an UDP URL is:
1055 @example
1056 udp://@var{hostname}:@var{port}[?@var{options}]
1057 @end example
1058
1059 @var{options} contains a list of &-separated options of the form @var{key}=@var{val}.
1060
1061 In case threading is enabled on the system, a circular buffer is used
1062 to store the incoming data, which allows one to reduce loss of data due to
1063 UDP socket buffer overruns. The @var{fifo_size} and
1064 @var{overrun_nonfatal} options are related to this buffer.
1065
1066 The list of supported options follows.
1067
1068 @table @option
1069 @item buffer_size=@var{size}
1070 Set the UDP socket buffer size in bytes. This is used both for the
1071 receiving and the sending buffer size.
1072
1073 @item localport=@var{port}
1074 Override the local UDP port to bind with.
1075
1076 @item localaddr=@var{addr}
1077 Choose the local IP address. This is useful e.g. if sending multicast
1078 and the host has multiple interfaces, where the user can choose
1079 which interface to send on by specifying the IP address of that interface.
1080
1081 @item pkt_size=@var{size}
1082 Set the size in bytes of UDP packets.
1083
1084 @item reuse=@var{1|0}
1085 Explicitly allow or disallow reusing UDP sockets.
1086
1087 @item ttl=@var{ttl}
1088 Set the time to live value (for multicast only).
1089
1090 @item connect=@var{1|0}
1091 Initialize the UDP socket with @code{connect()}. In this case, the
1092 destination address can't be changed with ff_udp_set_remote_url later.
1093 If the destination address isn't known at the start, this option can
1094 be specified in ff_udp_set_remote_url, too.
1095 This allows finding out the source address for the packets with getsockname,
1096 and makes writes return with AVERROR(ECONNREFUSED) if "destination
1097 unreachable" is received.
1098 For receiving, this gives the benefit of only receiving packets from
1099 the specified peer address/port.
1100
1101 @item sources=@var{address}[,@var{address}]
1102 Only receive packets sent to the multicast group from one of the
1103 specified sender IP addresses.
1104
1105 @item block=@var{address}[,@var{address}]
1106 Ignore packets sent to the multicast group from the specified
1107 sender IP addresses.
1108
1109 @item fifo_size=@var{units}
1110 Set the UDP receiving circular buffer size, expressed as a number of
1111 packets with size of 188 bytes. If not specified defaults to 7*4096.
1112
1113 @item overrun_nonfatal=@var{1|0}
1114 Survive in case of UDP receiving circular buffer overrun. Default
1115 value is 0.
1116
1117 @item timeout=@var{microseconds}
1118 Set raise error timeout, expressed in microseconds.
1119
1120 This option is only relevant in read mode: if no data arrived in more
1121 than this time interval, raise error.
1122 @end table
1123
1124 @subsection Examples
1125
1126 @itemize
1127 @item
1128 Use @command{ffmpeg} to stream over UDP to a remote endpoint:
1129 @example
1130 ffmpeg -i @var{input} -f @var{format} udp://@var{hostname}:@var{port}
1131 @end example
1132
1133 @item
1134 Use @command{ffmpeg} to stream in mpegts format over UDP using 188
1135 sized UDP packets, using a large input buffer:
1136 @example
1137 ffmpeg -i @var{input} -f mpegts udp://@var{hostname}:@var{port}?pkt_size=188&buffer_size=65535
1138 @end example
1139
1140 @item
1141 Use @command{ffmpeg} to receive over UDP from a remote endpoint:
1142 @example
1143 ffmpeg -i udp://[@var{multicast-address}]:@var{port} ...
1144 @end example
1145 @end itemize
1146
1147 @section unix
1148
1149 Unix local socket
1150
1151 The required syntax for a Unix socket URL is:
1152
1153 @example
1154 unix://@var{filepath}
1155 @end example
1156
1157 The following parameters can be set via command line options
1158 (or in code via @code{AVOption}s):
1159
1160 @table @option
1161 @item timeout
1162 Timeout in ms.
1163 @item listen
1164 Create the Unix socket in listening mode.
1165 @end table
1166
1167 @c man end PROTOCOLS