ocarina/design/library.txt

== Files ==
	ocarina/include/
		library.h
	ocarina/lib/
		library.cpp
	$HOME/.ocarina{-debug}/
		album.db
		artist.db
		genre.db
		library.db
		track.db

== Depends ==
idle database groups filter

Library: (lib/library.cpp)
	The library manages databases containing track information added by the
	user.  Ocarina 6 splits the library into multiple database tables for
	storing content.  The library will exist in a library namespace to
	to make functions and classes more unique.

	When a library : Track is created, it should be added to the "Library"
	group if it is NOT a member of the banned songs group.

- Databases:
	enum DB_Type {
		DB_ALBUM,
		DB_ARTIST,
		DB_GENRE,
		DB_LIBRARY,
		DB_TRACK,
	};

- Album:
	class library :: Album : public DatabaseEntry {
	public:
		string name;
		unsigned int year;
		unsigned int artist_id;
	};

	File << artist_id << year << name

- Artist:
	class library :: Artist : public DatabaseEntry {
	public:
		string name;
	};

	File << name

- Genre:
	class library :: Genre : public DatabaseEntry {
	public:
		string name;
	};

	File << name

- Library:
	class library :: Library : public DatabaseEntry {
	public:
		string root_path;
		bool enabled;
	};

	File << enabled << root_path

- Track:
	class library :: Track : public DatabaseEntry {
	public:
		unsigned int library_id;
		unsigned int artist_id;
		unsigned int album_id;
		unsigned int genre_id;

		unsigned int track;
		unsigned int last_year;
		unsigned int last_month;
		unsigned int last_day;
		unsigned int play_count;
		unsigned int length;

		bool banned;
		string title;
		string length_str;
		string filepath;
	};

	File << library_id << artist_id << album_id << genre_id << track << last_year
	File << last_month << last_day << play_count << length << banned << endl
	File << title << endl;
	File << filepath << endl;

- Track: /* This struct lies outside the library namespace */
	struct Track {
		library :: Album   *album;
		library :: Artist  *artist;
		library :: Genre   *genre;
		library :: Library *library;
		library :: Track   *track;
	};

- Databases:
	Database<library :: Album>   album_db(album.db);
	Database<library :: Artist>  artist_db(artist.db);
	Database<library :: Genre>   genre_db(genre.db);
	Database<library :: Library> library_db(library.db);
	Database<library :: Track>   track_db(track.db);

- Updating algorithm:
	set<pair<lib_id, track_path>> known_tracks;

	1) For each track currently in the library, check if the track exists
	   in the filesystem.
	   1a) If the track does exist, add to the known_tracks map.
	   1b) Else, mark track invalid.
	2) For each file in the scan directory, check if (lib_id, track_path)
	   exists in the known_tracks map.
	   2a) If the file is in the map, do nothing.
	   2b) Else, add track to the library, to the groups "All Music" and
	       "Library", and then to the filter index.
	3) Save all databases

	The taglib library should be used for finding artist, album, etc. tags
	for each track.

	Use idle tasks for step 2 to break up tagging new files into chunks.
	This way the user will still be able to use Ocarina and scanning can
	happen while idle.

- Testing:
	The script tests/library/gen_library.sh will create a sample library
	in the /tmp/ directory for testing purposes.  All the track files are
	complete silence, but the script will fake up tags for each file.

- API
	void library :: init();
		Initialize databases and read files from disk.  Fill out
		groups and prepare filter as tracks are read.

	bool library :: add_path(string dir);
		If dir is not a directory:
			return false

		Add new row to the library_db table, begin an update only
		on the new path.
		return true

	void library :: del_path(unsigned int lib_id);
		Invalidate a library_db row and all tracks owned by that path

	void library :: update_path(lib_id);
		Update the given library_db row, if valid.

	struct Track library :: lookup(track_id)
		Fill out a Track structure for the provided track_id

#ifdef CONFIG_DEBUG
	void library :: print_db(DB_Type);
		Print the database corresponding to DB_Type

	void library :: reset();
		Clear all databases, returning the library to an empty state.
endif /* CONFIG_DEBUG */