Filesystem::Library Class Reference

Filesystem-specific media library. More...

#include <filesystem.h>

Inheritance diagram for Filesystem::Library:

Collaboration diagram for Filesystem::Library:

Classes
struct	ScanWorkItem
	Structure for storing lists of pending file scanning. More...

Public Member Functions
	Library (Media::Source *const owner, const bool persistence, const std::string directory, const MusicLibrary::ScanFrequency behavior)
	Construct a library for filesystem media. More...
const std::string &	path ()
float	periodic ()
	Background tasks: More...
bool	checkValidity ()
	Validate that a filesystem souce is available. More...
void	startScan ()
	Initiate a scan to update the catalog with new/changed media. More...
void	clear ()
	Remove all indexed contents from the library. More...
bool	scanDirectory (const std::string &path)
	Queue a directory for addition to the library catalog. More...
void	indexFile (const std::string &path)
	Add a file to the library catalog, generating IDs based on data so they remain persistent in case the index is destroyed. More...
Public Member Functions inherited from MusicLibrary::Library
virtual bool	removePlaylist (Playlist *play) override
	Remove a playlist from the library. More...
virtual ThingieList	seedsForPlaylist (const Playlist *playlist) override
	Retrieve a list of seeds for a playlist. More...
virtual RetainedList< Song * >	getAllSongs (void) override
	Get a list of all songs in the library. More...
virtual RetainedList< Song * >	getMatchingSongs (const Filter &criteria) override
	Get a list of all songs matching a filter. More...
ThingieList	getSuggestions (const Filter &criteria, SearchRange what)
	Retrieve suggestions from the library. More...
RetainedList< Song * >	getMixSongs (void)
	Get a list of all songs belonging to enabled playlists. More...
virtual RetainedList< Song * >	getPlaylistSongs (const Playlist *play, bool reassess=false) override
	Get a list of all songs assigned to a playlist. More...
Playlist *	findPlaylistForSong (Song *song, bool enabled=true)
	Find a playlist for a song, preferring enabled playlists. More...
virtual void	populatePlaylist (Playlist *play, bool aggressive=false) override
	Review songs and assign them to a new candidate if they match. More...
void	unpopulatePlaylist (Playlist *play)
	Reassign all a playlists' songs to some other playlist. More...
void	mixRecalculate (void)
	Iterate over every song and replace its playlist assignment. More...
MusicThingie *	getById (MusicThingie::Type type, const std::string &id)
	Retrieve anything stored in the library by its ID. More...
virtual RetainedList< Song * >	getSongsForPlaylist (PianodPlaylist *playlist) override
	Retrieve all songs for a playlist, which may be a meta playlist. More...
PianodPlaylist *	createPlaylist (const std::string &name, MusicThingie::Type type, MusicThingie *from)
	Construct a playlist with an initial seed. More...
PianodPlaylist *	createPlaylist (const std::string &name, const Filter &filter)
	Construct a new smart playlist. More...
PianodPlaylist *	formTransientPlaylist (const Filter &criteria)
	Construct a temporary playlist. More...
virtual bool	writeIndexToFile (const std::string &filename) const override
	Persist the library's index into a file. More...
virtual bool	restoreIndexFromFile (const std::string &filename) override
	Restore the library's index, playlists, seeds and match criteria from a file. More...
Public Member Functions inherited from MusicLibrary::Foundation
	Foundation (Media::Source *const owner, const bool persistence)
	Construct a new media library. More...
void	markDirty (IMPORTANCE import=TRIVIAL) const
bool	load ()
	Restore persisted library data from a file. More...
bool	flush ()
	If memory is dirty, write library data to a file. More...
float	periodic ()
	Do intermittent tasks, such as occasionally persisting the catalog to a file. More...
RetainedList< Song * >	getRandomSongs (PianodPlaylist *playlist, const UserList &users, Media::SelectionMethod selectionMethod, const class LibraryParameters &settings)
	Retrieve some random selections from the library for queue/playback. More...

Protected Member Functions
void	purge ()
	Remove missing songs from the library. More...
virtual void	persist (Parsnip::Data &into) const override
virtual bool	restore (const Parsnip::Data &data) override
Protected Member Functions inherited from MusicLibrary::Library
	Library (Media::Source *const owner, const bool persistence, const SongAllocator &song_allocator=SongAllocator {song_allocate}, const AlbumAllocator &album_allocator=AlbumAllocator {album_allocate}, const ArtistAllocator &artist_allocator=ArtistAllocator {artist_allocate}, const PlaylistAllocator &playlist_allocator=PlaylistAllocator {playlist_allocate})
	Construct a library. More...
void	purge (void)
	Remove albums & artists from the library that don't have any songs & albums respectively. More...

Private Types
enum class	ScanItemType { DIRECTORY , FILE }
	Types of items to scan when indexing media on a filesystem. More...
using	base_library = MusicLibrary::Library
using	ScanFrequency = MusicLibrary::ScanFrequency
typedef std::list< ScanWorkItem >	SearchList
	Pending files to be scanned. Items are processed in LIFO (stack) order. More...

Private Attributes
friend	Source
friend	Song
std::string	_path
time_t	last_scan = 0
bool	links_warned = false
bool	permissions_warned = false
time_t	next_validity_check = 0
bool	valid = false
ScanFrequency	scan_behavior
SearchList	searches

