 tablet-encode - Transcoding video files for Nokia Internet Tablets
 ~~~~~~~~~~~~~   (c) Andrew Flegg 2006-2009.
 v2.30           Released under the Artistic Licence.
                 http://www.bleb.org/software/maemo/#encode

INTRODUCTION
 As the Nokia Internet Tablets have relatively slow processors, and relatively
 little storage space it is a good idea to "transcode" your videos to a smaller,
 more suitable format for watching them.
 
 Nokia's Internet Tablet Video Converter is by far the best GUI video converter
 for this task, however only runs on Windows. It is also sometimes useful to be
 able to convert videos on the command line. It is, of course, possible to
 use mencoder directly to get appropriately formatted videos, but making sure
 the output will work, without testing it, is a laborious process and involves
 remembering fairly long-winded command lines.
 
 tablet-encode can help with all these problems:
   * It runs on Linux, Mac OS X, Unix and Windows.
   * It guarantees the output to be playable on a Nokia Internet Tablet using
     a system of "profiles".
   * It can rip and encode DVDs in a single step (dependent on mencoder version)
   * It has a simple GUI available.
   * It has a command-line interface so it can be easily scripted to interface
     to your PVR (for example, MythTV, Freevo or VDR).
   * Presets allow tradeoff between space/quality to be decided on a per-video
     basis.
   * Can optimise video size for the Internet Tablet's 15:9 screen.
   * Handles anamorphic video sources such as widescreen DVDs.
   * Output works with either the built-in Media Player, or mplayer.
   * Audio and video streams are copied if they are lower quality than the
     selected preset, and compatible with the Nokia Internet Tablets.


DEPENDENCIES
 * mencoder   - http://www.mplayerhq.hu/
 * mplayer    - http://www.mplayerhq.hu/ (optional)
 * Gtk2::Perl - http://gtk2-perl.sourceforge.net/ (optional)
 * Perl       - see http://www.activestate.com/ for Windows version
 
 On a Debian or Ubuntu-based distribution, the dependencies can be met with:
 
     sudo apt-get install mencoder mplayer libgtk2-perl

 A good place to download mplayer and mencoder binaries for Windows is:
 
     http://oss.netfarm.it/mplayer-win32.php

USAGE
 1) Copy `tablet-encode' to a directory on your PATH, such as /usr/local/bin.
 2) Ensure you have mencoder installed (type `mencoder' on its own).
 3) Example commands:
 
    tablet-encode --help
    tablet-encode --preset list
    tablet-encode input.avi output.avi
    tablet-encode --list file1.avi file2.avi file3.avi
    tablet-encode --preset best input.avi output.avi
    tablet-encode --preset best dvd://1 dvd://2 dvd://3   media/

 As you can see from the above, there are a number of different ways of using
 tablet-encode, but the simplest is to give one existing movie (or URL) and
 the filename of the target:

     tablet-encode input.avi output.avi
     tablet-encode http://www.example.com/somefilm.mov output.avi
     tablet-encode dvd://1 output.avi

 The last of these has shown MPlayer's support for DVDs. tablet-encode will
 also auto-detect directories containing VIDEO_TS folders as DVDs, and
 if the title on the DVD is unspecified, the longest will be used:

     tablet-encode dvd: output.avi
     tablet-encode /media/dvd/ output.avi

 For TV series' DVDs, the '--episodes' option can be used. This will rip
 all episodes on the DVD within 10% of the middle-longest track (i.e. the
 median):
 
     tablet-encode --episodes dvd: /media/nokia-external/Video/

 A number of presets are available. If none is specified, it defaults to
 "average". A full list of the presets can be seen by passing `list' to the
 --preset option:

     tablet-encode --preset list

 If the target of the encoding is a directory, multiple input files can
 be specified:

     tablet-encode file1.avi file2.mov file3.wmv  output/

 There are many more options, a full listing is provided in the online help:

     tablet-encode --help

 Running tablet-encode with no parameters will start a GUI version, if
 possible. A GUI progress bar can be shown when specifying arguments with the
 `--gui' option. This requires the Gtk2-Perl bindings to be installed.


