ghurni 1.0.0

ghurni — Mechanical sound synthesis: engines, gears, motors, turbines, RPM-driven harmonics
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

//! # ghurni — Mechanical Sound Synthesis
//!
//! **ghurni** (Sanskrit: rotation / spinning) provides procedural synthesis of
//! mechanical sounds: engines, gears, motors, turbines, and other RPM-driven
//! machinery. All sounds are generated from physical models — rotational
//! harmonics, combustion impulses, resonant bodies.
//!
//! ## Architecture
//!
//! ```text
//! Machine (type, RPM, load)
//!       |
//!       v
//! Rotational Core ──────────────── Output
//!   Engine:      combustion cycle, exhaust/intake resonance, firing order
//!   Gear:        tooth mesh frequency, metallic ring
//!   Motor:       electromagnetic hum, commutator noise
//!   Turbine:     blade pass frequency, whoosh
//!   Clock:       escapement tick, spring resonance
//!   Transmission: gear mesh, shift transients, synchro whine
//!   Differential: hypoid gear whine, housing resonance
//!   ForcedInduction: turbo spool, supercharger whine, blow-off valve
//!   ChainDrive:  link engagement rattle
//!   BeltDrive:   squeal, flap
//! ```
//!
//! ## Key Concepts
//!
//! - **RPM**: Rotational speed — the fundamental parameter driving all mechanical sounds
//! - **Machine**: A mechanical device with specific acoustic character
//! - **Load**: Operating load (0.0-1.0) affects strain, noise, and harmonic content
//! - **Material**: Body material affects resonance (steel, aluminum, cast iron)
//! - **Synthesizer trait**: Common interface enabling mixers, effects chains, and generic composition
//!
//! ## Quick Start
//!
//! ```rust
//! use ghurni::prelude::*;
//!
//! // Synthesize a diesel engine at 2000 RPM
//! let mut engine = Engine::new(EngineType::Diesel, 6, 44100.0).unwrap();
//! let samples = engine.synthesize(2000.0, 0.7, 1.0).unwrap();
//!
//! // Generate gear mesh sound
//! let mut gear = Gear::new(32, GearMaterial::Steel, 44100.0).unwrap();
//! let samples = gear.synthesize(1500.0, 0.5).unwrap();
//! ```
//!
//! ## Feature Flags
//!
//! | Feature | Default | Description |
//! |---------|---------|-------------|
//! | `std` | Yes | Standard library support. Disable for `no_std` + `alloc` |
//! | `naad-backend` | Yes | Use naad for DSP primitives (oscillators, filters, noise) |
//! | `logging` | No | Structured logging via tracing-subscriber |

#![cfg_attr(not(feature = "std"), no_std)]

extern crate alloc;

pub mod belt_drive;
pub mod chain_drive;
pub mod clock;
pub mod differential;
pub(crate) mod dsp;
pub mod engine;
pub mod error;
pub mod event;
pub mod forced_induction;
pub mod gear;
#[cfg(not(feature = "naad-backend"))]
#[allow(dead_code)]
mod math;
pub mod mixer;
pub mod motor;
pub mod presets;
#[cfg(not(feature = "naad-backend"))]
#[allow(dead_code)]
pub(crate) mod rng;
pub mod smooth;
pub mod traits;
pub mod transmission;
pub mod turbine;

/// Convenience re-exports for common usage.
pub mod prelude {
    pub use crate::belt_drive::BeltDrive;
    pub use crate::chain_drive::ChainDrive;
    pub use crate::clock::{Clock, ClockType};
    pub use crate::differential::Differential;
    pub use crate::engine::{Engine, EngineType};
    pub use crate::error::{GhurniError, Result};
    pub use crate::event::MechanicalEvent;
    pub use crate::forced_induction::{ForcedInduction, InductionType};
    pub use crate::gear::{Gear, GearMaterial};
    pub use crate::mixer::MechanicalMixer;
    pub use crate::motor::{Motor, MotorType};
    pub use crate::traits::Synthesizer;
    pub use crate::transmission::Transmission;
    pub use crate::turbine::Turbine;
}

// Compile-time trait assertions: all public types must be Send + Sync.
#[cfg(test)]
mod assert_traits {
    fn _assert_send_sync<T: Send + Sync>() {}

    #[test]
    fn public_types_are_send_sync() {
        _assert_send_sync::<crate::error::GhurniError>();
        _assert_send_sync::<crate::engine::Engine>();
        _assert_send_sync::<crate::engine::EngineType>();
        _assert_send_sync::<crate::gear::Gear>();
        _assert_send_sync::<crate::gear::GearMaterial>();
        _assert_send_sync::<crate::motor::Motor>();
        _assert_send_sync::<crate::motor::MotorType>();
        _assert_send_sync::<crate::turbine::Turbine>();
        _assert_send_sync::<crate::clock::Clock>();
        _assert_send_sync::<crate::clock::ClockType>();
        _assert_send_sync::<crate::forced_induction::ForcedInduction>();
        _assert_send_sync::<crate::forced_induction::InductionType>();
        _assert_send_sync::<crate::transmission::Transmission>();
        _assert_send_sync::<crate::differential::Differential>();
        _assert_send_sync::<crate::chain_drive::ChainDrive>();
        _assert_send_sync::<crate::belt_drive::BeltDrive>();
        _assert_send_sync::<crate::event::MechanicalEvent>();
        _assert_send_sync::<crate::smooth::SmoothedParam>();
    }
}