[PATCH 1/2] Add protocols.texi.

[Stefano Sabatini]

---
 Makefile             |    6 +-
 doc/ffmpeg-doc.texi  |   14 +----
 doc/ffplay-doc.texi  |    1 +
 doc/ffprobe-doc.texi |    1 +
 doc/protocols.texi   |  191 ++++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 197 insertions(+), 16 deletions(-)
 create mode 100644 doc/protocols.texi

diff --git a/Makefile b/Makefile
index 09dc424..68c9663 100644
--- a/Makefile
+++ b/Makefile
@@ -115,9 +115,9 @@ documentation: $(addprefix doc/, developer.html faq.html general.html libavfilte
 
 $(HTMLPAGES) $(MANPAGES): doc/fftools-common-opts.texi
 
-doc/ffmpeg.pod doc/ffmpeg-doc.html: doc/indevs.texi doc/filters.texi doc/outdevs.texi
-doc/ffplay.pod doc/ffplay-doc.html: doc/indevs.texi doc/filters.texi doc/outdevs.texi
-doc/ffprobe.pod doc/ffprobe-doc.html: doc/indevs.texi
+doc/ffmpeg.pod doc/ffmpeg-doc.html: doc/indevs.texi doc/filters.texi doc/outdevs.texi doc/protocols.texi
+doc/ffplay.pod doc/ffplay-doc.html: doc/indevs.texi doc/filters.texi doc/outdevs.texi doc/protocols.texi
+doc/ffprobe.pod doc/ffprobe-doc.html: doc/indevs.texi doc/protocols.texi
 
 doc/%.html: TAG = HTML
 doc/%.html: doc/%.texi
diff --git a/doc/ffmpeg-doc.texi b/doc/ffmpeg-doc.texi
index a4330cf..ccf06b5 100644
--- a/doc/ffmpeg-doc.texi
+++ b/doc/ffmpeg-doc.texi
@@ -745,19 +745,6 @@ The following constants are available:
 
 @c man end
 
- at section Protocols
-
-The file name can be @file{-} to read from standard input or to write
-to standard output.
-
-FFmpeg also handles many protocols specified with an URL syntax.
-
-Use 'ffmpeg -protocols' to see a list of the supported protocols.
-
-The protocol @code{http:} is currently used only to communicate with
-FFserver (see the FFserver documentation). When FFmpeg will be a
-video player it will also be used for streaming :-)
-
 @chapter Tips
 @c man begin TIPS
 
@@ -966,6 +953,7 @@ file to which you want to add them.
 
 @include indevs.texi
 @include outdevs.texi
+ at include protocols.texi
 @include filters.texi
 
 @ignore
diff --git a/doc/ffplay-doc.texi b/doc/ffplay-doc.texi
index a55f30c..d761f13 100644
--- a/doc/ffplay-doc.texi
+++ b/doc/ffplay-doc.texi
@@ -155,6 +155,7 @@ Seek to percentage in file corresponding to fraction of width.
 
 @include indevs.texi
 @include outdevs.texi
+ at include protocols.texi
 @include filters.texi
 
 @ignore
diff --git a/doc/ffprobe-doc.texi b/doc/ffprobe-doc.texi
index 6792603..6d2d855 100644
--- a/doc/ffprobe-doc.texi
+++ b/doc/ffprobe-doc.texi
@@ -105,6 +105,7 @@ with name ``STREAM''.
 @end table
 @c man end
 
+ at include protocols.texi
 @include indevs.texi
 
 @ignore