CONFIGURING
 The file `.tablet-encode.conf' will be read from your home directory at start
 up. In this file you can define your own presets, change the default preset
 used if none is specified and a few other things.
 
 To define your own preset, say "dvd", create ~/.tablet-encode.conf in your
 favourite editor and add the content:
 
   $PRESET{dvd} = { abitrate => 256, vbitrate => 800, width => 400 };
   
 This will define a preset called 'dvd' with an audio bitrate of 256kbps,
 a video bitrate of 800kbps and a maximum width of 400 pixels. The height is
 auto-calculated based on the tablet's screen and the size of the input video.
 
 To use the 'dvd' preset instead of 'average' when no preset is specified,
 add the following line to ~/.tablet-encode.conf:
 
   $defaultPreset = 'dvd';
 
 Note that this is a mini-Perl script, so blank lines and lines starting `#'
 will be ignored. All statements MUST end in a semi-colon, `;'.
 
 For Nokia 770 users, you may wish to always use 770-compatibility mode. To
 achieve this, in ~/.tablet-encode.conf put:
 
   $options{770} = 1;
 
 
TROUBLESHOOTING
 Some users have reported harsh, white-noise on the output. There are three
 possible solutions:
 
 1) Reconfigure mplayer to use the MAD audio decoder in preference to libmp3.
    See this post for more details:
      http://www.internettablettalk.com/forums/showthread.php?t=10471#post90550
      
 2) If the audio track is already MP3, use the --copy-audio option to leave the
    audio unprocessed (this should happen automatically, if the existing audio
    is compatible with the selected preset).
    
 3) If you are using a PowerPC Mac, try using a PowerPC-specific build of
    MPlayer, rather than a Universal binary. Similarly, some builds of MPlayer
    on PowerPC Linux have also reported the same problem; however upgrading to
    the latest MPlayer fixes that.


KNOWN BUGS
 * GUI is currently very basic. No support for selecting DVD tracks etc.


CHANGELOG
 v2.30 (07-Nov-2009)
    * Add subtitle support (provided by Claes Holmerson)
    * Ensure 48kHz MP3 audio streams are not copied, but transcoded (reported
      by spock)
    * Massively improve output quality (provided by takla)
    * Fix two-pass encoding.
    * Add very high quality "N900" preset.

 v2.20 (07-Sep-2008)
    * Fix support for VDR files with spaces in name.
    * Fix --episodes on ripped DVDs (reported by Wouter Lagerweij).
    * Fix use of exec() when doing final encoding.

 v2.19 (09-Jun-2008)
    * Fix bug when auto-identifying longest DVD title.
    * Fix mis-calculated median which will effect --episodes with low number
      of episodes + extra features on a DVD.
    * Add vrc_minrate as half output bitrate (suggested by Navi).
    * Better error reporting when mencoder is not installed or doesn't support
      appropriate codecs.
    * Fix GUI fatal error when trying to launch conversion (reported by
      Sebastiaan Lauwers).
    * Improve error reporting when using GUI.
 
 v2.18 (29-Mar-2008)
    * Handle bitrate reduction after mplayer fails to read bitrate
      correctly (provided by Mike Lococo)
    * Re-introduce 'mplayer' preset with very high bitrate (suggested by
      rm_you and GeneralAntilles)
    * Add --episodes option. When auto-detecting a DVD title to rip (i.e.
      the source is "dvd:"), all titles within 10% of the *median* will be
      ripped.
    * #1900: Add --770 option to improve Nokia 770 compatibility (reported by
      Marius Gedminas)
    * Add ability to add presets and change default preset using
      ~/.tablet-encode.conf.
    * #1760: Fix GUI problem on Mandriva 2008.0 (reported by divinerites).
    * Add support for Freevo FXD files, including --episodes for all videos
      defined in a video.
    * Recognise direct VOB access and turn into 'dvd:' (reported by
      GeneralAntilles).

 v2.17 (09-Mar-2008)
    * Use /dev/null and a named log file when in two-pass mode (suggested by
      Dave Coutts).
    * When using DVD auto-detection, select language based on first key in
      $LANG (requested by Luca Olivetti and Brad Midgley).

 v2.16 (15-Dec-2007)
    * Make --help work again when GUI is available (reported by Marius Scurtescu
      and Riptorn).
    
 v2.15 (11-Dec-2007)
    * Add an initial basic GUI version (requires Gtk2+ Perl bindings).
    * Improve identification of VDR recordings (provided by Luca Olivetti).
    * Don't upscale videos smaller than the preset (reported by Tesiph).
    * When listing presets, include details on output quality (suggested by
      Corey Wright).

 v2.10 (02-Dec-2007)
    * --mencoder arguments weren't passed through when getting media info
      (reported by Stefano Z.)
    * Fix "argument ... is not numeric" warning when checking audio type
      of QuickTime videos.
    * Add detection of DVD directories & configure mencoder appropriately
      (requested by Peter Flynn).
    * Overhaul presets (thanks to czr).
    * Add support for VDR recording directories (requested by Luca Olivetti).
    * Remove "experimental" mencoder options.
    * Add sharpening filter to output.
    * Remove '-noidx' option and use FMP4 FOURCC to get better performance
      (thanks to Jeff Elkins and Frederic Crozat).
    * Fix superfluous prints when using --quiet.
    * Auto-detect longest DVD track when 'dvd:' or 'dvd://' are specified as
      inputs (requires mplayer).

 v2.00 (17-Nov-2007)
    * Rename to tablet-encode.
    * Include optional "vrcbufsize" and "vrcmaxrate" (suggested by sveinan).
    * Limit video bitrate to maximum of preset and equivalent bitrate of
      original file, when applicable (provided by Benjamin R�veill�).
    * Do the same for audio (suggested by mplawner).
    * Modify "--sample" option to allow to chose sample length (provided by
      Benjamin R�veill�).
    * Add "--index" option to force index generation (provided by Benjamin
      R�veill�).
    * Add "--list" option to allow processing multiple files (provided by
      Benjamin R�veill�).
    * Add support for command lines like `cp', so that multiple files and a
      directory can be specified.
    * Bump up quality on good/best/mplayer presets.

 v1.36 (22-Oct-2007)
    * Fix bug when only mp3lame available (reported by Ryan Abel)

 v1.35 (26-Sep-2006)
    * Allow presets to specify a height to encode for, rather than a width.
    * Make `mplayer' preset maximum height at 240 and increase max fps
      (suggested by ssvb).

 v1.34 (21-Sep-2006)
    * Win32 Perl can have weird effects, try to avoid.

 v1.33 (21-Aug-2006)
    * Add "mplayer" preset for https://garage.maemo.org/projects/mplayer/
    * Fix broken support for Windows (duh)

 v1.32 (30-Jul-2006)
    * Add new maximum frame rate, and allow presets to override.
    * Change "best" for maximum framerate.
    * Add support for ActiveState's Perl.

 v1.31 (05-Jul-2006)
    * Fix bug which resulted in incorrect resolution on very wide
      sources (e.g. 2.35:1 films)

 v1.30 (26-May-2006)
    * Add support for anamorphic data sources (e.g. DVDs)
    * Add ability to pass through options to mencoder, for example:
           770-encode -m-aid -m128 dvd://4 mydvd.avi

 v1.21 (19-May-2006)
    * Add volume normalisation flag (suggested by Neil Jerram)
 
 v1.20 (15-May-2006)
    * Fix bug with rounding when optimising wider inputs
    * Add two presets ("average" and "good"), with thanks to varis
    * Add "--sample" option (suggested by varis)

 v1.11 (12-May-2006)
    * Enhance "smallest" to better fit 770 screen
    * Add "small" preset
    * Fix cropping which just didn't work in some instances

 v1.10 (07-May-2006)
    * More intelligent cropping.
    * Fall back to lavc MP3 encoder if mp3lame not present
    * Die if lavc isn't present
    * Suppress "Skipping frame!" messages from mencoder

 v1.05 (03-May-2006)
    * Make handle FLV files' dodgy framerate

 v1.00 (08-Apr-2006)
    * Initial version: first 770-based media encoder aimed to:
         a) Guarantee playable video
         b) Use presets
         c) Provide "optimised video"


COPYRIGHT
 (c) Andrew Flegg 2006, 2007. Released under the Artistic Licence.

