Calliope Net Files

READ ME
CALLIOPE NET v.0.8

Author: Graham McCullough
Last Updated: March 26, 2011

CONTENTS
================================================================================
intro
dependancies
installing
troubleshooting
legal

INTRO
================================================================================
This little program is a bit of a mess. Since it's written in php for a server, 
I can't compile it down into a cute little .exe, you're going to have to figure
out where the pieces go and make it work from there. I've coded it to run from
your server's root, and this document should help you figure out where the files
go without making you get into the code and error logs. I only release versions
that run on my configuration, please email me at graham@lucentwebsitedevelopment.com
if you have any quesions about how to get it up and running, I'll reply as
quickly as possible. Keep in mind that I'm doing this in large part as a learning
experience, so I may not have the answer right away, but I should be able to get
it for you given enough snooping around the internet.

DEPENDANCIES
================================================================================
currently running on:
(Ubuntu,) (Apache2.2.16,) PHP5.3.3, mySQL5.1.49

I'm sure any popular OS would work, and it's possible you can get this up and
running on a Windows IS server, but I'm not going to check. Previous versions
of PHP and mySQL may also work. I haven't tried them. 

INSTALLING
================================================================================
This program NEEDS TO CONNECT TO YOUR mySQL DATABASE! Several files must be 
modified to include the right username and password. The user name and password
information is stored at the top of these files:

	libDisplay.php
	libRefresh.php
	search.php

Next, you must give these scripts some music to make use of, and it must be in
a location your virtual server can host. In the case of Ubuntu, the default
location is /var/www/. Anything in that file is readable unless you chmod it to
some ungodly number. Create a 'music' dirrectory here, (or wherever your server
is set to work from)

	/var/www/music

Once that's done, dump some music in there. This won't work unless it's in the
format /music/artist/album/songs.mp3 The structure should look like this:

	/var/
		www/
			music/
				Jimi Hendrix/
					First Rays Of The Rising Sun/
						Angel.mp3
						Astro Man.mp3 
						Beginnings.mp3
						Belly Button Window.mp3 
						Dolly Dagger.mp3
						Drifting.mp3
						Earth Blues.mp3
						Ezy Ryder.mp3
						Freedom.mp3
						Hey Baby (New Rising Sun).mp3
						In From The Storm.mp3
						Izabella.mp3
						My Friend.mp3 
						Night Bird Flying.mp3 
						Room Full Of Mirrors.mp3
						Stepping Stone.mp3
						Straight Ahead.mp3
					Valleys Of Neptune/
						Bleeding Heart.mp3
						Crying Blue Rain.mp3
						Fire.mp3
						Hear My Train a Comin'.mp3 
				Within Temptation/
					Enter/
						Enter.mp3
					The Silent Force/
						Angels.mp3
						Pale.mp3
						It's the Fear.mp3

Once this is done, you need to make sure that wherever your server is reading
from is the same place the php files actually expect the music to be. You can
change this (I believe) on just one line of code in libRefresh.php

	$musicDir = '/var/www/music/';		//change this if your server is somewhere else.

Now you need to make this stuff readable. When I move files into /var/www in 
Ubuntu, it tends to chmod them to 644 I believe without asking. I'm quite
likely wrong, but whatever happens, it doesn't work with the server, so you
need to change the permissions of the music folder. 777 works for me, if you
know a more secure code that still grants unlimited read, go ahead and use that
instead. Run this from the command line, and modify it so that it reflects
the location of your 'music' folder. The R must be capitalized.

	sudo chmod 777 -R /var/www/music

Using the command line, create a new database and then create a new table with
a songs row with these commands. Feel free to modify whatever you're comfortable
changing:

	mysql -u root -p
	[enter mySQL password for root]
	CREATE DATABASE music
	USE music
	CREATE TABLE library
	(
	songs int
	)\g
	quit

Place the rest of the files in /var/www/ to make this thing run.
	
	CalliopeGraphics		//folder, provides a button image
					//and a favicon

	favicon.ico			//to make the error log shut up

	libDisplay.php			//opens mySQL and reads ALL contents
					//of library table. Ajax'd onto
					//the page

	search.php			//uses a very crude search method to
					//create an html table with results
					//which is ajax'd onto the page.

	libRefresh.php			//drops the library table and rebuilds
					//it by reading through the music
					//folder.

	serverFunctions.php		//links to libRefresh.php, will
					//eventually include other links and
					//functions.

	randomSong.php			//currently returns any random song
					//from the entire library. Needs work.

	CalliopeNet.php			//This file is the main process, it has
					//all of the controlling javascript
					//and calls all of the apropriate php
					//files when they are needed.

Using Chrome (or hypothetically Safari) navigate to 127.0.0.1/CalliopeNet.php
Firefox can't play .mp3 files, and Chromium has a similar problem. Click a song
title or the Next button to make it play a song. Best of luck!
	
TROUBLESHOOTING
================================================================================
If you run into serious problems, email me at at graham@lucentwebsitedevelopment.com
and I'll try to sort you out, or take your chances with the internet. The php
error logger is invaluable.

LEGAL
================================================================================
This program is intended for personal use only. DO NOT USE THIS TO DISTRIBUTE YOUR
MUSIC! This program is licenced with the Creative Commons Attribution-ShareAlike 
3.0 Unported License. Details at http://creativecommons.org/licenses/by-sa/3.0/
This is largely untested software, use it at your own risk.