Additional Inherited Members
Public Types inherited from MusicLibrary::Library
using	ArtistAllocator = ArtistContainer::Allocator
using	AlbumAllocator = AlbumContainer::Allocator
using	SongAllocator = SongContainer::Allocator
using	PlaylistAllocator = PlaylistContainer::Allocator
Public Types inherited from MusicLibrary::Foundation
enum	IMPORTANCE { IMPORTANT = 300 , NOMINAL = 1800 , TRIVIAL = 60 * 60 * 6 }
Public Attributes inherited from MusicLibrary::Foundation
Media::Source *const	source
Protected Attributes inherited from MusicLibrary::Library
ArtistContainer	artists
AlbumContainer	albums
SongContainer	songs
PlaylistContainer	playlists

Detailed Description

Filesystem-specific media library.

Member Typedef Documentation

base_library

using Filesystem::Library::base_library = MusicLibrary::Library

private

ScanFrequency

using Filesystem::Library::ScanFrequency = MusicLibrary::ScanFrequency

private

SearchList

typedef std::list<ScanWorkItem> Filesystem::Library::SearchList

private

Pending files to be scanned. Items are processed in LIFO (stack) order.

Member Enumeration Documentation

ScanItemType

enum Filesystem::Library::ScanItemType

strongprivate

Types of items to scan when indexing media on a filesystem.

Enumerator
DIRECTORY
FILE

Constructor & Destructor Documentation

Library()

Filesystem::Library::Library	(	Media::Source *const	owner,
		const bool	persistence,
		const std::string	directory,
		const MusicLibrary::ScanFrequency	behavior
	)

Construct a library for filesystem media.

Parameters

owner	The source that owns the library.
persistence	If true, library contents should be persisted.
directory	The path to media files.
behavior	Indicates when to search for new media.

Here is the call graph for this function:

Member Function Documentation

checkValidity()

bool Filesystem::Library::checkValidity

(

)

Validate that a filesystem souce is available.

If the filesystem is missing, make the source invalid; when it becomes available, make it valid and start indexing it.

Here is the call graph for this function:

Here is the caller graph for this function:

clear()

void Filesystem::Library::clear

(

)

Remove all indexed contents from the library.

Here is the call graph for this function:

Here is the caller graph for this function:

indexFile()

void Filesystem::Library::indexFile

(

const std::string &

path

)

Add a file to the library catalog, generating IDs based on data so they remain persistent in case the index is destroyed.

• Album:
  1. use unique album ID, such as CDDB ID.
  2. ifnotfound or collision, use hash of album name.
  3. if collision, use randomly assigned.
• Artist:
  1. if album is compilation*, use dedicated compilation artist (acomp) and store artist name with track data.
  2. otherwise, ID is hash of artist name.
  3. Collisions do not apply to artists.
• Song:
  1. if track has a number, use album ID + track #.
  2. otherwise, hash the album name and track name.
  3. if collision, use randomly assigned ID. Albums are always non-compilations when their first track is added. When the additional tracks are added, if the artist differs, then the album is converted to a compilation.

     Parameters

     path	The pathname of the file to index.

Here is the call graph for this function:

Here is the caller graph for this function:

path()

const std::string& Filesystem::Library::path ( )

inline

Here is the caller graph for this function:

periodic()

float Filesystem::Library::periodic

(

void

)

Background tasks:

• Flush dirty data files periodically.
• If scanning, process one file or directory.

  Returns

  Number of seconds until next service is requested.

Here is the call graph for this function:

Here is the caller graph for this function:

persist()

void Filesystem::Library::persist ( Parsnip::Data &  into ) const

overrideprotectedvirtual

Reimplemented from MusicLibrary::Foundation.

purge()

void Filesystem::Library::purge ( void  )

protected

Remove missing songs from the library.

Invoked after a scan, removes all songs not present during the scan.

Here is the call graph for this function:

Here is the caller graph for this function:

restore()

bool Filesystem::Library::restore ( const Parsnip::Data &  data )

overrideprotectedvirtual

Reimplemented from MusicLibrary::Foundation.

Here is the call graph for this function:

scanDirectory()

bool Filesystem::Library::scanDirectory

(

const std::string &

path

)

Queue a directory for addition to the library catalog.

• Files are added to the scan list.
• Subdirectories (not . and ..) are added to the scan list.
• Symbolic links, generate a single warning that they are ignored.
• Devices, fifos, sockets and other weirdness are silently ignored. Future work is pushed onto the work list, rather than queued; maximum work list size is filesystem depth + longest directory whereas queueing could result in a much larger list.

  Parameters

  path	The directory to process.

Here is the call graph for this function:

Here is the caller graph for this function:

startScan()

void Filesystem::Library::startScan

(

)

Initiate a scan to update the catalog with new/changed media.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

_path

std::string Filesystem::Library::_path

private

last_scan

time_t Filesystem::Library::last_scan = 0

private

links_warned

bool Filesystem::Library::links_warned = false

private

next_validity_check

time_t Filesystem::Library::next_validity_check = 0

private

permissions_warned

bool Filesystem::Library::permissions_warned = false

private

scan_behavior

ScanFrequency Filesystem::Library::scan_behavior

private

searches

SearchList Filesystem::Library::searches

private

Song

friend Filesystem::Library::Song

private

Source

friend Filesystem::Library::Source

private

valid

bool Filesystem::Library::valid = false

private

---

The documentation for this class was generated from the following files:

• mediaunits/filesystem/filesystem.h
• mediaunits/filesystem/filesystem.cpp