encode: video encoding now supported using mencoder-like options

5 files changed, 470 insertions, 4 deletions

diff --git a/DOCS/encoding.rst b/DOCS/encoding.rst
new file mode 100644
index 0000000000..67ad19bae6
--- /dev/null
+++ b/DOCS/encoding.rst
@@ -0,0 +1,141 @@
+General usage
+=============
+
+::
+
+  mplayer infile -o outfile [-of outfileformat] [-ofopts formatoptions] \
+    [-ofps outfps | -oautofps] [-oharddup] [-ocopyts | -orawts] [-oneverdrop] \
+    [(any other mplayer options)] \
+    -ovc outvideocodec [-ovcopts outvideocodecoptions] \
+    -oac outaudiocodec [-oacopts outaudiocodecoptions]
+
+Help for these options is provided if giving help as parameter, as in::
+
+  mplayer -ovc help
+
+The suboptions of these generally are identical to ffmpeg's (as option parsing
+is simply delegated to ffmpeg). The option -ocopyts enables copying timestamps
+from the source as-is, instead of fixing them to match audio playback time
+(note: this doesn't work with all output container formats); -orawts even turns
+off discontinuity fixing.
+
+Note that if neither -ofps nor -oautofps is specified, VFR encoding is assumed
+and the time base is 24000fps. -oautofps sets -ofps to a guessed fps number
+from the input video. Note that not all codecs and not all formats support VFR
+encoding, and some which do have bugs when a target bitrate is specified - use
+-ofps or -oautofps to force CFR encoding in these cases.
+
+Of course, the options can be stored in a profile, like this .mplayer/config
+section::
+
+  [myencprofile]
+  vf-add = scale=480:-2
+  ovc = libx264
+  ovcopts-add = preset=medium,tune=fastdecode
+  ovcopts-add = crf=23
+  ovcopts-add = maxrate=1500k,bufsize=1000k,rc_init_occupancy=900k,refs=2
+  ovcopts-add = profile=baseline
+  oac = aac
+  oacopts-add = b=96k
+
+One can then encode using this profile using the command::
+
+  mplayer infile -o outfile.mp4 -profile myencprofile
+
+Some example profiles are provided in a file
+etc/encoding-example-profiles.conf; as for this, see below.
+
+
+Encoding examples
+=================
+
+These are some examples of encoding targets this code has been used and tested
+for.
+
+Typical MPEG-4 Part 2 ("ASP", "DivX") encoding, AVI container::
+
+  mplayer infile -o outfile.avi \
+    -ofps 25 \
+    -ovc mpeg4 -ovcopts qscale=4 \
+    -oac libmp3lame -oacopts ab=128k
+
+Note: AVI does not support variable frame rate, so -ofps must be used. The
+frame rate should ideally match the input (25 for PAL, 24000/1001 or 30000/1001
+for NTSC)
+
+Typical MPEG-4 Part 10 ("AVC", "H.264") encoding, Matroska (MKV) container::
+
+  mplayer infile -o outfile.mkv \
+    -ovc libx264 -ovcopts preset=medium,crf=23,profile=baseline \
+    -oac vorbis -oacopts qscale=3
+
+Typical MPEG-4 Part 10 ("AVC", "H.264") encoding, MPEG-4 (MP4) container::
+
+  mplayer infile -o outfile.mp4 \
+    -ovc libx264 -ovcopts preset=medium,crf=23,profile=baseline \
+    -oac aac -oacopts ab=128k
+
+Typical VP8 encoding, WebM (restricted Matroska) container::
+
+  mplayer infile -o outfile.mkv \
+    -of webm \
+    -ovc libvpx -ovcopts qmin=6,b=1000000k \
+    -oac libvorbis -oacopts qscale=3
+
+
+Device targets
+==============
+
+As the options for various devices can get complex, profiles can be used.
+
+An example profile file for encoding is provided in
+etc/encoding-example-profiles.conf in the source tree. You can include it into
+your configuration by doing, from the mplayer2-build directory::
+
+  mkdir -p ~/.mplayer
+  echo "include = $PWD/mplayer/etc/encoding-example-profiles.conf" >> ~/.mplayer/config
+
+Refer to the top of that file for more comments - in a nutshell, the following
+options are added by it::
+
+  -profile enc-to-dvdpal      DVD-Video PAL, use dvdauthor -v pal+4:3 -a ac3+en
+  -profile enc-to-dvdntsc     DVD-Video NTSC, use dvdauthor -v ntsc+4:3 -a ac3+en
+  -profile enc-to-bb-9000     MP4 for Blackberry Bold 9000
+  -profile enc-to-nok-6300    3GP for Nokia 6300
+  -profile enc-to-psp         MP4 for PlayStation Portable
+  -profile enc-to-iphone      MP4 for iPhone
+  -profile enc-to-iphone4     MP4 for iPhone 4 (double res)
+
+You can encode using these with a command line like::
+
+  mplayer infile -o outfile.mp4 -profile enc-to-bb-9000
+
+Of course, you are free to override options set by these profiles by specifying
+them after the -profile option.
+
+
+What works
+==========
+
+* Encoding at variable frame rate (default)
+* Encoding at constant frame rate using -ofps framerate -oharddup
+* 2-pass encoding (specify flags=+pass1 in the first pass's -ovcopts, specify
+  flags=+pass2 in the second pass)
+* Hardcoding subtitles using vobsub, ass or srt subtitle rendering (just
+  configure mplayer for the subtitles as usual)
+* Hardcoding any other mplayer OSD (e.g. time codes, using -osdlevel 3 and -vf
+  expand=::::1)
+* Encoding directly from a DVD, network stream, webcam, or any other source
+  mplayer supports
+* Using x264 presets/tunings/profiles (by using profile=, tune=, preset= in the
+  -ovcopts)
+* Deinterlacing/Inverse Telecine with any of mplayer's filters for that
+* Audio file converting: mplayer -o outfile.mp3 infile.flac -novideo -oac
+  libmp3lame -oacopts ab=320k
+* inverse telecine filters (confirmed working: detc, pullup, filmdint)
+
+What does not work yet
+
+* 3-pass encoding (ensuring constant total size and bitrate constraints while
+  having VBR audio; mencoder calls this "frameno")
+* Direct stream copy
diff --git a/DOCS/man/en/changes.rst b/DOCS/man/en/changes.rst
index e4f331e807..c4fc3a0812 100644
--- a/DOCS/man/en/changes.rst
+++ b/DOCS/man/en/changes.rst
@@ -63,6 +63,7 @@ General changes for mplayer2 to mplayer3
 * Do not lose settings when playing a new file in the same player instance
 * New location for config files, new name for the binary. (Planned change.)
 * Slave mode compatibility broken (see below)
+* Encoding functionality (replacement for mencoder)
 * General code cleanups
 * Many more changes
 
diff --git a/DOCS/man/en/encode.rst b/DOCS/man/en/encode.rst
new file mode 100644
index 0000000000..7ebd8e6c01
--- /dev/null
+++ b/DOCS/man/en/encode.rst
@@ -0,0 +1,134 @@
+.. _encode:
+
+ENCODING
+========
+
+You can encode files from one format/codec to another using this facility.
+
+-o <filename>
+    Enables encoding mode and specifies the output file name.
+
+--of=<format>
+    Specifies the output format (overrides autodetection by the extension of
+    the file specified by -o).
+    See --of=help for a full list of supported formats.
+
+--ofopts=<options>
+    Specifies the output format options for libavformat.
+    See --ofopts=help for a full list of supported options.
+
+    Options are managed in lists. There are a few commands to manage the
+    options list.
+
+    --ofopts-add=<options1[,options2,...]>
+        Appends the options given as arguments to the options list.
+
+    --ofopts-pre=<options1[,options2,...]>
+        Prepends the options given as arguments to the options list.
+
+    --ofopts-del=<index1[,index2,...]>
+        Deletes the options at the given indexes. Index numbers start at 0,
+        negative numbers address the end of the list (-1 is the last).
+
+    --ofopts-clr
+        Completely empties the options list.
+
+--ofps=<float value>
+    Specifies the output format time base (default: 24000). Low values like 25
+    limit video fps by dropping frames.
+
+--oautofps
+    Sets the output format time base to the guessed frame rate of the input
+    video (simulates mencoder behaviour, useful for AVI; may cause frame
+    drops). Note that not all codecs and not all formats support VFR
+    encoding, and some which do have bugs when a target bitrate is
+    specified - use --ofps or --oautofps to force CFR encoding in these
+    cases.
+
+--oharddup
+    If set, the frame rate given by --ofps is attained not by skipping time
+    codes, but by duplicating frames (constant frame rate mode).
+
+--oneverdrop
+    If set, frames are never dropped. Instead, time codes of video are
+    readjusted to always increase. This may cause AV desync, though; to
+    work around this, use a high-fps time base using --ofps and absolutely
+    avoid --oautofps.
+
+--oac=<codec>
+    Specifies the output audio codec.
+    See --oac=help for a full list of supported codecs.
+
+--oaoffset=<value>
+    Shifts audio data by the given time (in seconds) by adding/removing
+    samples at the start.
+
+--oacopts=<options>
+    Specifies the output audio codec options for libavcodec.
+    See --oacopts=help for a full list of supported options.
+
+    EXAMPLE: "--oac=libmp3lame --oacopts=b=128000" selects 128kbps MP3
+    encoding.
+
+    Options are managed in lists. There are a few commands to manage the
+    options list.
+
+    --oacopts-add=<options1[,options2,...]>
+        Appends the options given as arguments to the options list.
+
+    --oacopts-pre=<options1[,options2,...]>
+        Prepends the options given as arguments to the options list.
+
+    --oacopts-del=<index1[,index2,...]>
+        Deletes the options at the given indexes. Index numbers start at 0,
+        negative numbers address the end of the list (-1 is the last).
+
+    --oacopts-clr
+        Completely empties the options list.
+
+--ovc=<codec>
+    Specifies the output video codec.
+    See --ovc=help for a full list of supported codecs.
+
+--ovoffset=<value>
+    Shifts video data by the given time (in seconds) by shifting the pts
+    values.
+
+--ocopyts
+    Copies input pts to the output video (not supported by some output
+    container formats, e.g. avi). Discontinuities are still fixed.
+    By default, audio pts are set to playback time and video pts are
+    synchronized to match audio pts, as some output formats do not support
+    anything else.
+
+--orawts
+    Copies input pts to the output video (not supported by some output
+    container formats, e.g. avi). In this modem discontinuities are not fixed
+    and all pts are passed through as-is. Never seek backwards or use multiple
+    input files in this mode!
+
+--ovcopts <options>
+    Specifies the output video codec options for libavcodec.
+    See --ovcopts=help for a full list of supported options.
+
+    EXAMPLE: "--ovc=mpeg4 --oacopts=qscale=5" selects constant quantizer scale
+    5 for MPEG-4 encoding.
+
+    EXAMPLE: "--ovc=libx264 --ovcopts=crf=23" selects VBR quality factor 23 for
+    H.264 encoding.
+
+    Options are managed in lists. There are a few commands to manage the
+    options list.
+
+    --ovcopts-add=<options1[,options2,...]>
+        Appends the options given as arguments to the options list.
+
+    --ovcopts-pre=<options1[,options2,...]>
+        Prepends the options given as arguments to the options list.
+
+    --ovcopts-del=<index1[,index2,...]>
+        Deletes the options at the given indexes. Index numbers start at 0,
+        negative numbers address the end of the list (-1 is the last).
+
+    --ovcopts-clr
+        Completely empties the options list.
diff --git a/DOCS/man/en/mplayer-old.1 b/DOCS/man/en/mplayer-old.1
index 477244cc58..92592c7f27 100644
--- a/DOCS/man/en/mplayer-old.1
+++ b/DOCS/man/en/mplayer-old.1
@@ -6707,7 +6707,7 @@ This will give much better results for material that has undergone
 heavy editing after telecine was applied, but as a result it is not as
 forgiving of noisy input, for example TV capture.
 The optional parameter (ivtc=1) corresponds to the dr=1 option for the
-detc filter, and should not be used with MPlayer.
+detc filter, and should not be used for playback.
 Further development on ivtc has stopped, as the pullup and filmdint
 filters appear to be much more accurate.
 .
@@ -6765,9 +6765,6 @@ access to the field-flags set by the MPEG-2 decoder.
 Depending on the source MPEG, you may be fine ignoring this advice, as
 long as you do not see lots of "Bottom-first field" warnings.
 With no options it does normal inverse telecine.
-When this filter is used with MPlayer, it will result in an uneven
-framerate during playback, but it is still generally better than using
-pp=lb or no deinterlacing at all.
 Multiple options can be specified separated by /.
 .RSs
 .IPs crop=<w>:<h>:<x>:<y>
@@ -7510,6 +7507,197 @@ Using this filter together with any sort of seeking (including -ss and EDLs)
 may make demons fly out of your nose.
 .RE
 .
+.\" --------------------------------------------------------------------------
+.\" encoding
+.\" --------------------------------------------------------------------------
+.
+.SH ENCODING OPTIONS
+.
+.TP
+.B \-o <filename>
+Enable encoding mode and specify the output file name.
+.RE
+.
+.TP
+.B \-of <format>
+Specify the output format (overrides autodetection by the extension of the file specified by \-o).
+See \-of help for a full list of supported formats.
+.RE
+.
+.TP
+.B \-ofopts <options>
+Specify the output format options for libavformat.
+See \-ofopts help for a full list of supported options.
+.RE
+.PP
+.I NOTE:
+To get a full list of available format options, see \-ofopts help.
+.sp 1
+Options are managed in lists.
+There are a few commands to manage the options list.
+.
+.TP
+.B \-ofopts\-add <option1[,option2,...]>
+Appends the options given as arguments to the options list.
+.
+.TP
+.B \-ofopts\-pre <option1[,option2,...]>
+Prepends the options given as arguments to the options list.
+.
+.TP
+.B \-ofopts\-del <index1[,index2,...]>
+Deletes the options at the given indexes.
+Index numbers start at 0, negative numbers address the end of the
+list (\-1 is the last).
+.
+.TP
+.B \-ofopts\-clr
+Completely empties the options list.
+.
+.RE
+.
+.TP
+.B \-ofps <float value>
+Specifies the output format time base (default: 24000). Low values like 25 limit video fps by dropping frames.
+.RE
+.
+.TP
+.B \-oautofps
+Sets the output format time base to the guessed frame rate of the input video (simulates mencoder behaviour, useful for AVI; may cause frame drops). Note that not all codecs and not all formats support VFR encoding, and some which do have bugs when a target bitrate is specified - use
+.B \-ofps
+or
+.B \-oautofps
+to force CFR encoding in these cases.
+.RE
+.
+.TP
+.B \-oharddup
+If set, the frame rate given by
+.B \-ofps
+is attained not by skipping time codes, but by duplicating frames (constant frame rate mode).
+.RE
+.
+.TP
+.B \-oneverdrop
+If set, frames are never dropped. Instead, time codes of video are readjusted
+to always increase. This may cause AV desync, though; to work around this,
+use a high-fps time base using
+.B \-ofps
+and absolutely avoid
+.B \-oautofps
+.RE
+.
+.TP
+.B \-oac <codec>
+Specify the output audio codec.
+See \-oac help for a full list of supported codecs.
+.RE
+.
+.TP
+.B \-oaoffset <value>
+Shifts audio data by the given time (in seconds) by adding/removing samples at the start.
+.RE
+.
+.TP
+.B \-oacopts <options>
+Specify the output audio codec options for libavcodec.
+See \-oacopts help for a full list of supported options.
+.RE
+.PP
+.I EXAMPLE:
+.B \-oac libmp3lame \-oacopts b=128000
+selects 128kbps MP3 encoding.
+.PP
+.I NOTE:
+To get a full list of available audio codec options, see \-oacopts help.
+.sp 1
+Options are managed in lists.
+There are a few commands to manage the options list.
+.
+.TP
+.B \-oacopts\-add <option1[,option2,...]>
+Appends the options given as arguments to the options list.
+.
+.TP
+.B \-oacopts\-pre <option1[,option2,...]>
+Prepends the options given as arguments to the options list.
+.
+.TP
+.B \-oacopts\-del <index1[,index2,...]>
+Deletes the options at the given indexes.
+Index numbers start at 0, negative numbers address the end of the
+list (\-1 is the last).
+.
+.TP
+.B \-oacopts\-clr
+Completely empties the options list.
+.
+.TP
+.B \-ovc <codec>
+Specify the output video codec.
+See \-ovc help for a full list of supported codecs.
+.RE
+.
+.TP
+.B \-ovoffset <value>
+Shifts video data by the given time (in seconds) by shifting the pts values.
+.RE
+.
+.TP
+.B \-ocopyts
+Copies input pts to the output video (not supported by some output container formats, e.g. avi).
+By default, audio pts are set to playback time and video pts are synchronized to match audio pts, as some output formats do not support anything else.
+.RE
+.
+.TP
+.B \-ovcopts <options>
+Specify the output video codec options for libavcodec.
+See \-ovcopts help for a full list of supported options.
+.RE
+.PP
+.I EXAMPLE:
+.B \-ovc mpeg4 \-ovcopts qscale=5
+selects constant quantizer scale 5 for MPEG-4 encoding.
+.PP
+.B \-ovc libx264 \-ovcopts crf=23
+selects VBR quality factor 23 for H.264 encoding.
+.I NOTE:
+To get a full list of available video codec options, see \-ovcopts help.
+.PP
+.sp 1
+Options are managed in lists.
+There are a few commands to manage the options list.
+.
+.TP
+.B \-ovcopts\-add <option1[,option2,...]>
+Appends the options given as arguments to the options list.
+.
+.TP
+.B \-ovcopts\-pre <option1[,option2,...]>
+Prepends the options given as arguments to the options list.
+.
+.TP
+.B \-ovcopts\-del <index1[,index2,...]>
+Deletes the options at the given indexes.
+Index numbers start at 0, negative numbers address the end of the
+list (\-1 is the last).
+.
+.TP
+.B \-ovcopts\-clr
+Completely empties the options list.
+.
+.PP
+.I NOTE for \-ovc libx264:
+The x264 codec provides a set of presets/tunings/profiles which can be included with the ovcopts.
+.PP
+Available presets: preset=ultrafast, preset=superfast, preset=veryfast, preset=faster, preset=fast, preset=medium, preset=slow, preset=slower, preset=veryslow, preset=placebo (default: preset=medium)
+.PP
+Available tunings: tune=film, tune=animation, tune=grain, tune=stillimage, tune=psnr, tune=ssim, tune=fastdecode, tune=zerolatency (default: none)
+.PP
+Available profiles: profile=baseline, profile=main, profile=high (default: profile=high)
+.PP
+.I EXAMPLE:
+.B mplayer \-o <outfile> <infile> \-ovc libx264 \-ovcopts preset=veryslow,crf=23,tune=animation,profile=main \-oac aac \-oacopts b=128000
 .
 .\" --------------------------------------------------------------------------
 .\" environment variables
diff --git a/DOCS/man/en/mplayer.rst b/DOCS/man/en/mplayer.rst
index 8485ee7064..89b03737c3 100644
--- a/DOCS/man/en/mplayer.rst
+++ b/DOCS/man/en/mplayer.rst
@@ -407,6 +407,8 @@ OPTIONS
 
 .. include:: vf.rst
 
+.. include:: encode.rst
+
 Taking screenshots
 ==================