
INTRODUCTION
   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.

   For list of current todo's, known bug's, or other stuff to work on, grep the
   source for TODO's, FIXME's, and XXX's.  For longer stuff, there's an up-to-
   date list of big TODO's at the bottom of this file.

   Below you'll find 3 sections.
      1. Media-Library Structure: a quick overview of how the media is handled
      2. Code-Structure: Notable Globals.  Listing of the 3 key global structs
      2. Code-Structure: The Modules.  Overview of each of the 9 modules.

   Care has also been taken to make all .h files briefly document the api
   therein.  This should be maintained.

   This should be enough for most to jump-into hacking on vitunes.

   For debugging (which can be painful in a curses application), see debug.h
   and what happens when you "make -DDEBUG".  Two macros are created, one to
   log to a file (DFLOG) and one to log to the console (DCLOG).  The log
   file (log.txt) is opened in vitunes.c if "-DDEBUG".



MEDIA-LIBRARY STRUCTURE

   Before hacking on vitunes, it's important to understand the following about
   the overall structure.

      *  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 add ~/music  /path/to/more/music ...
               $ vitunes -e addurl "http://...."
         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]
         that are wrapped-together in meta_info.* into "meta_info_extract()".




CODE STRUCTURE: NOTABLE GLOBALS

   vitunes maintains 3 key global objects (structs) that are used throughout
   much of the code.  They are:

      1. mdb         Maintains all information about the media library,
                     including the database (an array of meta_info*'s), all
                     playlists, and the filter results.
                     See medialib.h for more info.

      2. player      Maintains all information about the fork()'d child
                     process of mplayer, including pipes to read/write to the
                     process, the currently playing playlist & song, and some
                     basic record-keeping (is mplayer playing, is it paused,
                     etc.)  See player.h for more info.

      3. ui          Maintains all key information about the display and each
                     of the 4 windows.  Of key interest are the two
                     "scrollable-windows" (the library and playlist windows).
                     The struct maintains their vertical/horizontall scroll
                     offsets, and a few more things.
                     See uinterface.h for more info.

   There are other globals, but none are "exported" in any of the .h files.
   These include global structs in:
      *  meta_info.c       For maintaining the current display description,
                           sort description, and search/query filter.  They
                           are (and should be) only used within meta_info.c.

      *  paint.c           For maintaining the colors used for painting all
                           of the text to curses.  Again, this is (and should
                           be) only used within paint.c.



CODE STRUCTURE: THE MODULES

   First, the basic configuration is all done in config.h.  Specifically,
      *  keybindings
      *  command-mode bindings
      *  default library-window width
   is all done there.  See that for quick fixes.

   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 2 functions used elsewhere.  They are used
                     for converting a string (char*) to an 'int argc' and
                     'char *argv[]' pair, 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 Variables Exported:
                        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.  It contains a
                     simple struct used to represent all such info (meta_info).

                     In addition to this, the logic for sorting songs,
                     searching/filtering songs, 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.  Nothing more.

                     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 Variables Exported:
                        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 Variables Exported:
                        ui    - the global user interface object, which again
                                contains mostly record-keeping info.


   paint             All major display stuff is in here.  Functions for
                     painting each of the 4 window, error/information
                     messages, and setting up colors.

                     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").


---

Hope this helps anyone interested in hacking on vitunes (specifically me... 6
months from now)

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


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


CURRENT LIST OF BIG "TODO"'s:

*  list of UNIMPLEMENTED on website (tend to be smaller)
*  in mi_display_set and mi_sort_addtoken, somehow get better error messages
   back to vitunes (e.g. "no such field name", "too many fields", etc.)
   do this in general.
*  provide a "set save-sorts=true" option, where sorting a playlist will flag
   the "needs saving" bit for a playlist.
*  my handling of colors and other text-attributes in paint.c (namely applying
   them and un-applying them) seems needlessly complicated.  i need to take
   the time to fully understand this and modify from there...
*  fix sorting of meta_info's so that numeric fields are sorted by their
   numeric values rather than character representations... this would require
   some re-working. damnit, i should re-structure extraction so that track
   number and year are converted to actual numbers, but sometimes track info
   includes album number (i.e. "2/3" for the second track on the theird album)

