README for the TOOLS directory
=============================

1. Preamble
-----------

In this directory you can find some nice scripts and code that makes
using MPlayer and MEncoder easier, for example scripts for DVD track
encoding in 3-pass mode or creating SVCDs from a movie.

2. Shell scripts in TOOLS dir
------------------------------

2.1 divx2svcd
        Author:         Miklos Vajna

        Description:    A simple utility that creates a SVCD from a video in an
                        AVI container

        Usage:          'divx2svcd input_avi [options]'
                        see 'divx2svcd -h' for more info

2.2 fastmem.sh
        Author:         Arpi

        Description:    benchmark/testbed for fastmemcpy stuff

        Usage:          './fastmem.sh'

2.3 mencvcd
        Author:         Jürgen Hammelmann

        Description:    Converts DVD (or anything else that MPlayer plays) to
                        (S)VCD

        Usage:          'mencvcd <basename> [mencvcd options] [mplayer options]'
                        see 'mencvcd -h' for more info

        Note:           Requires mplayer, mjpegtools, vcdimager, cdrdao, and
                        optionally lame, toolame and sox.
2.4 midentify
        Author:         Tobias Diedrich

        Description:    Runs 'mplayer -identify' for all arguments while
                        preventing video window flashing.

        Usage:          './midentify file1 [file2 ...]'

2.5 mpconsole
        Author:         Rich Felker

        Description:    Script to run MPlayer on the console (fbdev/mga_vid/etc)
                        without the console text and/or flashing cursor getting
                        in the way.

        Usage:          './mpconsole [mplayer options]'

2.6 mplmult.sh
        Author:         Reimar Döffinger

        Description:    Example how to output video on multiple windows in sync.
                        Might be even more useful in combination with vo ggi to
                        distribute the video arbitrarily.

        Usage:          './mplmult.sh n mplayer-opts'
                        n               number of MPlayer instances that display
                                        the video
                        mplayer-opts    any options you would pass to MPlayer,
                                        more than one file will usually not work

2.7 sws-test
        Author:         Michael Niedermayer

        Description:    Very simple script to generate PNG images from a video
                        with all -sws methods.

        Usage:          'sws-test <video-file> <start-pos> <res>'
                        example: 'sws-test abc.avi 10 160:120'

