DEVELOPERS

If you're interested in hacking away on calliope, by all
means, join the fray.  Current releases will be found on
Sourceforge at:

	http://sourceforge.net/projects/kalliope

Project home page is:

	http://neil.verplank.org/opensource/calliope

The project home page left menu has a "developers" heading, 
under which you'll find a fair amount of current documentation 
about code architecture, interface creation, artist cleaning, db 
architecture, as well as a to-do list, bugs, etc.  In addition,
there are copious comments throughout the modules as to what's
going on at any given point.  You can turn on DEBUG in the
conf file, and you'll get a lot more logging in ~/var/log/

If there's something you'd like to see in Calliope, and you're
interested in helping, or something on the TODO list, or bugs
you've found/fixed, let me know:

    http://neil.verplank.org/contact.htm





COMMAND LINE

"calliope help" from the command line will list all command line features,
which are many, and continue to change and improve.  Beyond simply starting
and stopping calliope, there are many useful command line features -
check 'em out!





EXTRA TOOLS

There are some simple scripts in dev/musicTools that you may find useful.
Among them are:

  copynew.pl     - copies files after a certain date to a directory
  mergeMusic.pl  - given two music libraries, merges one into the other sensibly

These are all quick hacks that I've used, but they're there.



GETTING INVOLVED

We're presently using cogito to share development work.  In general, 
I'll probably have the latest branch posted at:

    http://neil.verplank.org/opensource/calliope/calliope-git/

To get up to speed on Cogito, try this:

    http://neil.verplank.org/opensource/calliope/calliope-git/githowto.html

githowto should also be in calliope/dev/githowto.html


Other branches include:

    http://bitdrip.net/~jtwang/calliope-git/ 
    http://www.dgreaves.com/calliope-git/ 

ON CALLIOPE'S ARCHITECTURE

this section is *just* getting started, but here are some notes:

calliope accepts requests from the command line, and from the web.  The 
former go through Channel/Command.pm ("calliope help" from the command 
line lists these), and the latter, which of course comprise the bulk of 
possible requests, all start in Web/Dispatch.pm.  From there, they either 
get handled, or go to one of the other web modules.  Request handles non 
queue-specific requests (history, show an artist, etc.).  Action handles 
queue specific requests, Edit does editing, etc.  web requests in most 
cases do not return to Dispatch, but filter to the appropriate object, 
then get handed to HTML for final output, and the request exits.

many many requests result in a list of songs or albums.  List.pm is the 
core object, and is inherited by Queue (a playing list), ListWeb (a list 
displayed on the web, eg with artists/albums), or QueueWeb (the queue and 
actionqueue displays).  buildList is a key routine that processes a list 
for web output.  I think buildList used to actually add the artist/album/genre 
data to a list of songs, but it may now be that data is added in the requesting 
process before handing off to buildList.  List/ListWeb/Queue/QueueWeb all used 
to be one big mess until a recent re-writing, which is why it's a bit hazy 
in my head ;-)  Thus, the queue held by Jockey *used to* have all the associated 
data, but it was decided that since jockey only plays songs, it doesn't 
need that extra data.  wrong, as you've discovered.

displaying the actionqueue obviously creates a "full" queue, ie a list of 
songs with all the extra data attached, so following an incoming request 
for the actionqueue should help you determine where that data gets added, 
and how to therefore add it in Jockey so that it has the metadata needed.  
clearly, Web/QueueWeb->displayActionQueue displays the right thing, so 
the trick will be to find where the data associated with a song (artist 
etc) gets added into the list - I'd focus on looking at QueueWeb, i think 
it all happens there.

Also, rather than a database module that has 8 trillion different queuries 
spelled out, calliope builds queries on the fly, and uses its own internal 
"language" to represent a request type.  this is a whole separate discussion.  
See calliope/etc/db/README_DB, and try "perldoc Util/DB.pm" for more info 
on this.  To further complicate this, we are probably going to migrate to 
a new way to specify queries, and the DB.pm module's makeWhere has been 
modified.  There are now two ways to specify a query, the second using a 
boolean logic, and though the code is in place to handle such requests, 
there are no examples in calliope that *use* this new method - it's what 
the upcoming release is going to focus on.