plugdata Objects - Plugdata

plugindata provides specialized objects for integrating Pure Data patches with DAW environments. These objects only work in the plugin version of plugdata and enable features like automation, tempo sync, and session state management.

Overview

The plugdata-specific objects bridge Pure Data with modern DAW workflows:

[param] - Create and control DAW automation parameters
[playhead] - Receive DAW transport and timing information
[plugin_latency] - Report processing latency for compensation
[daw_storage] - Store persistent data in DAW session state

These objects only function in the plugin version of plugdata (VST3, AU, LV2, CLAP). They will not work in the standalone application.

DAW Automation

[param]

Create and control DAW automation parameters The [param] object sends and receives automation parameters to and from the DAW. Before using it, you must create an automation parameter in the plugdata sidebar.

Syntax

[param <name> <auto-mode>]

Arguments

name

symbol

required

Parameter name - must match a parameter created in the sidebar

auto-mode

float

default:"0"

When set to 1, automatically handles change state when interacting with connected GUI objects (sliders, number boxes, etc.)

Inlets

Inlet 1: Parameter Value

Type: floatSet the DAW parameter value. This will update the automation in your DAW when recording.

Inlet 2: Change State

Type: floatInform the DAW about parameter change state:

0 - Reading (not being changed by user)
1 - Writing (actively being changed)

This enables touch automation modes and proper automation recording.

Outlets

Outlet 1: Parameter Value

Type: floatOutputs the current parameter value received from the DAW automation.

Messages

create

message

Activate the automation parameter (creates it if it doesn’t exist)

range

message

Syntax: range <min> <max>Set the parameter’s minimum and maximum range values.

mode

message

Syntax: mode <mode-number>Set parameter scaling mode:

1 - Float (linear)
2 - Integer (stepped)
3 - Logarithmic
4 - Exponential

Example Usage