diff --git a/doc/protocols.texi b/doc/protocols.texi
new file mode 100644
index 0000000..0843a0a
--- /dev/null
+++ b/doc/protocols.texi
@@ -0,0 +1,191 @@
+ at chapter Protocols
+ at c man begin PROTOCOLS
+
+Protocols are configured elements in FFmpeg which allow to access
+resources which require the use of a particular protocol.
+
+When you configure your FFmpeg build, all the supported protocols
+are enabled by default. You can list them 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=@var{PROTOCOL}", or you can disable a
+particular protocol using the option
+"--disable-protocol=@var{PROTOCOL}".
+
+The option "-protocols" of the ff* tools will display the list of
+the supported protocols.
+
+A description of the currently available protocols follows.
+
+ at section concat
+
+Physical concatenation protocol.
+
+Allow to read and seek from many files in sequence as they were an
+unique file.
+
+An url accepted by this protocol has the syntax:
+ at example
+concat:@var{FILE1}|@var{FILE2}|...|@var{FILEN}
+ at end example
+
+where @var{FILE1}, @var{FILE2}, ..., @var{FILEN} are the files to be
+concatenated.
+
+For example to read a sequence of files @file{split1.mpeg}, @file{split2.mpeg},
+ at file{split3.mpeg} with @file{ffplay} use the command:
+ at example
+ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg
+ at end example
+
+Note that you may need to escape the character "|" which is special for
+many shells.
+
+ at section file
+
+File access protocol.
+
+Allow to read from or read to a file.
+
+For example to read from a file @file{input.mpeg} with @file{ffmpeg}
+use the command:
+ at example
+ffmpeg -i file:input.mpeg output.mpeg
+ at end example
+
+Note that if not specified otherwise, the ff* tools will use the file
+protocol by default, that is a resource specified with the name
+"FILE.mpeg" is interpreted as it were the url "file:FILE.mpeg".
+
+ at section gopher
+
+Gopher protocol.
+
+ at section http
+
+HTTP (Hyper Text Trasfer Protocol).
+
+ at section mmst
+
+MMS (Microsoft Media Server) protocol over TCP.
+
+Only input supported.
+
+ at section md5
+
+MD5 output protocol.
+
+Computes the MD5 hash of data 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.
+ at example
+# write the MD5 hash of the encoded AVI file in 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:
+ at end example
+
+Note that some formats (typically mov), require the output protocol to
+be seekable, so they will fail with the MD5 output protocol.
+
+ at section pipe
+
+UNIX pipe access protocol.
+
+Allow to read and write from UNIX pipes.
+
+The accepted syntax is:
+ at example
+pipe:[@var{number}]
+ at end example
+
+ at var{number} is the number corresponding to the file descriptor of the
+pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr).
+If @var{number} is not specified will use by default stdout if the
+protocol is used for writing, stdin if the protocol is used for
+reading.
+
+For example to read from stdin with @file{ffmpeg}:
+ at example
+cat test.wav | ffmpeg -i pipe:0
+# this is the same as
+cat test.wav | ffmpeg -i pipe:
+ at end example
+
+For writing to stdout using with @file{ffmpeg}:
+ at example
+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
+ at end example
+
+Note that some formats (typically mov), require the output protocol to
+be seekable, so they will fail with the pipe output protocol.
+
+ at section rtmp
+
+Real-Time Multimedia Protocol.
+
+The required syntax is:
+ at example
+rtmp://@var{server}[:@var{port}][/@var{app}][/@var{playpath}]
+ at end example
+
+Follows the description of the accepted parameters.
+ at table @option
+
+ at item server
+It is the address of RTMP server.
+
+ at item port
+It is the number of the TCP port to use (by default is 1935).
+
+ at item app
+It is the name of the application to be accessed, and corresponds to
+the first one or two directories in the path for the resources to be
+played (e.g. @file{/ondemand/}, @file{/flash/live/}, etc.).
+
+ at item playpath
+It is the name of the resource to be accessed in the namespace of the
+application specified in @var{app},  be prefixed with "mp4:".
+
+ at end table
+
+For example to read with @file{ffplay} a multimedia resource named
+"sample" from the application "vod" from an RTMP server "example.com":
+ at example
+ffplay rtmp://example.com/vod/sample
+ at end example
+
+ at section rtmp, rtmpe, rtmps, rtmpt, rtmpte
+
+Support Real-Time Multimedia Protocol and its variants RTMPS
+(Real-Time Multimedia Protocol with SSL encryption), RTMPT (Real-Time
+Multimedia Protocol with HTTP Tunnelling), RTMPTE (Real-Time
+Multimedia Protocol with Encryption and HTTP Tunnelling) through
+librtmp.
+
+Require the presence of the headers and library of librtmp during
+configuration. You need to explicitely configure the build with
+"--enable-librtmp". If enabled it will replace the native RTMP
+protocol.
+
+ at section rtp
+
+Real Time Protocol.
+
+ at section tcp
+
+Trasmission Control Protocol.
+
+ at section udp
+
+User Datagram Protocol.
+
+ at c man end PROTOCOLS
+
-- 
1.7.0.4


--cvVnyQ+4j833TQvp--