This file describes the contents of /q/cherry/proj/cherry.

Last updated: 2004-11-19 by mim

Directories
-----------
./
artist_moods
bin
doc
libraries
matlab
moods
mp3s



./
----
mostly contains other directories, but also a couple of files:

gmms.mat is all of the gmms extracted so far and the names of the
  mp3s for which they have been extracted.  The gmms are in the
  variable G and the names are in the variable "names".

mood_ids is a list of moods and their corresponding amg sql numbers,
  separated by tabs



Artist_moods
------------
This is a side project of mim's to try to infer from a similarity
matrix and a list of artist/album moods the moods of the individual
songs.


Bin
---
contains perl scripts for collecting and parsing metadata from amg

am2m.pl 
  Part of the artist_moods side project. takes the file
  artist_moods/artist_moods1 and from it creates a list of all of the
  artists, all of the moods, and a translation from words to numbers
  of the artist_moods1 file.

artist_moods.pl 
  Also part of the artist_moods side project.  Gets the moods of all
  of the artists listed in the first argument (a filename)

get_amg_moods.pl 
  Gets a list of all of the moods on amg and their corresponding ID
  numbers

get_mood_songs.pl 
  Gets a list of mood IDs and mood names from stdin and downloads the
  amg's list of "top songs" (or at least the first page's worth),
  putting the list in a file named with the name of the mood in the
  moods directory.

merge_playola.pl 
  Loads all of the mp3 files we know about into a big hash, then scans
  through all of the songs we want from the files in the moods
  directory.  Any song that we want that we have somewhere gets
  recorded in the file libraries/we_have.  Once all of the counts are
  in, any mood for which we have more than a threshold amount gets all
  of its songs added to libraries/we_have_best.  Run with the command
  "LANG=C ./bin/merge_playola.pl" so unicode characters don't mess
  things up.

organize_mp3s.pl
  Translates between the file names listed in the we_have file and the
  libraries directory and the [artist]-[song].mp3 format of the mp3s
  directory.  Copies any song it finds at that translated path to the
  mp3s directory as long as it's not already in the mp3s directory.

wh2m.pl
  Parse the file created by merge_playola.pl into a matlab readable
  form, the files libraries/{song_list,mood_list,smnums}



Doc
---
Contains our proposal and some notes



Libraries
---------
Contains files relating to where mp3s are and what we still need to
get.

listing-*
  Is just a list of all of the mp3s in each of the people's
  collections.  The script merge_playola.pl has a separate function
  for each listing file customized to extract the album, artist, song,
  and filename for each one.  They are all paths relative to different
  things, so any filename coming out of them needs to be translated by
  organize_mp3s.pl into something useable.

mp3s_to_get*
  Is a list of which mp3s to get from where.  Basically the same as
  the listing files, but without the extra artist, song, and mood
  fields.

we_have and we_have_best
  Are described above under merge_playola.pl

song_list, mood_list, and smnums
  Are described above under wh2m.pl

not_found_adam
  All of the songs that were supposed to be in playola but weren't.
  Should probably take them out of the listing-adam file.


Matlab
------
All of our matlab scripts.  Some are pretty static, hard coded to do
one specific thing, others are helper functions.

loadfeat.m
  Load the features from gmms.mat, returning a matrix of features.
  Should also be extended to load other features from disparate
  sources once we have them extracted.

loadgt.m
  Load the ground truth data (which songs are in which categories)
  from the files created by wh2m.pl

mfc2gmm.m
  Main training script.  Finds all of the mp3s that haven't been
  trained on yet (aren't yet in gmms.mat) and extracts mfcc
  coefficients on which it trains GMM models, saving the file gmms.mat
  as it goes.

netlab
  This is a link to matlab files in adam's home directory.  It
  contains the gmm code.

orderCell.m
  This is my hackish way of aligning lists of filenames so that the
  features and ground truth are in the same order.  Maybe should be a
  subfunction in loadgt.m

osu_svm
  Directory containing all of the scripts from Ohio State's SVM matlab
  package

seen.m
  Something resembling a tiny bit a hash table lookup.  Compares one
  string against a cell array of strings to see if it's there.  Used
  by orderCell.m to align arrays of strings and mfc2gmm to avoid
  calculating coefficients for files it's already seen.

tempo.m
  A tempo extractor based on Eric Schierer's paper but using an FFT
  instead of a comb filterbank.

textarray.m
  A script of Adam's for loading a stream of tokens from a text file
  into a 1D cell array.

trnmodels.m
  Adam's script for training his gmms on mfccs and anchor features.
  Here only for reference on how to use netlab's gmms.


Moods
-----
Has one file per mood, named with the name of the mood (minus any
special characters and spaces).  Each file contains the top 50 songs
that amg considers representative of that mood.  Every line of the
files is of the form [artist]\t[song]\t[hash] where I don't really
know what the hash is, but it somehow allows amg to find the page for
you.  The same song often gets multiple hashes, and a few days later
the hash points to a different song, so they're probably all bad by
now, but I included them for some sort of completeness.

Also contains a subdirectory "by_hand" where I put the data I
collected by hand from the amg web pages.  They also contain links to
similar moods, but aren't formatted nearly as nicely as the official
moods files.



MP3s
----

contains all of the mp3s we've got so far in files named
[artist]-[song].mp3.  Also contains the directory "todo" for mp3s we
haven't cannonicalized yet





SVM Interface
-------------
the SVM structure will have the following fields:
features, labels, shown, AlphaY, SVs, Bias, Parameters, nSV, nLabel

features 
  is the matrix of features, with one row per song

labels 
  is a vector of {-1,0,1}'s where -1 is a negative example, +1 is a
  positive example, and 0 is neither negative nor positive.  All
  entries start out as 0.

shown 
  is a binary vector representing whether the user has been shown each
  song yet.  1 means they have been shown it.

The remaining fields are created by the OSU SVM package


Functions for the SVM:
svm = seed(song, features)
songs = getResults(svm, N);
songs = getTraining(svm, N);
svm = setLabels(svm, songs, labels);

seed 
  initializes the svm and sets everything up.  song is the seed song,
  the first positive example of what the user is looking for.
  Features is the matrix of features, kept in the svm structure for
  easy learning and convenience.m

getResults
  returns the indices of the N songs furthest from the decision
  boundary of the svm

getTraining
  returns the indices of the N songs closest to the decision boundary
  of the svm

setLabels
  Is how the user responds to the svm, setting the songs listed in the
  vector songs to the corrsponding labels in the vector labels.  It
  returns a new svm which is a modified version of the old one.
