.. 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 born 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, and jPlayer
  itself, there is no client-side Javascript or AJAX-style dynamic page
  content.  All HTML is generated server-side.  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.

- Exordium itself will never attempt to write to your library directory for
  any reason - all music files (and album art) are managed outside of
  this app.  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
  is less important during the initial library import, but becomes much
  more important when updating tags or rearranging your filesystem layout,
  as Exordium uses the directory structure to help determine what kind of
  changes have been made.

  - 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.  PNGs will be
  preferred over JPGs, and JPGs will be preferred over GIFs.

  - 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 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 to be able
  to pass the zipfile URL to other apps for downloading, and for 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, and Artist is
  always a required field, whereas Group/Conductor/Composer are all
  optional.  Internally, these are all stored as "artists," so when
  browsing by artist, Exordium should do the right thing and show you
  all albums containing an artist, whether they showed up as artist,
  composer, conductor, or ensemble.

- 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 consider 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:

  - Updating album/artist names in the file's tags
  - Moving music files from one directory to another, or renaming the files

  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.

- Artist and Trackname tags are required.  Tracks will not be added to
  the library if either of those tags are missing.

- If two Various Artists albums with the same album name 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.
