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