// Create a filter cutoff parameter with linear range
[loadbang]
|
[range 20 20000, mode 3(  // Logarithmic scaling
|
[param filter_cutoff 1]  // Auto-mode enabled
|
[snapshot~]
|
[osc~]

Workflow

Create Parameter in Sidebar
- Open the Parameters panel in plugdata
- Add a new parameter with a unique name
- Set range and scaling options
Connect in Patch
- Create [param <name>] object matching sidebar name
- Connect to controls (sliders, number boxes)
- Enable auto-mode for GUI interaction
Use in DAW
- The parameter appears in your DAW’s automation list
- Record automation by adjusting controls
- Playback automation drives the parameter

DAW Transport

[playhead]

Receive DAW playhead and transport information The [playhead] object outputs comprehensive timing and transport information from the DAW, including play state, tempo, time signature, and position in multiple formats.

Syntax

[playhead]

Arguments

None.

Inlets

None - this object automatically receives updates from the DAW.

Outlets

The playhead object has 9 outlets providing different timing information:

Outlet 1: Playing State

Type: float

1 if DAW is playing
0 if stopped

Outlet 2: Recording State

Type: float

1 if DAW is recording
0 if not recording

Outlet 3: Loop Information

Type: list (3 floats)

First value: 1 if looping, 0 otherwise
Second value: Loop start position
Third value: Loop end position
All zeros when not looping

Outlet 4: Edit Time

Type: floatCurrent edit/cursor position in the DAW timeline

Outlet 5: Frame Rate

Type: floatVideo frame rate (for video sync)

Common values: 24, 25, 29.97, 30, 60

Outlet 6: BPM

Type: floatCurrent tempo in beats per minute

Outlet 7: Last Bar

Type: floatPosition of the most recent bar start

Outlet 8: Time Signature

Type: listCurrent time signature (e.g., 4 4 for 4/4 time)

Outlet 9: Position

Type: list (3 floats)Current playhead position in three formats:

PPQ (Pulses Per Quarter note) position
Time in samples
Time in seconds

Example Usage

Tempo-Synced Metronome

[playhead]
|      \
|       \
|        [unpack f f f]
|         |
|        [/ 1000]  // Convert to seconds
|         |
[select 1] [metro]
|           |
[bang~]    [bang]

Beat Counter

[playhead]
     |
     |  (outlet 6: BPM)
     |
[f]  [t b f]
|    |
[60000] [/]  // ms per beat
|
[metro]
|
[counter]
|
[% 4]  // Count 1-4

Plugin Configuration

[plugin_latency]

Report plugin processing latency to DAW The [plugin_latency] object informs the DAW about the processing delay introduced by your patch, enabling automatic delay compensation to keep tracks in sync.

Syntax

[plugin_latency]

Arguments

None.

Inlets

Inlet 1: Latency Value

Type: floatSet the latency compensation value in samples. The DAW will automatically compensate for this delay across all tracks.

Outlets

None.

When to Use

Report latency when your patch includes:

Look-ahead processing - FFT analysis, spectral effects
Large filter delays - High-order IIR filters
Buffering - Custom delay lines for processing

Example Usage

FFT Processing with Latency Compensation

// FFT requires one block of look-ahead
[block~ 2048]  // 2048 sample FFT
|
[2048(  // Report latency
|
[plugin_latency]

// Your FFT processing here
[rfft~]
[rifft~]

Calculate Latency from Block Size

[loadbang]
|
[; pd dsp 1(
|
[samplerate~]
|      \
|       [2048(  // Block size
|        |
[/]     // Calculate actual ms
|
[* 1000]
|
[plugin_latency]

Only set latency during patch initialization (with [loadbang]). Changing latency during playback can cause audio glitches.

Session State

[daw_storage]

Store persistent data in DAW session state The [daw_storage] object allows you to save arrays, lists, symbols, and other data as part of the DAW’s session/project file. This data persists between sessions and is saved with your DAW project.

While [daw_storage] is documented in the ELSE library folder, it is a plugdata-specific object that only functions in the plugin version.

Syntax

[daw_storage <unique-id>]

Arguments

unique-id

symbol

required

Unique identifier for this storage instance. Must be unique within your patch to avoid data conflicts.

Inlets

Inlet 1: Data to Store

Type: anything (float, symbol, list, array)Send any data to be stored in the DAW session. This data will be saved with the project file.

Outlets

Outlet 1: Stored Data

Type: anythingOutputs the last stored data when the patch loads. This allows you to restore state from the previous session.

Example Usage

Save Preset Data

// On patch load, restore last preset
[loadbang]
|
[daw_storage my_preset]
|
[route list]
|
[unpack f f f f]
|  |  |  |
// Restore parameter values

Store Array Contents

// Save wavetable data
[array get my_wavetable]
|
[daw_storage wavetable_data]

// On load, restore it
[loadbang]
|
[daw_storage wavetable_data]
|
[array set my_wavetable]

Save UI State

// Store toggle states and values
[pack f f f f]
|
[daw_storage ui_state]

// Restore on load
[loadbang]
|
[daw_storage ui_state]
|
[unpack f f f f]

Use Cases

Preset Management - Save and recall parameter combinations
Sequence Data - Store sequencer patterns and note data
Wavetables - Persist custom waveform data
UI State - Remember control positions and settings
Sample Data - Cache processed audio or analysis results

Best Practices

Use Unique IDs - Each storage instance needs a distinct identifier
Initialize on Load - Use [loadbang] to retrieve stored data
Limit Data Size - Large amounts of data can slow project loading
Version Your Data - Include version numbers if data format may change

// Good practice: versioned storage
[pack 1 f f f]  // Version 1 + 3 parameters
|
[daw_storage my_data_v1]

Integration Workflow

Combining plugdata objects for complete DAW integration:

Complete Plugin Template

// 1. Restore session state
[loadbang]
|
[daw_storage patch_state]
|
[unpack f f]
|        |
|        |  // 2. Create automation parameters
|        |  [param filter_freq 1]
|        |  |
|        \  /
|         \/
|         /\
|        /  \
//  3. Use playhead for tempo sync
[playhead]
     |
     (outlet 6: BPM)
     |
[expr 60000 / $f1]  // ms per beat
|
[metro]

// 4. Report any processing latency
[2048(
|
[plugin_latency]

Testing in DAW

Load plugin in your DAW
Create automation - Parameters appear in automation list
Test transport sync - Verify tempo and playhead tracking
Save and reload project - Confirm state persistence
Check latency - Ensure tracks remain in sync

Debugging

If objects don’t work:

Verify you’re using the plugin version (not standalone)
Check that parameters are created in sidebar before using [param]
Ensure unique IDs for all [daw_storage] instances
Look for console errors in the plugdata window

DAW Integration - How plugdata works in your DAW
Automation Parameters - Complete automation workflow guide
ELSE Library - Additional ELSE objects used with plugdata features

Getting Started

Core Concepts

User Guide

Objects Reference

Advanced

Resources

​Overview

​DAW Automation

​[param]

​Syntax

​Arguments

​Inlets

​Outlets

​Messages

​Example Usage

​Workflow

​DAW Transport

​[playhead]

​Syntax

​Arguments

​Inlets

​Outlets

​Example Usage

​Plugin Configuration

​[plugin_latency]

​Syntax

​Arguments

​Inlets

​Outlets

​When to Use

​Example Usage

​Session State

​[daw_storage]

​Syntax

​Arguments

​Inlets

​Outlets

​Example Usage

​Use Cases

​Best Practices

​Integration Workflow

​Complete Plugin Template

​Testing in DAW

​Debugging

​Related Documentation

Build docs developers (and LLMs) love

Overview

DAW Automation

[param]

Syntax

Arguments

Inlets

Outlets

Messages

Example Usage

Workflow

DAW Transport

[playhead]

Syntax

Arguments

Inlets

Outlets

Example Usage

Plugin Configuration

[plugin_latency]

Syntax

Arguments

Inlets

Outlets

When to Use

Example Usage

Session State

[daw_storage]

Syntax

Arguments

Inlets

Outlets

Example Usage

Use Cases

Best Practices

Integration Workflow

Complete Plugin Template

Testing in DAW

Debugging

Related Documentation