From 189ecf754d0c8131464bfdff98fb56e7752556b1 Mon Sep 17 00:00:00 2001 From: Xavier Del Campo Date: Sat, 4 Feb 2017 14:49:08 +0100 Subject: Initial commit --- Music/ffmpeg/doc/ffmpeg-protocols.html | 1691 ++++++++++++++++++++++++++++++++ 1 file changed, 1691 insertions(+) create mode 100755 Music/ffmpeg/doc/ffmpeg-protocols.html (limited to 'Music/ffmpeg/doc/ffmpeg-protocols.html') diff --git a/Music/ffmpeg/doc/ffmpeg-protocols.html b/Music/ffmpeg/doc/ffmpeg-protocols.html new file mode 100755 index 0000000..fe0adab --- /dev/null +++ b/Music/ffmpeg/doc/ffmpeg-protocols.html @@ -0,0 +1,1691 @@ + + + + + + + FFmpeg Protocols Documentation + + + + + + +
+

+ FFmpeg Protocols Documentation +

+
+
+ + + + + +

Table of Contents

+ +
+ + +
+ + + +

1 Description

+ +

This document describes the input and output protocols provided by the +libavformat library. +

+ + +

2 Protocol Options

+ +

The libavformat library provides some generic global options, which +can be set on all the protocols. In addition each protocol may support +so-called private options, which are specific for that component. +

+

The list of supported options follows: +

+
+
protocol_whitelist list (input)
+

Set a ","-separated list of allowed protocols. "ALL" matches all protocols. Protocols +prefixed by "-" are disabled. +All protocols are allowed by default but protocols used by an another +protocol (nested protocols) are restricted to a per protocol subset. +

+
+ + + +

3 Protocols

+ +

Protocols are configured elements in FFmpeg that enable access to +resources that require specific protocols. +

+

When you configure your FFmpeg build, all the supported protocols are +enabled by default. You can list all available ones using the +configure option "–list-protocols". +

+

You can disable all the protocols using the configure option +"–disable-protocols", and selectively enable a protocol using the +option "–enable-protocol=PROTOCOL", or you can disable a +particular protocol using the option +"–disable-protocol=PROTOCOL". +

+

The option "-protocols" of the ff* tools will display the list of +supported protocols. +

+

All protocols accept the following options: +

+
+
rw_timeout
+

Maximum time to wait for (network) read/write operations to complete, +in microseconds. +

+
+ +

A description of the currently available protocols follows. +

+ +

3.1 async

+ +

Asynchronous data filling wrapper for input stream. +

+

Fill data in a background thread, to decouple I/O operation from demux thread. +

+
+
async:URL
+async:http://host/resource
+async:cache:http://host/resource
+
+ + +

3.2 bluray

+ +

Read BluRay playlist. +

+

The accepted options are: +

+
angle
+

BluRay angle +

+
+
chapter
+

Start chapter (1...N) +

+
+
playlist
+

Playlist to read (BDMV/PLAYLIST/?????.mpls) +

+
+
+ +

Examples: +

+

Read longest playlist from BluRay mounted to /mnt/bluray: +

+
bluray:/mnt/bluray
+
+ +

Read angle 2 of playlist 4 from BluRay mounted to /mnt/bluray, start from chapter 2: +

+
-playlist 4 -angle 2 -chapter 2 bluray:/mnt/bluray
+
+ + +

3.3 cache

+ +

Caching wrapper for input stream. +

+

Cache the input stream to temporary file. It brings seeking capability to live streams. +

+
+
cache:URL
+
+ + +

3.4 concat

+ +

Physical concatenation protocol. +

+

Read and seek from many resources in sequence as if they were +a unique resource. +

+

A URL accepted by this protocol has the syntax: +

+
concat:URL1|URL2|...|URLN
+
+ +

where URL1, URL2, ..., URLN are the urls of the +resource to be concatenated, each one possibly specifying a distinct +protocol. +

+

For example to read a sequence of files split1.mpeg, +split2.mpeg, split3.mpeg with ffplay use the +command: +

+
ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg
+
+ +

Note that you may need to escape the character "|" which is special for +many shells. +

+ +

3.5 crypto

+ +

AES-encrypted stream reading protocol. +

+

The accepted options are: +

+
key
+

Set the AES decryption key binary block from given hexadecimal representation. +

+
+
iv
+

Set the AES decryption initialization vector binary block from given hexadecimal representation. +

+
+ +

Accepted URL formats: +

+
crypto:URL
+crypto+URL
+
+ + +

3.6 data

+ +

Data in-line in the URI. See http://en.wikipedia.org/wiki/Data_URI_scheme. +

+

For example, to convert a GIF file given inline with ffmpeg: +

+
ffmpeg -i "data:image/gif;base64,R0lGODdhCAAIAMIEAAAAAAAA//8AAP//AP///////////////ywAAAAACAAIAAADF0gEDLojDgdGiJdJqUX02iB4E8Q9jUMkADs=" smiley.png
+
+ + +

