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