kcode-speaker-v3-schema 0.1.1

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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

# kcode-speaker-v3-schema 0.1.1

Provider-independent Speaker V3 Ogg admission, speaker labels, frozen feature values, and structured-analysis schema. The crate performs no provider, filesystem, persistence, transaction, identity, training, or classifier work.

## Public constants

```rust
pub const MAX_AUDIO_DURATION_MS: u64 = 150_000;
pub const OGG_MEDIA_TYPE: &str = "audio/ogg";
pub const FEATURE_SCHEMA_REVISION: &str = "speaker-v3-features-24-r1";
pub const FEATURE_NAMES: [&str; 24];
```

## Validation and Ogg admission

```rust
pub enum ValidationError {
    InvalidOgg,
    InvalidDuration(u64),
    ByteLengthOverflow,
    Blank(&'static str),
    InvalidSpeakerLabel(String),
    DuplicateSpeakerLabel(LocalSpeakerLabel),
    NonFiniteFeature(&'static str),
}

pub struct OggAudioMetadata { /* private fields */ }

impl OggAudioMetadata {
    pub fn from_ogg_bytes(bytes: &[u8]) -> Result<Self, ValidationError>;

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

`from_ogg_bytes` is the strict active admission path. It accepts one complete single-logical-stream Ogg Opus value, verifies every page CRC and complete framing, requires one fixed serial and page sequence beginning at zero, enforces packet-continuation flags, requires one initial BOS and one terminal EOS with no trailing or chained pages, and rejects decreasing known granule positions.

The first completed packet must be an exact 19-byte `OpusHead` with version 1, one or two channels, and mapping family zero. Duration is derived from the terminal granule position minus Opus pre-skip at 48 kHz and rounded up to milliseconds. Zero-duration audio and durations above 150,000 milliseconds are rejected. Successful metadata records the exact byte length and no filename. The operation does not decode audio or inspect `OpusTags`.

`from_bytes` is the compatibility constructor. It trusts a caller-supplied duration from 1 through 150,000 milliseconds, accepts an optional nonblank filename, and validates only the legacy first-page Ogg shape. It does not validate a complete stream.

`OggAudioMetadata` implements `Debug`, `Clone`, `PartialEq`, `Eq`, and Serde serialization and deserialization. `ValidationError` implements `Debug`, `Clone`, `PartialEq`, `Eq`, `Display`, and `Error`.

## Speaker labels

```rust
pub struct LocalSpeakerLabel(/* private */);

impl LocalSpeakerLabel {
    pub fn new(number: u32) -> Result<Self, ValidationError>;
    pub fn number(self) -> u32;
}
```

A label has the exact display, parse, and Serde text form `Speaker N`, where `N` is positive. `LocalSpeakerLabel` implements `Debug`, `Clone`, `Copy`, equality, ordering, hashing, `Display`, `FromStr`, and Serde serialization and deserialization.

## Frozen feature schema

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

Feature 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 order, including vocal-gender presentation mapped from -2 through 2. `nominal_values` returns rhotic then lateral realization.

`FeatureVector24` implements `Debug`, `Clone`, `PartialEq`, `Default`, and Serde serialization and deserialization. `VocalGenderPresentation` implements `Debug`, `Clone`, `Copy`, `PartialEq`, `Eq`, and Serde serialization and deserialization with snake-case names.

## Structured analysis

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

A structured speaker requires a nonblank language and valid features. A structured analysis requires a nonblank transcript, valid speakers, and unique local speaker labels. It preserves the supplied training-usability flag and performs no transcript parsing, identity decision, or quality reassessment. Both values implement `Debug`, `Clone`, `PartialEq`, and Serde serialization and deserialization.

## Performance and concurrency

Strict Ogg admission is linear in the supplied bytes and uses temporary memory proportional only to the first packet being assembled. Compatibility admission scans only the first-page segment table. Feature validation is fixed work. Structured-analysis validation is `O(speakers log speakers)` with `O(speakers)` temporary label storage.

The crate owns no lock, queue, callback, retry, timeout, background task, or mutable global state. Independent operations may run concurrently.