3.7 file

+ +

File access protocol. +

+

Read from or write to a file. +

+

A file URL can have the form: +

+
file:filename
+
+ +

where filename is the path of the file to read. +

+

An URL that does not have a protocol prefix will be assumed to be a +file URL. Depending on the build, an URL that looks like a Windows +path with the drive letter at the beginning will also be assumed to be +a file URL (usually not the case in builds for unix-like systems). +

+

For example to read from a file input.mpeg with ffmpeg +use the command: +

+
ffmpeg -i file:input.mpeg output.mpeg
+
+ +

This protocol accepts the following options: +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +INT_MAX, which results in not limiting the requested block size. +Setting this value reasonably low improves user termination request reaction +time, which is valuable for files on slow medium. +

+
+ + +

3.8 ftp

+ +

FTP (File Transfer Protocol). +

+

Read from or write to remote resources using FTP protocol. +

+

Following syntax is required. +

+
ftp://[user[:password]@]server[:port]/path/to/remote/resource.mpeg
+
+ +

This protocol accepts the following options. +

+
+
timeout
+

Set timeout in microseconds of socket I/O operations used by the underlying low level +operation. By default it is set to -1, which means that the timeout is +not specified. +

+
+
ftp-anonymous-password
+

Password used when login as anonymous user. Typically an e-mail address +should be used. +

+
+
ftp-write-seekable
+

Control seekability of connection during encoding. If set to 1 the +resource is supposed to be seekable, if set to 0 it is assumed not +to be seekable. Default value is 0. +

+
+ +

NOTE: Protocol can be used as output, but it is recommended to not do +it, unless special care is taken (tests, customized server configuration +etc.). Different FTP servers behave in different way during seek +operation. ff* tools may produce incomplete content due to server limitations. +

+

This protocol accepts the following options: +

+
+
follow
+

If set to 1, the protocol will retry reading at the end of the file, allowing +reading files that still are being written. In order for this to terminate, +you either need to use the rw_timeout option, or use the interrupt callback +(for API users). +

+
+
+ + +

3.9 gopher

+ +

Gopher protocol. +

+ +

3.10 hls

+ +

Read Apple HTTP Live Streaming compliant segmented stream as +a uniform one. The M3U8 playlists describing the segments can be +remote HTTP resources or local files, accessed using the standard +file protocol. +The nested protocol is declared by specifying +"+proto" after the hls URI scheme name, where proto +is either "file" or "http". +

+
+
hls+http://host/path/to/remote/resource.m3u8
+hls+file://path/to/local/resource.m3u8
+
+ +

Using this protocol is discouraged - the hls demuxer should work +just as well (if not, please report the issues) and is more complete. +To use the hls demuxer instead, simply use the direct URLs to the +m3u8 files. +

+ +

3.11 http

+ +

HTTP (Hyper Text Transfer Protocol). +

+

This protocol accepts the following options: +

+
+
seekable
+

Control seekability of connection. If set to 1 the resource is +supposed to be seekable, if set to 0 it is assumed not to be seekable, +if set to -1 it will try to autodetect if it is seekable. Default +value is -1. +

+
+
chunked_post
+

If set to 1 use chunked Transfer-Encoding for posts, default is 1. +

+
+
content_type
+

Set a specific content type for the POST messages or for listen mode. +

+
+
http_proxy
+

set HTTP proxy to tunnel through e.g. http://example.com:1234 +

+
+
headers
+

Set custom HTTP headers, can override built in default headers. The +value must be a string encoding the headers. +

+
+
multiple_requests
+

Use persistent connections if set to 1, default is 0. +

+
+
post_data
+

Set custom HTTP post data. +

+
+
user_agent
+

Override the User-Agent header. If not specified the protocol will use a +string describing the libavformat build. ("Lavf/<version>") +

+
+
user-agent
+

This is a deprecated option, you can use user_agent instead it. +

+
+
timeout
+

Set timeout in microseconds of socket I/O operations used by the underlying low level +operation. By default it is set to -1, which means that the timeout is +not specified. +

+
+
reconnect_at_eof
+

If set then eof is treated like an error and causes reconnection, this is useful +for live / endless streams. +

+
+
reconnect_streamed
+

If set then even streamed/non seekable streams will be reconnected on errors. +

+
+
reconnect_delay_max
+

Sets the maximum delay in seconds after which to give up reconnecting +

+
+
mime_type
+

Export the MIME type. +

+
+
icy
+

If set to 1 request ICY (SHOUTcast) metadata from the server. If the server +supports this, the metadata has to be retrieved by the application by reading +the icy_metadata_headers and icy_metadata_packet options. +The default is 1. +

+
+
icy_metadata_headers
+

If the server supports ICY metadata, this contains the ICY-specific HTTP reply +headers, separated by newline characters. +

