Struct Player 

pub struct Player {
    pub info: Info,
    pub finished_tracks: Arc<Mutex<Vec<i32>>>,
    pub ts: Arc<Mutex<f64>>,
    /* private fields */
}

Primary playback controller.

Player owns the playback threads, buffering state, and runtime settings such as volume and reverb configuration.

Fields

info: Info

finished_tracks: Arc<Mutex<Vec<i32>>>

ts: Arc<Mutex<f64>>

Implementations

impl Player

pub fn play_at(&mut self, ts: f64)

Start playback from a specific timestamp (seconds).

Arguments

• ts - Target start position in seconds.

pub fn play(&mut self)

Start playback from the current timestamp.

If no playback thread is currently alive, a new runtime is created.

pub fn pause(&self)

Pause playback.

pub fn resume(&self)

Resume playback if paused.

pub fn kill_current(&self)

Stop the current playback thread and wait for it to exit.

Internal state is moved through Stopping and finalized as Stopped.

pub fn stop(&self)

Stop playback and reset timing state.

pub fn is_playing(&self) -> bool

Return true if playback is currently active.

pub fn is_paused(&self) -> bool

Return true if playback is currently paused.

pub fn get_time(&self) -> f64

Get the current playback time in seconds.

pub fn is_finished(&self) -> bool

Return true if playback has reached the end.

pub fn sleep_until_end(&self)

Block the current thread until playback finishes.

pub fn get_duration(&self) -> f64

Get the total duration (seconds) of the active selection.

pub fn seek(&mut self, ts: f64)

Seek to the given timestamp (seconds).

Seeking rebuilds the playback runtime at ts and applies configured seek fade-out/fade-in behavior when currently playing.

Arguments

• ts - New playback position in seconds.

pub fn refresh_tracks(&mut self)

Refresh active track selections from the underlying container.

Existing reverb overrides are re-applied and active playback is restarted at the current timestamp.

pub fn shuffle(&mut self)

Shuffle track selections and restart playback.

pub fn set_volume(&mut self, new_volume: f32)

Set the playback volume (linear gain).

Arguments

• new_volume - Desired sink gain multiplier.

pub fn get_volume(&self) -> f32

Get the current playback volume.

pub fn get_ids(&self) -> Vec<String>

Get the track identifiers used for display.

pub fn get_shuffle_schedule(&self) -> Vec<(f64, Vec<String>)>

Get the full timestamped shuffle schedule used by playback.

Each entry is (time_seconds, selected_ids_or_paths).

pub fn set_reporting( &mut self, reporting: Arc<Mutex<dyn Fn(Report) + Send>>, reporting_interval: Duration, )

Enable periodic reporting of playback status for UI consumers.

Any previous reporter instance is stopped before a new one is started.

Arguments

• reporting - Callback invoked with periodic playback snapshots.
• reporting_interval - Time between callback invocations.

impl Player

pub fn set_impulse_response_spec(&mut self, spec: ImpulseResponseSpec)

Override the impulse response used for convolution reverb.

Arguments

• spec - Parsed IR selection/configuration to persist on the player.

pub fn set_impulse_response_from_string(&mut self, value: &str)

Parse and apply an impulse response spec string.

Invalid input is ignored and leaves the current override unchanged.

pub fn set_impulse_response_tail_db(&mut self, tail_db: f32)

Override the impulse response tail trim (dB).

Arguments

• tail_db - Trim threshold in decibels applied to IR tails.

pub fn set_reverb_enabled(&self, enabled: bool)

Enable or disable supported reverb effects in the active chain.

The toggle is applied to convolution and delay-reverb instances when present.

pub fn set_reverb_mix(&self, dry_wet: f32)

Set the reverb wet/dry mix (clamped to [0.0, 1.0]).

The value is mapped across convolution, delay, and diffusion reverb variants when those effects are part of the chain.

pub fn get_reverb_settings(&self) -> ReverbSettingsSnapshot

Retrieve the current reverb settings snapshot.

Returns a disabled/zeroed snapshot when no known reverb effect exists.

pub fn get_effect_names(&self) -> Vec<String>

Snapshot the active effect chain names.

This is primarily intended for diagnostics and UI display.

pub fn set_effects(&mut self, effects: Vec<AudioEffect>)

Replace the active DSP effects chain.

This method preserves legacy behavior: it forces an effect-state reset and re-seeks to the current timestamp so the new chain is applied immediately, which also refreshes the sink.

Arguments

