Subversion Repositories Kolibri OS

=encoding utf8

=head1 NAME

ffmpeg-protocols - FFmpeg protocols

=head1 DESCRIPTION

This document describes the input and output protocols provided by the

libavformat library.

=head1 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=I", or you can disable a

particular protocol using the option

"--disable-protocol=I".

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

supported protocols.

A description of the currently available protocols follows.

=head2 async

Asynchronous data filling wrapper for input stream.

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

	async:

	async:http://host/resource

	async:cache:http://host/resource

=head2 bluray

Read BluRay playlist.

The accepted options are:

=over 4

=item B

BluRay angle

=item B

Start chapter (1...N)

=item B

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

=back

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

=head2 cache

Caching wrapper for input stream.

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

	cache:

=head2 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:||...|

where I, I, ..., I are the urls of the

resource to be concatenated, each one possibly specifying a distinct

protocol.

For example to read a sequence of files F,

F, F with B 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.

=head2 crypto

AES-encrypted stream reading protocol.

The accepted options are:

=over 4

=item B

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

=item B

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

=back

Accepted URL formats:

	crypto:

	crypto+

=head2 data

Data in-line in the URI. See EBE.

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

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

=head2 file

File access protocol.

Read from or write to a file.

A file URL can have the form:

	file:

where I 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 F with B

use the command:

	ffmpeg -i file:input.mpeg output.mpeg

This protocol accepts the following options:

=over 4

=item B

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

truncating. Default value is 1.

=item B

Set I/O operation maximum block size, in bytes. Default value is

C, 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.

=back

=head2 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.

=over 4

=item B

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.

=item B

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

should be used.

=item B

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.

=back

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.

=head2 gopher

Gopher protocol.

=head2 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

"+I" after the hls URI scheme name, where I

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.

=head2 http

HTTP (Hyper Text Transfer Protocol).

This protocol accepts the following options:

=over 4

=item B

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.

=item B

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

=item B

Set a specific content type for the POST messages.

=item B

Set custom HTTP headers, can override built in default headers. The

value must be a string encoding the headers.

=item B

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

=item B

Set custom HTTP post data.

=item B

=item B

Override the User-Agent header. If not specified the protocol will use a

string describing the libavformat build. ("Lavf/EversionE")

=item B

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.

=item B

Export the MIME type.

=item B

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 B and B options.

The default is 1.

=item B

If the server supports ICY metadata, this contains the ICY-specific HTTP reply

headers, separated by newline characters.

=item B

If the server supports ICY metadata, and B 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.

=item B

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.

=item B

Set initial byte offset.

=item B

Try to limit the request to bytes preceding this offset.

=item B

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.

=item B

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 mutli-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://:

	# Client side (receiving):

	ffmpeg -i http://: -c copy somefile.ogg

	# Client can also be done with wget:

	wget http://: -O somefile.ogg

	# Server side (receiving):

	ffmpeg -listen 1 -i http://: -c copy somefile.ogg

	# Client side (sending):

	ffmpeg -i somefile.ogg -chunked_post 0 -c copy -f ogg http://:

	# Client can also be done with wget:

	wget --post-file=somefile.ogg http://:

=back

=head3 HTTP Cookies

Some HTTP requests will be denied unless cookie values are passed in with the

request. The B 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

=head2 Icecast

Icecast protocol (stream to Icecast servers)

This protocol accepts the following options:

=over 4

=item B

Set the stream genre.

=item B

Set the stream name.

=item B

Set the stream description.

=item B

Set the stream website URL.

=item B

Set if the stream should be public.

The default is 0 (not public).

=item B

Override the User-Agent header. If not specified a string of the form

"Lavf/EversionE" will be used.

=item B

Set the Icecast mountpoint password.

=item B

Set the stream content type. This must be set if it is different from

audio/mpeg.

=item B

This enables support for Icecast versions E 2.4.0, that do not support the

HTTP PUT method but the SOURCE method.

=back

	icecast://[[:]@]:/

=head2 mmst

MMS (Microsoft Media Server) protocol over TCP.

=head2 mmsh

MMS (Microsoft Media Server) protocol over HTTP.

The required syntax is:

	mmsh://[:][/][/]