+
+
icy_metadata_packet
+

If the server supports ICY metadata, and icy was set to 1, this +contains the last non-empty metadata packet sent by the server. It should be +polled in regular intervals by applications interested in mid-stream metadata +updates. +

+
+
cookies
+

Set the cookies to be sent in future requests. The format of each cookie is the +same as the value of a Set-Cookie HTTP response field. Multiple cookies can be +delimited by a newline character. +

+
+
offset
+

Set initial byte offset. +

+
+
end_offset
+

Try to limit the request to bytes preceding this offset. +

+
+
method
+

When used as a client option it sets the HTTP method for the request. +

+

When used as a server option it sets the HTTP method that is going to be +expected from the client(s). +If the expected and the received HTTP method do not match the client will +be given a Bad Request response. +When unset the HTTP method is not checked for now. This will be replaced by +autodetection in the future. +

+
+
listen
+

If set to 1 enables experimental HTTP server. This can be used to send data when +used as an output option, or read data from a client with HTTP POST when used as +an input option. +If set to 2 enables experimental multi-client HTTP server. This is not yet implemented +in ffmpeg.c or ffserver.c and thus must not be used as a command line option. +

+
# Server side (sending):
+ffmpeg -i somefile.ogg -c copy -listen 1 -f ogg http://server:port
+
+# Client side (receiving):
+ffmpeg -i http://server:port -c copy somefile.ogg
+
+# Client can also be done with wget:
+wget http://server:port -O somefile.ogg
+
+# Server side (receiving):
+ffmpeg -listen 1 -i http://server:port -c copy somefile.ogg
+
+# Client side (sending):
+ffmpeg -i somefile.ogg -chunked_post 0 -c copy -f ogg http://server:port
+
+# Client can also be done with wget:
+wget --post-file=somefile.ogg http://server:port
+
+ +
+
+ + +

3.11.1 HTTP Cookies

+ +

Some HTTP requests will be denied unless cookie values are passed in with the +request. The cookies option allows these cookies to be specified. At +the very least, each cookie must specify a value along with a path and domain. +HTTP requests that match both the domain and path will automatically include the +cookie value in the HTTP Cookie header field. Multiple cookies can be delimited +by a newline. +

+

The required syntax to play a stream specifying a cookie is: +

+
ffplay -cookies "nlqptid=nltid=tsn; path=/; domain=somedomain.com;" http://somedomain.com/somestream.m3u8
+
+ + +

3.12 Icecast

+ +

Icecast protocol (stream to Icecast servers) +

+

This protocol accepts the following options: +

+
+
ice_genre
+

Set the stream genre. +

+
+
ice_name
+

Set the stream name. +

+
+
ice_description
+

Set the stream description. +

+
+
ice_url
+

Set the stream website URL. +

+
+
ice_public
+

Set if the stream should be public. +The default is 0 (not public). +

+
+
user_agent
+

Override the User-Agent header. If not specified a string of the form +"Lavf/<version>" will be used. +

+
+
password
+

Set the Icecast mountpoint password. +

+
+
content_type
+

Set the stream content type. This must be set if it is different from +audio/mpeg. +

+
+
legacy_icecast
+

This enables support for Icecast versions < 2.4.0, that do not support the +HTTP PUT method but the SOURCE method. +

+
+
+ +
+
icecast://[username[:password]@]server:port/mountpoint
+
+ + +

3.13 mmst

+ +

MMS (Microsoft Media Server) protocol over TCP. +

+ +

3.14 mmsh

+ +

MMS (Microsoft Media Server) protocol over HTTP. +

+

The required syntax is: +

+
mmsh://server[:port][/app][/playpath]
+
+ + +

3.15 md5

+ +

MD5 output protocol. +

+

Computes the MD5 hash of the data to be written, and on close writes +this to the designated output or stdout if none is specified. It can +be used to test muxers without writing an actual file. +

+

Some examples follow. +

+
# Write the MD5 hash of the encoded AVI file to the file output.avi.md5.
+ffmpeg -i input.flv -f avi -y md5:output.avi.md5
+
+# Write the MD5 hash of the encoded AVI file to stdout.
+ffmpeg -i input.flv -f avi -y md5:
+
+ +

Note that some formats (typically MOV) require the output protocol to +be seekable, so they will fail with the MD5 output protocol. +

+ +

3.16 pipe

+ +

UNIX pipe access protocol. +

+

Read and write from UNIX pipes. +

+

The accepted syntax is: +

+
pipe:[number]
+
+ +

number is the number corresponding to the file descriptor of the +pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr). If number +is not specified, by default the stdout file descriptor will be used +for writing, stdin for reading. +

+

For example to read from stdin with ffmpeg: +

+
cat test.wav | ffmpeg -i pipe:0
+# ...this is the same as...
+cat test.wav | ffmpeg -i pipe:
+
+ +

