Trait Decoder 

pub trait Decoder {
    // Required method
    fn decode(&self, path: &Path) -> AnalysisResult<ResampledAudio>;

    // Provided methods
    fn analyze_path<P: AsRef<Path>>(&self, path: P) -> AnalysisResult<Analysis> { ... }
    fn analyze_paths<P: Into<PathBuf>, I: Send + IntoIterator<Item = P>>(
        &self,
        paths: I,
        callback: Sender<(PathBuf, AnalysisResult<Analysis>)>,
    ) -> Result<(), SendError<()>>
       where Self: Sync + Send { ... }
    fn analyze_paths_with_cores<P: Into<PathBuf>, I: IntoIterator<Item = P>>(
        &self,
        paths: I,
        number_cores: NonZeroUsize,
        callback: Sender<(PathBuf, AnalysisResult<Analysis>)>,
    ) -> Result<(), SendError<()>>
       where Self: Sync + Send { ... }
    fn process_songs_with_cores(
        &self,
        paths: &[PathBuf],
        callback: ProcessingCallback,
        number_cores: NonZeroUsize,
        model_config: ModelConfig,
    ) -> AnalysisResult<()>
       where Self: Sync + Send { ... }
    fn process_songs(
        &self,
        paths: &[PathBuf],
        callback: ProcessingCallback,
        model_config: ModelConfig,
    ) -> AnalysisResult<()>
       where Self: Sync + Send { ... }
}

Trait used to implement your own decoder.

The decode function should be implemented so that it decodes and resample a song to one channel with a sampling rate of 22050 Hz and a f32le layout. Once it is implemented, several functions to perform analysis from path(s) are available, such as analyze_paths_with_cores and analyze_paths.

Required Methods

fn decode(&self, path: &Path) -> AnalysisResult<ResampledAudio>

A function that should decode and resample a song, optionally extracting the song’s metadata such as the artist, the album, etc.

The output sample array should be resampled to f32le, one channel, with a sampling rate of 22050 Hz. Anything other than that will yield wrong results.

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 or an analysis error.

Provided Methods

fn analyze_path<P: AsRef<Path>>(&self, path: P) -> AnalysisResult<Analysis>

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

see:

• Decoder::decode for how songs are decoded
• Analysis::from_samples for how analyses are calculated from ResampledAudio

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 or an analysis error.

fn analyze_paths<P: Into<PathBuf>, I: Send + IntoIterator<Item = P>>( &self, paths: I, callback: Sender<(PathBuf, AnalysisResult<Analysis>)>, ) -> Result<(), SendError<()>>

where Self: Sync + Send,

Analyze songs in paths in parallel across all logical cores, and emits the AnalysisResult<Analysis> objects (along with the Path they correspond to) through the provided callback channel.

This function is blocking, so it should be called in a separate thread from where the receiver is consumed.

You can cancel the job by dropping the callback channel’s receiver.

see Decoder::analyze_path for more details on how the analyses are generated.

Example

use mecomp_analysis::decoder::{Decoder as _, MecmopDecoder as Decoder};

let paths = vec![
    "data/piano.wav",
    "data/s32_mono_44_1_kHz.flac"
];

let (tx, rx) = std::mpsc::channel();

let handle = std::thread::spawn(move || {
    Decoder::new().unwrap().analyze_paths(paths, tx).unwrap();
});

for (path, maybe_analysis) = rx {
    if let Ok(analysis) = maybe_analysis {
        println!("{} analyzed successfully!", path.display());
        // do something with the analysis
    } else {
        eprintln!("error analyzing {}!", path.display());
    }
}

Errors

Errors if the callback channel is closed.

fn analyze_paths_with_cores<P: Into<PathBuf>, I: IntoIterator<Item = P>>( &self, paths: I, number_cores: NonZeroUsize, callback: Sender<(PathBuf, AnalysisResult<Analysis>)>, ) -> Result<(), SendError<()>>

where Self: Sync + Send,

Analyze songs in paths in parallel across number_cores threads, and emits the AnalysisResult<Analysis> objects (along with the Path they correspond to) through the provided callback channel.

This function is blocking, so it should be called in a separate thread from where the receiver is consumed.

You can cancel the job by dropping the callback channel’s receiver.

See also: Decoder::analyze_paths

Errors

Errors if the callback channel is closed.

fn process_songs_with_cores( &self, paths: &[PathBuf], callback: ProcessingCallback, number_cores: NonZeroUsize, model_config: ModelConfig, ) -> AnalysisResult<()>

where Self: Sync + Send,

Process raw audio samples in audios, and yield the Analysis and Embedding objects through the provided callback channel. Parallelizes the process across number_cores CPU cores.

You can cancel the job by dropping the callback channel.

Note: A new AudioEmbeddingModel session will be created for each thread.

Errors

Errors if the callback channel is closed.

fn process_songs( &self, paths: &[PathBuf], callback: ProcessingCallback, model_config: ModelConfig, ) -> AnalysisResult<()>

where Self: Sync + Send,

Process raw audio samples in audios, and yield the Analysis and Embedding objects through the provided callback channel. Parallelizes the process across all available CPU cores.

You can cancel the job by dropping the callback channel.

Note: A new AudioEmbeddingModel session will be created for each thread.

Errors

Errors if the callback channel is closed.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Decoder for MecompDecoder