NOTE: it will be immediately obvious to anyone who read this that I was
   first a C++ programmer.  Sorry about that.


Updated: 11 March 2009

vitunes is a collection of the following "modules" represented hierarchically
(by dependency) in the following graph:

The interaction between the modules is STRICT.  That is, each module below
uses/references functions/constants from the modules it depends on (which
appear lower than it in the graph).


                                vitunes
                                   |
                             input_handler
                                   |
                     +-------------+------------+
                     |                          |
                  command_mode                 viui
                     |                          |
                     +-------------+------------+
                                   |
             +---------------------+--------------------+
             |                     |                    |
       media_library          media_player          uinterface
             |
             +--------+
             |        |
             |     playlist
             |        |
             +--------+
             |
        meta_info_db
             |
             |
         meta_info


A brief description of each modules follows.

   1) meta_info      Files: meta_info.h, meta_info.c

      This module provides functionality for representing and extracting
      the meta information from media files.  The key structure defined
      here is the "meta_info" struct, which stores all of the meta data
      that vitunes is interested in, which is the following:

            *  Filename    - The file the work is stored in, full path
                             (see realpath(3))
            *  Artist      - Who composed/created the work
            *  Album       - The album the work was originally released on
            *  Title       - The title of the work
            *  Track       - If the work appears on a disk, which number it is
            *  Year        - When the work was composed
            *  Genre       - Simple category description of content
            *  PlayTime    - How long (in microseconds) the file will play for

      The key function defined is "meta_info_extract(filename)", which
      extracts any of the above meta information from the file and returns
      a pointer to a meta_info struct filled as necessary.


   2) meta_info_db   Files: meta_info_db.h, meta_info_db.c

      This module contains the struct "meta_info_db" which is nothing more
      than an array of "meta_info" structs.  It provides functionality for

            *  Loading/Saving a meta_info_db to/from a file
            *  Displaying the contents of a meta_info_db in an easily-
               parsable format to stdout
            *  Adding/removing/updating elements in a meta_info_db
            *  Searching a meta_info_db by filename

      And, probably most importantly,

            *  Creating/Updating a meta_info_db given a list of files and/or
               directories to be searched recursively for media files.


   3) playlist       Files: playlist.h, playlist.c

      This module contains the "playlist" struct which is used to represent
      a sequence of media files.  It is nothing more than an array of
      meta_info objects.

      Playlists are stored on disk in files where each line contains the
      filename of a song in the playlist, in the order they appear in the
      playlist.

      Functionality provided in this module is:

            *  Loading/Saving playlists from/to file
            *  Deleting a playlist, including it's file
            *  Removing files from playlists

      When playlists are loaded from file, they are compared against a
      meta_info_db object to see if each file in the playlist exists in the
      database.  If so, the corresponding entry in the playlist struct is
      simply a pointer to the existing record in the meta_info_db.
      Otherwise, a new record is created in the meta_info_db and the
      corresponding entry in the meta_info_db is pointed to the newly created
      record.


   4) media_library  Files: media_library.h, media_library.c

      This module contains the "media_library" struct, which represents the
      core meta information database (a meta_info_db struct), plus all of
      the playlists.

      It provides functionality for:

            *  Loading the entire media library (this includes loading the
               meta_info_db, as well as all the playlists)
            *  Adding/Removing/Searching playlists in the media library

      It's nothing more than a high-level wrapper around the meta_info_db
      and playlist struct's, that contains all of the media files vitunes
      is aware of.


   5) media_player   Files: media_player.h, media_player.c

      This module is the wrapper around `mplayer' (http://www.mplayerhq.hu)
      It provides the following functionality:

            *  Creating the bastard child that is `mplayer'
            *  Loading files for playback
            *  Pausing/Un-pausing playback
            *  Stopping playback
            *  Seeking forward/backward in the currently playing file

      Additionally, this module contains a function (media_player_monitor)
      that is meant to be setup on a timer to monitor the child mplayer
      process to retrieve the the following information:
            -  Is mplayer currently playing anything?
            -  How far (in seconds) is mplayer into the current file?
      And, most imporantly,
            -  If playback of the current file has stopped because the file
               has ended, start playing the next song.


TODO: finish this!

   6) uinterface     Files: uinterface.h, uinterface.c

   7) viui
   9) command_mode
  10) input_handler
  11) vitunes


