ocarina/design.txt

===============================================================================
=                                                                             =
=                                 Ocarina 6.0                                 =
=                                                                             =
===============================================================================

My main goal for Ocarina 6.x is to plan out all of my actions before writing
code.  In the past I was adding features as I thought of them before thinking
out how everything works together, and this made Ocarina difficult to maintain
because I had no overall plan.  This document aims to fix that.

I will also create unit tests as I add features so bugs can be found faster.


Files:
	ocarina/
		design.txt
	ocarina/gui/
	ocarina/include/
		library.h
		playlist.h
	ocarina/lib/
		library.cpp
		playlist.cpp
	ocarina/tests/

	$HOME/.ocarina{-debug}/
		library/global.db
		library/{0-X}



Database: (ocarina.db)
	<Research FTS tables and inverted indexes for filtering>

	Tags index -
		<another FTS table>
		Tag Name -> song ids

	User settings - 
		create table if not exists config(
			name PRIMARY KEY,
			value INT,
		);

Library: (lib/library.cpp)

	This file will manage and control access to the library.

	Album and artist information tables will be saved to a file in
	library/global.db and can be shared across multiple library paths.

Internal:

	struct Album {
		unsigned int id;
		string name;
		short  year;
	};
	vector<Album>;

	struct Artist {
		unsigned int id;
		string name;
	};
	vector<Artist>

struct Track {
	unsigned int id;
	unsigned int artist_id;
	unsigned int album_id;
	bool valid;

	string filepath;
	string title;
	string genre;
	string length_str;
	short track;
	short last_year;
	short last_month;
	short last_day;
	unsigned int play_count;
	unsigned int length;
};

class Library {
	string base_path;
	bool enabled;
	bool valid;
	vector<struct Track>
};

typedef struct trackid_t {
	unsigned int library_id;
	unsigned int track_id;
};



- API
	/* Path management */
	add_path_to_library(dir);
		Add new row to paths table, update
	rm_path_from_library(dir);
		Remove row from paths table
	update_path(dir);
		Scan tracks table, remove paths that don't exist
		Scan dir, add new files to database
		Consider having SQLite create an index on tracks.filepath
	update_all();
		Call update_path() for each paths.dirpath
	list_paths(list<>);
		Tell the caller basic information about library paths
		(dir, enabled, size,...)



Playlist: (lib/playlist.cpp)
	A playlist is a simple list of songs that can be played either randomly
	or in a user-defined order.  It would probably be best to use a linked
	list or vector to represent playlists, rather than creating a SQLite
	table.  I will be able to easily rearrange tracks in the playlist this
	way.  This will also make it easier to deal with playlist renames and
	reordering by the user.

- API
	/* Playlist management */
	new_playlist();
	del_playlist(playlist);
	add_to_playlist(playlist, songid);
	rm_from_playlist(playlist, songid);
	playlist_size(playlist)
	set_flag(playlist, flag)

- Flags
	PL_ENABLED (1 << 0)
	PL_RANDOM  (1 << 1)
	PL_DRAIN   (1 << 2)



Tags:
	Tags will be a new feature in Ocarina 6 and will be a more generic way
	of implementing a banned-songs playlist.  Users will be able to create
	new tags on the fly and add songs to and from them.  I can also use
	an SQLite trigger to manage automatic tags.

	The following tags will be created by default and will not be
	deletable by the user: Artist, Album, Unplayed Songs, Genre

- API
	new_tag(name);
	del_tag(name);
	tag_song(name, songid);
	untag_song(name, songid);
	set_tag_visible(name, visible);