wavecraft_protocol/ipc/
methods.rs

1use serde::{Deserialize, Serialize};
2
3// ============================================================================
4// Method-Specific Types
5// ============================================================================
6
7// ----------------------------------------------------------------------------
8// getParameter
9// ----------------------------------------------------------------------------
10
11/// Parameters for getParameter request
12#[derive(Debug, Clone, Serialize, Deserialize)]
13pub struct GetParameterParams {
14    /// Parameter ID to retrieve
15    pub id: String,
16}
17
18/// Result of getParameter request
19#[derive(Debug, Clone, Serialize, Deserialize)]
20pub struct GetParameterResult {
21    /// Parameter ID
22    pub id: String,
23    /// Current parameter value in the parameter's declared range.
24    pub value: f32,
25}
26
27// ----------------------------------------------------------------------------
28// setParameter
29// ----------------------------------------------------------------------------
30
31/// Parameters for setParameter request
32#[derive(Debug, Clone, Serialize, Deserialize)]
33pub struct SetParameterParams {
34    /// Parameter ID to update
35    pub id: String,
36    /// New parameter value in the parameter's declared range.
37    pub value: f32,
38}
39
40/// Result of setParameter request (empty success)
41#[derive(Debug, Clone, Serialize, Deserialize)]
42pub struct SetParameterResult {}
43
44// ----------------------------------------------------------------------------
45// getAllParameters
46// ----------------------------------------------------------------------------
47
48/// Result of getAllParameters request
49#[derive(Debug, Clone, Serialize, Deserialize)]
50pub struct GetAllParametersResult {
51    /// List of all parameters with their metadata and current values
52    pub parameters: Vec<ParameterInfo>,
53}
54
55/// Information about a single parameter
56#[derive(Debug, Clone, Serialize, Deserialize)]
57pub struct ParameterInfo {
58    /// Parameter ID (unique identifier)
59    pub id: String,
60    /// Human-readable name
61    pub name: String,
62    /// Parameter type (float, bool, enum, etc.)
63    #[serde(rename = "type")]
64    pub param_type: ParameterType,
65    /// Current parameter value in the parameter's declared range.
66    pub value: f32,
67    /// Default parameter value in the parameter's declared range.
68    pub default: f32,
69    /// Minimum value for this parameter.
70    pub min: f32,
71    /// Maximum value for this parameter.
72    pub max: f32,
73    /// Unit suffix for display (e.g., "dB", "%", "Hz")
74    #[serde(skip_serializing_if = "Option::is_none")]
75    pub unit: Option<String>,
76    /// Group name for UI organization (e.g., "Input", "Processing", "Output")
77    #[serde(skip_serializing_if = "Option::is_none")]
78    pub group: Option<String>,
79    /// Variant labels for enum parameters (e.g., ["Sine", "Square", "Saw", "Triangle"]).
80    /// Only present when `param_type` is `Enum`.
81    #[serde(skip_serializing_if = "Option::is_none")]
82    pub variants: Option<Vec<String>>,
83}
84
85/// Information about a discovered processor in the signal chain.
86#[derive(Debug, Clone, Serialize, Deserialize)]
87pub struct ProcessorInfo {
88    /// Canonical processor ID (snake_case type-derived identifier).
89    pub id: String,
90}
91
92/// Parameter type discriminator
93#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
94#[serde(rename_all = "lowercase")]
95pub enum ParameterType {
96    Float,
97    Bool,
98    Enum,
99}
100
101// ----------------------------------------------------------------------------
102// Notification: parameterChanged
103// ----------------------------------------------------------------------------
104
105/// Notification sent when a parameter changes (e.g., from host automation)
106#[derive(Debug, Clone, Serialize, Deserialize)]
107pub struct ParameterChangedNotification {
108    /// Parameter ID that changed
109    pub id: String,
110    /// New parameter value in the parameter's declared range.
111    pub value: f32,
112}
113
114// ============================================================================
115// Method Name Constants
116// ============================================================================
117
118/// Method: Get single parameter value
119pub const METHOD_GET_PARAMETER: &str = "getParameter";
120/// Method: Set single parameter value
121pub const METHOD_SET_PARAMETER: &str = "setParameter";
122/// Method: Get all parameters with metadata
123pub const METHOD_GET_ALL_PARAMETERS: &str = "getAllParameters";
124/// Method: Get current meter frame (peak/RMS levels)
125pub const METHOD_GET_METER_FRAME: &str = "getMeterFrame";
126/// Method: Get current oscilloscope frame (1024-point waveform)
127pub const METHOD_GET_OSCILLOSCOPE_FRAME: &str = "getOscilloscopeFrame";
128/// Method: Get current audio runtime status
129pub const METHOD_GET_AUDIO_STATUS: &str = "getAudioStatus";
130/// Method: Request resize of editor window
131pub const METHOD_REQUEST_RESIZE: &str = "requestResize";
132/// Method: Register audio client with dev server
133pub const METHOD_REGISTER_AUDIO: &str = "registerAudio";
134/// Notification: Parameter changed (push from Rust to UI)
135pub const NOTIFICATION_PARAMETER_CHANGED: &str = "parameterChanged";
136/// Notification: Meter update from audio binary (push to browser)
137pub const NOTIFICATION_METER_UPDATE: &str = "meterUpdate";
138/// Notification: Audio runtime status changed
139pub const NOTIFICATION_AUDIO_STATUS_CHANGED: &str = "audioStatusChanged";
140
141// ============================================================================
142// Metering Types
143// ============================================================================
144
145/// Meter frame data for UI visualization.
146///
147/// All values are in linear scale (not dB).
148#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
149pub struct MeterFrame {
150    /// Left channel peak (linear, 0.0 to 1.0+)
151    pub peak_l: f32,
152    /// Right channel peak (linear, 0.0 to 1.0+)
153    pub peak_r: f32,
154    /// Left channel RMS (linear, 0.0 to 1.0+)
155    pub rms_l: f32,
156    /// Right channel RMS (linear, 0.0 to 1.0+)
157    pub rms_r: f32,
158    /// Sample timestamp (monotonic)
159    pub timestamp: u64,
160}
161
162/// Result for getMeterFrame method
163#[derive(Debug, Clone, Serialize, Deserialize)]
164pub struct GetMeterFrameResult {
165    /// Latest meter frame, or null if no data available
166    pub frame: Option<MeterFrame>,
167}
168
169// ============================================================================
170// Oscilloscope Types
171// ============================================================================
172
173/// Trigger mode for oscilloscope frame alignment.
174#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
175#[serde(rename_all = "camelCase")]
176pub enum OscilloscopeTriggerMode {
177    RisingZeroCrossing,
178}
179
180/// Channel view mode for oscilloscope visualization.
181#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
182#[serde(rename_all = "camelCase")]
183pub enum OscilloscopeChannelView {
184    Overlay,
185    Left,
186    Right,
187}
188
189/// Oscilloscope waveform frame data for UI visualization.
190#[derive(Debug, Clone, Serialize, Deserialize)]
191pub struct OscilloscopeFrame {
192    /// Left channel waveform points (length 1024).
193    pub points_l: Vec<f32>,
194    /// Right channel waveform points (length 1024).
195    pub points_r: Vec<f32>,
196    /// Sample rate in Hz used to capture the frame.
197    pub sample_rate: f32,
198    /// Sample timestamp (monotonic).
199    pub timestamp: u64,
200    /// True when signal amplitude stayed below threshold for full frame.
201    pub no_signal: bool,
202    /// Trigger mode used for alignment.
203    pub trigger_mode: OscilloscopeTriggerMode,
204}
205
206/// Result for getOscilloscopeFrame method.
207#[derive(Debug, Clone, Serialize, Deserialize)]
208pub struct GetOscilloscopeFrameResult {
209    /// Latest oscilloscope frame, or null if no data available.
210    pub frame: Option<OscilloscopeFrame>,
211}
212
213// ----------------------------------------------------------------------------
214// getAudioStatus
215// ----------------------------------------------------------------------------
216
217/// Audio runtime phase as observed by browser dev mode.
218#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
219#[serde(rename_all = "camelCase")]
220pub enum AudioRuntimePhase {
221    Disabled,
222    Initializing,
223    RunningFullDuplex,
224    RunningInputOnly,
225    Degraded,
226    Failed,
227}
228
229/// Structured diagnostic code for audio startup/runtime issues.
230#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
231#[serde(rename_all = "camelCase")]
232pub enum AudioDiagnosticCode {
233    LoaderUnavailable,
234    VtableMissing,
235    ProcessorCreateFailed,
236    NoInputDevice,
237    InputPermissionDenied,
238    NoOutputDevice,
239    StreamStartFailed,
240    Unknown,
241}
242
243/// Optional diagnostic details for the current runtime status.
244#[derive(Debug, Clone, Serialize, Deserialize)]
245pub struct AudioDiagnostic {
246    /// Machine-readable diagnostic code.
247    pub code: AudioDiagnosticCode,
248    /// Human-readable error/diagnostic message.
249    pub message: String,
250    /// Optional actionable hint for the user.
251    #[serde(skip_serializing_if = "Option::is_none")]
252    pub hint: Option<String>,
253}
254
255/// Current audio runtime status for browser dev mode.
256#[derive(Debug, Clone, Serialize, Deserialize)]
257pub struct AudioRuntimeStatus {
258    /// Current runtime phase.
259    pub phase: AudioRuntimePhase,
260    /// Optional startup/runtime diagnostic details.
261    #[serde(skip_serializing_if = "Option::is_none")]
262    pub diagnostic: Option<AudioDiagnostic>,
263    /// Active sample rate when available.
264    #[serde(skip_serializing_if = "Option::is_none")]
265    pub sample_rate: Option<f32>,
266    /// Active audio buffer size when available.
267    #[serde(skip_serializing_if = "Option::is_none")]
268    pub buffer_size: Option<u32>,
269    /// Last update timestamp (milliseconds since UNIX epoch).
270    pub updated_at_ms: u64,
271}
272
273/// Result for getAudioStatus method.
274#[derive(Debug, Clone, Serialize, Deserialize)]
275pub struct GetAudioStatusResult {
276    /// Current status if available on this host.
277    pub status: Option<AudioRuntimeStatus>,
278}
279
280// ----------------------------------------------------------------------------
281// requestResize
282// ----------------------------------------------------------------------------
283
284/// Parameters for requestResize request
285#[derive(Debug, Clone, Serialize, Deserialize)]
286pub struct RequestResizeParams {
287    /// Desired width in logical pixels
288    pub width: u32,
289    /// Desired height in logical pixels
290    pub height: u32,
291}
292
293/// Result of requestResize request
294#[derive(Debug, Clone, Serialize, Deserialize)]
295pub struct RequestResizeResult {
296    /// Whether the host approved the resize
297    pub accepted: bool,
298}
299
300// ----------------------------------------------------------------------------
301// registerAudio
302// ----------------------------------------------------------------------------
303
304/// Parameters for registerAudio request (audio binary → dev server)
305#[derive(Debug, Clone, Serialize, Deserialize)]
306pub struct RegisterAudioParams {
307    /// Unique client identifier
308    pub client_id: String,
309    /// Audio sample rate (e.g., 44100.0)
310    pub sample_rate: f32,
311    /// Buffer size in samples
312    pub buffer_size: u32,
313}
314
315/// Result of registerAudio request
316#[derive(Debug, Clone, Serialize, Deserialize)]
317pub struct RegisterAudioResult {
318    /// Acknowledgment message
319    pub status: String,
320}
321
322// ----------------------------------------------------------------------------
323// Notification: meterUpdate
324// ----------------------------------------------------------------------------
325
326/// Notification sent from audio binary to browser via dev server
327#[derive(Debug, Clone, Serialize, Deserialize)]
328pub struct MeterUpdateNotification {
329    /// Timestamp in microseconds
330    pub timestamp_us: u64,
331    /// Left channel peak (linear scale)
332    pub left_peak: f32,
333    /// Left channel RMS (linear scale)
334    pub left_rms: f32,
335    /// Right channel peak (linear scale)
336    pub right_peak: f32,
337    /// Right channel RMS (linear scale)
338    pub right_rms: f32,
339}
wavecraft_protocol/ipc/methods.rs

wavecraft_protocol/ipc/
methods.rs
