Struct bliss_audio::library::Library

pub struct Library<Config> {
    pub config: Config,
    pub sqlite_conn: Arc<Mutex<Connection>>,
}

A struct used to hold a collection of Songs, with convenience methods to add, remove and update songs.

Provide it either the BaseConfig, or a Config extending BaseConfig. TODO code example

Fields

config: Config

The configuration struct, containing both information from BaseConfig as well as user-defined values.

sqlite_conn: Arc<Mutex<Connection>>

SQL connection to the database.

Implementations

impl<Config: AppConfigTrait> Library<Config>

pub fn new(config: Config) -> Result<Self>

Create a new Library object from the given Config struct that implements the AppConfigTrait. writing the configuration to the file given in config.config_path.

This function should only be called once, when a user wishes to create a completely new “library”. Otherwise, load an existing library file using Library::from_config_path.

pub fn from_config_path(config_path: Option<PathBuf>) -> Result<Self>

Load a library from a configuration path.

If no configuration path is provided, the path is set using default data folder path.

pub fn version_sanity_check(&mut self) -> Result<bool>

Check whether the library contains songs analyzed with different, incompatible versions of bliss.

Returns true if the database is clean (only one version of the features), and false otherwise.

pub fn new_from_base( config_path: Option<PathBuf>, database_path: Option<PathBuf>, number_cores: Option<NonZeroUsize> ) -> Result<Self>

where BaseConfig: Into<Config>,

Create a new Library object from a minimal configuration setup, writing it to config_path.

pub fn playlist_from<T: Serialize + DeserializeOwned>( &self, song_path: &str, playlist_length: usize ) -> Result<Vec<LibrarySong<T>>>

Build a playlist of playlist_length items from an already analyzed song in the library at song_path.

It uses a simple euclidean distance between songs, and deduplicates songs that are too close.

pub fn playlist_from_custom<F, G, T: Serialize + DeserializeOwned + Debug>( &self, song_path: &str, playlist_length: usize, distance: G, sort_by: F, dedup: bool ) -> Result<Vec<LibrarySong<T>>>

where F: FnMut(&LibrarySong<T>, &mut Vec<LibrarySong<T>>, G, fn(_: &LibrarySong<T>) -> Song), G: DistanceMetric + Copy,

Build a playlist of playlist_length items from an already analyzed song in the library at song_path, using distance metric distance, the sorting function sort_by and deduplicating if dedup is set to true.

You can use ready to use distance metrics such as euclidean_distance, and ready to use sorting functions like closest_to_first_song_by_key.

In most cases, you just want to use Library::playlist_from. Use playlist_from_custom if you want to experiment with different distance metrics / sorting functions.

Example: library.playlist_from_song_custom(song_path, 20, euclidean_distance, closest_to_first_song_by_key, true). TODO path here too

pub fn album_playlist_from<T: Serialize + DeserializeOwned + Clone + PartialEq>( &self, album_title: String, number_albums: usize ) -> Result<Vec<LibrarySong<T>>>

Make a playlist of number_albums albums closest to the album with title album_title. The playlist starts with the album with album_title, and contains number_albums on top of that one.

Returns the songs of each album ordered by bliss’ track_number.

pub fn update_library<P: Into<PathBuf>>( &mut self, paths: Vec<P>, delete_everything_else: bool, show_progress_bar: bool ) -> Result<()>

Analyze and store all songs in paths that haven’t been already analyzed.

Use this function if you don’t have any extra data to bundle with each song.

Setting delete_everything_else to true will delete the paths that are not mentionned in paths_extra_info from the database. If you do not use it, because you only pass the new paths that need to be analyzed to this function, make sure to delete yourself from the database the songs that have been deleted from storage.

If your library contains CUE files, pass the CUE file path only, and not individual CUE track names: passing vec![file.cue] will add individual tracks with the cue_info field set in the database.

pub fn update_library_extra_info<T: Serialize + DeserializeOwned, P: Into<PathBuf>>( &mut self, paths_extra_info: Vec<(P, T)>, delete_everything_else: bool, show_progress_bar: bool ) -> Result<()>

Analyze and store all songs in paths_extra_info that haven’t already been analyzed, along with some extra metadata serializable, and known before song analysis.

Setting delete_everything_else to true will delete the paths that are not mentionned in paths_extra_info from the database. If you do not use it, because you only pass the new paths that need to be analyzed to this function, make sure to delete yourself from the database the songs that have been deleted from storage.

pub fn update_library_convert_extra_info<T: Serialize + DeserializeOwned, U, P: Into<PathBuf>>( &mut self, paths_extra_info: Vec<(P, U)>, delete_everything_else: bool, show_progress_bar: bool, convert_extra_info: fn(_: U, _: &Song, _: &Self) -> T ) -> Result<()>

