NAME
    Neon Goat MP3 Report Generator - mp3report.pl

DESCRIPTION
     A customizable program to scan a list of (sub)directories, creating a report
     from an HTML template. Also calculates various statistics and each song's
     playing time. Supports ID3 and ID3v2 tags. Should work on any perl-ized OS;
     see homepage for demo - http://mp3report.sourceforge.net

CONFIGURING
     All options can be configured through the command line, see mp3report.pl --help
     for more info. You may also want to modify the hard coded defaults at the
     top of the program file.

     See documentation.html for information on customizing your own template file.

USAGE
     Usage: mp3report.pl [options] [directory...]
      --help                 shows this help screen
      --printmode            uses a smaller font for printing
      --title=TITLE          sets the title used in the report
      --outfile=OUTFILE      file to write report to, '-' for STDOUT
      --template=FILE        file to use as report template
      --stdgenres            use standard genres instead of winamp genres
      --id3v2                enable id3v2 support (experimental)
      directory...           dirs to scan (subdirs included)

INSTALLATION
     You should be able to run mp3report.pl directly after decompressing it:
     
     tar xfzv mp3report-1.0.2.tar.gz
     cd mp3report-1.0.2
     ./mp3report.pl --help
     
     If your perl interpreter isn't in /usr/bin/perl, you'll need to change the first line
     of mp3report.pl
     
     If you'd like to install the MP3::Info perl module so that other programs can
     use it, it is available at http://search.cpan.org/search?dist=MP3-Info.

