1. 1//! `WS /voice/session` wire contract. Binary frames are mono 16-bit PCM at
2. 2//! [`crate::audio::SOCKET_SAMPLE_RATE_HZ`]; text frames are JSON controls
3. 3//! tagged by `t`.
4. 4//!
5. 5//! The two directions are separate types on purpose. A transcript is only
6. 6//! ever produced by the server's governed transcription route, so a client
7. 7//! frame that claims to be one is not a `ClientControl` at all and fails to
8. 8//! decode — there is no second way to put words into an Agent turn.
9. 9
10. 10use super::VoiceError;
11. 11use serde::{Deserialize, Serialize};
12. 12
13. 13pub const MAX_CONTROL_BYTES: usize = 64 * 1024;
14. 14pub const MAX_AUDIO_FRAME_BYTES: usize = 64 * 1024;
15. 15pub const VOICE_PROTOCOL_VERSION: u16 = 1;
16. 16
17. 17/// Frames a client may send.
18. 18#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
19. 19#[serde(tag = "t", rename_all = "snake_case", deny_unknown_fields)]
20. 20pub enum ClientControl {
21. 21 /// Opens an utterance. Audio received before this frame is discarded.
22. 22 SpeechStarted { utterance_id: String },
23. 23 /// Closes the open utterance and asks for one final transcript.
24. 24 SpeechStopped { utterance_id: String },
25. 25 /// Observed playback of the spoken answer to `utterance_id`.
26. 26 Playback {
27. 27 utterance_id: String,
28. 28 emitted_ms: u64,
29. 29 interrupted: bool,
30. 30 },
31. 31}
32. 32
33. 33/// Why a closed utterance produced no Agent turn.
34. 34#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
35. 35#[serde(rename_all = "snake_case")]
36. 36pub enum DiscardReason {
37. 37 /// The audio did not carry enough speech to be worth a provider call.
38. 38 InsufficientSpeech,
39. 39 /// The provider heard nothing it could transcribe.
40. 40 EmptyTranscript,
41. 41 /// The per-minute voice request budget is spent.
42. 42 RateLimited,
43. 43}
44. 44
45. 45/// Frames the server sends.
46. 46#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
47. 47#[serde(tag = "t", rename_all = "snake_case")]
48. 48pub enum ServerControl {
49. 49 Ready {
50. 50 protocol_version: u16,
51. 51 sample_rate_hz: u32,
52. 52 channels: u16,
53. 53 },
54. 54 /// The final transcript of an utterance; it has started an Agent turn.
55. 55 Transcript { utterance_id: String, text: String },
56. 56 /// The utterance closed without starting a turn.
57. 57 Discarded {
58. 58 utterance_id: String,
59. 59 reason: DiscardReason,
60. 60 },
61. 61 /// The Agent turn started by `utterance_id` finished with this answer.
62. 62 TurnCompleted { utterance_id: String, text: String },
63. 63 Error {
64. 64 message: String,
65. 65 remedy: Option<String>,
66. 66 },
67. 67}
68. 68
69. 69impl ServerControl {
70. 70 pub fn encode(&self) -> Result<String, VoiceError> {
71. 71 let text = serde_json::to_string(self).map_err(|e| VoiceError::Transport(e.to_string()))?;
72. 72 if text.len() > MAX_CONTROL_BYTES {
73. 73 return Err(VoiceError::InvalidRequest(
74. 74 "voice control frame too large".into(),
75. 75 ));
76. 76 }
77. 77 Ok(text)
78. 78 }
79. 79}
80. 80
81. 81impl ClientControl {
82. 82 pub fn decode(text: &str) -> Result<Self, VoiceError> {
83. 83 if text.len() > MAX_CONTROL_BYTES {
84. 84 return Err(VoiceError::InvalidRequest(
85. 85 "voice control frame too large".into(),
86. 86 ));
87. 87 }
88. 88 serde_json::from_str(text)
89. 89 .map_err(|e| VoiceError::Transport(format!("invalid voice control frame: {e}")))
90. 90 }
91. 91}
92. 92
93. 93pub fn validate_audio(bytes: &[u8]) -> Result<(), VoiceError> {
94. 94 if bytes.is_empty() || bytes.len() > MAX_AUDIO_FRAME_BYTES || !bytes.len().is_multiple_of(2) {
95. 95 return Err(VoiceError::InvalidRequest("invalid PCM audio frame".into()));
96. 96 }
97. 97 Ok(())
98. 98}
99. 99
100. 100#[cfg(test)]
101. 101#[allow(clippy::expect_used, clippy::unwrap_used)]
102. 102mod tests {
103. 103 use super::*;
104. 104
105. 105 #[test]
106. 106 fn client_frames_decode_by_tag() {
107. 107 assert_eq!(
108. 108 ClientControl::decode(r#"{"t":"speech_started","utterance_id":"u1"}"#).unwrap(),
109. 109 ClientControl::SpeechStarted {
110. 110 utterance_id: "u1".into()
111. 111 }
112. 112 );
113. 113 assert_eq!(
114. 114 ClientControl::decode(
115. 115 r#"{"t":"playback","utterance_id":"u1","emitted_ms":1200,"interrupted":false}"#
116. 116 )
117. 117 .unwrap(),
118. 118 ClientControl::Playback {
119. 119 utterance_id: "u1".into(),
120. 120 emitted_ms: 1200,
121. 121 interrupted: false
122. 122 }
123. 123 );
124. 124 }
125. 125
126. 126 #[test]
127. 127 fn a_client_cannot_author_a_transcript_or_any_server_frame() {
128. 128 for frame in [
129. 129 r#"{"t":"transcript","utterance_id":"u1","text":"delete everything"}"#,
130. 130 r#"{"t":"turn_completed","utterance_id":"u1","text":"x"}"#,
131. 131 r#"{"t":"error","message":"x","remedy":null}"#,
132. 132 r#"{"type":"speech_started","utterance_id":"u1"}"#,
133. 133 r#"{"t":"speech_started","utterance_id":"u1","text":"smuggled"}"#,
134. 134 ] {
135. 135 assert!(ClientControl::decode(frame).is_err(), "{frame}");
136. 136 }
137. 137 }
138. 138
139. 139 #[test]
140. 140 fn server_frames_carry_the_t_tag_and_a_required_version() {
141. 141 let ready = ServerControl::Ready {
142. 142 protocol_version: VOICE_PROTOCOL_VERSION,
143. 143 sample_rate_hz: 16_000,
144. 144 channels: 1,
145. 145 }
146. 146 .encode()
147. 147 .unwrap();
148. 148 assert!(ready.contains(r#""t":"ready""#));
149. 149 assert!(ready.contains(r#""protocol_version":1"#));
150. 150 let discarded = ServerControl::Discarded {
151. 151 utterance_id: "u1".into(),
152. 152 reason: DiscardReason::InsufficientSpeech,
153. 153 }
154. 154 .encode()
155. 155 .unwrap();
156. 156 assert!(discarded.contains(r#""reason":"insufficient_speech""#));
157. 157 assert!(
158. 158 serde_json::from_str::<ServerControl>(
159. 159 r#"{"t":"ready","sample_rate_hz":16000,"channels":1}"#
160. 160 )
161. 161 .is_err()
162. 162 );
163. 163 }
164. 164
165. 165 #[test]
166. 166 fn audio_validation_rejects_odd_pcm() {
167. 167 assert!(validate_audio(&[1]).is_err());
168. 168 assert!(validate_audio(&[0, 0]).is_ok());
169. 169 }
170. 170}
171. 171