For writing to stdout with ffmpeg: +

+
ffmpeg -i test.wav -f avi pipe:1 | cat > test.avi
+# ...this is the same as...
+ffmpeg -i test.wav -f avi pipe: | cat > test.avi
+
+ +

This protocol accepts the following options: +

+
+
blocksize
+

Set I/O operation maximum block size, in bytes. Default value is +INT_MAX, which results in not limiting the requested block size. +Setting this value reasonably low improves user termination request reaction +time, which is valuable if data transmission is slow. +

+
+ +

Note that some formats (typically MOV), require the output protocol to +be seekable, so they will fail with the pipe output protocol. +

+ +

3.17 rtmp

+ +

Real-Time Messaging Protocol. +

+

The Real-Time Messaging Protocol (RTMP) is used for streaming multimedia +content across a TCP/IP network. +

+

The required syntax is: +

+
rtmp://[username:password@]server[:port][/app][/instance][/playpath]
+
+ +

The accepted parameters are: +

+
username
+

An optional username (mostly for publishing). +

+
+
password
+

An optional password (mostly for publishing). +

+
+
server
+

The address of the RTMP server. +

+
+
port
+

The number of the TCP port to use (by default is 1935). +

+
+
app
+

It is the name of the application to access. It usually corresponds to +the path where the application is installed on the RTMP server +(e.g. /ondemand/, /flash/live/, etc.). You can override +the value parsed from the URI through the rtmp_app option, too. +

+
+
playpath
+

It is the path or name of the resource to play with reference to the +application specified in app, may be prefixed by "mp4:". You +can override the value parsed from the URI through the rtmp_playpath +option, too. +

+
+
listen
+

Act as a server, listening for an incoming connection. +

+
+
timeout
+

Maximum time to wait for the incoming connection. Implies listen. +

+
+ +

Additionally, the following parameters can be set via command line options +(or in code via AVOptions): +

+
rtmp_app
+

Name of application to connect on the RTMP server. This option +overrides the parameter specified in the URI. +

+
+
rtmp_buffer
+

Set the client buffer time in milliseconds. The default is 3000. +

+
+
rtmp_conn
+

Extra arbitrary AMF connection parameters, parsed from a string, +e.g. like B:1 S:authMe O:1 NN:code:1.23 NS:flag:ok O:0. +Each value is prefixed by a single character denoting the type, +B for Boolean, N for number, S for string, O for object, or Z for null, +followed by a colon. For Booleans the data must be either 0 or 1 for +FALSE or TRUE, respectively. Likewise for Objects the data must be 0 or +1 to end or begin an object, respectively. Data items in subobjects may +be named, by prefixing the type with ’N’ and specifying the name before +the value (i.e. NB:myFlag:1). This option may be used multiple +times to construct arbitrary AMF sequences. +

+
+
rtmp_flashver
+

Version of the Flash plugin used to run the SWF player. The default +is LNX 9,0,124,2. (When publishing, the default is FMLE/3.0 (compatible; +<libavformat version>).) +

+
+
rtmp_flush_interval
+

Number of packets flushed in the same request (RTMPT only). The default +is 10. +

+
+
rtmp_live
+

Specify that the media is a live stream. No resuming or seeking in +live streams is possible. The default value is any, which means the +subscriber first tries to play the live stream specified in the +playpath. If a live stream of that name is not found, it plays the +recorded stream. The other possible values are live and +recorded. +

+
+
rtmp_pageurl
+

URL of the web page in which the media was embedded. By default no +value will be sent. +

+
+
rtmp_playpath
+

Stream identifier to play or to publish. This option overrides the +parameter specified in the URI. +

+
+
rtmp_subscribe
+

Name of live stream to subscribe to. By default no value will be sent. +It is only sent if the option is specified or if rtmp_live +is set to live. +

+
+
rtmp_swfhash
+

SHA256 hash of the decompressed SWF file (32 bytes). +

+
+
rtmp_swfsize
+

Size of the decompressed SWF file, required for SWFVerification. +

+
+
rtmp_swfurl
+

URL of the SWF player for the media. By default no value will be sent. +

+
+
rtmp_swfverify
+

URL to player swf file, compute hash/size automatically. +

+
+
rtmp_tcurl
+

URL of the target stream. Defaults to proto://host[:port]/app. +

+
+
+ +

For example to read with ffplay a multimedia resource named +"sample" from the application "vod" from an RTMP server "myserver": +

+
ffplay rtmp://myserver/vod/sample
+
+ +

To publish to a password protected server, passing the playpath and +app names separately: +

+
ffmpeg -re -i <input> -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@myserver/
+
+ + +

3.18 rtmpe

+ +

Encrypted Real-Time Messaging Protocol. +

+

The Encrypted Real-Time Messaging Protocol (RTMPE) is used for +streaming multimedia content within standard cryptographic primitives, +consisting of Diffie-Hellman key exchange and HMACSHA256, generating +a pair of RC4 keys. +