• effects - New ordered list of effects to apply.

pub fn set_effects_inline(&self, effects: Vec<AudioEffect>)

Replace the active DSP effects chain inline during playback.

Unlike Self::set_effects, this does not reset effect internals, clear effect tails, or rebuild the sink. The updated chain settings are used for future chunks processed by the mixing thread, with a short internal crossfade to reduce boundary clicks.

Arguments

• effects - New ordered list of effects to apply.

pub fn get_dsp_metrics(&self) -> DspChainMetrics

Retrieve the latest DSP chain performance metrics.

Returns

A copy of the most recent metrics updated by the playback thread.

pub fn get_levels(&self) -> Vec<f32>

Retrieve the most recent per-channel peak levels.

pub fn get_levels_db(&self) -> Vec<f32>

Retrieve the most recent per-channel peak levels in dBFS.

pub fn get_levels_avg(&self) -> Vec<f32>

Retrieve the most recent per-channel average levels.

pub fn set_output_meter_refresh_hz(&self, hz: f32)

Set the output meter refresh rate (frames per second).

impl Player

pub fn set_start_buffer_ms(&self, start_buffer_ms: f32)

Configure the minimum buffered audio (ms) before playback starts.

Arguments

• start_buffer_ms - Startup prebuffer target in milliseconds.

pub fn set_track_eos_ms(&self, track_eos_ms: f32)

Configure heuristic end-of-track threshold for containers (ms).

Arguments

• track_eos_ms - End-of-track threshold in milliseconds.

pub fn set_start_sink_chunks(&self, chunks: usize)

Configure minimum sink chunks queued before playback starts/resumes.

pub fn set_max_sink_chunks(&self, chunks: usize)

Configure the maximum sink chunks queued before producer backpressure.

Set to 0 to disable this guard.

pub fn set_startup_silence_ms(&self, ms: f32)

Configure the startup silence pre-roll (ms).

pub fn set_startup_fade_ms(&self, ms: f32)

Configure the startup fade-in length (ms).

pub fn set_seek_fade_out_ms(&self, ms: f32)

Configure seek fade-out length (ms) before restarting playback.

pub fn set_seek_fade_in_ms(&self, ms: f32)

Configure seek fade-in length (ms) after restarting playback.

pub fn set_append_jitter_log_ms(&self, ms: f32)

Configure the append jitter logging threshold (ms). 0 disables logging.

pub fn set_inline_effects_transition_ms(&self, ms: f32)

Configure inline effects transition duration (ms) for set_effects_inline.

pub fn set_effect_boundary_log(&self, enabled: bool)

Enable or disable per-effect boundary discontinuity logging.

pub fn set_track_mix_inline( &self, slot_index: usize, level: f32, pan: f32, ) -> bool

Update per-slot track level/pan without restarting playback.

This mutates the underlying track model and queues an inline update for the active mix thread. Returns false if slot_index is out of range.

pub fn debug_playback_state(&self) -> (bool, PlayerState, bool)

Debug helper returning thread alive, state, and audio heard flags.

pub fn debug_buffering_done(&self) -> bool

Debug helper indicating whether buffering has completed.

pub fn debug_timing_ms(&self) -> (u64, u64)

Debug helper returning internal timing markers in milliseconds.

pub fn debug_sink_state(&self) -> (bool, bool, usize)

Debug helper returning sink paused/empty flags and queued length.

impl Player

pub fn new(file_path: &String) -> Self

Create a new player for a single container path.

Arguments

• file_path - Path to a .prot/.mka container file.

pub fn new_from_file_paths(file_paths: Vec<PathsTrack>) -> Self

Create a new player for a set of standalone file paths.

Arguments

• file_paths - Pre-normalized track path groups.

pub fn new_from_file_paths_legacy(file_paths: Vec<Vec<String>>) -> Self

Create a new player for legacy standalone file-path groups.

Arguments

• file_paths - Legacy track grouping shape where each inner vector is interpreted as one track candidate set.

pub fn new_from_path_or_paths( path: Option<&String>, paths: Option<Vec<PathsTrack>>, ) -> Self

Create a player from either a container path or standalone file paths.

Exactly one input source is expected. path takes precedence when provided; otherwise paths is used for file-based playback.

Arguments

• path - Optional container path.
• paths - Optional standalone track path groups.

Trait Implementations

impl Clone for Player

fn clone(&self) -> Player

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Drop for Player

fn drop(&mut self)

Executes the destructor for this type.