========================================
arubomu: Music Album Description Library
========================================

.. contents:: Table of Contents

Description
===========

The arubomu library defines a simple format for representing information related
to a music album, for user-specific information about a specific copy of an
album (mp3 encoding parameters, source, defects, etc.), to represent songlists
and statistics associated with files (e.g. number of times listened).

It is a simpler alternative than the more powerful generic RDF format that other
systems use, yet more descriptive than CDDB files. It is meant as a simple,
reasonable format for describing albums, one where you can edit files directly.

This format addresses the *minimal practical needs* for representing a music
album. We do not intend this as a final solution for all possible needs ever to
crop up, but we need something that *works* and that is *adequate* (i.e. cddb
format is not adequate for many reasons). To give you an idea, the basic format
include the following kind of information, and a little more:

- album artist and title;
- label and release date;
- online catalog references (amazon, descarga, eventually musicbrainz, amg);
- list of songs for each disc including titles, duration, extra info, artist
  (when needed).
- review text


Motivation
----------

This was developed part of the jukebox scripts project, which is an effort in
providing scripts to cleanly manage and organize directories of entire albums
converted to mp3 files.

The author believes that a full database approach like `MusicBrainz
<http://musicbrainz.org>`_ is the right approach to pursue, and that it could
eventually succeed (and we certainly hope so), but that it will never be able
to match all of a user's mp3 entries and thus there will always be a need for
representing and editing information locally (even if just for a cache).
Besides, at the moment MusicBrainz does not include label and release date and
disc information so we have decided to go through with this project anyway
because we use and need this *now*.

Also, think of the cases where an album is a home-made compilation of songs
made by a friend, or recorded by a local artist. These should not go in a
central database, but it is nevertheless necessary to be able to gather or
enter information about that title.


Documentation
=============

- `CHANGES <CHANGES>`_
- `TODO <TODO>`_

Album Format
------------

- `Album example <test/album/album-main.xml>`_.
- `Album schema <share/rng/album.rng>`_.

The ``album`` chunk is meant to contain information about the album that is
entirely independent of the user and that could be shared between different
users.  There is space to shove reviews in it but personal comments that relate
to the specific copy of the music (e.g. encoding errors) should not be included
in there.

There is also a "loose" version of the ``album`` format, that is meant to be
used within album lists (see `Container formats`_ below). The idea is that we
should be able to write in a single file lists of misc. info about an album
without having to provide the full set of required info for a strict album.



User Format
-----------

- `User example <test/user/user-main.xml>`_.
- `User schema <share/rng/user.rng>`_.

The ``user`` chunk is meant to contain information about the album that is only
dependent of the user and that should not be shared between different users.
This is where peculiarities, encoding problems, missing songs, etc. will be
described. Some of that information can be used to verify the validity of the
XML file against the files stored for the music.

Songlist Format
---------------

- `Songlist example <test/songlist/songlist-main.xml>`_.
- `Songlist schema <share/rng/songlist.rng>`_.

A simple way to stored references to songs.  Some scripts can use this as a way
to provide compilations of songs.

Playfile Format
---------------

- `Playfile example <test/playfile/playfile-main.xml>`_.
- `Playfile schema <share/rng/playfile.rng>`_.

A file format that allows storing which songs have been listened to and how many
times.

Container formats
-----------------

Rip and Rip List
~~~~~~~~~~~~~~~~

- `Container for album, user info and an associated id <share/rng/rip.rng>`_;
- `A list of rips in a single file <share/rng/riplist.rng>`_;

Album List
~~~~~~~~~~

- `A list of albums in a single file <share/rng/albumlist.rng>`_;


Download
========

- `Download distribution </downloads/arubomu>`_.


Installation
============

Dependencies
------------

- Python-2.3 or greater;
- effbot's elementtree (Python library);


Copyright and License
=====================

Copyright (C) 2001-2004  Martin Blais.  All Rights Reserved.

This code is distributed under the `GNU General Public License <COPYING>`_;


Author
======

Martin Blais <blais@furius.ca>
