plughost_core/state.rs
1use crate::plugin::{PluginId, PluginInfo};
2
3mod encoding;
4
5/// A plugin's saved state with the identity of the class it belongs to. Its contents are opaque:
6/// store it with [`PluginState::to_bytes`] and read it back with [`PluginState::from_bytes`],
7/// which later plughost versions keep reading. Where it is stored is up to the
8/// application.
9///
10/// The name, vendor and version are those of the plugin that saved it, for display: a restore
11/// checks only the [`PluginId`], so a state saved by another version of the plugin restores, and
12/// the plugin decides what to make of it.
13#[derive(Clone, Debug, PartialEq, Eq)]
14pub struct PluginState {
15 pub(crate) id: PluginId,
16 pub(crate) name: String,
17 pub(crate) vendor: String,
18 pub(crate) version: String,
19 /// The processor's state, or the single state blob of formats that have one.
20 pub(crate) component: Vec<u8>,
21 /// The VST3 edit controller's own state, when it has one; `None` for other formats.
22 pub(crate) controller: Option<Vec<u8>>,
23}
24
25/// Maximum aggregate processor and controller payload for one project state (128 MiB).
26/// This does not include the plugin's identity strings or serialization framing.
27pub const MAX_STATE_BYTES: usize = 128 << 20;
28
29impl PluginState {
30 /// A state of the loaded plugin `info` describes, which names its identity, with a
31 /// `controller` state only for VST3 and a payload of at most [`MAX_STATE_BYTES`]. Internal to
32 /// the plughost crates; exempt from semver.
33 #[doc(hidden)]
34 #[must_use]
35 pub fn new(info: &PluginInfo, component: Vec<u8>, controller: Option<Vec<u8>>) -> PluginState {
36 PluginState {
37 id: info.id.clone(),
38 name: info.name.clone(),
39 vendor: info.vendor.clone(),
40 version: info.version.clone(),
41 component,
42 controller,
43 }
44 }
45
46 /// The plugin class that may restore this state.
47 pub fn id(&self) -> &PluginId {
48 &self.id
49 }
50
51 /// The display name of the plugin that saved the state.
52 pub fn name(&self) -> &str {
53 &self.name
54 }
55
56 /// The vendor of the plugin that saved the state, or empty when it gave none.
57 pub fn vendor(&self) -> &str {
58 &self.vendor
59 }
60
61 /// The version of the plugin that saved the state, or empty when it gave none.
62 pub fn version(&self) -> &str {
63 &self.version
64 }
65
66 /// The processor's state, or the format's single state blob. Internal to the plughost crates;
67 /// exempt from semver.
68 #[doc(hidden)]
69 pub fn component(&self) -> &[u8] {
70 &self.component
71 }
72
73 /// The VST3 edit controller's state, if it saved one. Internal to the plughost crates; exempt
74 /// from semver.
75 #[doc(hidden)]
76 pub fn controller(&self) -> Option<&[u8]> {
77 self.controller.as_deref()
78 }
79
80 /// Checks the opaque payload before it is cloned or handed to a native plugin.
81 pub fn validate(&self) -> Result<(), crate::InputError> {
82 let controller = self.controller.as_ref().map_or(0, Vec::len);
83 if self.component.len().saturating_add(controller) > MAX_STATE_BYTES {
84 return Err(crate::InputError::StateSize);
85 }
86 Ok(())
87 }
88
89 /// The state in plughost's persisted form: a versioned container of tagged sections for the
90 /// identity and each native payload, independent of the helper protocol. Store these bytes;
91 /// [`PluginState::from_bytes`] reads them in this and later plughost versions.
92 pub fn to_bytes(&self) -> Vec<u8> {
93 encoding::encode(self)
94 }
95
96 /// Reads bytes [`PluginState::to_bytes`] wrote, in this or an earlier plughost version from
97 /// 0.2.0 on,
98 /// without a plugin, so a state of a plugin that is not installed can be kept and written
99 /// again unchanged. Bytes that are not such a state fail with [`crate::InputError::StateBytes`],
100 /// and a payload over [`MAX_STATE_BYTES`] with [`crate::InputError::StateSize`], before
101 /// anything of that size is allocated.
102 pub fn from_bytes(bytes: &[u8]) -> Result<PluginState, crate::InputError> {
103 encoding::decode(bytes)
104 }
105}
106
107/// Why a state is being saved or applied. Unsupported native contexts are explicit errors.
108#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
109#[non_exhaustive]
110pub enum StatePurpose {
111 /// Save or restore persistent project state. This is the default.
112 #[default]
113 Project,
114 /// Save or restore a reusable preset.
115 Preset,
116 /// Transfer state to a duplicate instance.
117 Duplicate,
118}
119
120/// Bound for encoded preset files, separate from opaque project state and the IPC frame limit.
121pub const MAX_PRESET_BYTES: usize = 64 << 20;
122
123/// Native file metadata, kept separate from a plugin's opaque state.
124#[derive(Clone, Debug, PartialEq, Eq)]
125#[non_exhaustive]
126pub enum PresetMetadata {
127 /// The VST3 Info chunk is opaque XML bytes, preserved without interpreting vendor attributes.
128 Vst3 {
129 /// Uninterpreted XML bytes from the native `Info` chunk.
130 info: Vec<u8>,
131 },
132 /// Metadata from an Audio Unit property-list preset.
133 AudioUnit {
134 /// Native preset name, if supplied.
135 name: Option<String>,
136 },
137}
138
139/// Plugin identity and metadata read from a native preset container.
140#[derive(Clone, Debug, PartialEq, Eq)]
141#[non_exhaustive]
142pub struct PresetInfo {
143 /// Native class ID identifying the plugin that may restore this state.
144 pub class_id: String,
145 /// Format-specific container metadata, separate from DSP state.
146 pub metadata: PresetMetadata,
147}
148
149impl PresetInfo {
150 /// Constructs decoded preset identity and native metadata.
151 #[must_use]
152 pub fn new(class_id: impl Into<String>, metadata: PresetMetadata) -> PresetInfo {
153 PresetInfo {
154 class_id: class_id.into(),
155 metadata,
156 }
157 }
158}