For the hacking sort, this document may help navigate the source code to
vitunes.  I'm writing it mostly as future reference to myself, but others may
find it usefull.


First, recall the following:

   *  vitunes works by maintaining a database of all known files in
            ~/.vitunes/vitunes.db

   *  the database is initialized, updated, and stuff added to it via,
            $ vitunes -e init
            $ vitunes -e update
            $ vitunes -e scan  ~/music  /path/to/more/music ...
      respectively.  See "vitunes -e help" for more details.

   *  if a media file is not in the database, vitunes cannot play it.

   *  once the database is setup, vitunes can be run normally as
            $ vitunes

   *  once vitunes is run normally, one can browse the library, filter, sort,
      search, copy/paste/delete/etc and create new playlists.  all playlists
      are stored in
            ~/.vitunes/playlists/

   *  the playlist files contain nothing more than the absolute
      paths to the music files contained in the database.  there
      is no meta information in playlists.  all meta information
      is in the database.

   *  media playback is done with a fork()'d instance of mplayer [4].

   *  extracting meta-information from media files is done with 3 libraries:
         *  libid3tag (part of mad) [1]
         *  libvorbis (part of xiph.org package) [2]
         *  libmp4 [3]



Onto the code structure...


First, the basic configuration is all done in config.h.  Specifically,
   *  keybindings
   *  command-mode bindings
   *  default colors/text-attributes

After that, the source code for vitunes is broken into 9 modules, each
relatively small.  A brief description of each follows, starting with the
smallest.  Note the code-naming conventions and which ones export a
global object that is used throughout the other modules.

Tracing through the source code from "main" to keybindings is, at this
point, relatively straight-forward.



MODULE            DESCRIPTION
--------------    -----------------------------------------------------------
str2argv          Contains only 1 (ok 2) functions used elsewhere.  They are
                  the functions for converting a string (char*) to an int argc
                  char *argv[] style parameter list, used for the command-mode
                  function bindings.  The second function is used to free()
                  a previously built argc/argv structure.


player            Contains all of the code to handle the mplayer [4] child-
                  process fork()'d by vitunes.  Includes loading files for
                  playback, pausing, seeking, etc.

                  NAMING CONVENTION:   player_*
                  GLOBAL EXPORTS:   player
                     player   - a global object used for record keeping
                                of what mplayer is up to.


meta_info         Contains all of the code to extract the meta information
                  (artist name, album name, song title, track number, genre,
                  and year) from a media-file.  It makes uses of 3 external
                  libraries: the id3tag library [1] (part of mad), the vorbis
                  library [2], and the libmp4 library.  In contains a simple
                  struct used to represent all such info (meta_info).

                  In addition to this, the logic for sorting song, searching
                  song, and changing their display in vitunes is contained
                  here.

                  NAMING CONVENTION:   mi_*


playlist          Contains all of the code to represent and work with
                  playlists, which is a simple struct containing an array
                  of meta_info's.

                  NAMING CONVENTION:   playlist_*


medialib          Contains all of the code to represent the media library,
                  which is the database of all known files and array of all
                  playlists.  Handles initializing, loading, updating, and
                  adding to the database.

                  NAMING CONVENTION:   medialib_*
                  GLOBAL EXPORTS:
                     mdb   - the global media-library struct, containing
                             the database of known files and playlists.


uinterface        A small abstraction layer on top of curses(3), mostly for
                  record keeping.  Provides the code to setup the 4 windows,
                  resize, and some routines for getting input from the user
                  (from the command window).

                  NAMING CONVENTION:   ui_*
                  GLOBAL EXPORTS:
                     ui    - the global user interface object, which again
                             contains mostly record-keeping info.


paint             All major display stuff is in here.  4 functions for
                  painting the 4 window, plus 2 more used to paint
                  informational/error messages in the command/status widnow.

                  NAMING CONVENTION:   paint_*


input_handlers    All of the keybinding-handlers in vitunes plus all of the
                  command-mode handlers.  This is the real "guts" of vitunes.
                  To see which function corresponds to what, look at config.h


vitunes           The "main" program.  In normal mode, does setup of media-
                  library, user interface, and main input loop.
                  Also contains all of the code for all of the e-commands
                  (things like "vitunes -e update").



References:
   [1]   http://mad.sourceforge.net/
   [2]   http://www.xiph.org/vorbis/
   [3]   http://resare.com/libmp4v2/
   [4]   http://www.mplayerhq.hu/


-Ryan Flannery  <ryan.flannery@gmail.com>  17 Dec. 2009
