Neon Goat MP3 Report Generator - mp3report.pl

- NAME
- DESCRIPTION
- CONFIGURING
- USAGE
- INSTALLATION
- CUSTOMIZATION AND TEMPLATES
  - General Information
  - Report Settings
  - Item Information
  - MP3 Information
  - ID3 Tag Information
  - ID3v2 Tag Information
- ACKNOWLEDGEMENTS
- SEE ALSO
- AUTHOR AND COPYRIGHT

# 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 `&lt;TD BGCOLOR="$item_bgcolor"&gt;``...&lt;/TD&gt;`.

$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