=head2 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.

=head2 pipe

UNIX pipe access protocol.

Read and write from UNIX pipes.

The accepted syntax is:

	pipe:[]

I is the number corresponding to the file descriptor of the

pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr).  If I

is not specified, by default the stdout file descriptor will be used

for writing, stdin for reading.

For example to read from stdin with B:

	cat test.wav | ffmpeg -i pipe:0

	# ...this is the same as...

	cat test.wav | ffmpeg -i pipe:

For writing to stdout with B:

	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:

=over 4

=item B

Set I/O operation maximum block size, in bytes. Default value is

C, 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.

=back

Note that some formats (typically MOV), require the output protocol to

be seekable, so they will fail with the pipe output protocol.

=head2 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://[:@][:][/][/][/]

The accepted parameters are:

=over 4

=item B

An optional username (mostly for publishing).

=item B

An optional password (mostly for publishing).

=item B

The address of the RTMP server.

=item B

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

=item B

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. F, F, etc.). You can override

the value parsed from the URI through the C option, too.

=item B

It is the path or name of the resource to play with reference to the

application specified in I, may be prefixed by "mp4:". You

can override the value parsed from the URI through the C

option, too.

=item B

Act as a server, listening for an incoming connection.

=item B

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

=back

Additionally, the following parameters can be set via command line options

(or in code via Cs):

=over 4

=item B

Name of application to connect on the RTMP server. This option

overrides the parameter specified in the URI.

=item B

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

=item B

Extra arbitrary AMF connection parameters, parsed from a string,

e.g. like C.

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. C). This option may be used multiple

times to construct arbitrary AMF sequences.

=item B

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;

Elibavformat versionE).)

=item B

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

is 10.

=item B

Specify that the media is a live stream. No resuming or seeking in

live streams is possible. The default value is C, 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 C and

C.

=item B

URL of the web page in which the media was embedded. By default no

value will be sent.

=item B

Stream identifier to play or to publish. This option overrides the

parameter specified in the URI.

=item B

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.

=item B

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

=item B

Size of the decompressed SWF file, required for SWFVerification.

=item B

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

=item B

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

=item B

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

=back

For example to read with B 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  -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@myserver/

=head2 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.

=head2 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.

=head2 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.

=head2 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.

=head2 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.

=head2 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.

=over 4

=item B

Set timeout in miliseconds 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.

=item B

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

truncating. Default value is 1.

=item B

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

=back

For more information see: EBE.

=head2 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.

=over 4

=item B

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.

=item B

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

truncating. Default value is 1.

=item B

Specify the path of the file containing private key to use during authorization.

By default libssh searches for keys in the F<~/.ssh/> directory.

=back

Example: Play a file stored on remote server.

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

=head2 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:

	://[:][/][/] 

where I is one of the strings "rtmp", "rtmpt", "rtmpe",

"rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and

I, I, I and I have the same

meaning as specified for the RTMP native protocol.

I contains a list of space-separated options of the form

I=I.

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

B:

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

To play the same stream using B:

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

=head2 rtp

Real-time Transport Protocol.

The required syntax for an RTP URL is:

rtp://I[:I][?I=I...]

I specifies the RTP port to use.

The following URL options are supported:

=over 4

=item BI

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

=item BI

Set the remote RTCP port to I.

=item BI

Set the local RTP port to I.

=item BIB<'>

Set the local RTCP port to I.

=item BI

Set max packet size (in bytes) to I.

=item B

Do a C on the UDP socket (if set to 1) or not (if set

to 0).

=item BIB<[,>IB<]>

List allowed source IP addresses.

=item BIB<[,>IB<]>

List disallowed (blocked) source IP addresses.

=item B

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).

=item BI

Set the local RTP port to I.

This is a deprecated option. Instead, B should be

used.

=back

Important notes:

=over 4

=item 1.

If B is not set the RTCP port will be set to the RTP

port value plus 1.

=item 2.

If B (the local RTP port) is not set any available

port will be used for the local RTP and RTCP ports.

=item 3.

If B (the local RTCP port) is not set it will be

set to the local RTP port value plus 1.

=back

=head2 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

EBE).

The required syntax for a RTSP url is:

	rtsp://[:]/