VirtualDJ's C++ plugin interface: the native-code extension point, and — more importantly for this repo — the boundary where VDJScript's return values are still typed.
Written 2026-07-30. Source labels follow Evidence Standards: the
headers are Official (Tier 2 — official documentation, which this repo has caught being
incomplete before), the on-disk observations are Local observation on VirtualDJ 2026
(bundle 18.0.9482, macOS arm64), and the binary findings are Binary symbol table.
For the bounded host-memory experiment and its build/verification commands, see Runtime Memory Probe. It is separate from the query introspection plugin and does not establish parser or verb behaviour.
The HTTP control interface returns everything as text, so a query's real type has to be recovered by observation. The plugin SDK shows why: the host exposes two separately typed query entry points, and HTTP collapses both into a response body.
struct IVdjCallbacks8
{
virtual HRESULT SendCommand(const char *command)=0; // execute
virtual HRESULT GetInfo(const char *command, double *result)=0; // numeric query
virtual HRESULT GetStringInfo(const char *command, void *result, int size)=0; // text query
virtual HRESULT DeclareParameter(void *parameter, int type, int id,
const char *name, const char *shortName,
float defaultvalue)=0;
virtual HRESULT GetSongBuffer(int pos, int nb, short **buffer)=0;
};VDJScript is not stringly typed. Script goes in as const char *; results come out as
either a double or a UTF-8 buffer, chosen by which call you make. Everything numeric —
booleans, counts, 0..1 sliders, percentages — shares the single double. That is why
tests/verb-return-types.json records 334 "bool" verbs: those are doubles that the HTTP layer
renders as yes/no.
This maps exactly onto the vtable slots
extract_action_contracts.py calibrated from compiled
ACTION_ classes, before these headers were consulted — independent corroboration of the
same three-way split (Evidence Standards rule 1g):
| Verb-table vtable slot | SDK callback |
|---|---|
| slot 2 — execute | SendCommand |
| slot 3 — generic query (the variant) | GetInfo → double * |
| slot 4 — specialized text query | GetStringInfo → buffer |
Corrected by measurement (Local test, plugin channel, 2026-08-15). Calling both
callbacks on all 1,028 verbs partitions the result exactly, and the slot 3/slot 4 split above
is not what happens:
- Slot 3 backs both callbacks — 594 of the 599 text answers, and every numeric answer.
GetStringInfois mostly the variant rendered as text. - Slot 5 is a fallback label provider. Of the 174 verbs that do not override slot 3,
exactly 5 answer text and all 5 override slot 5 —
stop_button→"■",scratchbank_load→"Bank A",sampler_pad_page→"1 to 8". The other 169 answer nothing. Every text answer in the capture therefore comes from slot 3 or slot 5, with no remainder. - Slot 4's role is unproven. All 85 of its text-answering verbs also override slot 3, so it explains nothing on its own.
Two operational facts from the same capture. E_INVALIDARG is the numeric channel's "wrong
channel, ask the other one" code and S_FALSE is the text channel's; VirtualDJ writes
0.0 to *result even when it returns an error, so the HRESULT is the answer and a raw
0 is meaningless without it. And because the HRESULT arrives separately from the value, this
channel can tell a recognized argument from an ignored one — is_using cue answers
S_OK/off where is_using zzznotakeyword answers E_NOTIMPL — which HTTP structurally
cannot. See the tracker's Plugin Channel section.
It also localised a known defect — and then refuted the guess about it. master_beat_num
returns float32 bits through an integer path over HTTP
(HTTP Control Interface), and this page previously reasoned
that since the core hands back a double, the coercion was "almost certainly in the rendering
path, not the engine." Wrong. GetInfo("master_beat_num", &d) on VirtualDJ 2026 (bundle
18.0.9583, Local test via the plugin channel, 2026-08-15) returns S_OK with d holding
exactly 1083943558.0 — the int32 reading of float32 bits 0x409baa86 (= 4.8646),
already punned before it reaches any channel. The defect is in the core; HTTP was rendering
a broken number faithfully. Consumers of this verb must reinterpret the int32 bits as float32
on either channel.
Worth stating plainly, because the headers look like they should be a reference and are not.
Checked mechanically 2026-07-30 against the 1,028-name verb table: across all 32 KB of unique
header text, not one verb name appears as a verb. Sixteen names match as ordinary English
in comments and C++ parameter names — // the crossfader moves continuously…,
float *volume in OnTransformPosition, // load and unload a plugin,
OnSearch(const char* search, …) — and that is the entire overlap.
This is structural rather than an omission. The command parameter is opaque:
virtual HRESULT GetInfo(const char *command, double *result)=0;The SDK defines how to ask — calling convention, type channels, HRESULT contract — and says nothing about what may be asked. The vocabulary lives entirely inside VirtualDJ, which is why the verb set had to be extracted from the binary (Undocumented VDJScript Candidates §verb table) rather than read out of a header.
Consequences worth keeping straight:
- The plugin is not a discovery instrument for verbs. It is for types and behaviour that only exist at runtime. Existence, aliases, categories and capability are already settled from the binary.
- Verb questions can be answered with no VirtualDJ present — from this repo's committed
artifacts (
tests/verb-table.json,action-contracts.json,verb-return-types.json,verb-existence-sweep.json, all read byjust get-verb <name>). Producing them requires the app; consuming them does not.
| Fact | Detail |
|---|---|
| Copyright | (c)Atomix Productions 2011-2018, in every header |
| License | None stated. No LICENSE text in the headers, and no terms of use or redistribution conditions on the SDK download page. |
| Official download | PluginSDK8.html → VirtualDJ8_SDK_20211003.zip ("header files for all types of plug-ins") |
| Community examples | github.com/szemek/virtualdj-plugins-examples — 8 buildable examples, Xcode 14.3 / macOS 13.3, "copied and adapted from official documentation". No LICENSE file; the headers are still Atomix's. |
Publishing the SDK for plugin authors implies permission to use it; it grants nothing about
redistribution. This repo therefore does not vendor the headers — vendor/ is gitignored,
with fetch instructions in the ignore entry. just download-sdk fetches a local copy into vendor/vdj-sdk/ (with a SOURCE.txt recording the URL, date and sha256, since the headers carry no version of their own); put one there by hand to build
anything described here.
Everything derives from IVdjPlugin8, which supplies lifecycle, parameters, UI, and the three
host callbacks above.
class IVdjPlugin8
{
virtual HRESULT VDJ_API OnLoad() {return S_OK;}
virtual HRESULT VDJ_API OnGetPluginInfo(TVdjPluginInfo8 *info) {return E_NOTIMPL;}
virtual ULONG VDJ_API Release() {delete this; return S_OK;}
virtual HRESULT VDJ_API OnParameter(int id) {return S_OK;}
virtual HRESULT VDJ_API OnGetParameterString(int id, char *outParam, int outParamSize);
virtual HRESULT VDJ_API OnGetUserInterface(TVdjPluginInterface8 *pluginInterface);
IVdjCallbacks8 *cb;
};| Subclass | Header | Key virtuals |
|---|---|---|
IVdjPluginStartStop8 |
vdjPlugin8.h |
OnStart, OnStop |
IVdjPluginDsp8 |
vdjDsp8.h |
OnProcessSamples(float *buffer, int nb) |
IVdjPluginBufferDsp8 |
vdjDsp8.h |
buffered audio variant |
IVdjPluginPositionDsp8 |
vdjDsp8.h |
OnTransformPosition(double *songPos, double *videoPos, float *volume, float *srcVolume) |
IVdjPluginVideoFx8 |
vdjVideo8.h |
OnDraw, OnDeviceInit, OnDeviceClose, GetDevice, GetTexture |
IVdjPluginVideoTransition8 |
vdjVideo8.h |
OnDraw(float crossfader) |
IVdjPluginVideoTransitionMultiDeck8 |
vdjVideo8.h |
OnDrawMultiDeck(int nbVideoDecks, int *videoDecks) |
IVdjPluginOnlineSource |
vdjOnlineSource.h |
OnSearch, GetStreamUrl, GetFolder, GetFolderList, OnLogin/OnOAuth, context menus |
OnTransformPosition and the online-source interface are worth noting for this repo: they
expose song position and browser/source integration at a level VDJScript does not reach.
virtual HRESULT GetSongBuffer(int pos, int nb, short **buffer)=0;Undocumented in every header beyond that signature; measured on VirtualDJ 2026
(bundle 18.0.9583), and the full evidence is in the
Local Test Tracker.
posandnbboth count stereo frames. A frame is 4 bytes: interleaved left/rightint16.- It returns an interior pointer, not a copy:
buffer = base + 4 × pos, holding exactly over hundreds of thousands of frames. The whole track is decoded and resident (~54 MB for five minutes), so reading any part of it is free. - Sample rate is 44,100 Hz, established by cross-check rather than assumption.
- The buffer runs past the song, silence-padded by roughly 2^16 frames.
- Bounds are checked at the top only.
pos + nbbeyond the buffer givesE_FAIL, but a negativeposis accepted and returns a pointer before the buffer — an out-of-bounds read. Clamp it yourself.
Track length is not available as get_totaltime or get_length (neither is a verb
on this build); use get_time 'total', in milliseconds.
Typeinfo names present in /Applications/VirtualDJ.app/Contents/MacOS/VirtualDJ but absent
from every public header (Binary symbol table, 2026-07-30):
IVdjPluginHelperBeats— see below, now characterized.IVdjTransitionCallbacks8— see below.
The public surface is a subset of the live one. Treat the SDK as a partial export of an internal framework, not a complete description of it.
Full re-pass (Binary symbol table, VirtualDJ 2026 bundle 18.0.9246, macOS universal
x86_64+arm64, 2026-09-27) against a debug-symbol-rich build turned up more of the internal
surface than the stripped installed copy exposes (321k demangled symbols vs. 1,238 on the
Mac App Store-style bundle at 18.0.9482). Every RTTI-backed class name present:
IVdjFolder IVdjString IVdjPlugin8 IVdjCallbacks8 IVdjPluginDsp8 IVdjTracksList
IVdjContextMenu IVdjPluginVideoFx8 IVdjSubfoldersList IVdjVideoCallbacks8
IVdjPluginStartStop8 IVdjPluginHelperBeats IVdjPluginOnlineSource IVdjPluginPositionDsp8
IVdjTransitionCallbacks8 IVdjVideoMouseCallbacks8 IVdjPluginVideoTransition8
IVdjPluginVideoTransitionMultiDeck8 IVdjOAuth
IVdjFolder, IVdjString, IVdjTracksList, IVdjSubfoldersList, IVdjContextMenu, and
IVdjOAuth are the data-model types passed into IVdjPluginOnlineSource methods
(GetFolder, GetFolderList, onSearch, context menus, OnOAuth) — named here for the
first time but not yet individually characterized.
Four real method bodies exist in the binary (not just a typeinfo stub), all under a private namespace so no plugin-facing header declares them:
class IVdjPluginHelperBeats
{
virtual void onLoadBeats(std::vector<float> beats, int deck, IVdjPlugin8 *plugin);
virtual void onParameterBeats(int id, IVdjPlugin8 *plugin);
virtual void onGetParameterStringBeats(int id, char *outParam, int outParamSize);
virtual void formatBeats(char *outParam, int outParamSize, float value);
};(Signatures inferred from the demangled linkage names — onLoadBeats(std::vector<float, std::allocator<float>>, int, IVdjPlugin8*) etc. — parameter names are guesses; HRESULT
vs. void return is not yet confirmed.)
This is a mixin in the same family as IVdjPluginDsp8/IVdjPluginPositionDsp8: a plugin
that also inherits it gets onLoadBeats called with the full beatgrid as a
vector<float> whenever a track loads — almost certainly beat timestamps, at a
granularity VDJScript does not expose (no get_beat-family verb returns the whole grid).
The *Beats-suffixed calls shadow the ordinary OnParameter/OnGetParameterString so a
beat-specific control group can exist independently of the plugin's main one, and
formatBeats looks like a value→string formatter for that group. The only confirmed
implementer of the mixin is VirtualDJ's own built-in beatgrid editor
(CInternalPluginAFX_BeatGrid) — not established as available to third-party bundles from
evidence gathered so far.
Unresolved: whether a third-party (non-internal) plugin can actually opt into this mixin
the way it can IVdjPluginDsp8, or whether it is reserved to CInternalPluginAFX_BeatGrid.
No header exists to declare the base class, so a plugin would have to hand-declare a
matching vtable shape — untested.
CPlugin (VirtualDJ's own plugin-host wrapper object, not a plugin) carries:
CPlugin::registerTransitionCallbacks(IVdjTransitionCallbacks8*)
CPlugin::unregisterTransitionCallbacks(IVdjTransitionCallbacks8*)
CPlugin::transitionCallbacks // stored pointer
CPlugin::transitionCallbackUse // guard flagNo method bodies for IVdjTransitionCallbacks8 itself survive (it is implemented by the
plugin side, called by the host — same shape as IVdjPluginVideoFx8), so its virtuals are
still unknown; only the registration plumbing is characterized.
Adjacent and newly named: IVdjVideoCallbacks8 and IVdjVideoMouseCallbacks8 —
also RTTI-only, also host-calls-plugin. The name of the second strongly implies the video-FX
render target (GetDevice/GetTexture from IVdjPluginVideoFx8) can also receive mouse
input, not just accept draw calls — unconfirmed, no method bodies recovered yet.
The video draw/composite path that backs all of this, from CPlugin and CVideoEngine:
CPlugin::GetDevice(EVdjVideoEngine, void**)
CPlugin::GetTexture(EVdjVideoEngine, void**, TVertex**)
CPlugin::setVideoDevice(IRenderTarget*, int, int)
CPlugin::DrawDeck()
CVideoEngine::DrawDeck(int deck)
CVideoEngine::_DrawDeck(int deck, TVertex*)plus ten free-function overloads DrawDeck0(int, TVertex*) … DrawDeck9(int, TVertex*) and
a __DrawDeck data symbol (a dispatch table, by name and by being a d-type symbol next to
ten near-identical functions) — consistent with up to 10 video decks, each with its own
compiled draw routine, selected by table lookup rather than a runtime switch.
setVideoDevice taking an IRenderTarget* confirms the texture handed to a video-FX plugin
is a real GPU render target (this build is Metal-only on macOS arm64), not a copied buffer.
Caller trace, decompiled (Binary decompiler, Ghidra 12.1.3 headless, full auto-analysis of
the arm64 slice of 18.0.9246, 2026-09-27 — first decompiler pass on this build; prior
findings in this file were symbol-table/disassembly only). CPlugin::DrawDeck() has no
plain call sites in code at all — its only two references are vtable-slot data references
(one for the primary vtable, one for the Thn8_ secondary-base thunk), i.e. it is reached
purely through virtual dispatch, never called by name. Its body is a one-line forward:
void CPlugin::DrawDeck(CPlugin *this) {
CVideoEngine::DrawDeck(&_videoEngine, *(int *)(this + 0x30));
}— this + 0x30 is the CPlugin instance's own deck index, confirming each plugin instance
knows which deck it's bound to and forwards into the single global CVideoEngine.
CVideoEngine::DrawDeck(int) and CVideoEngine::_DrawDeck(int, TVertex*) are in turn called
from exactly three places:
CVideoEngine::thread()— the video engine's own per-frame render loop. For each deck, per frame, it callsCPlugin::setVideoDevice(...)then invokes the transition plugin's public virtual —CPlugin::onDraw(crossfader)(IVdjPluginVideoTransition8::OnDraw) orCPlugin::onDrawMultiDeck(...)(IVdjPluginVideoTransitionMultiDeck8::OnDrawMultiDeck) — and only falls back to the raw_DrawDeck(deckIndex, NULL)compositing when that call returns non-zero, i.e. this is the exact frame in the exact function where third-party video-transition plugins get invoked, sitting right beside (not instead of) the internal no-transition path.CSamplerEngine::drawVideo(CDeck*, int, int)— the sample-pad grid's live video thumbnails; it callsCVideoEngine::DrawDeckfirst to render a deck's current frame, then composites that into a sampler-pad thumbnail surface. A second, independent consumer of the same per-deck render path, confined to the sampler grid, not exposed to plugins.CPlugin::create()— not a runtime call; a huge dispatcher matching a plugin'sinternal://path against known built-in class names (.lrcreader, and so on) to decide which concrete C++ class to construct. TheDrawDeckreference here is a class/vtable identity check, not an invocation.
No third path exists: a third-party plugin never gets a call to DrawDeck itself, and never
calls it either. The only plugin-facing hook into this whole system remains the public
OnDraw/OnDrawMultiDeck virtuals on IVdjPluginVideoTransition8/
IVdjPluginVideoTransitionMultiDeck8 (transitions) and IVdjPluginVideoFx8 (effects) —
DrawDeck/_DrawDeck are the internal fallback/base-compositing routines the engine calls
around those, not an additional entry point.
Built-in video transitions (CInternalPluginVT_Fade, CInternalPluginVT_None,
CInternalPluginVT_Additive) each implement a lowercase drawDeck(int, TVertex*), distinct
from the traced DrawDeck/_DrawDeck above and not yet reconciled with it — plausibly a
separate per-built-in-transition draw call reached through the same onDraw/onDrawMultiDeck
virtual slots the public interface exposes, but this is inferred from naming, not traced.
Bearing on the "custom draw surface inside the app" question: nothing here adds a fourth
option beyond VDJINTERFACE_SKIN/VDJINTERFACE_DIALOG/video-FX texture (see above). The
video-FX render target remains the only drawable surface a plugin can get handed, and it is
scoped to the video mixer's output (deck video / transition compositing), not to app chrome.
IVdjVideoMouseCallbacks8 suggests that surface can also take pointer input, which would
make it interactive as well as drawable — still confined to the video plane.
DeclareParameter is called during OnLoad(); typed wrappers exist for each kind.
| Constant | Value | Wrapper / notes |
|---|---|---|
VDJPARAM_BUTTON |
0 | DeclareParameterButton(int *) |
VDJPARAM_SLIDER |
1 | DeclareParameterSlider(float *, …, float defaultvalue) |
VDJPARAM_SWITCH |
2 | DeclareParameterSwitch(int *, …, bool) |
VDJPARAM_STRING |
3 | DeclareParameterString(char *, …, int parameterSize) |
VDJPARAM_CUSTOM |
4 | DeclareParameterCustom(void *, …, int parameterSize) |
VDJPARAM_RADIO |
5 | DeclareParameterRadio(int *) |
VDJPARAM_COMMAND |
6 | DeclareParameterCommand(char *) |
VDJPARAM_COLORFX |
7 | slider with default 0.5; one per effect, single-knob full control |
VDJPARAM_BEATS |
8 | float, number of beats |
VDJPARAM_BEATS_RELATIVE |
9 | int; set ±1 to step the beat count when OnParameter fires |
VDJPARAM_POSITION |
10 | float[4]; user resize/position in a video plugin's GUI |
VDJPARAM_RELEASEFX |
11 | pairs with the release-FX model in Effects Engines |
VDJPARAM_TRANSITIONFX |
12 | name fixed to "Transition FX" / "Trans" |
Declared parameters are persisted to a per-plugin .ini beside the plugin, in an
[autoparams] section of <Type> <Name> <id>=<value>:
[autoparams]
Slider Strength 0=1925 ; native_Blur.ini
String Nudge 2=0.0 ms ; native_Ableton Link.ini
Custom HttpPort 1=50000000 ; native_Network Control.ini
SString Auth 2=Slider values are integers on a 0–4096 scale (Local test, 2026-08-15). Decoded from
a plugin of our own: DeclareParameterSlider(..., 0.5f) wrote Slider Probe Slider 1=2048,
and 2048 = 4096 / 2. That decodes every shipped manifest — native_Blur.ini's
Strength 0=1925 is 47 %, not 1925 of anything. A written-down default in an .ini is
therefore readable as a fraction, which is what the FX catalog reports.
VDJFLAG_EPHEMERAL (0x200) really does suppress the file. Same session, two builds: the
AutoStart build set the flag and left no .ini beside it; the Sound Effect build did not set
it and VirtualDJ wrote one on removal. An accidental natural experiment, but a clean one.
This is the same framework VirtualDJ is built with. 173 native_*.ini manifests ship in
~/Library/Application Support/VirtualDJ/PluginsMacArm/ — Blur, Backspin, Beat Grid, Slicer,
Ableton Link and Network Control all declare parameters this way. Type-name frequency across
all of them: Slider ×487, Switch ×220, Custom ×11, SString ×6, Position ×5,
String ×3.
Note SString — used for the Network Control plugin's Auth password field, and not a
documented VDJPARAM_ constant. Another piece of internal surface that did not make it into
the public header. (Its meaning is unconfirmed; "secure string" is a guess from its one known
use, not a claim.)
NODOCK 0x1 · PROCESSAFTERSTOP 0x2 · PROCESSFIRST 0x4 · PROCESSLAST 0x8 ·
EXTENSION1 0x10 (set by VirtualDJ when the passed struct is the extended type) ·
SETPREVIEW 0x20 · POSITION_NOSLIP 0x40 · ALWAYSPREFADER 0x80 · ALWAYSPOSTFADER 0x100 ·
EPHEMERAL 0x200 (do not save/load params from the ini).
This matters for Evidence Standards rule 1b, which treats absence from the verb table as disproof: if plugins could register verbs, the table would only be the built-in set.
The public SDK has no verb-registration call. Every registration entry point it offers is a
parameter declaration — DeclareParameter plus its thirteen typed wrappers. There is no
DeclareAction, RegisterVerb, AddCommand, or equivalent, in any of the four headers.
Instead, plugin capability is surfaced through existing verbs that take a name or index:
| A plugin adds | Reached from VDJScript by |
|---|---|
| An effect (DSP / video FX / transition) | effect_select "Blur", effect_slider, effect_button — by name or slot index |
| Effect-specific commands | effect_command — "send a command to this effect" |
| Declared parameters | the effect slider/button verbs, by id |
| An online source | browser entries, not verbs |
Consistent with that, every plugin-related name in the verb table is a built-in verb for
plugins, not a verb from one: handshake, get_plugindeck, pluginsongpos,
show_pluginpage, effect_command. And with two Beatport online-source plugins installed on
the test machine, the table contains no beatport/tidal/soundcloud/deezer/spotify
name at all.
Scope limit, stated honestly. This is evidence about the public SDK and the stock app. Native plugins are compiled into the binary, so anything they contribute is already in the table. But the public headers are a known subset of the live interface (see the internal interfaces above), so an internal registration path cannot be ruled out from headers alone. Rule 1b should be read as: complete for a stock VirtualDJ plus any plugin using the public API. The test that would settle the rest is a built plugin probing for an undocumented registration path — queued with the introspection plugin.
handshake is a real verb (verb table id 84, category system) and it autocompletes in
VirtualDJ's editor. The bundled catalog documents it (Official, languages.zip):
Perform an encrypted handshake to ensure that this plugin is currently being called by a real VirtualDJ environment. Call this passing any string, decrypt the result using VirtualDJ's handshake public key, and check that it matches what you passed.
Observed over HTTP (Local test, VirtualDJ 2026, 2026-07-30):
| Call | Result |
|---|---|
handshake (bare) |
E_INVALIDARG — argument required |
handshake 'nonce' |
exactly 128 bytes of binary (not UTF-8), i.e. a 1024-bit RSA block |
| same nonce, repeated | byte-identical — deterministic, so no random padding |
| different nonce | completely different 128 bytes |
So a plugin verifies it is talking to genuine VirtualDJ by having it sign a challenge with a private key the plugin checks against a bundled public key.
Worth knowing before building a shim. Because handshake is reachable through the HTTP
control channel, any process that can reach that port can have VirtualDJ sign arbitrary
challenges — a signing oracle. A fake host could therefore relay a plugin's challenge to a real
VirtualDJ and return a valid response, which is precisely the attack the handshake exists to
prevent. This is directly relevant to the shim-server work in
VDJScript Local Test Tracker: a shim that needs to
satisfy a plugin's handshake can proxy it, rather than needing the key. Recorded as an
architectural observation about local software on the tester's own machine; the practical
exposure is bounded by the same thing that bounds the whole channel — see the security note in
HTTP Control Interface.
OnGetUserInterface fills TVdjPluginInterface8, whose Type selects one of three models:
| Type | Value | Meaning |
|---|---|---|
VDJINTERFACE_DEFAULT |
0 | VirtualDJ builds the UI from the declared parameters |
VDJINTERFACE_SKIN |
1 | the plugin supplies skin XML + a PNG — the same skin dialect documented in Skin SDK |
VDJINTERFACE_DIALOG |
2 | native window: HWND on Windows, NSWindow * on macOS |
The skin path is the interesting one for this repo: a plugin hands VirtualDJ an XML buffer and an image buffer, so plugin GUIs and skins share a rendering vocabulary.
VERIFIED (Local test, VirtualDJ 2026, macOS arm64, 2026-08-22). The skin path works, and
the vocabulary really is shared. Instrument: tools/plugin/build.sh --skin --install.
- When it is called. On a Sound Effect,
OnGetUserInterfacefires when the effect's GUI is shown (deck 1 effect_show_gui '<bundle name>') — not at load, and not merely because the effect is active. A plugin VirtualDJ gives no surface to is never asked. - It is called again on every panel open. So the XML need not be a bundle resource the way
the SDK example builds it: read it from disk inside the call and a skin edit costs a panel
re-open rather than a rebuild and a restart. That is what
just plugin-skin-prepare/just plugin-skin-reload/just plugin-skin-logdrive. - What renders. Backtick-interpolated VDJScript in
format="",action=""on a<text>,visibility=""conditions,<define>visual classes with starred placeholders, and sprite-sheet state offsets (<selected y="+200"/>) against a PNG that exists only in memory. - The surface is a flat element list.
<group>renders nothing — its children are dropped — and so is a<define>body containing a whole nested element, because a define body is spliced in as property children (<size>,<pos>,<text>) of the call-site element. Whether a full deck skin behaves the same way is untested. - Buffer lifetime.
Xmlis a borrowedconst char *andImageBuffer/ImageSizea raw pointer and length. The SDK never says when the host is done reading them, so hold them for the plugin instance's lifetime; do not free them when the call returns. - Hazard.
<group class="...">— a visual class instantiated onto a<group>— crashed VirtualDJ twice, after the XML had been served. See the tracker.
What the skin path cannot do for a plugin (consequence, from the findings above and in
Skin SDK). The plugin supplies XML and a PNG and nothing else: there is no
host call that pushes a plugin-owned string or image into a rendered skin, every displayed
value comes from a backtick VDJScript expression, VDJScript variables are numeric (string
variables are write-only, see the tracker), and <cover source=""> is a closed list (deck,
browser, automix, karaoke, background music). So a plugin whose data VirtualDJ does not hold —
linked tracks from extra.db were the 2026-09-25 case — cannot show it through a skin, and
the same limit applies to any custom panel or sidebar added to a skin. Two workarounds, with
their costs: regenerate the XML and PNG with the data baked in and force a panel re-open with
effect_show_gui (the host re-asks on every open) — static between opens, flickers, and still
lives in the FX panel; or bring a native window (VDJINTERFACE_DIALOG, or an AutoStart
plugin's own NSWindow, below). A third route is untested: VirtualDJ's browser displays any
list file under MyLists (see Application Internals § Lists),
so a plugin could write a .vdjfolder of paths and let the native browser render it with
cover art and key colours. Unsettled: whether a displayed list refreshes when its file
changes, and whether sideview accepts a list name. No VDJScript verb adds a path to the
sidelist; sidelist_add takes the browser selection.
The documented entry point is COM-style class-object negotiation:
VDJ_EXPORT HRESULT VDJ_API DllGetClassObject(const GUID &rclsid, const GUID &riid, void **ppObject);with CLSID_VdjPlugin8 plus a per-type IID (IID_IVdjPluginBasic8, IID_IVdjPluginStartStop8,
IID_IVdjPluginDsp8, IID_IVdjPluginBuffer8, IID_IVdjPluginOnlineSource,
IID_IVdjPluginVideoFx8, IID_IVdjPluginVideoTransition8,
IID_IVdjPluginVideoTransitionMultiDeck8). The host string DllGetClassObject does appear in
the VirtualDJ binary.
RESOLVED for the documented path (Local test, plugin channel, 2026-08-15). A bundle
exporting DllGetClassObject and answering CLSID_VdjPlugin8 + IID_IVdjPluginBasic8 loads
and runs on VirtualDJ 2026 (bundle 18.0.9583), from
~/Library/Application Support/VirtualDJ/PluginsMacArm/AutoStart/, ad-hoc signed. The host
type-probes by calling the same export repeatedly, once per interface, in this order:
IID_IVdjPluginDsp8IID_IVdjPluginBuffer8IID_IVdjPluginVideoFx8IID_IVdjPluginVideoTransition8IID_IVdjPluginVideoTransitionMultiDeck8IID_IVdjPluginBasic8— accepted here, after which probing stopped
So a plugin declares its type by which IID it accepts, not by any manifest. Because probing
stops at the first acceptance, the positions of IID_IVdjPluginStartStop8 and
IID_IVdjPluginOnlineSource in the order are unknown — a plugin that declines everything would
reveal the full list.
Sound Effect bundles load lazily, and the loading path is language-agnostic (Local test,
VirtualDJ 2026 bundle 18.0.9644, macOS 26.6.2 arm64, 2026-09-22). A new bundle dropped into
SoundEffect/ appears in the effects catalog after a restart without being loaded: no
DllGetClassObject, no OnLoad, no auto-written .ini. The catalog identity is the bundle
filename (get_effect_title 'RustTremolo' answers; the declared PluginName "Rust Tremolo"
does not). First effect_select triggers the real load — negotiation, OnGetPluginInfo,
OnLoad — and the host instantiated the plugin twice. The instrument was the first
Rust-built plugin (monomadic/virtualdj-plugin,
hand-laid Itanium vtables, no Atomix code): it loaded,
listed, ran its OnStart/OnStop lifecycle, and from inside OnLoad observed the typed-channel
split directly — GetStringInfo("get_version") → S_OK + "2026" while
GetInfo("get_version") → E_INVALIDARG with 0.0 written to the out-parameter anyway,
corroborating both the two-channel model above and the HRESULT-is-the-answer rule.
The first launch after installing a new bundle binary starts with the plugin layer inert
(Local test, VirtualDJ 2026 bundle 18.0.9644, 2026-09-22, observed twice — once per freshly
built bundle): no Network Control listener on port 80, no plugin loads, go.txt triggers
unconsumed, while the app itself runs normally. A plain second relaunch, the bundle still
installed, comes up clean in ~3 s; nothing needs to be removed (the first occurrence's
remove-then-reinstall dance worked only because it was a second launch). Cause unconfirmed —
first-seen-binary system assessment fits the shape.
Counter-observation (Local test, same bundle 18.0.9644, macOS 27.0, 2026-09-26): a
freshly built AutoStart bundle (UpNext, never loaded by the running instance) was installed
over the previous build while VirtualDJ ran; VirtualDJ was quit cleanly and launched once.
Within 25 s the plugin's log had grown, its window was listed by System Events, and the HTTP
interface answered get_version. So the inert first launch is not a rule about new binaries in
general. What distinguished the two 2026-09-22 occurrences is not known — candidates are a
first-ever install of a bundle name into the folder (both were), or an unrelated startup
race — and the double restart should be treated as a fallback, not a step: install, launch
once, confirm the HTTP interface answers, and only relaunch if it does not.
The skin-interface path is also confirmed language-agnostic (same session): the Rust plugin's
OnGetUserInterface returned VDJINTERFACE_SKIN buffers and VirtualDJ rendered the panel,
bound backtick format="" expressions live, honored visibility="" gating, and re-asked on
every panel open — matching the 2026-08-22 C++ findings in §Plugin user interfaces exactly.
A basic AutoStart/ plugin can own its own AppKit UI (Local test, same build,
2026-09-22): a Rust basic plugin created a floating NSWindow from OnLoad (deferred to the
main queue), polled deck state from its own thread through the host callbacks, and drove its
window's visibility from a VDJScript variable (set/get_var round-trips through
SendCommand/GetInfo), so pads and custom buttons reach it with toggle '$nowplaying'. The
headless lifecycle is therefore no obstacle to plugin UI — the plugin just has to bring its
own, and shared $variables work as the script-visible control surface for it.
Two lessons from running that design as a daily tool (UpNext, 2026-09-26, Inference from
AppKit behaviour, not a host test): a floating-level window (NSFloatingWindowLevel) sits
above every app, not just VirtualDJ; attaching it instead as a child of VirtualDJ's main
window (addChildWindow:ordered: above, normal level) with hidesOnDeactivate keeps it above
VirtualDJ only, moves it with that window, and hides it whenever another app is in front. And
because AppKit hides such a window while the app is inactive, isVisible can no longer be read
as "the user closed it" — reconcile window state with the $variable only while
NSApplication.isActive. OnLoad runs before the main window exists, so the attach has to
be retried on the first show.
Still open — the second path. The bundled
beatport16_vdj.bundle (an online-source plugin) exports 11,303 symbols and none is
DllGetClassObject, nor does it contain any SDK GUID as raw bytes. Nor do those GUID byte
sequences appear in the host binary — consistent with the compiler materialising constant GUIDs
inline, so that part is unremarkable. But a shipped online-source plugin with no documented
entry point suggests a second, newer loading path. Unresolved; needs a built test plugin to
settle.
~/Library/Application Support/VirtualDJ/ contains both Plugins64/ and PluginsMacArm/
(same contents on this machine), with per-category subfolders: AutoStart, OnlineSources,
SoundEffect, VideoEffect, VideoTransition, Visualisations. Bundles sit at the top level
(*.bundle), and native_*.ini manifests for built-in plugins sit alongside them.
It is not linked from the wiki's main navigation and surfaces mainly in the context of the
(also obscure) Network Control plugin. The shape of the evidence — headers copyrighted
2011-2018, an interface versioned 8 (the VirtualDJ 8 era), a zip packaged in 2021, 173
first-party plugins built on it, and at least two interfaces plus one parameter type that were
never exported — reads as an internal framework that was published quietly and partially,
rather than a product-managed public API.
Practical consequence: the interface is stable and heavily dogfooded (Atomix's own effects depend on it), which makes it a reasonable foundation to build tooling against.
A read-only introspection plugin is the next instrument for task 10 in RETIRED.md —
built and offline-verified 2026-08-15 (tools/plugin/, just plugin-build),
though not yet loaded into VirtualDJ, so nothing below is claimed as observed. Two build facts
worth recording: Xcode is not needed (Command Line Tools clang++ produces a loadable
signed bundle), and VirtualDJ ships with com.apple.security.cs.disable-library-validation, so
an ad-hoc signature suffices. It can do what the HTTP channel structurally cannot:
- call
GetInfoandGetStringInfoon each of the 955 verbs and read native types plus raw HRESULTs, giving a definitive per-verb type-path map instead of one inferred from rendered text; - probe argument forms in-process, making the 301-verb optional-argument queue and the 217 binary-discovered keyword sets tractable at loop speed rather than HTTP round-trip speed;
- run without the Network Control plugin or a Pro license — a fifth Tier-1 channel with different prerequisites from the existing four.
Caveat that survives the channel change: unrecognised arguments are silently ignored rather than rejected, so keyword confirmation still needs prepared state where forms would differ, not an error code.