anna
/
ocarina
1
0
Fork 0
Code Issues 7 Pull Requests Releases Wiki Activity
ocarina/DESIGN

1456 lines
39 KiB
Plaintext
Raw Blame History

===============================================================================
= =
= Ocarina 6.2 =
= =
===============================================================================
Ocarina 6.2 is the 6th implementation of the Ocarina music player - a
lightweight, GTK+ based music player with all the features that I want.
Improvements over the 5.x series will include the existence of both a design
document (this file) and unit tests. This should make maintenance easier and
help me stay focused.
Ocarina 6.2 will use Gstreamer 1.0 for audio playback, GTK-MM 3 for user
interface development, and Taglib for extracting tags.
Install:
Ocarina will be compiled into a single executable placed under
/usr/bin/. Any extra files needed to run will be placed under
/usr/share/ocarina/.
Version:
This file contains a simple function for returning a string stating
the current version. The current version will be set by the build
system and passed using the CONFIG_VERSION macro.
API:
const char *get_version();
Returns a string describing the current version.
Printing:
Sometimes text needs to be printed to the screen so users (or debuggers)
can trace what is going on.
API:
void print(string fmt, ...);
void dprint(string fmt, ...);
Print text to the screen. The dprint() option will only only
be implemented when when CONFIG_DEBUG or CONFIG_TEST is enabled,
and will be an empty function otherwise.
Callbacks:
Callbacks are used to notify a unit test or the gui that something in
the backend has changed. The callbacks structure should be initialized
with no-op default values and filled in by the user through the
get_callbacks() function.
- Callback functions:
struct Callbacks {
void (*on_library_add)(unsigned int, library :: Library *);
void (*on_library_update)(unsigned int, library :: Library *);
void (*on_library_track_add)();
};
static struct Callbacks callbacks;
- API:
struct Callbacks *get_callbacks();
Return the Callbacks structure;
On-disk files:
Data will be stored in the user's home directory according to the
XDG / freedesktop.org specification. This means data will be stored
in a subdirectory of $XDG_DATA_HOME.
The filse class will support reading and writing files in the users
$XDG_CONFIG_HOME/ocarina{-debug|test}.
Items should be written to a file with either a space or new line
separating multiple values.
- Notation:
"File << aaaaa << bbbbb << endl" is translated into "aaaaa bbbbb\n"
- Open mode:
enum OpenMode {
OPEN_READ,
OPEN_WRITE,
NOT_OPEN,
}
- File:
class File : public std::fstream {
private:
unsigned int version;
unsigned int prev_version;
OpenMode mode;
string filename;
public:
File(const std::string &, unsigned int);
~File();
const std::string get_filepath();
const unsigned int get_version();
bool exists();
void open(OpenMode);
void close();
string getline();
}
- File format:
File << FILE_VERSION << endl;
File << <OTHER_DATA>;
- API:
File :: File(const std::string &filename, unsigned int version);
Store the name of the file and the file version.
File :: ~File();
Close the file stream if it is open.
const std::string File :: get_filepath();
If filename == "":
return ""
Otherwise, resolve filepath to one of:
XDG_DATA_HOME/ocarina/filepath
XDG_DATA_HOME/ocarina-debug/filepath
XDG_DATA_HOME/ocarina-test/filepath
and return the result.
const unsigned int File :: get_version();
if mode == OPEN_READ:
return prev_version
return version
bool File :: exists();
Return true if the file exists in the filesystem.
Return false otherwise.
bool File :: open(OpenMode mode);
Return false if:
- filename == ""
- mode == NOT_OPEN
- The file is already open
When opening a file for reading (mode == OPEN_READ),
- Return false if the file does not exist
- Open the file
- Read in prev_version from the start of the file
When opening a file for writing (mode == OPEN_WRITE),
- Create missing directories as needed
- Write version information to the start of the file
Return true on success.
void File :: close();
Close a file after IO.
string File :: getline();
Read an entire line from the file and return it to the caller.
In theory a return value optimization will occur so returning
a string by value won't be a problem.
Database Entry:
The database entry class is a base class used for storing data inside
a database (below). The valid flag and id counter will be managed by
the database itself, and should be initialized to false and 0.
- DatabaseEntry:
class DatabaseEntry {
public:
unsigned int id;
DatabaseEntry();
virtual void ~DatabaseEntry() = 0;
virtual const std::string primary_key() const = 0;
virtual void write(File &) = 0;
virtual void read(File &) = 0;
};
- API:
DatabaseEntry :: DatabaseEntry():
Set id = 0.
const std::string DatabaseEntry :: primary_key() const;
This function should return a unique string representing this
DatabaseEntry instance, which will be used to prevent
duplicates in a database. This string is not expected to
change once a DatabaseEntry has been initialized.
void DatabaseEntry :: write(File &);
This function is called to write a specific DatabaseEntry to
file.
void DatabaseEntry :: read(File &);
This function is called to read a DatabaseEntry from a file.
Database:
Databases are a generic store for information used by Ocarina. Users
need to inherit from a DatabaseEntry class (above) to properly use a
database.
The Database class is a templated class, so code could potentially
get messy. Normal class declarations can still exist in the file
include/database.h and member functions are written in the file
include/database.hpp, which will be included by database.h. Any
function not relying on a template can be written in lib/database.cpp.
- Automatic saving:
Databases can save automatically whenever a new value is inserted or
deleted. This will be more efficient for Databases that do not change
often but will be a huge performance hit for Databases that have many
changes at once. All databases will be loaded automatically from disk.
- Primary keys:
Databases use the primary_key() function of a DatabaseEntry to enforce
uniqueness. This key is used when inserting a new value into the
Database, and will not be updated after.
- Id:
The "id" field of a DatabaseEntry is also managed by the entry's
Database container It will be set to the entry's ID when the entry is
inserted into the database.
- Database:
template <class T>
class Database {
private:
std::vector<T *> _db;
std::map<const std::string, unsigned int> _keys;
unsigned int _size; /* Number of valid rows */
bool _autosave;
File _file;
public:
typedef std::vector<T *>::iterator iterator;
typedef std::vector<T *>::const_iterator const_iterator;
Database(std::string, bool);
~Database();
void save();
void load();
T *insert(const T &);
void remove(unsigned int);
unsigned int size();
unsigned int actual_size();
iterator begin();
iterator end();
iterator next(iterator &);
T *at(unsigned int);
T *find(const std::string &);
};
- File format:
File << db.size() << endl
File << INDEX_0 << db[INDEX_0].valid << db[INDEX_0] << endl;
File << INDEX_1 << db[INDEX_1].valid << db[INDEX_1] << endl;
...
- API:
Database :: Database(std::string filepath, bool autosave);
Initialize a database using "filepath" as a location to store
data on disk. If the file already exists, read the data into
the backing vector.
Database :: ~Database();
Delete all entries remaining in the database.
void Database :: save();
Save the database to disk.
void Database :: load();
Load the database from disk.
T *Database :: insert(const T &item);
Look up the item in the _keys map.
If we find an item with the same key:
- Return NULL.
Otherwise:
- Use new to allocate memory for a new item.
- Add the new item to the end of the _db.
- Add the new item to _keys.
- Set new item.id to the index of the new item.
_ Increment _size.
- If autosave == true: save().
- Return a pointer to the new item.
unsigned int Database :: remove(unsigned int id);
- Remove the item from the _keys map.
- Delete _db[id]
- Set _db[id] = NULL
- If autosave == true: save().
- Decrement _size.
unsigned int Database :: size();
return _size;
unsigned int Database :: actual_size();
return _db.size();
iterator Database :: begin();
Return _db.end() if there are no valid entries
If the first entry is valid:
- return _db.begin();
Otherwise:
- return an iterator to the first valid entry.
iterator Database :: end();
return _db.end();
iterator Database :: next(iterator &cur);
Return the next DatabaseEntry with valid == true or _db.end()
if there are no valid entries left.
T *Database :: at(unsigned int i);
If i is beyond the end of the container:
Return NULL
Otherwise:
Return _db[i];
T *Database :: find(const std::string &key);
If key is in the _keys map:
Return a pointer to the corresponding entry.
Otherwise:
Return NULL;
Index:
An index is a special database used to map a std::string key to
multiple integer values.
- IndexEntry:
class IndexEntry : public DatabaseEntry {
public:
const std::string key;
set<unsigned int> values;
IndexEntry(const std::string &);
const std::string primary_key() const;
void insert(unsigned int);
void remove(unsigned int);
void write(File &);
void read(File &);
};
File << key << endl;
File << values.size() << values[0] << .. << values[N] << endl;
- IndexEntry API:
IndexEntry :: IndexEntry();
Creat an empty IndexEntry.
std::string IndexEntry :: primary_key() const;
return key;
void IndexEntry :: insert(unsigned int value);
Add value to the values set.
void IndexEntry :: remove(unsigned int value);
Remove value from the values set.
void IndexEntry :: write(File &f);
Write the values set to a file.
void IndexEntry :: read(File &f);
Read values from a file.
- Index:
class Index : public Database<IndexEntry> {
public:
Index(const std::string &, bool);
void insert(const std::string &, unsigned int);
void remove(const std::string &, unsigned int);
};
- Index API:
Index :: Index(const std::string &filepath, bool autosave);
Pass values on to the Database constructor.
void Index :: insert(const std::string &key, unsigned int value);
Create an IndexEntry for key if one does not exist yet.
Insert value into the IndexEntry corresponding to key.
If autosave is enabled, save().
void Index :: remove(const std::string &key, unsigned int value);
Remove value from the IndexEntry corresponding to key. Do not
remove the IndexEntry, even if it is empty.
If autosave is enabled, save().
Filter:
Filtering is used to generate a subset of songs displayed by the UI to
that users can choose from. The inverted index is generated at startup
so there is no need for a remove() function, since it will be wiped
the next time the application starts.
- Parsing:
- Scan over the input text to create a list of words using the following
characters as delimiters: \/,;()_-~+"
- While scanning, convert the string to lowercase and strip out any
other special characters.
- API:
std::string filter :: add(const std::string &key, unsigned int track_id);
Parse the key into words following the "Parsing" section above.
Generate substrings for each word and add each (substring,
track_id) pair to the index. Return the lowercased text to the
caller.
To generate substrings, iterate over the word starting from
the front. For example: "goron" would contain the substrings
{g, go, gor, goro, goron}.
std::string filter :: lowercase(const std::string &text);
Parse the text into lowercased words following the "Parsing"
section above. Return the lowercased string to the caller.
void filter :: search(const std::string &text, std::set<track_id> &res);
This function finds all track_ids matching the input text.
Parse the string into substrings and take the intersection of
all sets returned by the index for each substring.
Idle queue:
The idle queue is used to schedule function calls that run at a later
time.
A single queue instance needs to be able to run functions that take
different types of arguments. This is done by creating an IdleBase
base class that the templated IdleTask class inherits from.
- IdleBase:
class IdleBase {
private:
schedule();
public:
IdleBase();
~IdleBase();
virtual void run() = 0;
};
- IdleTask:
template <class T>
class IdleTask : IdleBase {
private:
void (*func)(T &);
T &data;
public:
IdleTask(void (*)(T &), T);
void run();
};
- Queue:
queue<IdleBase *> idle_queue;
float queued = 0.0
float serviced = 0.0
- API:
void IdleBase :: schedule();
Add the idle task to the idle queue. This should be called
by the IdleTask constructor.
queued++;
template <class T>
static inline void idle :: schedule(void (*)(T &), T);
Create a new IdleTask to run the function later.
bool idle :: run_task();
If there are tasks on the queue:
run the next task
scheduled++
If there are still tasks on the queue:
return true
else:
queued = 0
scheduled = 0
return false
float idle :: get_progress();
Return (serviced / queued) to the caller. If there are no
tasks, return 1.0 to indicate that the queue is finished (and
to avoid a divide-by-zero error).
Tag Database:
The tag database is actually several databases that describe every
track added by the user. I do not expect the artist_db, album_db,
genre_db and library_db to change often, so they can be created as
autosaving databases that will write to disk whenever they are changed.
The track_db can have several additions and removals in a row, so the
commit() function is used to control when this db is written to disk,
avoiding the huge performance hit that would come with saving on EVERY
change.
Tags are defined in the sections below.
- Databases:
Database<Artist> artist_db;
Database<Album> album_db;
Database<Genre> genre_db;
Database<Library> library_db;
Database<Track> track_db;
- API:
void tagdb :: init();
Load all databases from disk.
void tagdb :: commit();
Write track_db to disk.
Track *tagdb :: add_track(const std::string &filepath, Library *library);
Add a new track to the track_db and return a pointer to it.
Return NULL if this track is already in the database or if
there is an error when tagging.
Library *tagdb :: add_library(const std::string &filepath);
Add a new path to library_db. Return a pointer to the new path
or return NULL if the path is already in the database.
void tagdb :: remove_track(unsigned int track_id);
Remove the track with id equal to track_id from the track_db.
void tagdb :: remove_library(unsigned int library_id);
Remove all tracks associated with this library from the
track_db, then remove this library from the library_db.
Track *tagdb :: lookup(unsigned int track_id);
Look up the track_id in the track database. Return NULL if
there is no matching track.
Database<Track> &tagdb :: get_track_db();
Return a reference to the track_db.
Database<Library> &tagdb :: get_library_db();
Return a reference to the library_db.
Artist Tag:
The arist tag is used to collect basic information about the various
artists that have been added to the library.
- Artist:
class Artist : public DatabaseEntry {
public:
std::string name;
std::string lower;
Artist();
Artist(const std::string &);
const std::string primary_key() const;
void read(File &);
void write(File &);
};
- File Format:
File << name;
- API:
Artist();
Initialize an invalid Artist instance.
Artist(const std::string &artist_name);
Set artist_name and find the lowercase form.
const std::string Artist :: primary_key() const;
Use artist name as primary key.
void Artist :: read(File &f);
Read artist name from file and find the lowercase form.
void Artist :: write(File &f);
Write artist name to file.
Album Tag:
The album tag is used to collect information about each artist's albums.
- Album:
class Album : public DatabaseEntry {
public:
std::string name;
std::string lower;
unsigned int year;
Album();
Album(const std::string &, unsigned int);
const std::string primary_key() const;
void read(File &);
void write(File &);
};
- File Format:
File << year << name;
- API:
Album();
Initialize an invalid Album instance.
Album(const std::string &album_name, unsigned int album_year);
Set name and year from album name and album_year. Find the
lowercase form of the album name.
const std::string Album :: primary_key() const;
Return the string: "$year.$name"
void Album :: read(File &f);
Read year, and name from file. Then set the lowercase form
of the album name.
void Artist :: write(File &f);
Write album information to file.
Genre Tag:
The genre tag is used to collect basic information about the various
genres of songs in the library.
- Genre:
class Genre : public DatabaseEntry {
public:
std::string genre;
std::string lower;
Genre();
Genre(const std::string &);
const std::string primary_key() const;
void read(File &);
void write(File &);
};
- File Format:
File << name;
- API:
Genre();
Initialize an invalid Genre instance.
Genre(const std::string &genre_name);
Set genre from genre name and find the lowercase form.
const std::string Genre :: primary_key() const;
Use genre as primary key.
void Genre :: read(File &f);
Read genre from file and find the lowercase form.
void Genre :: write(File &f);
Write genre to file.
Library Tag:
The library tag is used to store a single directory added to Ocarina
by the user. It is not an ID3 tag, and is instead something I use
internally to keep track of paths added by the user. The count field
will be managed by the Track tag class.
- Library:
class Library : public DatabaseEntry {
public:
std::string root_path;
unsigned int count;
bool enabled;
Library();
Library(const std::string &);
const std::string primary_key() const;
void read(File &);
void write(File &);
};
- File Format:
File << enabled << root_path
- API:
Library();
Initialize an invalid Library instance.
Set count = 0.
Set enabled = false.
Library(const std::string &path);
Set root_path from the provided path.
Set count = 0.
Set enabled = true.
const std::string Library :: primary_key() const;
Use root_path as the primary key,
void read(File &f);
Read a library path from file.
void write(File &f);
Write a library path to file.
Track Tag:
The track tag is used to store information about a single track in the
user's music collection.
- Sorting:
enum sort_t {
SORT_ARTIST,
SORT_ALBUM,
SORT_COUNT,
SORT_GENRE,
SORT_LENGTH,
SORT_PLAYED,
SORT_TITLE,
SORT_TRACK,
SORT_YEAR,
};
- Track:
class Track : public DatabaseEntry {
public:
Library *library;
Artist *artist;
Album *album;
Genre *genre;
unsigned int track;
unsigned int length;
unsigned int play_count;
unsigned int last_year;
unsigned int last_month;
unsigned int last_day;
std :: string title;
std :: string title_lower;
std :: string filepath;
std :: string length_str;
Track();
Track(const std::string &, Library *);
const std::string primary_key() const;
void read(File &);
void write(File &);
bool tag();
const std::string path();
void played();
bool less_than(Track *, sort_t);
};
- File Format:
File << library->id << artist->id << album->id << genre->id << track;
File << last_year << last_month << last_day << play_count << length;
File << title << endl;
File << filepath << endl;
- API:
Track();
Initialize an invalid Track instance.
Track(const std::string &full_path, Library *lib);
This function will only set up the primary key, and the tag()
function must be called to find audio tags.
- Strip library path from the beginning of full_path and use
the result to set filepath.
- Set library = lib.
const std::string Track :: primary_key() const;
return path();
void read(File &f);
Read track information from file. Look up the corresponding
Library, Artist, Album and Genre pointers. Add title to the
filter and find the string version of length.
void write(File &f);
Write track information to file.
bool Track :: tag();
Use TagLib to find tags and audio properties for this file.
- Insert Artist, Album, and Genre into their databases and
set the corresponding pointers.
- Find title, track number, and length.
- Set play_count, last_year, last_month and last_day = 0.
- Set lowercase title and find the string form of length.
Return true if the track could be tagged and false otherwise.
const std::string Track :: path();
Combine library->path and filepath to find the full path to
the audio file.
void Track :: played();
Called when a track has been played. Increment the play count
and set last_day, last_month, and last_year to today's date.
Call tagdb :: commit() to save the track database.
int Track :: less_than(Track *rhs, sort_t field);
Compare the requested field for this Track instance to the same
field in the provided track.
Return -1 if this < rhs.
Return 0 if this == rhs.
Return 1 if this > rhs.
Random:
The random number generator is used by the Queue to pick a song as
randomly as possible. I use two different RNG implementations,
depending on if Ocarina is compiled with CONFIG_TEST or not.
When CONFIG_TEST is enabled, the RNG is a simple counter. Every time
_pick_random() is called, the counter is incremented and returned.
When compiled without CONFIG_TEST we will return values using the
rand() function from stdlib.h.
- API:
void random_seed(unsigned int n);
Seed the random number generator based on n.
void random(unsigned int min, unsigned int max);
Return a random number between min and max, inclusive.
If min >= max: return min.
Queue:
Queues are lists of songs that the user has requested to play. They
are the main interface for all music played by Ocarina.
- Flags:
enum queue_flag {
Q_ENABLED (1 << 0),
Q_RANDOM (1 << 1),
Q_REPEAT (1 << 2),
Q_NO_SORT (1 << 3),
};
- Sort info:
struct sort_info {
sort_t field;
bool ascending;
};
- Sorting:
Sorting is done using std::stable_sort() to make sure that orders won't
change unexpectedly.
- Queue:
class Queue {
protected:
vector<Track *> _tracks;
list<sort_t> _sort_order;
unsigned int _cur;
unsigned int _flags;
unsigned int _length;
public:
Queue();
Queue(unsigned int);
void read(File &);
void write(File &);
void set_flag(queue_flag);
void unset_flag(queue_flag);
bool has_flag(queue_flag);
unsigned int add(Track *);
void del(Track *);
void del(unsigned int);
void updated(Track *);
Track *next();
unsigned int size();
const std::string size_str();
const std::string length_str();
void sort(sort_t, bool);
Track *operator[](unsigned int);
void track_selected(unsigned int);
};
File Format:
File << flags << tracks.size() << tracks[0] << tracks[1] << ... << tracks[N];
- API
Queue :: Queue();
Initialize _flags = 0, _cur = -1, _length = 0, and empty sort
order.
Queue :: Queue(unsigned int flags);
Initialize _flags = flags, _cur = -1, _length = 0, and empty
sort order.
void Queue :: read(File &f);
Read queue from file.
void Queue :: write(File &f);
Write queue to file.
void Queue :: set_flag(queue_flag f);
Set the appropriate flag.
void Queue :: unset_flag(queue_flag f);
Unset the appropriate flag.
bool Queue :: has_flag(queue_flag f);
Return true if the queue has the flag enabled and false
otherwise.
unsigned int Queue :: add(Track *track);
Add a new track to the tracks vector and return the index.
Increase length by the length of the track.
void Queue :: del(Track *track);
Remove all instances of the requested track from the queue.
void Queue :: del(unsigned int queue_id);
Remove the track at the given index from the queue.
void Queue :: updated(Track *track);
Find all indexes of the updated track and notify the UI that
it has changed.
Track *Queue :: next();
Return the next track to play.
if (tracks.size() == 0)
return NULL;
if (flags & PL_RANDOM):
_cur += rand() % tracks.size();
else:
_cur += 1;
if (_cur >= tracks.size())
_cur -= tracks.size();
track = tracks[_cur];
if (!(flags & PL_REPEAT)):
del(_cur);
return track;
unsigned int Queue :: size();
Return the number of tracks currently on the queue.
const std::string Queue :: size_str();
Return the number of tracks currently on the queue, in string
form.
const std::string Queue :: length_str();
Return the remaining length of the queue in a human-readable
format.
void Queue :: sort(sort_t field, bool reset);
If the field is already in the sort order, toggle its
ascending value. Otherwise, add a new sort field to the end
of the sort order with ascending set to true. If reset is set
to true, clear the sorting list before appending.
Track *Queue :: operator[](unsigned int i);
Return the track and index i.
void Queue :: track_selected(unsigned int queue_id);
Set _cur to queue_id. If PQ_REPEAT is not set, remove the
track from the queue.
Library:
The library is in charge of scanning and updating library paths added
to the tag database. In addition, the library layer is also in charge
of managing a library queue used by the UI. This queue has a special
file format, and will be saved to the file "library.q".
- Queue:
class LibraryQueue : public Queue {
public:
LibraryQueue();
save();
load();
set_flag(queue_flag);
unset_flag(queue_flag);
sort(sort_t, bool);
};
File << flags << _sort_order.size()
File << _sort_order[N].field << _sort_order[N].ascending << ...
- Validation:
Use a single idle function to loop over each track in the track
database. Check if the track still exists in the filesystem and remove
it from the tagdb if not.
- Updating:
Scan over all files in the current directory directory.
For each encountered directory:
Use the idle queue to call the update function with the new
directory as the "current" directory.
For each encountered file:
Attempt to add the file to the track_db.
Commit the database if at least one new file has been added.
- 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.
To test importing, create several mock library files and copy them to
~/.ocarina-test/library/ and attempt to read them in.
- LibraryQueue API:
LibraryQueue :: LibraryQueue();
Initialize a Queue with the flags Q_ENABLED and Q_REPEAT. The
default sorting order should be artist, year, track.
LibraryQueue :: save();
Write a library queue to disk.
LibraryQueue :: load();
Read a library queue from disk.
LibraryQueue :: set_flag(queue_flag f);
LibraryQueue :: unset_flag(queue_flag f);
LibraryQueue :: sort(sort_t field, bool reset);
These functions are wrappers around the default Queue
implementation. First call the original function, then use
save() to store the changes.
- API
void library :: init();
Scan the tagdb track list, and add each track to the library
queue.
Library *library :: add(string dir);
If dir is not a directory:
return NULL
Add a new path to the tag database, trigger an update, and
then return the corresponding Library tag to the caller.
void library :: remove(Library *library);
Invalidate a library_db row and all tracks owned by that path.
Do not use the library pointer after calling this function.
void library :: update(Library *library);
First, validate all tracks in the given library.
Next, trigger an update on the given library.
void library :: update_all();
Update all valid library paths.
void library :: set_enabled(Library *library, bool enabled);
Toggle if a library path is enabled or not. A disabled
library path will have its tracks removed from the
LibraryQueue.
Queue *library :: get_queue();
Return the LibraryQueue to the caller.
Playlist:
Playlists are a new feature in Ocarina 6 and are modeled after Gmail
labels. Ocarina 6.2 will support two different playlists that the
user can add tracks to: banned and favorites.
The playlist layer will maintain a queue that is used by the UI to
display tracks in a given playlist. This queue is inherited from
the base Queue class to provide extra features.
Future releases will add support for more playlists.
- Index:
Index playlist_db("playlist.db", true);
- Queue:
class PlaylistQueue : public Queue {
public:
PlaylistQueue();
fill(IndexEntry *);
};
- Default playlists:
Favorites:
The user will add music they really like to this playlist.
Banned:
The user should add music they do not like to this playlist.
Tracks should be removed from the Library playqueue when they
are banned and added back to the playqueue when they are
un-banned.
- PlaylistQueue API:
PlaylistQueue :: PlaylistQueue();
Initialize a Queue with the flags Q_ENABLED, Q_REPEAT, and
Q_NO_SORT set. Default sorting order should be artist, year,
track.
PlaylistQueue :: fill(IndexEntry *ent);
Remove all tracks in the queue and repopulate using ent.
- API
void playlist :: init():
Load the playlist index from file. Remove every banned song
from the LibraryQueue in the library layer.
void playlist :: add(Track *track, const std::string &name);
Add track->id to the playlist named "name" and return true.
Return false if the playlist does not exist.
If "name" is the currently selected playlist, add the track
to the PlaylistQueue.
If "name" is "Banned", remove the track from the LibraryQueue
in the library layer.
void playlist :: del(Track *track, const std::string &name);
Remove track->id from the playlist named "name" and return true.
Return false if the playlist does not exist or if the track
is not in the playlist.
If "name" is the currently selected playlist, remove the track
from the PlaylistQueue.
If "name" is "Banned", add the track to the LibraryQueue in the
library layer.
bool playlist :: has(Track *track, const std::string &name);
Return true if the chosen playlist has the given track.
Return false otherwise.
void playlist :: select(const std::string &name);
Change the currently displayed playlist to "name".
const IndexEntry *playlist :: get_tracks(const std::string &name);
Return the IndexEntry represeting the requested playlist.
Return NULL if the requested playlist does not exist.
Queue *playlist :: get_queue();
Return the PlaylistQueue to the caller.
Deck:
The deck is used to hold temporary queues created by the user. This
layer is also in charge of maintaining a "recently played" queue of
tracks.
The deck will be saved to the file "deck". When upgrading from file
version V0 to V1, use the saved random flag and sort order to set up
the library_q.
- TempQueue:
class TempQueue : public Queue {
public:
TempQueue(bool);
void set_flag(queue_flag);
void unset_flag(queue_flag);
unsigned int add(Track *);
void del(Track *);
void del(unsigned int);
void sort(sort_t, bool);
};
- Deck:
list<TempQueue> deck;
V0:
File << library_q.random << library_q.sort_order().size();
File << lib12order()[N].field << lib12order()[N].ascending;
File << deck.size() << endl;
File << deck[0] << endl;
File << deck[N] << endl;
V1:
File << deck.size() << endl;
File << deck[0] << endl;
File << deck[1] << endl;
- RecentQueue:
class RecentQueue : public Queue {
public:
RecentQueue();
unsigned int add(Track *);
};
- TempQueue API:
TempQueue :: TempQueue(bool random);
Initialize a new TempQueue with the flag Q_ENABLED set.
If random is True then also set the Q_RANDOM flag.
void TempQueue :: set_flag(queue_flag flag);
void TempQueue :: unset_flag(queue_flag flag);
unsigned int TempQueue :: add(Track *track);
void TempQueue :: del(Track *track);
void TempQueue :: del(unsigned int index);
void TempQueue :: sort(sort_t field, bool ascending);
These functions are all wrappers around the basic Queue
functions of the same name. First, call the corresponding
Queue :: <whatever>() function to make the correct Queue
modification. Then, call deck :: write() to save changes to
disk.
- RecentQueue API:
RecentQueue :: RecentQueue();
Initialize a Queue with the flags Q_ENABLED, Q_REPEAT, and
Q_NO_SORT set.
unsigned int RecentQueue :: add(Track *track);
The RecentQueue is designed to be a uniqueue queue that displays
the most recent tracks first.
del(track);
_cur = 0;
return _add_at(track, 0);
- API
void deck :: init();
Read the deck file from disk and restore the queues.
void deck :: write(File &);
Read or write the playqueue file. This will be called
from the audio layer to store state.
Queue *deck :: create(bool random);
Adds a new queue to the end of the deck and return a pointer
to it. Save the deck to disk.
void deck :: destroy(Queue *queue);
Remove the requested queue from the deck and trigger the
on_pq_removed() callback. Save the deck to disk.
void deck :: move(Queue *queue, unsigned int pos);
Move the queue to the new location in the deck. Save the deck
to disk.
unsigned int deck :: index(Queue *queue);
Return the index of the queue in the deck or deck.size() if
the queue is not currently in the deck.
Queue *deck :: get(unsigned int index);
Return the queue at the requested index, or NULL if no queue
is found.
Track *deck :: next();
Find the first enabled queue on the deck and return the track
given by queue->next().
If the queue is empty after calling next(), call destroy() to
remove it from the list.
If there are no enabled queues, return a track from the library
queue. If the library queue is empty, return NULL.
If the result is non-NULL, add the found track to the recent
queue.
Save the deck before returning.
Track *deck :: prev();
Return the track given by recent_queue->next(). If the recent
queue is empty, return NULL.
list<Queue> &deck :: get_queues();
Return the list of queues to the caller.
Queue *deck :: get_queue();
Return the RecentQueue to the caller.
Audio Driver:
The audio driver creates a way to fake audio playback for testing. This
will allow for more accurate tests, since I will know in advance what
values are returned to the Audio layer. This layer will derive from
the Driver class to implement either the GSTDriver or the TestDriver.
- Seconds -> Nanoseconds conversion:
static const unsigned long O_SECOND = 1000000000;
- Driver:
class Driver {
protected:
void (*on_eos)();
public:
Driver();
~Driver();
virtual void init(int *, char ***, void (*)(), void (*)()) = 0;
virtual void load(const std::string &) = 0;
virtual void play() = 0;
virtual void pause() = 0;
virtual void is_playing() = 0;
virtual void seek_to(long) = 0;
virtual long position() = 0;
virtual long duration() = 0
};
- Driver API:
void Driver :: Driver();
Initialize the audio driver. This involves setting up a GST
Bus in the GSTDriver case.
void Driver :: ~Driver();
In the GSTDriver case, call gst_deinit() to avoid memory leak
false positives.
void Driver :: init(int argc, char **argv, void (*eos_cb)(),
void (*error_cb)());
The GSTDriver will use this function to set up the playbin2.
When an end-of-stream message is received, call eos_cb().
If there is an error, call error_cb();
void Driver :: load(const std::string &file);
Load file for playback, but do not begin playback yet.
void Driver :: play();
Start playback. Return true if the state change operation
succeeds, false otherwise.
void Driver :: pause();
Pause playback. Return true if the state change operation
succeeds, false otherwise.
bool Driver :: is_playing();
Return true if the player is currently playing, false otherwise.
void Driver :: seek_to(long pos);
Change playback position in the current track in nanoseconds.
long Driver :: position();
Return the current position in the track in nanoseconds.
long Driver :: duration();
Return the duration of the track in nanoseconds.
- API:
Driver *driver :: get_driver();
Return the current driver to be used for audio playback. This
could be either the GSTDriver or the TestDriver depending on
if CONFIG_TEST is set when compiling.
Audio:
The audio layer uses the configured driver to control audio playback.
Gstreamer options passed to audio :: init() can be found by running
`gst-inspect-1.0 --help-gst` on the command line.
- File:
File cur_track("cur_track");
File << current_track->id << endl;
- API:
void audio :: init(int *argc, char ***argv);
Initialize the audio driver through argc and argv. Read in
the current track file and load the track.
void audio :: play();
void audio :: pause();
void audio :: seek_to(long pos);
Call the corresponding function from the audio driver, but only
if a track is loaded.
void audio :: stop();
pause()
seek_to(0)
long audio :: position();
long audio :: duration();
Call the corresponding function from the audio driver. Return
0 if no track is currently loaded.
std::string audio :: position_str();
Return the current audio position in string form.
Return an empty string if there is no current track.
void audio :: next();
Call the deck :: next() function to get the next track that
should be played and use the audio driver to load the track.
Save that track's ID to the cur_track file.
void audio :: prev();
Call the deck :: previous() function to find a new track to
play and use the audio driver to load the track.
Save that track's ID to the cur_track file.
void audio :: load_track(Track *track);
Load the requested track.
Save that track's ID to the cur_track file.
Track *audio :: current_track();
Return the currently playing Track.
Return NULL if there is no current track.
void audio :: pause_after(bool enabled, unsigned int N);
If enabled == true:
Configure Ocarina to pause playback after N tracks
have been played.
If enabled == false:
Do not automatically pause.
If N is greater than the current pause count then enabled should
be set to true.
bool audio :: pause_enabled();
unsigned int audio :: pause_count();
Use these functions to access the current "pause after N" state.
Gui: (ocarina/*)
The GUI will be written in C++ using gtkmm3 for (hopefully) cleaner code.
- Design requirements:
- gtkmm3
- Front-end for the library to add, remove and modify paths
- This can be hidden since it's not a common task
- Double-click to play songs
- Front-end for groups to add and remove tracks
- This is a common task and should not be hidden
- Don't save / restore window size
- Some window managers already do this automatically
- Set reasonable defaults
Reference in New Issue View Git Blame Copy Permalink