+ +

3.19 rtmps

+ +

Real-Time Messaging Protocol over a secure SSL connection. +

+

The Real-Time Messaging Protocol (RTMPS) is used for streaming +multimedia content across an encrypted connection. +

+ +

3.20 rtmpt

+ +

Real-Time Messaging Protocol tunneled through HTTP. +

+

The Real-Time Messaging Protocol tunneled through HTTP (RTMPT) is used +for streaming multimedia content within HTTP requests to traverse +firewalls. +

+ +

3.21 rtmpte

+ +

Encrypted Real-Time Messaging Protocol tunneled through HTTP. +

+

The Encrypted Real-Time Messaging Protocol tunneled through HTTP (RTMPTE) +is used for streaming multimedia content within HTTP requests to traverse +firewalls. +

+ +

3.22 rtmpts

+ +

Real-Time Messaging Protocol tunneled through HTTPS. +

+

The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used +for streaming multimedia content within HTTPS requests to traverse +firewalls. +

+ +

3.23 libsmbclient

+ +

libsmbclient permits one to manipulate CIFS/SMB network resources. +

+

Following syntax is required. +

+
+
smb://[[domain:]user[:password@]]server[/share[/path[/file]]]
+
+ +

This protocol accepts the following options. +

+
+
timeout
+

Set timeout in milliseconds of socket I/O operations used by the underlying +low level operation. By default it is set to -1, which means that the timeout +is not specified. +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
workgroup
+

Set the workgroup used for making connections. By default workgroup is not specified. +

+
+
+ +

For more information see: http://www.samba.org/. +

+ +

3.24 libssh

+ +

Secure File Transfer Protocol via libssh +

+

Read from or write to remote resources using SFTP protocol. +

+

Following syntax is required. +

+
+
sftp://[user[:password]@]server[:port]/path/to/remote/resource.mpeg
+
+ +

This protocol accepts the following options. +

+
+
timeout
+

Set timeout of socket I/O operations used by the underlying low level +operation. By default it is set to -1, which means that the timeout +is not specified. +

+
+
truncate
+

Truncate existing files on write, if set to 1. A value of 0 prevents +truncating. Default value is 1. +

+
+
private_key
+

Specify the path of the file containing private key to use during authorization. +By default libssh searches for keys in the ~/.ssh/ directory. +

+
+
+ +

Example: Play a file stored on remote server. +

+
+
ffplay sftp://user:password@server_address:22/home/user/resource.mpeg
+
+ + +

3.25 librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte

+ +

Real-Time Messaging Protocol and its variants supported through +librtmp. +

+

Requires the presence of the librtmp headers and library during +configuration. You need to explicitly configure the build with +"–enable-librtmp". If enabled this will replace the native RTMP +protocol. +

+

This protocol provides most client functions and a few server +functions needed to support RTMP, RTMP tunneled in HTTP (RTMPT), +encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and tunneled +variants of these encrypted types (RTMPTE, RTMPTS). +

+

The required syntax is: +

+
rtmp_proto://server[:port][/app][/playpath] options
+
+ +

where rtmp_proto is one of the strings "rtmp", "rtmpt", "rtmpe", +"rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and +server, port, app and playpath have the same +meaning as specified for the RTMP native protocol. +options contains a list of space-separated options of the form +key=val. +

+

See the librtmp manual page (man 3 librtmp) for more information. +

+

For example, to stream a file in real-time to an RTMP server using +ffmpeg: +

+
ffmpeg -re -i myfile -f flv rtmp://myserver/live/mystream
+
+ +

To play the same stream using ffplay: +

+
ffplay "rtmp://myserver/live/mystream live=1"
+
+ + +

3.26 rtp

+ +

Real-time Transport Protocol. +

+

The required syntax for an RTP URL is: +rtp://hostname[:port][?option=val...] +

+

port specifies the RTP port to use. +

+

The following URL options are supported: +

+
+
ttl=n
+

Set the TTL (Time-To-Live) value (for multicast only). +

+
+
rtcpport=n
+

Set the remote RTCP port to n. +

+
+
localrtpport=n
+

Set the local RTP port to n. +

+
+
localrtcpport=n'
+

Set the local RTCP port to n. +

+
+
pkt_size=n
+

Set max packet size (in bytes) to n. +

+
+
connect=0|1
+

Do a connect() on the UDP socket (if set to 1) or not (if set +to 0). +

+
+
sources=ip[,ip]
+

List allowed source IP addresses. +

+
+
block=ip[,ip]
+

List disallowed (blocked) source IP addresses. +

+
+
write_to_source=0|1
+

Send packets to the source address of the latest received packet (if +set to 1) or to a default remote address (if set to 0). +

+
+
localport=n
+

Set the local RTP port to n. +

+

This is a deprecated option. Instead, localrtpport should be +used. +

