diff --git a/packages/app/studio/src/ui/devices/DeviceEditor.tsx b/packages/app/studio/src/ui/devices/DeviceEditor.tsx index 8bcd8157c..90c1e0104 100644 --- a/packages/app/studio/src/ui/devices/DeviceEditor.tsx +++ b/packages/app/studio/src/ui/devices/DeviceEditor.tsx @@ -3,6 +3,8 @@ * * The component renders a device header, delegates menu and control creation, * and wires up drag-and-drop reordering for effect devices. + * + * @packageDocumentation */ import css from "./DeviceEditor.sass?inline" import {Lifecycle, ObservableValue, Procedure, Provider} from "@opendaw/lib-std" @@ -21,6 +23,9 @@ import {Colors, Project} from "@opendaw/studio-core" const className = Html.adoptStyleSheet(css, "DeviceEditor") +/** + * Returns the color used for the editor's header based on device type. + */ const getColorFor = (type: DeviceType) => { switch (type) { case "midi-effect": @@ -33,6 +38,7 @@ const getColorFor = (type: DeviceType) => { } } +/** Parameters required to construct a {@link DeviceEditor}. */ type Construct = { lifecycle: Lifecycle project: Project @@ -44,6 +50,9 @@ type Construct = { icon: IconSymbol } +/** + * Creates a label element bound to the box's label field. + */ const defaultLabelFactory = (lifecycle: Lifecycle, labelField: StringField): Provider => () => { const label: HTMLElement =

@@ -54,6 +63,9 @@ const defaultLabelFactory = (lifecycle: Lifecycle, labelField: StringField): Pro return label } +/** + * Renders an editor for the given device box. + */ export const DeviceEditor = ({lifecycle, project, adapter, populateMenu, populateControls, populateMeter, createLabel, icon}: Construct) => { const {editing} = project diff --git a/packages/app/studio/src/ui/devices/panel/DevicePanel.tsx b/packages/app/studio/src/ui/devices/panel/DevicePanel.tsx index 60304947f..dd6ec325a 100644 --- a/packages/app/studio/src/ui/devices/panel/DevicePanel.tsx +++ b/packages/app/studio/src/ui/devices/panel/DevicePanel.tsx @@ -3,6 +3,8 @@ * * The panel hosts individual device editors, meters and the channel strip * while supporting scrolling and drag-and-drop reordering of devices. + * + * @packageDocumentation */ import css from "./DevicePanel.sass?inline" import {asDefined, Lifecycle, ObservableValue, Option, Terminable, Terminator, UUID} from "@opendaw/lib-std" @@ -34,6 +36,7 @@ import {Project} from "@opendaw/studio-core" const className = Html.adoptStyleSheet(css, "DevicePanel") +/** Options used to construct a {@link DevicePanel}. */ /** Props for {@link DevicePanel}. */ type Construct = { lifecycle: Lifecycle @@ -77,7 +80,8 @@ export const DevicePanel = ({lifecycle, service}: Construct) => { scrollModel.contentSize = containers.clientWidth } - const getContext = (project: Project, box: Box): Context => { +/** Resolves the device host context for the box being edited. */ +const getContext = (project: Project, box: Box): Context => { const deviceHost = project.boxAdapters.adapterFor(box, Devices.isHost) return asDefined(box.accept>({ visitAudioUnitBox: (_box: AudioUnitBox): Context => ({ @@ -138,6 +142,9 @@ export const DevicePanel = ({lifecycle, service}: Construct) => { updateScroller() })) + /** + * Subscribes to changes in the device chain and manages editor mounts. + */ const subscribeChain = ({midiEffects, instrument, audioEffects, host}: { midiEffects: IndexedBoxAdapterCollection, instrument: ObservableValue>, diff --git a/packages/docs/docs-dev/extending/plugin-host.md b/packages/docs/docs-dev/extending/plugin-host.md new file mode 100644 index 000000000..f2b99b719 --- /dev/null +++ b/packages/docs/docs-dev/extending/plugin-host.md @@ -0,0 +1,20 @@ +# Plugin Host + +OpenDAW's plugin host allows devices written with the SDK to run inside the +application. It manages the lifecycle of plugins and provides access to the +transport, parameter automation and messaging APIs. + +## Capabilities + +- Loads WebAssembly or JavaScript based processors +- Connects plugin parameters to the automation system +- Exposes audio and MIDI buffers for real‑time processing + +## Host environment + +Plugins execute in a sandboxed environment and communicate with the host via +a message channel. The host is responsible for instantiating the processor and +supplying state such as the current tempo or sample rate. + +For a walk‑through on creating your own plugin, see the +[plugin guide](./plugin-guide.md). diff --git a/packages/docs/docs-user/features/devices-and-plugins.md b/packages/docs/docs-user/features/devices-and-plugins.md index 1e59f7f4e..2f64d8c1b 100644 --- a/packages/docs/docs-user/features/devices-and-plugins.md +++ b/packages/docs/docs-user/features/devices-and-plugins.md @@ -21,7 +21,7 @@ OpenDAW loads plugins built with the project's SDK or other compatible Web Audio - Traditional desktop formats like VST or Audio Unit may require additional support and are not guaranteed to work. - Different plugins may expose unique parameters; test them in your environment to confirm full compatibility. -Interested in building your own plugins? Check out the [plugin guide](../../docs-dev/extending/plugin-guide.md) and the [device boxes guide](../../docs-dev/extending/device-boxes.md) in the developer documentation. +Interested in building your own plugins? Check out the [plugin guide](../../docs-dev/extending/plugin-guide.md), the [device boxes guide](../../docs-dev/extending/device-boxes.md), and the [plugin host overview](../../docs-dev/extending/plugin-host.md) in the developer documentation. For how device controls are connected to automation, see the [parameter adapter guide](../../docs-dev/extending/parameter-adapters.md). diff --git a/packages/docs/sidebarsDev.js b/packages/docs/sidebarsDev.js index e09df28f6..9a16e83f3 100644 --- a/packages/docs/sidebarsDev.js +++ b/packages/docs/sidebarsDev.js @@ -132,6 +132,7 @@ module.exports = { { type: "doc", id: "extending/plugin-guide" }, { type: "doc", id: "extending/plugin-api" }, { type: "doc", id: "extending/plugin-examples" }, + { type: "doc", id: "extending/plugin-host" }, { type: "doc", id: "extending/device-boxes" }, { type: "doc", id: "extending/testing-plugins" }, { type: "doc", id: "extending/processor-guide" }, diff --git a/packages/studio/adapters/src/DeviceBox.ts b/packages/studio/adapters/src/DeviceBox.ts index 2de2d95b9..53ca8b24f 100644 --- a/packages/studio/adapters/src/DeviceBox.ts +++ b/packages/studio/adapters/src/DeviceBox.ts @@ -1,3 +1,8 @@ +/** + * Utility types and helper functions for working with device boxes. + * + * @packageDocumentation + */ import { Pointers } from "@opendaw/studio-enums"; import { BooleanField, diff --git a/packages/studio/adapters/src/ParameterAdapterSet.ts b/packages/studio/adapters/src/ParameterAdapterSet.ts index 0034129fb..afb2e22c2 100644 --- a/packages/studio/adapters/src/ParameterAdapterSet.ts +++ b/packages/studio/adapters/src/ParameterAdapterSet.ts @@ -1,3 +1,8 @@ +/** + * Maintains adapters for device parameters and provides lookup utilities. + * + * @packageDocumentation + */ import {FieldKeys, PointerTypes, PrimitiveField, PrimitiveValues} from "@opendaw/lib-box" import {assert, NumberArrayComparator, SortedSet, StringMapping, Terminable, unitValue, ValueMapping} from "@opendaw/lib-std" import {AutomatableParameterFieldAdapter} from "./AutomatableParameterFieldAdapter" diff --git a/packages/studio/boxes/src/device-boxes.ts b/packages/studio/boxes/src/device-boxes.ts index e8384fb90..60209adef 100644 --- a/packages/studio/boxes/src/device-boxes.ts +++ b/packages/studio/boxes/src/device-boxes.ts @@ -10,5 +10,8 @@ export interface DeviceBox { id: string; } -/** Collection of registered device boxes. */ +/** + * Registry of all available device boxes. Plugins may append to this list + * during initialization to expose new device types to the host. + */ export const deviceBoxes: DeviceBox[] = []; diff --git a/packages/studio/core-processors/src/DeviceProcessorFactory.ts b/packages/studio/core-processors/src/DeviceProcessorFactory.ts index 9f3c8d7f9..afa001b46 100644 --- a/packages/studio/core-processors/src/DeviceProcessorFactory.ts +++ b/packages/studio/core-processors/src/DeviceProcessorFactory.ts @@ -1,3 +1,10 @@ +/** + * Factories that construct processor instances for the various device + * categories used by the engine. + * + * @packageDocumentation + */ + import { ArpeggioDeviceBox, AudioBusBox, @@ -66,6 +73,13 @@ import { UnknownMidiEffectDeviceProcessor } from "./devices/midi-effects/Unknown * {@link @opendaw/studio-enums#AudioUnitType.Instrument | AudioUnitType.Instrument}. */ export namespace InstrumentDeviceProcessorFactory { + /** + * Creates an instrument processor for the provided device box. + * + * @param context - Engine context used to resolve adapters. + * @param box - Box describing the instrument device. + * @returns Processor instance or `undefined` when the box is not supported. + */ export const create = ( context: EngineContext, box: Box, @@ -110,6 +124,13 @@ export namespace InstrumentDeviceProcessorFactory { * {@link @opendaw/studio-enums#AudioSendRouting | AudioSendRouting}. */ export namespace MidiEffectDeviceProcessorFactory { + /** + * Instantiates a MIDI effect processor for the given box. + * + * @param context - Engine context used to resolve adapters. + * @param box - Box describing the MIDI effect device. + * @returns The created processor. + */ export const create = ( context: EngineContext, box: Box, @@ -157,6 +178,13 @@ export namespace MidiEffectDeviceProcessorFactory { * ``` */ export namespace AudioEffectDeviceProcessorFactory { + /** + * Creates an audio effect processor for the specified device box. + * + * @param context - Engine context used to resolve adapters. + * @param box - Box describing the audio effect. + * @returns The created processor. + */ export const create = ( context: EngineContext, box: Box, diff --git a/packages/studio/core/src/EffectFactories.ts b/packages/studio/core/src/EffectFactories.ts index 3c83517d5..3fdb22cdb 100644 --- a/packages/studio/core/src/EffectFactories.ts +++ b/packages/studio/core/src/EffectFactories.ts @@ -1,3 +1,8 @@ +/** + * Built-in collection of effect factory definitions. + * + * @packageDocumentation + */ import {INVERSE_SQRT_2, UUID} from "@opendaw/lib-std" import { ArpeggioDeviceBox, @@ -192,17 +197,18 @@ export namespace EffectFactories { }) } } - - /** Mapping of MIDI effect names to their factory definitions. */ + /** Mapping of available MIDI effect factories by name. */ export const MidiNamed = {Arpeggio, Pitch, Zeitgeist} - /** Mapping of audio effect names to their factory definitions. */ + /** Mapping of available audio effect factories by name. */ export const AudioNamed = {StereoTool, Delay, Reverb, Revamp, Modular} - /** List of all built-in MIDI effect factories. */ + /** List of registered MIDI effect factories. */ export const MidiList: ReadonlyArray> = Object.values(MidiNamed) - /** List of all built-in audio effect factories. */ + /** List of registered audio effect factories. */ export const AudioList: ReadonlyArray> = Object.values(AudioNamed) - /** Combined lookup of MIDI and audio effect factories. */ + /** Combined mapping of all effect factories. */ export const MergedNamed = {...MidiNamed, ...AudioNamed} + /** Keys of the {@link MidiNamed} mapping. */ export type MidiEffectKeys = keyof typeof MidiNamed + /** Keys of the {@link AudioNamed} mapping. */ export type AudioEffectKeys = keyof typeof AudioNamed } diff --git a/packages/studio/core/src/EffectFactory.ts b/packages/studio/core/src/EffectFactory.ts index 05ea7a61f..d5a06d1c5 100644 --- a/packages/studio/core/src/EffectFactory.ts +++ b/packages/studio/core/src/EffectFactory.ts @@ -1,3 +1,8 @@ +/** + * Interface definition for effect factories used to construct effect boxes. + * + * @packageDocumentation + */ import {EffectPointerType, IconSymbol} from "@opendaw/studio-adapters" import {Field} from "@opendaw/lib-box" import {int} from "@opendaw/lib-std" diff --git a/packages/studio/core/src/InstrumentFactories.ts b/packages/studio/core/src/InstrumentFactories.ts index edb3a889a..d3468c9e8 100644 --- a/packages/studio/core/src/InstrumentFactories.ts +++ b/packages/studio/core/src/InstrumentFactories.ts @@ -1,3 +1,9 @@ +/** + * Built-in instrument factory descriptors. + * + * @packageDocumentation + */ + import { AudioFileBox, NanoDeviceBox, diff --git a/packages/studio/sdk/src/device-api.ts b/packages/studio/sdk/src/device-api.ts index b3b49d106..ff4e0d5d9 100644 --- a/packages/studio/sdk/src/device-api.ts +++ b/packages/studio/sdk/src/device-api.ts @@ -1,3 +1,10 @@ +/** + * High level abstraction for interacting with connected audio and MIDI + * hardware. + * + * @packageDocumentation + */ + /** * Interacts with input and output devices such as audio interfaces or MIDI * controllers.