kcode-speaker-v3-schema 0.1.0

Provider-independent Speaker V3 schema types
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

# Purpose

Defines provider-independent Speaker V3 audio metadata and structured speaker-analysis schema values.

# 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 FEATURE_NAMES: [&str; 24];

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>;
}
```

Public data values implement `Debug`, `Clone`, `PartialEq`, and Serde serialization where applicable. Copyable scalar values additionally implement `Copy` and `Eq`. `LocalSpeakerLabel` additionally implements `PartialOrd`, `Ord`, and `Hash`. `VocalGenderPresentation` serializes with snake-case variant names.

`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 O(bytes in the first-page segment table), retained memory is constant apart from the supplied filename, and its deterministic local work has no timeout or retry.

`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. Each projection and validation is constant work and allocation-free apart from error construction.

`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. It performs O(speakers) feature validation and O(speakers log speakers) label tracking, with O(speakers) temporary memory. The included validation tests use one valid speaker and duplicate-label fixtures.

All operations are deterministic and stateless. Independent calls share no state or serialization, perform no filesystem, network, provider, persistence, transaction, identity, or classifier work, and have no timeout, retry, queue, or backpressure behavior.