README.md

Reference Documentation

This folder is moving toward a reliable local API reference for the VirtualDJ scripting environment.

Start here:

• Evidence Standards Governs every claim in this repository. What counts as proof (the four live-observation channels) versus a lead (forums, unbacked binary analysis, official example files); the existence/kind/behavior distinction; why a channel's own return value is not a result; and how the existing source labels map onto the tiers. Read before recording a finding.

• VirtualDJ Reference Method choices, source policy, quirks, and preferred patterns.

• Active Task Queue Current startable maintenance and evidence-pass tasks; completed ones move to HISTORY.md.

• Routing Index Topic-to-file map for cheaper navigation.

• VDJScript Verbs Curated API reference for high-frequency verbs, alias handling, and scripting surfaces.

• Official VDJScript Coverage Audit Names-only audit comparing the live official VDJScript appendix against this repo's local verb reference.

• Completeness Roadmap Evidence backlog for turning searchable names and source hints into locally observed, curated guidance.

• VDJScript Reference Consolidation Plan Frozen design reference (2026-07-22) for the shape of the verb documentation. Like the Completeness Roadmap it is not active state; the queue is TASKS.md.

• Historical Installer Excavation Build-stamped compatibility history and named skin-reader leads from the older macOS installers, including the clickthrough boolean-path correction.

• Button Editor Catalog Audit Local cross-check of the VDJScript action descriptions bundled in VirtualDJ's Button Editor language resources, plus binary string-table counts.

• Button Editor Taxonomy Extracted Button Editor category mapping from the compiled executable tables, including visible/hidden counts and symbol-capability joins.

• Undocumented VDJScript Candidates Where the verb table lives: VirtualDJ's own serialised verb set (1,032 records on build 18.0.9598, arm64, extracted 2026-09-05 — name, id, flags, Button Editor category; just verb-table-stamp), which decides existence and non-existence outright (just verb-table <name>, Evidence Standards rule 1). Also the hidden-verb notes, probe order, and promotion rules.

• VDJScript Grammar The language itself: chaining, conditionals, quoting, scope prefixes, and the traps. Read its summary before writing VDJScript; jump via its Contents for detail. Per-verb argument rules are not here — those are just get-verb <name>.

