blazen_audio_core/lib.rs
1//! Shared candle primitives for Diffusion Transformer (DiT) backends.
2//!
3//! Wave 0 of the audio capability completion push extracted these
4//! reusable building blocks out of the Stable Audio Open Small backend
5//! in `blazen-audio-music` so other audio + 3D ports (F5-TTS,
6//! AudioLDM, future video DiTs) can share them without copying code.
7//!
8//! # What lives here
9//!
10//! - [`dit`] — multi-head attention (self + cross) and the SwiGLU
11//! feed-forward block.
12//! - [`adaln`] — AdaLN-Zero modulation (the six-chunk
13//! `(scale_*, shift_*, gate_*)` projection used to drive a DiT block
14//! from a global conditioning vector) and the broadcasting
15//! [`modulate`](adaln::modulate) helper.
16//! - [`rope`] — Rotary Position Embedding helpers
17//! ([`precompute_rope_freqs`](rope::precompute_rope_freqs) and the
18//! partial-rotary [`apply_rope`](rope::apply_rope)) plus a
19//! [`FourierFeatures`](rope::FourierFeatures) block for embedding
20//! continuous scalars.
21//!
22//! # What lives in the consuming backend
23//!
24//! - Backend-specific configs (e.g. `DiTConfig` for Stable Audio),
25//! conditioner wiring, numeric / timestep embedding heads, output
26//! projections sized to specific latent shapes, and the actual DiT
27//! block recipe (e.g. self-attn → cross-attn → SwiGLU FFN with
28//! `sigmoid(1 - gate)` blending for Stable Audio).
29//!
30//! These primitives are intentionally feature-free; consuming crates
31//! gate their own backends as needed.
32
33// The candle-error / shape-mismatch failure modes of every function in
34// this crate are documented inline in the function bodies and through
35// the candle docs; repeating an `# Errors` section on every wrapper
36// would be pure noise. Same for `# Panics` — the `assert!` calls that
37// would trip these lints all guard against compile-time-constant
38// shape invariants (e.g. `embed_dim == num_heads * head_dim`) that
39// any reasonable caller respects.
40// `clippy::doc_markdown` fires on every math abbreviation
41// (`RoPE`, `SiLU`, `SwiGLU`, `B`, `T`, `D`, `MLP`, ...) — these are
42// terms-of-art that look wrong in backticks; suppress the lint at the
43// crate level rather than papering over every doc line.
44#![allow(
45 clippy::missing_errors_doc,
46 clippy::missing_panics_doc,
47 clippy::doc_markdown
48)]
49
50pub mod adaln;
51pub mod dit;
52pub mod rope;