Crate nidhi 

nidhi — Sample Playback Engine

nidhi (Sanskrit: treasure, storehouse) provides sample-based instrument playback for the AGNOS ecosystem. It handles sample mapping, key/velocity zones, loop modes, time-stretching, and format import (SFZ/SF2).

Architecture

SampleBank (loaded samples)
      |
      v
Instrument (key/velocity zones → sample mapping)
      |
      v
SamplerVoice (playback with interpolation, looping, envelope)
      |
      v
SamplerEngine (polyphonic voice pool)

Key Concepts

• Sample: A loaded audio waveform (mono or stereo f32 data)
• Zone: A key/velocity region mapped to a sample with root note, tuning, and loop points
• Instrument: A collection of zones forming a playable instrument
• SamplerEngine: Polyphonic playback engine with voice stealing

Quick Start

use nidhi::prelude::*;

// Load a sample and create an instrument
let sample = Sample::from_mono(vec![0.0f32; 44100], 44100);
let mut bank = SampleBank::new();
let id = bank.add(sample);

let mut inst = Instrument::new("piano");
inst.add_zone(Zone::new(id).with_key_range(60, 72).with_root_note(66));

// Create engine and play
let mut engine = SamplerEngine::new(16, 44100.0);
engine.set_instrument(inst);
engine.note_on(66, 100); // middle C#, velocity 100

Modules

capture

Sample capture — record audio input into Sample with auto-processing.

effect_chain

Per-instrument effect chain — routes audio through naad effects.

engine

Sampler engine — polyphonic sample playback with voice management.

envelope

ADSR envelope — lightweight per-voice amplitude envelope.

error

Error types for the nidhi sampler engine.

instrument

Instrument — a collection of zones forming a playable sampled instrument.

loop_mode

Loop modes for sample playback.

prelude

Convenience re-exports for common usage.

sample

Sample storage — loaded audio waveforms and a sample bank.

sf2

SoundFont 2 (SF2) binary file parser.

sfz

SFZ format parser — converts SFZ text files into nidhi Instrument + Zone structures.

stretch

Time-stretching — change duration without affecting pitch.

zone

Zone — key/velocity region mapped to a sample.