MP3REPORT(1)

📦
version 1.0.3 · 3 versions
, in debian trixie, ubuntu noble, ubuntu questing

💖 MP3REPORT(1) — User Contributed Perl Documentation 💖

okay bestie, gather round, because this one is literally the Neon Goat MP3 Report Generator and it's about to change your whole filesystem situation ✨

🌸 NAME 🌸

mp3report — Neon Goat MP3 Report Generator. that's it, that's the name, and honestly? iconic. 💅

🦋 DESCRIPTION 🦋

so here's the vibe: this is a customizable program that scans a whole list of (sub)directories and then builds you a report from an HTML template. like, it goes through your music folders and makes you a whole cute lil report. 🎀

and it doesn't just list stuff — it also calculates various statistics and works out each song's playing time. the math? she's mathing. 🔥

tag support, because of course:

  • ID3 tags ✅
  • ID3v2 tags ✅

It should work on any perl-ized OS — no cap. and if you wanna see a demo before you commit, the homepage has one: http://mp3report.sourceforge.net 👑

✨ CONFIGURING ✨

every single option can be configured through the command line, fr fr. if you want more info on that, just run:

mp3report --help

you can also go in and modify the hard coded defaults at the top of the program file if that's your thing. main character energy, do what you want. 💜

also!! check out documentation.html for info on customizing your own template file. yes, your own. bespoke. artisan. 🧚

🌈 USAGE 🌈

the whole deal is:

Usage: mp3report [options] [directory...]

and here's every option, no gatekeeping:

  • --help — shows this help screen. the classic. the beloved. 😌
  • --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) 🗂️

for real, that's the entire help screen, verbatim, look:

 --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)
heads up about --id3v2: it's marked experimental in the source, so treat it like a new pair of shoes — cute, but don't run in them. 🩰

🎀 INSTALLATION 🎀

good news bestie: you should be able to run mp3report directly after decompressing it. no build step, no drama. 🫶

tar xfzv mp3report-1.0.2.tar.gz
cd mp3report-1.0.2
./mp3report.pl --help

that's it. that's the install. 🌸

one lil caveat tho — if your perl interpreter isn't in /usr/bin/perl, you'll need to change the first line of mp3report.pl. literally just that one line. 💀

and if you'd like to install the MP3::Info perl module so that other programs can use it too (sharing is caring 💖), it's available at:

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

okay and there's more where this came from, so don't go anywhere… 👀✨

💖 CUSTOMIZATION AND TEMPLATES 💖

Okay bestie, you can absolutely make this report your own. 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 separate 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 generate 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 👀

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

That's the whole manual, bestie. Source/version: perl v5.36.0 — date: 2023-10-05. Now go make the most iconic MP3 report. 💅✨

📦 where this page comes from