.. Assumptions / Limitations

Assumptions and Limitations
===========================

As mentioned on the main page, Exordium does not really attempt to be
a general-purpose web music library suitable for widespread use.  The
only configuration options currently available are those necessary for
basic operation.  Exordium was bourne out of my persistent
dissatisfaction with existing web music library applications.  I've
been using various library applications over the years but have always
ended up maintaining my own patchsets to alter their behavior to suit
what I like, and in the end I figured it would be more rewarding to
just write my own.

So, Exordium represents essentially my own personal ideal of a web
music library application, and its design decisions and operational
goals reflect a very specific set of requirements: my own.  If your
ideal music library differs from my own in even moderate ways, other
music library apps are much more likely to be to your liking.

I would, of course, be happy to accept patches which add, extend, or
modify Exordium behavior, so long as the current functionality remains
the default.  I certainly don't actually *expect* any patches, of course,
given that Exordium's target market is exactly one individual.

Assumptions
-----------

- Except for the Javascript necessary to hook into jPlayer, all content is
  generated server-side.  There is no other Javascript, and the application is
  quite usable from text-based browsers.

- Music files must be accessible via the local filesystem on which Django
  is running, and stored as either mp3 or ogg vorbis.

- The entire music library must be available from a single directory
  prefix.  If subdirs of this root dir span multiple volumes (or network
  mounts), that's fine, but there is NO support for multiple libraries in
  Exordium.

- All music files (and album art) are managed outside of Exordium.  Exordium
  itself will never attempt to write to your library directory for any reason.
  It requires read access only.  (Write access to a directory on the filesystem
  is required for zipfile downloads, but that directory need not be in your
  music library.)

- Music files should be, in general, arranged scrupulously: All files
  within a single directory belong to the same album, and an album should
  never span multiple directories.  There's actually plenty of wiggle room
  here, and Exordium should correctly deal with directories full of
  "miscellaneous" files, etc, but in general the library should be
  well-ordered and have albums contained in their own directories.  This
  becomes more important when rearranging your filesystem layout or
  updating music with fresh tags.

  - Directory containment is the primary method through which Various Artists
    albums are collated.  A group of files in the same directory with different
    artists but the same album name will be sorted into a single "Various"
    album containing all those tracks.  Conversely, if an album name is shared
    by tracks from different directories (each dir's files with a different
    artist name), multiple albums will be created.

  - Tracks without an album tag will be sorted into a "virtual" album entitled
    "Non-Album Tracks: Band Name" - this is the one case where it's expected that
    this virtual "album" might span multiple directories.
 
- The artwork for albums should be contained in gif/jpg/png files stored
  alongside the mp3s/oggs, or in the immediate parent folder (in the case
  of multi-disc albums, for instance).  Filenames which start with "cover"
  will be preferred over other graphics in the directory.

- Artwork thumbnails will be stored directly in Django's database, in
  blatant disregard for Django best practices.  IMO the benefits far
  outweigh the performance concerns, given the scale of data involved.

- Music files should be available directly via HTTP/HTTPS, using the same
  directory structure as the library.  This does not have to be on the same
  port or even server as Django, but the direct download and streaming
  functionality rely on having a direct URL to the files.  Album downloads
  via zipfiles will still work even if this is not the case.

- Album zipfile downloads, similarly, require that the zipfile directory be
  accessible directly over the web.  As with the music files, this does not
  need to be on the same port or even server as Django, but Django will not
  serve the zipfile itself.  The reason for this is that I want zipfile
  downloads to be easily resumable in the event they're accidentally
  cancelled before they're finished.  The text on the download page
  mentions that zipfiles are kept for around 48 hours, but that cleanup is
  actually not a function of Exordium itself.  Instead, I just have a
  cronjob set on the box like so::

    0 2 * * * /usr/bin/find /var/audio/exordiumzips -type f -name "*.zip" -mtime +2 -print -exec unzip -v {} \; -exec rm {} \;

- Tags for information commonly associated with classical music are
  supported, namely: Group/Ensemble, Conductor, and Composer.  *(For ID3
  tags: TPE2, TPE3, and TCOM, respectively.  In Ogg Vorbis, the more
  sensible ENSEMBLE, CONDUCTOR, and COMPOSER.)*  Albums will still be
  defined by their main Artist/Album association, though, and Artist is
  always a required field, whereas Group/Conductor/Composer are all
  optional.  Internally, these are all stored as "artists," and Exordium
  should do the right thing and show you all albums containing an artist,
  whether they showed up as an Artist or as an Ensemble, for instance.

- There are many live concert recordings in my personal library, which I've
  uniformly tagged with an album name starting with "YYYY.MM.DD - Live".
  Given the volume of these albums, Exordium will automatically tag any
  album matching that name as a "live" album.  *(Dashes and underscores are
  also acceptable inbetween the date components.)*  By default, Exordium
  will hide those live albums from its display, since they otherwise often
  get in the way.  A checkbox is available in the lefthand column to turn
  on live album display, though, and it can be toggled at any time.

- The "addition date" of albums into the library is an important data point;
  Exordium's main view is the twenty most recently-added albums.  To that
  point, updates of the music files will allow the album records to be
  updated while keeping the addition time intact.  Some specific cases in
  which this is ensured:

  - Fixing typos in album names / artist names
  - Moving music files from one directory to another

  Combining the two may, however, result in the album being deleted from
  the library and then re-added.  If the tags on a collection of files are
  updated (so that the file's checksum changes), **and** the files are
  moved into a separate directory, the album will end up being re-added,
  since there's no reasonable way to associate the updated files with the
  old ones.

  The most common case of that would be if there was a typo in the album
  or artist name for an album, and that typo was replicated in the directory
  structure containing the files.  Fixing the typo would involve changing
  both the tags and the directory names.  In order to keep the addition time
  intact in this case, you would have to perform both steps separately, running
  an update after each one.

Limitations
-----------

There are some inherent limitations of Exordium, based on the assumptions
that have been made during its development (and in my own music library).

- The artist name "Various" is reserved.  Tracks with an artist tag of
  "Various" will not be added to the library.

- If two Various Artists albums with the same title exist in the library,
  they'll end up stored as one single album in the DB.

- If two directories contain files which seem to be in the same album (by
  the same artist), you'll end up with an album which spans directories.
  Behavior may not be well-defined in that case.

- Exordium completely ignores genre tags.  I've personally always been
  lousy at putting reasonable values in there on my media, and so that's
  been very unimportant to me.  It'd probably be good to support them
  anyway, though.

- Exordium only supports mp3 and ogg currently, though m4a and other
  support should be reasonably simple to add in, so long as Mutagen
  supports the format.
