2bppconv: README (for the "improved" version, patched by Zach
Brewster-Geisz based on Adam Johnston's original)

2bppconv takes .avi files created by mencoder 
(http://www.mplayerhq.hu/) in BGR24 or BGR32 format, as detailed at 
http://ipodlinux.org/Video_Player, and converts them to 2-bit
grayscale files which can be played on grayscale iPods, such as the
1G-3G iPods and the iPod Mini.  Note that you will need to have Linux
installed on your iPod to do this--if you don't know what that means,
stop right now.

The original version of 2bppconv converted directly to the four grays
that the iPod's screen supported.  This version implements a
pattern-based dither which allows 16 perceived shades of gray, and a
random-based dither which allows smooth gradiation from white to black
(at the expense of a "snowy" picture).

In addition, videos with low contrast will be normalized to use the
iPod's full dynamic range.  This normalization is user-configurable.

As of 6 December 2005, 2bppconv has only been tested on Mac OS X
10.3.9, but it should compile without any problems on Linux and,
presumably, Windows under Cygwin.

Invoking this version of 2bppconv is exactly the same as the previous
version, so there is no need to update your shell-scripts, etc. unless
you want the added functionality.

*However*, there is one major change you should make if you are on Mac
 OS X: when encoding the original movie in mencoder, you should encode
 to bgr32, *not* bgr24, as mencoder doesn't encode bgr24 correctly on
 Mac OS X (at least in the current release and CVS).  You can also
 encode this way on other platforms if you like.

Read on for the various command-line options.

Invocation is simply: 2bppconv [-k] [-f <floor>] [-c <ceiling] [-d]
			       [-r] <infile.avi> <outfile.avi>

-k : When mencoder encodes to iPod Mini resolution (138x110)
     it introduces artifacts which (for example) make a straight
     vertical line look like a sawtooth.  Use -k (for "kludge") to fix
     these jaggies.  Should never be neccesary with other iPods.
-f : Specifies the floor luminance value, below which all luminance
     will be pure white (0 is pure white on grayscale iPods).  Can be
     any integer between 0 and 127.  If you append a '!' to the
     number, the floor will be forced to this value for every frame
     (by default the floor is computed dynamically on a per-frame
     basis, with your value as an absolute limit).  Defaults to 0.
-c : Specifies the ceiling luminance value, above which all luminance
     will be pure black (255 is pure black on grayscale iPods).  Can
     be any integer between 128 and 255.  If you append a '!' to the
     number, the floor will be forced to this value for every frame
     (by default the floor is computed dynamically on a per-frame
     basis, with your value as an absolute limit).  Defaults to 224.
-r : The default dither for 2bppconv is a pattern-based dither which
     allows 16 perceived levels of gray.  Use -r to change to a
     random-based dither which allows 256 (theoretical) levels of
     gray.  A side effect is noise, like a TV set with broken rabbit
     ears.
-d : By default, dithering is enabled.  If you want to turn it off,
     use -d.
-i : First generation iPods invert their colors when the backlight is
     on (or so I'm told).  Use -i to invert the movie's colors so you
     can watch it with the backlight.  (This encodes an inverted
     movie--it does *not* autodetect when your backlight is on!)

Examples:

To encode a graysale movie for the iPod Mini on Mac OS X:

	  mencoder -ovc raw -ofps 15 -oac pcm -vf \
	      scale=138:-2,expand=138:110,format=bgr32 in.avi -o out.avi
	  2bppconv -k out.avi ipodmovie.avi

(Note that on Linux, you should *not* invoke -k, at least I don't
think so.)

To encode a grayscale movie for any other grayscale iPod:

	  mencoder -ovc raw -ofps 15 -oac pcm -vf \
	     scale=160:-2,expand=160:128,format=bgr32 in.avi -o out.avi
	  2bppconv out.avi ipodmovie.avi

If your movie doesn't appear dark enough, try lowering the ceiling:

	  2bppconv -c 192 out.avi ipodmovie.avi

Likewise, if it's too dark, try raising the ceiling to 255 and raising
the floor:

	  2bppconv -f 24 -c 255 out.avi ipodmovie.avi

(Note that in most cases, the value 255 will _always_ be present in
your movie, because of the black bars added by the "expand" filter in
mencoder.  This is why 224 is the default ceiling, not 255.)

If the pattern-based dither annoys you, or you prefer more subtle
shades of gray, try the random-based dither:

          2bppconv -r out.avi ipodmovie.avi

Finally, if you prefer the old-style 2bppconv look, the following
invocation (no dither, floor forced to 0, ceiling forced to 192)
approximates it:

	  2bppconv -d -f 0! -c 192! out.avi ipodmovie.avi

2bppconv is released under the GNU GPL.  I'm indebted to Adam Johnston
and Jeffrey Nelson for doing most of the heavy lifting on the program.

Zach Brewster-Geisz, 6 December 2005
zach@brewstergeisz.cjb.net