• Verb arguments live in artifacts, not prose. What a verb's tail accepts is answered by four independent sources under tests/, deliberately kept apart because they fail in different places: action-catalog.json (the vendor's own descriptions, shipped in the app bundle — what a parameter means), attested-tails.json (tails Atomix wrote into shipped skins, pad pages and the app's own compiled menu scripts — that a token is used — and argument shapes with return evidence for value-taking verbs), binary-vocabularies.json (shared enumerations recovered as binary structures — the rest of a vocabulary a verb draws from, as leads), and verb-arg-forms.json (probed against nonsense controls in 10 named fixtures — that a token is not nonsense). Read them all at once with just verb <name>, or one at a time with just action-catalog --get <name>, just attested-tails --verb <name>, just binary-vocab --verb <name>, just verb-arg-forms <name>, and diff catalog, corpus and probe with just action-catalog --cross-check. See ../tests/README.md for what each artifact proves and does not.

• Verb Tail Structural Discovery How the bounded binary techniques from skin discovery carry over to verb tails, and what they cannot reach. LC_FUNCTION_STARTS intervals replace RET-terminated scans and padded xref windows in both the contract and vocabulary extractors; helper fan-out separates a verb's own argument matcher from the script evaluator's dispatch; the verb store is joined live so settled tails leave the probe queue. Value arguments stay outside keyword recovery entirely. Queries: just action-tail-leads, just verb-contract <name>, just verb-traces <name>.

• Runtime Argument Grammar Tests H4 (closed 2026-09-19 with named limits): the common argument parser captured from the b9246 binary, expressed as executable predictions with per-fixture HTTP verdicts on builds 9598 and 9628. A candidate specification, not a grammar reference; just runtime-grammar runs it, --audit joins cases to branch families, and "Named limits at H4 closure" lists what stays untested and why.

• VDJScript Syntax Evidence Local notes on Button Editor syntax highlighting, hover tokenization, parser symbols, and conditional grammar test targets.

• VDJScript Local Test Tracker Manual verification matrix for sparse, hardware-specific, and environment-dependent official verbs.

• Published Skin Findings Source-backed notes from working public skins, including undocumented-looking commands, provenance, and local test plans.

• Lyrics AI and Skins Focused notes on VirtualDJ 2026 AI lyric detection, skin styling limits, lyric queries, filters, and forum-observed quirks.

• Mapper XML Controller and keyboard mapper file format: the <mapper>/<map value=""> split model, special control names (ONINIT, SHIFT_*, LED_*), device-definition XML (MIDI and HID), and the relationship to pad pages. Ground truth in examples/Mappers/Local/.

• Compiled Controller Definitions controllers.dat is an encrypted ZIP of the vendor's original definition XML. How to decode one archive per build into gitignored vendor/controllers/, and diff builds from the committed manifests (just controllers-vendor, just controllers-diff).

• Pad Page XML Formal pad-page container schema: <page> attributes, <padN>/<shift_padN> attribute surface, <param1>/<param2>, the <menu> mini-DSL, <custompadsmode>, color forms, and samplerbank XML.

• Example Pad XML Pages Sampler-focused pad page walkthroughs: the read-only multi-page sampler pattern, sampler_pad_page text ranges, and absolute-slot sampler_loaded guards.

• Skin SDK Broad element-and-attribute reference for VirtualDJ 8+ skins (~2,900 lines, section-addressed; do not read end-to-end). Raw material not yet normalised to source labels; just element <name> is the one-screen summary per element.

• Example Skin XML Objects Paste-ready skin XML chunks, mainly a full sampler panel with bank/page display and navigation.

• Skin Waveforms The waveform/rhythm skin element family: <rhythmzone>, <scratchwave>, <songpos>, <scratch>, <blockwave>, <beattunnel>, their children (<colors>, <grid>, <cue>, <overlay>, ...), and how they differ from visual type="waveform".

• Effects Usage The mental model: which FX engines exist (deck slots, ColorFX, master, video, ...) and how each is driven from skins and pad pages. Start here.

• Effects Engines

• Pad FX Argument Contract — named and positional assignment evidence The deep per-engine control reference (~1,700 lines, section-addressed): verbs, slot semantics, and usage patterns for every engine.

• Native Effects Catalog of the built-in audio and video effects, transitions, and visualisations by name. Slider and button maps come from just get-fx <name>, not from here.

• Plugin SDK VirtualDJ's C++ native-code extension point — and the boundary where VDJScript return values are still typed (GetInfo → double, GetStringInfo → text, SendCommand → execute). Interface hierarchy, VDJPARAM_* parameter model and the [autoparams] manifest that all 173 built-in plugins use, plugin UI models, loading, and the interfaces present in the binary that the public headers never declare. The headers themselves are third-party and deliberately not vendored here.

• Skin XML Inventory (JSON) Element×attribute usage data across built-in/curated skin, pad, samplerbank, video-skin, and mapper XML, cross-checked against the docs. Refresh with just inventory; query with just get-xml-element <name>, just list-skin-elements --undocumented, just xml-stats. Do not hand-edit and do not generate a Markdown copy. The undocumented count measures mentions of the elements shipped files happen to use — an element no shipped file writes cannot appear in it, and attributes and behavior contracts are out of scope — so xml-stats reports reader_vocabulary_unused beside it, the reader-vocabulary names from tools/extract_skin_readers.py that no shipped file writes.

• Skin Element Discovery

• Statement Branch Probe — calibrated conditional

• Argument Type Probe — observed debug types, units and relative flags paired with set readback on build 9644. branch markers and debug controls; limits of statement validation.

• Skin Element Validity — contextual recognition, native instrumentation targets, and controlled element/attribute/script canaries. Editorial categories and provenance-preserving observed parent/child relationships. Query just list-skin-categories, just element button --children, or just element text --parents; regenerate nesting with just skin-relations. Observed nesting is not a supported-child schema.

• Skin Schema Recovery Build-scoped button XML ownership pilot: outer/shared/child read paths and unresolved alternatives. just skin-schema button queries the capture; structural evidence only.

• Topic Tags (JSON) The only hand-maintained input to just topic <term>. Everything else that command reports is derived — verb section, element name, grep — so this file exists purely for what a topic cannot reach by name: the elements that draw the waveform are called rhythmzone, scratchwave, zoomed and songpos, and say so nowhere. Also carries the alias table that folds color fx into colorfx and beat grid into waveform. Tags are navigation, never evidence. just check fails on a tag that names a verb, element or doc which does not exist, and on a topic with no stated reason.

• VDJScript Verb Index (JSON) Generated machine-readable verb index: every official name with tier (curated/catalog/alias/official-name-only), kind, aliases, and surfaces, built from the artifacts (verb table, store, coverage audit) rather than from prose since task 11 (2026-09-06). Regenerate with just verb-index; consumed by the verb store bootstrap.

• VDJScript Verb Record Store (JSON) Start every per-verb question with just get-verb <name> — it now joins the store record with the verb table (id, category, aliases, hidden flag, or the rule-1b disproof), the structural contract (class, family, capability, arg demands, keyword candidates), the HTTP existence probe, and the observed return type, at read time. --raw returns the bare store record. Authoritative, hand-editable per-verb records: tier, aliases, surfaces, kind, doc coverage, plus local-test status, confidence, and evidence. Query and edit through the just verb API — do not hand-edit the JSON and do not generate Markdown copies of it. search filters (--surface, --section, --tier, --status, --kind, --needs-test) with --format=json, so reports come out of a query on demand rather than a stored listing. Seeded from the index, coverage audit, and tracker via python3 tools/verbdb.py bootstrap; validated by just check.

• Tools Validator/generator suite (just check gates) and the version-pinned binary-extraction pipeline, including the new-VirtualDJ-build refresh procedure.

• Pad Page Inventory Status labels for every pad page under examples/Pads/Built-In/ and examples/Pads/Quarantine/ (no page is Canonical any more), built-in pad-page copies, and maintenance checklist.

• Skin Inventory Local skin examples, copied built-in skins, and build-system demos.

• Skin Runtime Findings Local-test notes for skin placeholder substitution, conditional placement, and other runtime behavior promoted from skin project experiments.

• Sysicon Binary Resolver Build 18.0.9598 arm64 resolver findings, saved skin-rendering tests, opaque-atlas controls, and unresolved wiki cells. just sysicon-atlas --cell H6 joins the dated wiki table to tested keys and Tier-2 candidates, keeping primary icons, state graphics, and internal numeric selectors distinct.

• Documentation Tests Reproducible local test harnesses used to support reference claims.

• HTTP Control Interface Local HTTP execute/query channel for VDJScript: endpoints, verified request/response behavior, gotchas, and the just vdj-query / just vdj-execute probe workflow. The preferred channel for local-test probes.

• MCP Server Serves the verb store, FX catalog, XML inventory, grammar, linters and the live HTTP probe channel to any MCP client over stdio, so an agent can author skins, pads and VDJScript without loading the large docs. Registration, tool list, and the vdj_execute opt-in and denylist.

• Remote Protocol Wire protocol for the VirtualDJ Remote companion app: _vdjremote8._tcp discovery, inverted client/server roles, 8JDV framing, and the VDJScript query-subscription push model. Distinct from the HTTP interface.

• Application Internals Low-level macOS-first notes on VirtualDJ paths, databases, caches, stem sidecars, linked tracks, and shell tooling.

• Configuration Options Settings reference by category: option name, meaning, and accepted values. Not source-labelled.

• Filter Syntax Browser filter-folder syntax with worked examples. Not source-labelled.

• VirtualDJ Stem File Format Focused .vdjstems sidecar format notes: Matroska container, five-stream order, stream-title metadata, inspection commands, and MP4/standalone caveats.

• Resources Useful official, staff, community, and local sources for follow-up research.

Current status:

• VirtualDJ Reference.md is the policy and architecture layer.
• VDJScript Verbs.md is the first API-focused pass.
• Official VDJScript Coverage Audit.md tracks official verb coverage depth, missing-name status, and the remaining local-test gap.
• Button Editor Catalog Audit.md tracks the bundled Button Editor action-description catalog and runtime string-table cross-checks.
• Button Editor Taxonomy.md tracks the compiled Button Editor category mapping and metadata join: 37 displayed categories, 918 visible actions, 1028 compiled action items, and exact ACTION_* method-symbol coverage.
• Undocumented VDJScript Candidates.md hosts the authoritative verb table (existence, aliases, hidden flag, categories) and tracks the editor-hidden verbs (count in just verb-table-stamp) separately from the normal VDJScript API reference.
• VDJScript Syntax Evidence.md tracks the separate parser/highlighter evidence stream for grammar and conditional semantics.
• VDJScript Local Test Tracker.md is the default place to record manual VirtualDJ verification runs for Needs local test verbs.
• Verb Tail Structural Discovery.md is the method note behind the bounded contract and vocabulary extractors; the queue it produces is a query (just action-tail-leads), not a stored listing, and every name in it is a Tier-2 lead.
• Completeness Roadmap.md is a frozen snapshot of evidence tiers and hardware gates; the active queue is TASKS.md.
• Published Skin Findings.md tracks empirical commands and skin idioms before they are fully folded into the curated reference.
• Skin Runtime Findings.md tracks local skin runtime behavior that should be shared across projects rather than kept in one skin repo.
• Lyrics AI and Skins.md is the focused lyric/autodetection reference.
• Application Internals.md is the low-level file/database/stem architecture reference.
• Stem File Format.md is the focused file-format reference for .vdjstems sidecars.
• Resources.md is the source index.
• Current official coverage and local-test gap counts are tracked in Official VDJScript Coverage Audit.md.
• Existence is settled (method established 2026-07-27): the verb table in the binary is the complete verb set for the build it was read from — 1,032 records / 958 distinct verbs / 62 alias groups / 38 editor-hidden on build 18.0.9598 (arm64, extracted 2026-09-05), every one categorised. Quote that stamp from just verb-table-stamp; the July figures (1,028 / 955 / 61 / 37) were an earlier build's and are superseded, not corrected. just verb-table <name> answers membership, aliasing, hidden flag, and category in one query. Absence from the table is disproof on the inspected build. The older catalog/string-table counts below it in the history are corroboration only.
• The compiled Button Editor taxonomy doc remains useful as category metadata (and its example column has been corrected against the verb table), but the verb table is the authority; neither is behavior proof.
• Button Editor syntax highlighting and hover tokenization are now tracked as parser evidence, with DLGActionWizard::STree, customDraw, getCurrentWord, and related symbols as the current binary anchors.
• The other topical files still contain useful raw material, but they are not yet normalized to the same reliability standard.

Source labels used in the curated docs:

• Official: current VirtualDJ manual or VDJPedia.
• Official forum: VirtualDJ staff, Development Manager, CTO, or Support staff forum guidance. Treat Adion/CTO replies as high-authority implementation notes when they answer scripting, audio-engine, or feature-behavior questions; VirtualDJ forum badges identify Adion as CTO, and Atomix's own press archive confirms Atomix Productions acquired AdionSoft in 2011.
• Community: forum moderators, non-staff forum users, Reddit posts, or other community examples.
• Published skin: command or pattern observed in a working public skin.
• Built-in skin: command or pattern observed in skin XML shipped inside the VirtualDJ app bundle.
• Published pad page: command or pattern observed in a working public pad page.
• Built-in pad page: command or pattern observed in pad-page XML shipped inside the VirtualDJ app bundle.
• Built-in app resource: command name, description, or UI catalog entry observed in non-skin/non-pad resources shipped inside the VirtualDJ app bundle, such as Resources/languages.zip.
• Binary compiled table: structured command metadata observed in compiled executable tables; useful for UI taxonomy and visibility evidence, not behavior evidence by itself.
• Binary symbol table: demangled implementation symbols observed in the VirtualDJ executable; useful for action-class and method-surface hints such as onExecute/onQuery, not behavior evidence by itself.
• Binary string-table: command-looking string observed in the VirtualDJ executable; use for discovery only, not as behavior evidence.
• Local test: behavior reproduced in VirtualDJ locally.
• Inference: conclusion drawn from official docs plus repo testing or architecture.

Dated review records

• Repository assessment, 2026-09-05 — diagnosis and review decisions; accepted work is maintained only in TASKS.md.