+
+
+ +

Important notes: +

+
    +
  1. If rtcpport is not set the RTCP port will be set to the RTP +port value plus 1. + +
  2. If localrtpport (the local RTP port) is not set any available +port will be used for the local RTP and RTCP ports. + +
  3. If localrtcpport (the local RTCP port) is not set it will be +set to the local RTP port value plus 1. +
+ + +

3.27 rtsp

+ +

Real-Time Streaming Protocol. +

+

RTSP is not technically a protocol handler in libavformat, it is a demuxer +and muxer. The demuxer supports both normal RTSP (with data transferred +over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with +data transferred over RDT). +

+

The muxer can be used to send a stream using RTSP ANNOUNCE to a server +supporting it (currently Darwin Streaming Server and Mischa Spiegelmock’s +RTSP server). +

+

The required syntax for a RTSP url is: +

+
rtsp://hostname[:port]/path
+
+ +

Options can be set on the ffmpeg/ffplay command +line, or set in code via AVOptions or in +avformat_open_input. +

+

The following options are supported. +

+
+
initial_pause
+

Do not start playing the stream immediately if set to 1. Default value +is 0. +

+
+
rtsp_transport
+

Set RTSP transport protocols. +

+

It accepts the following values: +

+
‘udp’
+

Use UDP as lower transport protocol. +

+
+
‘tcp’
+

Use TCP (interleaving within the RTSP control channel) as lower +transport protocol. +

+
+
‘udp_multicast’
+

Use UDP multicast as lower transport protocol. +

+
+
‘http’
+

Use HTTP tunneling as lower transport protocol, which is useful for +passing proxies. +

+
+ +

Multiple lower transport protocols may be specified, in that case they are +tried one at a time (if the setup of one fails, the next one is tried). +For the muxer, only the ‘tcp’ and ‘udp’ options are supported. +

+
+
rtsp_flags
+

Set RTSP flags. +

+

The following values are accepted: +

+
‘filter_src’
+

Accept packets only from negotiated peer address and port. +

+
‘listen’
+

Act as a server, listening for an incoming connection. +

+
‘prefer_tcp’
+

Try TCP for RTP transport first, if TCP is available as RTSP RTP transport. +

+
+ +

Default value is ‘none’. +

+
+
allowed_media_types
+

Set media types to accept from the server. +

+

The following flags are accepted: +

+
‘video’
+
‘audio’
+
‘data’
+
+ +

By default it accepts all media types. +

+
+
min_port
+

Set minimum local UDP port. Default value is 5000. +

+
+
max_port
+

Set maximum local UDP port. Default value is 65000. +

+
+
timeout
+

Set maximum timeout (in seconds) to wait for incoming connections. +

+

A value of -1 means infinite (default). This option implies the +rtsp_flags set to ‘listen’. +

+
+
reorder_queue_size
+

Set number of packets to buffer for handling of reordered packets. +

+
+
stimeout
+

Set socket TCP I/O timeout in microseconds. +

+
+
user-agent
+

Override User-Agent header. If not specified, it defaults to the +libavformat identifier string. +

+
+ +

When receiving data over UDP, the demuxer tries to reorder received packets +(since they may arrive out of order, or packets may get lost totally). This +can be disabled by setting the maximum demuxing delay to zero (via +the max_delay field of AVFormatContext). +

+

When watching multi-bitrate Real-RTSP streams with ffplay, the +streams to display can be chosen with -vst n and +-ast n for video and audio respectively, and can be switched +on the fly by pressing v and a. +

+ +

3.27.1 Examples

+ +

The following examples all make use of the ffplay and +ffmpeg tools. +

+ + + +

3.28 sap

+ +

Session Announcement Protocol (RFC 2974). This is not technically a +protocol handler in libavformat, it is a muxer and demuxer. +It is used for signalling of RTP streams, by announcing the SDP for the +streams regularly on a separate port. +

+ +

3.28.1 Muxer

+ +

The syntax for a SAP url given to the muxer is: +

+
sap://destination[:port][?options]
+
+ +

The RTP packets are sent to destination on port port, +or to port 5004 if no port is specified. +options is a &-separated list. The following options +are supported: +

+
+
announce_addr=address
+

Specify the destination IP address for sending the announcements to. +If omitted, the announcements are sent to the commonly used SAP +announcement multicast address 224.2.127.254 (sap.mcast.net), or +ff0e::2:7ffe if destination is an IPv6 address. +

+
+
announce_port=port
+

Specify the port to send the announcements on, defaults to +9875 if not specified. +

+
+
ttl=ttl
+

Specify the time to live value for the announcements and RTP packets, +defaults to 255. +

+
+
same_port=0|1
+

If set to 1, send all RTP streams on the same port pair. If zero (the +default), all streams are sent on unique ports, with each stream on a +port 2 numbers higher than the previous. +VLC/Live555 requires this to be set to 1, to be able to receive the stream. +The RTP stack in libavformat for receiving requires all streams to be sent +on unique ports. +