Analyze and store all songs in paths_extra_info that haven’t been already analyzed, as well as handling extra, user-specified metadata, that can’t directly be serializable, or that need input from the analyzed Song to be processed. If you just want to analyze and store songs along with some directly serializable values, consider using Library::update_library_extra_info, or Library::update_library if you just want the analyzed songs stored as is.

paths_extra_info is a tuple made out of song paths, along with any extra info you want to store for each song. If your library contains CUE files, pass the CUE file path only, and not individual CUE track names: passing vec![file.cue] will add individual tracks with the cue_info field set in the database.

Setting delete_everything_else to true will delete the paths that are not mentionned in paths_extra_info from the database. If you do not use it, because you only pass the new paths that need to be analyzed to this function, make sure to delete yourself from the database the songs that have been deleted from storage.

convert_extra_info is a function that you should specify how to convert that extra info to something serializable.

pub fn analyze_paths<P: Into<PathBuf>>( &mut self, paths: Vec<P>, show_progress_bar: bool ) -> Result<()>

Analyze and store all songs in paths.

Updates the value of features_version in the config, using bliss’ latest version.

Use this function if you don’t have any extra data to bundle with each song.

If your library contains CUE files, pass the CUE file path only, and not individual CUE track names: passing vec![file.cue] will add individual tracks with the cue_info field set in the database.

pub fn analyze_paths_extra_info<T: Serialize + DeserializeOwned + Debug, P: Into<PathBuf>>( &mut self, paths_extra_info: Vec<(P, T)>, show_progress_bar: bool ) -> Result<()>

Analyze and store all songs in paths_extra_info, along with some extra metadata serializable, and known before song analysis.

Updates the value of features_version in the config, using bliss’ latest version. If your library contains CUE files, pass the CUE file path only, and not individual CUE track names: passing vec![file.cue] will add individual tracks with the cue_info field set in the database.

pub fn analyze_paths_convert_extra_info<T: Serialize + DeserializeOwned, U, P: Into<PathBuf>>( &mut self, paths_extra_info: Vec<(P, U)>, show_progress_bar: bool, convert_extra_info: fn(_: U, _: &Song, _: &Self) -> T ) -> Result<()>

Analyze and store all songs in paths_extra_info, along with some extra, user-specified metadata, that can’t directly be serializable, or that need input from the analyzed Song to be processed. If you just want to analyze and store songs, along with some directly serializable metadata values, consider using Library::analyze_paths_extra_info, or Library::analyze_paths for the simpler use cases.

Updates the value of features_version in the config, using bliss’ latest version.

paths_extra_info is a tuple made out of song paths, along with any extra info you want to store for each song. If your library contains CUE files, pass the CUE file path only, and not individual CUE track names: passing vec![file.cue] will add individual tracks with the cue_info field set in the database.

convert_extra_info is a function that you should specify to convert that extra info to something serializable.

pub fn songs_from_library<T: Serialize + DeserializeOwned>( &self ) -> Result<Vec<LibrarySong<T>>>

Retrieve all songs which have been analyzed with current bliss version.

Returns an error if one or several songs have a different number of features than they should, indicating the offending song id.

pub fn songs_from_album<T: Serialize + DeserializeOwned>( &self, album_title: &str ) -> Result<Vec<LibrarySong<T>>>

Get a LibrarySong from a given album title.

This will return all songs with corresponding bliss “album” tag, and will order them by track number.

pub fn song_from_path<T: Serialize + DeserializeOwned>( &self, song_path: &str ) -> Result<LibrarySong<T>>

Get a LibrarySong from a given file path. TODO pathbuf here too

pub fn store_song<T: Serialize + DeserializeOwned>( &mut self, library_song: &LibrarySong<T> ) -> Result<(), BlissError>

Store a Song in the database, overidding any existing song with the same path by that one.

pub fn store_failed_song<P: Into<PathBuf>>( &mut self, song_path: P, e: BlissError ) -> Result<()>

Store an errored Song in the SQLite database.

If there already is an existing song with that path, replace it by the latest failed result.

pub fn delete_path<P: Into<PathBuf>>(&mut self, song_path: P) -> Result<()>

Delete a song with path song_path from the database.

Errors out if the song is not in the database.

pub fn delete_paths<P: Into<PathBuf>, I: IntoIterator<Item = P>>( &mut self, paths: I ) -> Result<usize>

Delete a set of songs with paths song_paths from the database.

Will return Ok(count) even if less songs than expected were deleted from the database.