CUSTOMIZATION AND TEMPLATES
    By creating your own HTML file or modifying one of the provided
    templates, you can customize the output of MP3 Report Generator.
    These are the various identifiers that MP3 Report Generator can
    look for in a report:

  General Information

    $t_fontsize
        This is either 1 or 2, depending on the `--printmode' flag.
        If printing mode is on, the idea is that the font size
        should be a little bit smaller so that it looks better on
        paper. To make sure this field does something, use `<FONT
        SIZE="$t_fontsize"'> in your HTML code.

    $t_title
        Used for the HTML `<TITLE'> tag as well as the first line of
        the report, and is set by specifying `--title=SOMETHING' on
        the command line.

    $t_datetime
        The local date and time when the report was generated.

    $t_dirs
        The list of parent directories that was scanned in the
        report. Each directory is separated by
        `<BR&gt;&amp;nbsp;&amp;nbsp;' so that they are on seperate
        lines and indented.

    $t_numdirs
        The total number of directories and subdirectories scanned
        in the report.

    $t_numfiles
        The total number of MP3 files included in the report.

    $t_size
        The total size of all MP3 files included in the report
        combined. This is formatted into "x.xx GB (y.yy MB)".

    $t_playtime
        The total playing time of all songs combined. This is
        formatted into an English sentence (4 days, 3 hours, 2
        minutes, 1 second).

    $t_exectime
        The total time it took to genereate the report. This is
        formatted into an English sentence (4 days, 3 hours, 2
        minutes, 1 second).

    $t_avgsize
        The average size of the MP3s in this report. This is
        formatted into "x.xx MB".

    $t_avgplaytime
        The average playing time of a single song in the report.
        This is formatted into an English sentence (3 hours, 2
        minutes, 1 second).

  Report Settings

    $t_filename
        The filename that the report is being written to.

    $t_template_filename
        The filename of the template that is being used.

    $t_printmode
        Either "Yes" or "No" depending on whether the `--printmode'
        flag was specified.

    $t_customdirs
        Either "Yes" or "No" depending on whether user specified
        custom directories to scan on the command line.

    $t_genretype
        Either "Standard" or "WinAMP" depending on whether or not
        the user specified `--stdgenres'.

    $t_id3v2
        Either "Yes" or "No" depending on whether the `--id3v2' flag
        was specified.

  Item Information

    $item_dir
        The current directory that is being scanned.

    $item_num
        The current sequential number of the item found.

    $item_filename
        The filename of the item found. NOTE: This in versions older
        than 1.0.2, this variable was called $item_name.

    $item_size
        The size of the item found. This is formatted into "x.xx
        MB".

    $item_bgcolor
        This will either be `#FFFFFF' or `#EEEEEE' (white or light
        gray) depending on whether or not the current item number is
        even or odd. This is used to make the cell color in tables
        alternate to make the report easier to read. In order for
        this to work, your HTML code must look something like `<TD
        BGCOLOR="$item_bgcolor">'`...</TD>'.

    $item_len
        The playing time of the song found, formatted into "XX:YY"
        (minutes:seconds).

  MP3 Information

    $item_totalseconds
        The total number of seconds in the current song.

    $item_mp3version
        The MPEG version number of the current MP3, usually 1.

    $item_stereo
        Either "Stereo" or "Mono" depending on the number of
        channels in the MP3.

    $item_mpeglayer
        The MPEG layer number, usually 3.

    $item_bitrate
        The bitrate of the current MP3 in kbps.

    $item_vbr
        If the current MP3 is encoded at a variable bitrate, this
        will equal "VBR". If not, it will be a blank string.

    $item_copyrighted
        Either "Copyrighted" or "Not copyrighted" depending on the
        MP3's copyright flag.

    $item_frequency
        The frequency of the current MP3 in kHz.

  ID3 Tag Information

    $item_id3title
        The song's ID3 title, maximum 30 characters.

    $item_id3artist
        The song's ID3 artist, maximum 30 characters.

    $item_id3album
        The song's ID3 album, maximum 30 characters.

    $item_id3year
        The song's ID3 year, maximum 4 characters.

    $item_id3comment
        The song's ID3 comment, maximum 30 characters (28 if the ID3
        tag also contains a track number).

    $item_id3genre
        The song's ID3 genre. You may disable WinAMP genres by
        specifying the `--stdgenres' flag.

    $item_id3tracknum
        The song's ID3v1.1 track number (if present), maximum 2
        characters.

  ID3v2 Tag Information

    ID3v2.3.0 (or later) tags are also supported. To enable ID3v2
    support, use the `--id3v2' flag on the command line. The
    following is taken from `MPEG::MP3Info::v2_tag_names'

    $item_id3v2_wpay
        WPAY: Payment

    $item_id3v2_text
        TEXT: Lyricist/Text writer

    $item_id3v2_toly
        TOLY: Original lyricist(s)/text writer(s)

    $item_id3v2_tmed
        TMED: Media type

    $item_id3v2_rvad
        RVAD: Relative volume adjustment

    $item_id3v2_time
        TIME: Time

    $item_id3v2_rbuf
        RBUF: Recommended buffer size

    $item_id3v2_toal
        TOAL: Original album/movie/show title

    $item_id3v2_trck
        TRCK: Track number/Position in set

    $item_id3v2_ipls
        IPLS: Involved people list

    $item_id3v2_mllt
        MLLT: MPEG location lookup table

    $item_id3v2_tkey
        TKEY: Initial key

    $item_id3v2_apic
        APIC: Attached picture

    $item_id3v2_sytc
        SYTC: Synchronized tempo codes

    $item_id3v2_tyer
        TYER: Year

    $item_id3v2_tpos
        TPOS: Part of a set

    $item_id3v2_trsn
        TRSN: Internet radio station name

    $item_id3v2_ufid
        UFID: Unique file identifier

    $item_id3v2_trso
        TRSO: Internet radio station owner

    $item_id3v2_tsiz
        TSIZ: Size

    $item_id3v2_tenc
        TENC: Encoded by

    $item_id3v2_trda
        TRDA: Recording dates

    $item_id3v2_comm
        COMM: Comments

    $item_id3v2_sylt
        SYLT: Synchronized lyric/text

    $item_id3v2_woaf
        WOAF: Official audio file webpage

    $item_id3v2_link
        LINK: Linked information

    $item_id3v2_comr
        COMR: Commercial frame

    $item_id3v2_tbpm
        TBPM: BPM (beats per minute)

    $item_id3v2_pcnt
        PCNT: Play counter

    $item_id3v2_tofn
        TOFN: Original filename

    $item_id3v2_woar
        WOAR: Official artist/performer webpage

    $item_id3v2_woas
        WOAS: Official audio source webpage

    $item_id3v2_tpe1
        TPE1: Lead performer(s)/Soloist(s)

    $item_id3v2_tflt
        TFLT: File type

    $item_id3v2_tpe2
        TPE2: Band/orchestra/accompaniment

    $item_id3v2_tsrc
        TSRC: ISRC (international standard recording code)

    $item_id3v2_tpe3
        TPE3: Conductor/performer refinement

    $item_id3v2_rvrb
        RVRB: Reverb

    $item_id3v2_tpe4
        TPE4: Interpreted, remixed, or otherwise modified by

    $item_id3v2_mcdi
        MCDI: Music CD identifier

    $item_id3v2_tdly
        TDLY: Playlist delay

    $item_id3v2_tdat
        TDAT: Date

    $item_id3v2_tory
        TORY: Original release year

    $item_id3v2_tlan
        TLAN: Language(s)

    $item_id3v2_tcom
        TCOM: Composer

    $item_id3v2_tlen
        TLEN: Length

    $item_id3v2_tcon
        TCON: Content type

    $item_id3v2_tcop
        TCOP: Copyright message

    $item_id3v2_owne
        OWNE: Ownership frame

    $item_id3v2_tpub
        TPUB: Publisher

    $item_id3v2_txxx
        TXXX: User defined text information frame

    $item_id3v2_geob
        GEOB: General encapsulated object

    $item_id3v2_tsse
        TSSE: Software/Hardware and settings used for encoding

    $item_id3v2_priv
        PRIV: Private frame

    $item_id3v2_tit1
        TIT1: Content group description

    $item_id3v2_talb
        TALB: Album/Movie/Show title

    $item_id3v2_tit2
        TIT2: Title/songname/content description

    $item_id3v2_tit3
        TIT3: Subtitle/Description refinement

    $item_id3v2_poss
        POSS: Position synchronisation frame

    $item_id3v2_grid
        GRID: Group identification registration

    $item_id3v2_uslt
        USLT: Unsychronized lyric/text transcription

    $item_id3v2_encr
        ENCR: Encryption method registration

    $item_id3v2_town
        TOWN: File owner/licensee

    $item_id3v2_wors
        WORS: Official internet radio station homepage

    $item_id3v2_etco
        ETCO: Event timing codes

    $item_id3v2_equa
        EQUA: Equalization

    $item_id3v2_wcom
        WCOM: Commercial information

    $item_id3v2_aenc
        AENC: Audio encryption

    $item_id3v2_tope
        TOPE: Original artist(s)/performer(s)

    $item_id3v2_wcop
        WCOP: Copyright/Legal information

    $item_id3v2_popm
        POPM: Popularimeter

    $item_id3v2_wpub
        WPUB: Publishers official webpage

    $item_id3v2_wxxx
        WXXX: User defined URL link frame

    $item_id3v2_user
        USER: Terms of use

ACKNOWLEDGEMENTS
     Much thanks to Chris Nandor and contributors to MP3::Info... 
     it saved me a lot of time :) And to Larry Wall for such a great language.
     
     Hello to MMT, UCLA LUG, cX, and of course the DJs of Mister Balak's Neighborhood!

SEE ALSO
    MP3::Info
        http://search.cpan.org/search?dist=MP3-Info

    ID3v2
        http://www.id3.org/

    SourceForge
        http://www.sourceforge.net Damn, these guys rock.

    icecast
        http://www.icecast.org

AUTHOR AND COPYRIGHT
     Neon Goat MP3 Report Generator
     v1.0.2 - April 5, 2000
     Copyright (C) 2000, David Parker, Neon Goat Productions.
     
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
     
     See COPYING or http://www.gnu.org for more information.
     
     David Parker
     david@neongoat.com
     http://www.neongoat.com
     http://mp3report.sourceforge.net

