Struct bliss_audio::Song

pub struct Song {
    pub path: PathBuf,
    pub artist: Option<String>,
    pub title: Option<String>,
    pub album: Option<String>,
    pub album_artist: Option<String>,
    pub track_number: Option<String>,
    pub genre: Option<String>,
    pub analysis: Analysis,
    pub duration: Duration,
    pub features_version: u16,
    pub cue_info: Option<CueInfo>,
}

Simple object used to represent a Song, with its path, analysis, and other metadata (artist, genre…)

Fields

path: PathBuf

Song’s provided file path

artist: Option<String>

Song’s artist, read from the metadata

title: Option<String>

Song’s title, read from the metadata

album: Option<String>

Song’s album name, read from the metadata

album_artist: Option<String>

Song’s album’s artist name, read from the metadata

track_number: Option<String>

Song’s tracked number, read from the metadata TODO normalize this into an integer

genre: Option<String>

Song’s genre, read from the metadata ("" if empty)

analysis: Analysis

bliss analysis results

duration: Duration

The song’s duration

features_version: u16

Version of the features the song was analyzed with. A simple integer that is bumped every time a breaking change is introduced in the features.

cue_info: Option<CueInfo>

Populated only if the song was extracted from a larger audio file, through the use of a CUE sheet. By default, such a song’s path would be path/to/cue_file.wav/CUE_TRACK00<track_number>. Using this field, you can change song.path to fit your needs.

Implementations

impl Song

pub fn distance(&self, other: &Self) -> f32

Compute the distance between the current song and any given Song.

The smaller the number, the closer the songs; usually more useful if compared between several songs (e.g. if song1.distance(song2) < song1.distance(song3), then song1 is closer to song2 than it is to song3.

Currently uses the euclidean distance, but this can change in an upcoming release if another metric performs better.

pub fn custom_distance( &self, other: &Self, distance: impl DistanceMetric ) -> f32

Compute distance between two songs using a user-provided distance metric.

For this function to be integrated properly with the rest of bliss’ parts, it should be a valid distance metric, i.e.:

1. For X, Y real vectors, d(X, Y) = 0 ⇔ X = Y
2. For X, Y real vectors, d(X, Y) >= 0
3. For X, Y real vectors, d(X, Y) = d(Y, X)
4. For X, Y, Z real vectors d(X, Y) ≤ d(X + Z) + d(Z, Y)

Note that almost all distance metrics you will find obey these properties, so don’t sweat it too much.

pub fn closest_from_pool_custom( &self, pool: Vec<Self>, distance: impl DistanceMetric ) -> Vec<Self>

Orders songs in pool by proximity to self, using the distance metric distance to compute the order. Basically return a playlist from songs in pool, starting from self, using distance (some distance metrics can be found in the playlist module).

Note that contrary to Song::closest_from_pool, self is NOT added to the beginning of the returned vector.

No deduplication is ran either; if you’re looking for something easy that works “out of the box”, use Song::closest_from_pool.

pub fn closest_from_pool(&self, pool: Vec<Self>) -> Vec<Self>

Order songs in pool by proximity to self. Convenience method to return a playlist from songs in pool, starting from self.

The distance is already chosen, deduplication is ran, and the first song is added to the top of the playlist, to make everything easier.

If you want more control over which distance metric is chosen, run deduplication manually, etc, use Song::closest_from_pool_custom.

pub fn from_path<P: AsRef<Path>>(path: P) -> BlissResult<Self>

Returns a decoded Song given a file path, or an error if the song could not be analyzed for some reason.

Arguments

• path - A Path holding a valid file path to a valid audio file.

Errors

This function will return an error if the file path is invalid, if the file path points to a file containing no or corrupted audio stream, or if the analysis could not be conducted to the end for some reason.

The error type returned should give a hint as to whether it was a decoding (DecodingError) or an analysis (AnalysisError) error.

pub fn analyze(sample_array: &[f32]) -> BlissResult<Analysis>

Analyze a song decoded in sample_array. This function should NOT be used manually, unless you want to explore analyzing a sample array you already decoded yourself. Most people will want to use Song::from_path instead to just analyze a file from its path.

The current implementation doesn’t make use of it, but the song can also be streamed wrt. each descriptor (with the exception of the chroma descriptor which yields worse results when streamed).

Useful in the rare cases where the full song is not completely available.

If you do want to use this with a song already decoded by yourself, the sample format of sample_array should be f32le, one channel, and the sampling rate 22050 Hz. Anything other than that will yield aberrant results. To double-check that your sample array has the right format, you could run ffmpeg -i path_to_your_song.flac -ar 22050 -ac 1 -c:a pcm_f32le -f hash -hash addler32 -, which will give you the addler32 checksum of the sample array if the song has been decoded properly. You can then compute the addler32 checksum of your sample array (see _test_decode in the tests) and make sure both are the same.

(Running ffmpeg -i path_to_your_song.flac -ar 22050 -ac 1 -c:a pcm_f32le will simply give you the raw sample array as it should look like, if you’re not into computing checksums)

Trait Implementations

impl Clone for Song

fn clone(&self) -> Song

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Song

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Song

fn default() -> Song

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Song

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Song

fn eq(&self, other: &Song) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Song

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Song