encode: video encoding now supported using mencoder-like options

1 files changed, 141 insertions, 0 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