Skip to main content

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}