# Purpose
Defines Speaker V3 analysis data, shallow Ogg input validation, frozen Gemini and GPT prompt artifacts, and the structured result expected from GPT.
# Public API
```rust
pub const MAX_AUDIO_DURATION_MS: u64 = 150_000;
pub const OGG_MEDIA_TYPE: &str = "audio/ogg";
pub const FEATURE_SCHEMA_REVISION: &str;
pub const GEMINI_TRANSCRIPT_PROMPT_REVISION: &str;
pub const GEMINI_FEATURE_PROMPT_ONE_REVISION: &str;
pub const GEMINI_FEATURE_PROMPT_TWO_REVISION: &str;
pub const GEMINI_FEATURE_PROMPT_THREE_REVISION: &str;
pub const GPT_STRUCTURING_PROMPT_REVISION: &str;
pub const GEMINI_FEATURE_PROMPT_REVISIONS: [&str; 3];
pub const FEATURE_NAMES: [&str; 24];
pub const GEMINI_TRANSCRIPT_PROMPT: &str;
pub const GEMINI_FEATURE_PROMPT_ONE: &str;
pub const GEMINI_FEATURE_PROMPT_TWO: &str;
pub const GEMINI_FEATURE_PROMPT_THREE: &str;
pub const GPT_STRUCTURING_PROMPT: &str;
pub enum ValidationError {
InvalidOgg,
InvalidDuration(u64),
ByteLengthOverflow,
Blank(&'static str),
InvalidSpeakerLabel(String),
DuplicateSpeakerLabel(LocalSpeakerLabel),
NonFiniteFeature(&'static str),
}
impl Display for ValidationError;
impl Error for ValidationError;
pub struct OggAudioMetadata { /* private fields */ }
impl OggAudioMetadata {
pub fn from_bytes(
bytes: &[u8],
duration_ms: u64,
filename: Option<String>,
) -> Result<Self, ValidationError>;
pub fn validate(&self) -> Result<(), ValidationError>;
pub fn duration_ms(&self) -> u64;
pub fn byte_length(&self) -> u64;
pub fn filename(&self) -> Option<&str>;
pub fn media_type(&self) -> &'static str;
}
pub struct LocalSpeakerLabel(/* private */);
impl LocalSpeakerLabel {
pub fn new(number: u32) -> Result<Self, ValidationError>;
pub fn number(self) -> u32;
}
impl Display for LocalSpeakerLabel;
impl FromStr for LocalSpeakerLabel;
pub enum VocalGenderPresentation {
StronglyFeminine,
Feminine,
Androgynous,
Masculine,
StronglyMasculine,
}
impl VocalGenderPresentation {
pub fn numeric_value(self) -> f64;
}
pub struct FeatureVector24 {
pub median_f0_hz: Option<f64>,
pub high_front_vowel_f1_hz: Option<f64>,
pub high_back_vowel_f2_hz: Option<f64>,
pub spectral_tilt_db_per_octave: Option<f64>,
pub cepstral_peak_prominence_db: Option<f64>,
pub foreign_accentedness_1_to_9: Option<f64>,
pub dominant_rhotic_realization: Option<String>,
pub unstressed_vowel_reduction_percent: Option<f64>,
pub high_front_vowel_f2_hz: Option<f64>,
pub low_vowel_f1_hz: Option<f64>,
pub h1_minus_h2_db: Option<f64>,
pub rhotic_f3_minus_f2_hz: Option<f64>,
pub word_initial_t_vot_ms: Option<f64>,
pub dominant_lateral_realization: Option<String>,
pub monophthongization_percent: Option<f64>,
pub vocal_gender_presentation: Option<VocalGenderPresentation>,
pub low_vowel_f2_hz: Option<f64>,
pub high_back_vowel_f1_hz: Option<f64>,
pub mean_formant_dispersion_hz: Option<f64>,
pub creaky_phonation_percent: Option<f64>,
pub hypernasality_0_to_4: Option<f64>,
pub sibilant_center_of_gravity_hz: Option<f64>,
pub consonant_cluster_reduction_percent: Option<f64>,
pub perceived_vocal_age_years: Option<f64>,
}
impl Default for FeatureVector24;
impl FeatureVector24 {
pub fn validate(&self) -> Result<(), ValidationError>;
pub fn numeric_values(&self) -> [Option<f64>; 22];
pub fn nominal_values(&self) -> [Option<&str>; 2];
pub fn present_feature_count(&self) -> u8;
}
pub struct StructuredSpeaker {
pub speaker: LocalSpeakerLabel,
pub language: String,
pub features: FeatureVector24,
pub features_usable_for_training: bool,
}
impl StructuredSpeaker {
pub fn validate(&self) -> Result<(), ValidationError>;
}
pub struct StructuredAnalysis {
pub transcript: String,
pub speakers: Vec<StructuredSpeaker>,
}
impl StructuredAnalysis {
pub fn validate(&self) -> Result<(), ValidationError>;
}
pub struct GeminiCohort {
pub model_id: String,
pub transcript_prompt_revision: String,
pub feature_prompt_revisions: [String; 3],
pub feature_schema_revision: String,
}
impl GeminiCohort {
pub fn new(model_id: impl Into<String>) -> Self;
pub fn validate(&self) -> Result<(), ValidationError>;
}
pub struct StructurerProvenance {
pub model_id: String,
pub prompt_revision: String,
}
impl StructurerProvenance {
pub fn new(model_id: impl Into<String>) -> Self;
pub fn validate(&self) -> Result<(), ValidationError>;
}
pub struct AnalysisEnvelope {
pub audio: OggAudioMetadata,
pub analysis: StructuredAnalysis,
pub gemini: GeminiCohort,
pub structurer: StructurerProvenance,
}
impl AnalysisEnvelope {
pub fn validate(&self) -> Result<(), ValidationError>;
}
```
Public data values implement `Debug`, `Clone`, `PartialEq`, and Serde serialization where applicable. Copyable scalar values additionally implement `Copy` and `Eq`.
`OggAudioMetadata::from_bytes` accepts durations from 1 through 150,000 milliseconds and checks only the Ogg capture pattern, stream-structure version, first-page segment table, and first-page body length. It scans at most the first-page segment table, performs no I/O, does not decode codec packets, and trusts the supplied duration. Its work is bounded by the Ogg first-page segment count and its retained memory is constant.
`LocalSpeakerLabel` has the exact text and Serde form `Speaker N`, where `N` is positive.
`FeatureVector24` preserves the frozen feature schema. Validation rejects non-finite numeric values and blank present nominal values. It imposes no empirical ranges. `numeric_values` returns the 22 numeric or ordered values in frozen non-nominal order, including vocal-gender presentation mapped from -2 through 2. `nominal_values` returns rhotic then lateral realization.
`StructuredAnalysis::validate` requires a nonblank transcript, unique speaker labels, nonblank languages, and valid features. It accepts `features_usable_for_training` exactly as supplied and performs no transcript parsing, word counting, identity work, or quality reassessment.
`GeminiCohort::new` binds the current frozen Gemini prompt and feature-schema revisions. Gemini cohort compatibility excludes GPT structuring provenance.
All operations are deterministic and stateless. Independent calls share no state. The library performs no filesystem, network, provider, persistence, transaction, identity, or classifier operations.