+
+ +

Example command lines follow. +

+

To broadcast a stream on the local subnet, for watching in VLC: +

+
+
ffmpeg -re -i input -f sap sap://224.0.0.255?same_port=1
+
+ +

Similarly, for watching in ffplay: +

+
+
ffmpeg -re -i input -f sap sap://224.0.0.255
+
+ +

And for watching in ffplay, over IPv6: +

+
+
ffmpeg -re -i input -f sap sap://[ff0e::1:2:3:4]
+
+ + +

3.28.2 Demuxer

+ +

The syntax for a SAP url given to the demuxer is: +

+
sap://[address][:port]
+
+ +

address is the multicast address to listen for announcements on, +if omitted, the default 224.2.127.254 (sap.mcast.net) is used. port +is the port that is listened on, 9875 if omitted. +

+

The demuxers listens for announcements on the given address and port. +Once an announcement is received, it tries to receive that particular stream. +

+

Example command lines follow. +

+

To play back the first stream announced on the normal SAP multicast address: +

+
+
ffplay sap://
+
+ +

To play back the first stream announced on one the default IPv6 SAP multicast address: +

+
+
ffplay sap://[ff0e::2:7ffe]
+
+ + +

3.29 sctp

+ +

Stream Control Transmission Protocol. +

+

The accepted URL syntax is: +

+
sctp://host:port[?options]
+
+ +

The protocol accepts the following options: +

+
listen
+

If set to any value, listen for an incoming connection. Outgoing connection is done by default. +

+
+
max_streams
+

Set the maximum number of streams. By default no limit is set. +

+
+ + +

3.30 srtp

+ +

Secure Real-time Transport Protocol. +

+

The accepted options are: +

+
srtp_in_suite
+
srtp_out_suite
+

Select input and output encoding suites. +

+

Supported values: +

+
‘AES_CM_128_HMAC_SHA1_80’
+
‘SRTP_AES128_CM_HMAC_SHA1_80’
+
‘AES_CM_128_HMAC_SHA1_32’
+
‘SRTP_AES128_CM_HMAC_SHA1_32’
+
+ +
+
srtp_in_params
+
srtp_out_params
+

Set input and output encoding parameters, which are expressed by a +base64-encoded representation of a binary block. The first 16 bytes of +this binary block are used as master key, the following 14 bytes are +used as master salt. +

+
+ + +

3.31 subfile

+ +

Virtually extract a segment of a file or another stream. +The underlying stream must be seekable. +

+

Accepted options: +

+
start
+

Start offset of the extracted segment, in bytes. +

+
end
+

End offset of the extracted segment, in bytes. +

+
+ +

Examples: +

+

Extract a chapter from a DVD VOB file (start and end sectors obtained +externally and multiplied by 2048): +

+
subfile,,start,153391104,end,268142592,,:/media/dvd/VIDEO_TS/VTS_08_1.VOB
+
+ +

Play an AVI file directly from a TAR archive: +

+
subfile,,start,183241728,end,366490624,,:archive.tar
+
+ + +

3.32 tee

+ +

Writes the output to multiple protocols. The individual outputs are separated +by | +

+
+
tee:file://path/to/local/this.avi|file://path/to/local/that.avi
+
+ + +

3.33 tcp

+ +

Transmission Control Protocol. +

+

The required syntax for a TCP url is: +

+
tcp://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form +key=val. +

+

The list of supported options follows. +

+
+
listen=1|0
+

Listen for an incoming connection. Default value is 0. +

+
+
timeout=microseconds
+

Set raise error timeout, expressed in microseconds. +

+

This option is only relevant in read mode: if no data arrived in more +than this time interval, raise error. +

+
+
listen_timeout=milliseconds
+

Set listen timeout, expressed in milliseconds. +

+
+
recv_buffer_size=bytes
+

Set receive buffer size, expressed bytes. +

+
+
send_buffer_size=bytes
+

Set send buffer size, expressed bytes. +

+
+ +

The following example shows how to setup a listening TCP connection +with ffmpeg, which is then accessed with ffplay: +

+
ffmpeg -i input -f format tcp://hostname:port?listen
+ffplay tcp://hostname:port
+
+ + +

3.34 tls

+ +

Transport Layer Security (TLS) / Secure Sockets Layer (SSL) +

+

The required syntax for a TLS/SSL url is: +

+
tls://hostname:port[?options]
+
+ +

The following parameters can be set via command line options +(or in code via AVOptions): +

+
+
ca_file, cafile=filename
+

A file containing certificate authority (CA) root certificates to treat +as trusted. If the linked TLS library contains a default this might not +need to be specified for verification to work, but not all libraries and +setups have defaults built in. +The file must be in OpenSSL PEM format. +

