Home

The multi-room media manager utilities m3util provide utility functionality for managing large media libraries by using high-quality sources for tag information.

The m3util utilities in their current state support MP3 audio only. More media formats are not likely to be added soon, as we are focusing more on the library management aspect than on support for many different audio formats. This was a very deliberate decision as supporting different formats is quite complex and gets even more complex when targeting multiple platforms.

All m3util tools operate on a fixed folder structure, which looks like this:

• M3_LIBRARY_HOME
• audio - the managed audio root folder
  • 01-gold - high-quality tags, tagged with data from MusicBrainz
  • 02-silver - medium-quality tags, tagged via freedb or other sources
  • 03-bronze - low-quality tags, maybe not tagged at all
  • playlist - audio playlists
• tools - the tools for managing the library
  • bin - the binaries/shell scripts
  • etc - tool config fies
  • lib - tool libraries
    • java - Java runtime environments for different platforms
  • var - Directory structure for log files and databases
    • log - log files
    • cache - caching folder
      • images - the cover image cache
    • lib - database folder
      • db - for example the Derby DB files
      • lucene - the lucene index files
    • incoming - Folder for new MP3s
      • audio - incoming audio files
        • unsorted - new contributions by "username"
        • cleaned - staging, for files prepared to be added to the repository
        • dupes - duplicates identified by the tool-chain

We have divided the audio folder into 3 quality categories:

• GOLD - MusicBrainz tagged content only
• SILVER - tagging was done by other authorities, like iTunes or Amazon for example
• BRONZE - all the rest (we do not even know whether there are tags at all)

The structure below those quality folders is always [A-Z+#]/<ARTIST>/<ALBUM> or [A-Z+#]/<ARTIST>/[Singles].

The tools folder contains all the tools or the tool data, like database files or lucene index files.

The root of the folder structure can be declared in several ways. By environment variables like this:

# UNIX
export M3_LIBRARY_HOME=<PATH>
REM Windows
set M3_LIBRARY_HOME=<PATH>

Or by VM parameter like this:

java -DM3_LIBRARY_HOME=<PATH> -jar m3util.jar

If the root of the folder structure cannot be determined by any of the settings above, the tools will exit with an error message.

The tools can be invoked by the following command:

m3util [options] <CMD> [cmd-options]

Where [options]are general tool options and [cmd-options] are tool-specific options.

The current set of m3util tools include the following functionality:

• create an empty folder structure
• create or update the index (database & lucene)
• id ...
• refresh the file-, folder- and tag-structure (based on MusicBrainz)
• plainly rename files based on tag information
• ...