OAA Agent for a song database, version 1.0 (April 2005)

1. WHAT IS THIS?

This is a simple database application using a text file as
database. The application searches a given directory for music files
and makes a database file from the meta information. 


==============================================================


2. REQUIREMENTS.

In order to run this agent you need the following software together with the
appropriate CLASSPATHs and PATHs.


2.1 OAA 2.3

The OAA agent requires OAA to run. If you do not allready have it installed
on your system, download and install it.

Download from: http://www.ai.sri.com/oaa/distribution/v2.3/


2.2 JlGuiPlayer 

In order to get the meta information from the music files, this
application uses JlGuiPlayer. The necessary jar files will be included
in DbaseAgentFiles.jar.

Download JlGui from: http://www.javazoom.net/jlgui/jlgui.html


2.3 Extra jarfiles

Extract all the files in the DbaseAgentFiles.jar file in a chosen
directory. Then extract the jlGuiJars.jar file which contains the
JlGui files needed for this application. 

Make sure the CLASSPATH environment variable points to those jar
files. Either in the java call, or as pre-defined environment
variables.


==============================================================


3. RUNNING THE APPLICATION

3.1 STARTING UP

3.1.1 Starting OAA

An OAA facilitator must be started in order to run the
application. Start an OAA facilitator in accordance with the OAA
specifications. 


3.1.2 Starting the database agent

For a short help text, run the application with the '-h' flag.

java -classpath ${CLASSPATH}:dbaseAgent.jar DbaseAgent -h


The agent could be used in two ways; making a new database file or
using an existing one. When making a new file the user must give a
directory and a file name as arguments in the command line. The flags
used are '-dir' and '-dbfile'.

java -classpath ${CLASSPATH}:dbaseAgent.jar DbaseAgent 
		-dir PathToMusicDir -dbfile PathToPutDbFile 
 
When there exists a database file, no arguments are needed except
OAA arguments(if needed).

java -classpath ${CLASSPATH}:dbaseAgent.jar DbaseAgent {optional OAA arguments} 



The user can also slightly modify the database file when it is created. If the
meta information of a song contains a "'", it cannot be parsed
correctly in the database application. For example, if a song is
called "Hello, I'm here". Open the database file in a text editor and
just put ** first on the relevant line. This will make the application
ignore the line.


3.2 THE SOLVABLES

searchDbase(+DbaseFile,+Query,-Answer)

This is the only solvable available in this application. The user
specifies what database file to use and the search query. So far there
is only one sort of query available which uses unification in order to
find the answer/-s. The query's form is song(ListOfEntries). The
returning Answer is in the form of a list. I.e. an IclList.

The example below shows a query. The order of the entries must be as
shown. All arguments starting with an upper case letter, is a variable
that will unify with the database. The user can instantiate how many
variables he wants when searching.

song([ artist(Artist),
       title(Title),
       ablbum(Album),
       length(SongLengthInSeconds),
       track(TrackNo),
       genre(Genre),
       year(Year),
       bitrate(BitRate),
       samplingrate(SamplingRate),
       comment(Comment),
       path(PathToSong) ] )

The DbaseFileName and the arguments in the query are all IclStr. That
is, Java Strings or Prolog atoms.


Example query 1: returning a list with all songs by Tomas Ledin

searchDbase( 'path_to_dbase',
	     song([ artist('Tomas Ledin'),
		    title(Tit),
		    album(Alb),
		    length(Len),
		    track(Tra),
		    genre(Gen),
		    year(Year),
		    bitrate(Bit),
		    samplingrate(Samp),
		    comment(Com),
		    path(Path)]),
	     Answer)


Example query 2: returning a list with all songs in the genre rock
		 made by the artist Uno Svenningson

searchDbase( 'path_to_dbase',
	     song([ artist('Uno Svenningsson'),
		    title(Tit),
		    album(Alb),
		    length(Len),
		    track(Tra),
		    genre('Rock'),
		    year(Year),
		    bitrate(Bit),
		    samplingrate(Samp),
		    comment(Com),
		    path(Path)]),
	     Answer)