2.8 x2mpsub.sh
        Author:         Gabucino

        Description:    Converts the subtitles in the current directory into
                        MPsub format (subtitles go in ./converted-subtitles/*)

        Usage:          './x2mpsub.sh'


3. Perl scripts in TOOLS dir
----------------------------

3.1 calcbpp.pl
        Author:         Moritz Bunkus

        Description:    A script that calculates the $bpp for a movie, mentioned
                        in DOCS/tech/encoding-tips.txt, see that document for
                        more info.

        Usage:          './calcbpp.pl <resolution> <aspect ratio> <bitrate>
                        <fps>'
                        resolution:     the cropped but unscaled resolution (use
                                        '-vf cropdetect')
                        aspect ratio:   the encoded aspect ratio. All DVDs come
                                        at 720x576 but contain a flag that tells
                                        the player wether it should display the
                                        DVD at an aspect ratio of 4/3 (1.333) or
                                        at 16/9 (1.777). Have a look at
                                        MPlayer's output - there's something
                                        about 'prescaling'. That's what you are
                                        looking for.
                        bitrate:        the video bitrate in kbit/s
                        fps:            the fps.
                        example:        './calcbpp.pl 720x440 16/9 896 25'

3.2 countquant.pl
        Author:         Moritz Bunkus

        Description:    Counts the quantizers used for the encoding, mentioned
                        in DOCS/tech/encoding-tips.txt, see that document for
                        more info.

        Usage:          './countquant.pl < divx2pass.log'
                        It will print out which quantizer was used how often.
                        If you see that e.g. the lowest quantizer (vqmin=2) gets
                        used for > 95% of the frames then you can safely
                        increase your picture size.

3.3 dvd2divxscript.pl
        Author:         Florian Schilhabel

        Description:    Yet another DVD to divx helper script.
                        This script encodes a DVD track in 3-pass mode to
                        libavcodec's mpeg4. Optionally it writes the resulting
                        moviefile to a CD-ROM as well as the corresponding audio
                        track to MP3. Optionally it writes the resulting
                        moviefile to a CD-ROM and shuts down the computer.
                        If you like, you can watch the mencoder output on
                        /dev/tty8.

        Usage:          --help       show help
                        --abr        (AudioBitRate) Please enter the desired
                                     bitrate this can be either [96|128|192]
                                     kbit/sec.
                                     Default: 128 kbit/sec.
                        --lang       specify the Language of the audio track
                                     this can be for example <en> or <de>
                                     Default: <de>
                        --dvd        specify the DVD track you want to encode
                        --cdsize     specify the size of your CD-ROM
                                     Default: 700MB
                        --shutdown   Shutdown the system, when the encoding
                                     process has finished. This will only be
                                     possible if you are root.
                        --out        Specify the name of your encoded movie. The
                                     file extension will be appended
                                     automatically.
                        --writecd    Takes the newly created movie and writes it
                                     to a CD-ROM.
                        --writedev   The usual cdrecord device identifier, for 
                                     example 0,1,0
                        --speed      the writing speed
                                     Default: 4
                        --dvd-device device to pull the video off
                                     Default: /dev/dvd

3.4 mp.pl
        Author:         Felix Buenemann

        Description:    Small helper script that allows to play multiple files
                        with MPlayer. Wildcards are supported (eg. './mp.pl -vo
                        x11 /data/*.avi').

        Usage:          mp.pl <parameters> <files>
                        Where <parameters> are all possible commandline switches
                        for MPlayer and <files> can be either a list of files,
                        like file1 file2 file3 and/or a wildcard definition,
                        like *.avi. Example:
                        './mp.pl -vo x11 /dvd/VIDEO_TS/VTS_05_*.VOB movie.asf'

3.5 perlbench.pl
        Author:         Felix Buenemann

        Description:    fastmemcpy benchmark script

        Usage:          './perlbench.pl'

3.6 plotpsnr.pl
        Author:         Jonas Jermann

        Description:    Draw PSNR log graphs using gnuplot.

        Usage:          './plotpsnr.pl [options] <file>'
                        -h, --help    Display this help message
                        -quant        Display quantizers
                        -size         Display size
                        -psnr         Display PSNR
                        -iframes      Display I-frames
                        -pframes      Display P-frames
                        -bframes      Display B-frames
                        -aframes      Display all frames in different colors
                        -cmp <file2>  Compare two files
                        -qs <style>   Quantizer style
                        -ss <style>   Size style
                        -ps <style>   PSNR style
                        Default: -quant -size -psnr -qs "p" -ss "i" -ps "p"

          Note:         Requires gnuplot.
                        Comparison is based on file2.
                        Comparison assumes that the frame numbers of both files
                        fit.

3.7 subedit.pl
        Author:         Michael Klepikov

        Description:    A script for pipelined editing of subtitle files.

        Usage:          './subedit.pl [switches]'
                        -if,--input-format <fmt>  input format; supported: SRT
                                                  default is SRT
                        -of,--output-format <fmt> output format; supported: SRT
                                                  default is same as input
                                                  format
                        -s,--shift <time>         shift all subtitles by <time>
                                                  (format: [-]hh:mm:ss,fraction)
                        -c,--scale <time>         scale by adding <time> to
                                                  overall duration
                        -f,--split-from <time>    Drop subtitles that end before
                                                  <time>
                        -t,--split-to <time>      Drop subtitles that start
                                                  after <time> (will truncate
                                                  timing if it overlaps a
                                                  boundary)
                        -r,--renumber             renumber SRT subtitles in
                                                  output
                        -d,--debug                enable debug output
                        -h,--help                 help message

3.8 w32codec_dl.pl
        Author:         Tom Lees

        Description:    This script will download MS's codec dl interface as 
                        used by MS Media Player to attempt to locate the codecs
                        listed in codecs.conf. It will download them to a
                        directory "codecs/" below the current dir.

        Usage:          w32codec_dl.pl <codec.conf location>

        Note:           You will need the libwww-perl stuff and the utility
                        "cabextract" which may be found at
                        http://www.kyz.uklinux.net/cabextract.php3

3.9 wma2ogg.pl
        Author:         Peter Simon

        Description:    Converts WMA files to Ogg or MP3.

        Usage:          './wma2ogg [options] (-f FILE1 | -f FILE2 ... | -a)'
                        -f, -file         filename
                        -a                converts all WMA files in the current
                                          directory
                        options:
                        -t                output filetype (ogg, mp3)
                                          [default=ogg]
                        -lame             I wanna use L.A.M.E. sure enough!
                        -br               bitrate (kb/s) [default=from the WMA]
                        -del              remove WMA file(s) after the
                                          transcoding

4. C codes in TOOLS dir
-----------------------

4.1 alaw-gen.c
        Author:         Arpi

        Description:    It is here to solve some license issue (It is technical
                        tool to use sox for alaw/ulaw table generation, which is
                        used by MPlayer, but sox is not GPL.)

        Note:           It is not useful anyway, never was.

4.2 asfinfo.c
        Author:         Arpi

        Description:    A simple ASF header display program

        Usage:          './asfinfo <filename.asf>'

        Note:           Also see mplayer's -identify option.

4.3 avi-fix.c
        Author:         Arpi

        Description:    A simple tool to fix chunk sizes in a RIFF AVI file

        Usage:          './avi-fix [-fix] badfile.avi'

        Note:           It does not check/fix index, use mencoder -forceidx -oac
                        copy -ovc copy to fix index!

4.4 bios2dump.c
        Author:         Nick Kurshev

        Description:    Extract BIOS of your PC and save it to file.

        Usage:          As argument requires DOS interrupt number in hexadecimal
                        form.
                        As output - will write 64KB file which will named:
                        SSSS_OOOO.intXX
                        where:  SSSS - segment of BIOS interrupt handler
                                OOOO - offset of BIOS interrupt handler
                                XX   - interrupt number which was passed as
                                       argument

4.5 cpuinfo.c
        Author:         Jürgen Keil

        Description:    The prototype ../cpuinfo.c

        Note:           It is used to simulate /proc/cpuinfo on non-linux
                        systems by ./configure.

4.6 dump_mp4.c
        Author:         Arpi

        Description:    MPEG4-ES stream inspector, dump the startcodes of the
                        stream.

4.7 fastmemcpybench.c
        Author:         Felix Bünemann

        Description:    benchmark/testbed for fastmemcpy stuff

        Note:           Also see fastmem.sh.

4.8 mem2dump.c
        Author:         Nick Kurshev

        Description:    Dump memory block to file.

        Usage:          As argument requires absolute address of memory dump and
                        its lenght (int hexadecimal form).
                        As output - will write file which will named:
                        memADDR_LEN.dump
                        where:  ADDR - given address of memory
                                LEN  - given length of memory

4.9 movinfo.c
        Author:         Arpi

        Description:    Show QuickTime .mov file structure. Similar to
                        'asfinfo', but a bit more useful until all .mov bugs are
                        fixed.

        Usage:          './movinfo <filename.mov>'

4.10 png2raw.c
        Author:         Arpi

        Description:    PNG to RAW image converter, used by .raw font creators.

        Usage:          './png2raw file1 [file2...]'

4.11 subrip.c
        Author:         Kim Minh Kaplan
        Description:    Transform Vobsub subtitles into Subrip text subtitles
                        using GOCR/JOCR.

        Usage:       './subrip <vobsub basename> [<subid> [<output filename>] ]'

        Note:           Requires CVS JOCR/GOCR.
                        You will have to change 'vobsub_id' value if you want an
                        other subtitle than number 0.
                        Hint: you can view the subtitle that is being decoded
                        with "display subtitle-*.pgm"

4.12 vivodump.c
        Author:         Arpi

        Description:    Dump h263 frame headers from vivo files.

        Usage:          Usage: './vivodump <input_file> <output_file>'


5. the GL-test dir
------------------

(...)