+
+
tls_verify=1|0
+

If enabled, try to verify the peer that we are communicating with. +Note, if using OpenSSL, this currently only makes sure that the +peer certificate is signed by one of the root certificates in the CA +database, but it does not validate that the certificate actually +matches the host name we are trying to connect to. (With GnuTLS, +the host name is validated as well.) +

+

This is disabled by default since it requires a CA database to be +provided by the caller in many cases. +

+
+
cert_file, cert=filename
+

A file containing a certificate to use in the handshake with the peer. +(When operating as server, in listen mode, this is more often required +by the peer, while client certificates only are mandated in certain +setups.) +

+
+
key_file, key=filename
+

A file containing the private key for the certificate. +

+
+
listen=1|0
+

If enabled, listen for connections on the provided port, and assume +the server role in the handshake instead of the client role. +

+
+
+ +

Example command lines: +

+

To create a TLS/SSL server that serves an input stream. +

+
+
ffmpeg -i input -f format tls://hostname:port?listen&cert=server.crt&key=server.key
+
+ +

To play back a stream from the TLS/SSL server using ffplay: +

+
+
ffplay tls://hostname:port
+
+ + +

3.35 udp

+ +

User Datagram Protocol. +

+

The required syntax for an UDP URL is: +

+
udp://hostname:port[?options]
+
+ +

options contains a list of &-separated options of the form key=val. +

+

In case threading is enabled on the system, a circular buffer is used +to store the incoming data, which allows one to reduce loss of data due to +UDP socket buffer overruns. The fifo_size and +overrun_nonfatal options are related to this buffer. +

+

The list of supported options follows. +

+
+
buffer_size=size
+

Set the UDP maximum socket buffer size in bytes. This is used to set either +the receive or send buffer size, depending on what the socket is used for. +Default is 64KB. See also fifo_size. +

+
+
bitrate=bitrate
+

If set to nonzero, the output will have the specified constant bitrate if the +input has enough packets to sustain it. +

+
+
burst_bits=bits
+

When using bitrate this specifies the maximum number of bits in +packet bursts. +

+
+
localport=port
+

Override the local UDP port to bind with. +

+
+
localaddr=addr
+

Choose the local IP address. This is useful e.g. if sending multicast +and the host has multiple interfaces, where the user can choose +which interface to send on by specifying the IP address of that interface. +

+
+
pkt_size=size
+

Set the size in bytes of UDP packets. +

+
+
reuse=1|0
+

Explicitly allow or disallow reusing UDP sockets. +

+
+
ttl=ttl
+

Set the time to live value (for multicast only). +

+
+
connect=1|0
+

Initialize the UDP socket with connect(). In this case, the +destination address can’t be changed with ff_udp_set_remote_url later. +If the destination address isn’t known at the start, this option can +be specified in ff_udp_set_remote_url, too. +This allows finding out the source address for the packets with getsockname, +and makes writes return with AVERROR(ECONNREFUSED) if "destination +unreachable" is received. +For receiving, this gives the benefit of only receiving packets from +the specified peer address/port. +

+
+
sources=address[,address]
+

Only receive packets sent to the multicast group from one of the +specified sender IP addresses. +

+
+
block=address[,address]
+

Ignore packets sent to the multicast group from the specified +sender IP addresses. +

+
+
fifo_size=units
+

Set the UDP receiving circular buffer size, expressed as a number of +packets with size of 188 bytes. If not specified defaults to 7*4096. +

+
+
overrun_nonfatal=1|0
+

Survive in case of UDP receiving circular buffer overrun. Default +value is 0. +

+
+
timeout=microseconds
+

Set raise error timeout, expressed in microseconds. +

+

This option is only relevant in read mode: if no data arrived in more +than this time interval, raise error. +

+
+
broadcast=1|0
+

Explicitly allow or disallow UDP broadcasting. +

+

Note that broadcasting may not work properly on networks having +a broadcast storm protection. +

+
+ + +

3.35.1 Examples

+ + + + +

3.36 unix

+ +

Unix local socket +

+

The required syntax for a Unix socket URL is: +

+
+
unix://filepath
+
+ +

The following parameters can be set via command line options +(or in code via AVOptions): +

+
+
timeout
+

Timeout in ms. +

+
listen
+

Create the Unix socket in listening mode. +

+
+ + + +

4 See Also

+ +

ffmpeg, ffplay, ffprobe, ffserver, +libavformat +

+ + +

5 Authors

+ +

The FFmpeg developers. +

+

For details about the authorship, see the Git history of the project +(git://source.ffmpeg.org/ffmpeg), e.g. by typing the command +git log in the FFmpeg source directory, or browsing the +online repository at http://source.ffmpeg.org. +

+

Maintainers for the specific components are listed in the file +MAINTAINERS in the source code tree. +

+ + +

+ This document was generated using makeinfo. +

+
+ + -- cgit v1.2.3