App Control Definition File Format

An App Control definition file is a JSON file that maps detected events to key sequences sent to your target application. Each definition file covers one target application window.

For how to enable App Control and trigger it during an inspection, see Controlling Your Recorder App with Vidsy.

Where definition files are loaded from

Definition files are loaded every time a project is opened, from two locations in order:

1. <template>/control-definitions/*.json
2. <project>/control-definitions/*.json

If both locations contain a file with the same name, the project file overrides the template file.

Top-level fields

Field	Description
name	Display name shown in the UI definition dropdown.
window	Part of the target app window title used to locate the window.
mode	Input mode: hardware (default) or virtual.
templates	Reusable named instruction lists.
events	Mapping from event names to template references.
running	List of running-event groups, each with start and end behavior.

Instruction items

A template is a list of instruction items. Each item can include:

Field	Required	Description
c	Yes (or w only)	List of characters or key names to send.
m	No	Modifier keys applied to all keys in c (e.g. "alt", "ctrl", "shift").
w	No	Wait time in milliseconds after this item is sent.

Supported special key names include: space, enter, tab, F1–F12, ctrl, alt, del, left, right, up, down, pgUp, pgDn.

Example — send F10, a, and 1 simultaneously with Alt+Ctrl held:

[{ "c": ["F10", "a", "1"], "m": ["alt", "ctrl"] }]

Example — send space, wait 200 ms, then send a, b, c:

[{ "c": ["space"], "w": 200 }, { "c": ["a", "b", "c"] }]

Placeholders

Placeholders inside instruction c lists are replaced at runtime:

Placeholder	Replaced with
{{keys}}	The keys list from the event template reference.
{{value}}	The value field of the detected event.

Event template reference format

An event template reference is an object with exactly one field:

• key: the template name to use
• value: the list of keys/tokens to inject into {{keys}}

{ "obs": ["a", "e", "c", "a"] }

{ "obs_value": ["b", "a", "j", "c"] }

Events field

The events field maps event names to template references. An event entry is either:

• A direct template reference (for events without distinct values):

  "angular rotation": { "obs_value": ["b", "a", "j", "c"] }

• A dictionary keyed by possible event values (for events with enumerated values):

  "shape": {
    "round": { "obs": ["a", "e", "c", "a"] },
    "rectangle": { "obs": ["a", "e", "c", "b"] }
  }

Running events

The running field is a list of groups. Each group has:

• start: a dictionary of event names mapped to event template references — these are sent when the event is triggered.
• end: one event template reference — sent automatically when a triggered running event later receives an endTime.

Additional behavior:

• If a new event from the same running group is triggered while another tracked event in that group is still active, end instructions are sent first for each tracked active event in that group.

Full example

{
  "name": "My pretty display name",
  "window": "CAM-I",
  "mode": "hardware",
  "templates": {
    "obs_value": [
      { "c": ["space"] },
      { "w": 200 },
      { "c": "{{keys}}" },
      { "c": ["enter"] },
      { "w": 200 },
      { "c": ["{{value}}"] },
      { "w": 200 },
      { "c": ["tab", "tab", "tab", "tab", "tab"] }
    ],
    "obs": [
      { "c": ["space"] },
      { "w": 200 },
      { "c": "{{keys}}" }
    ]
  },
  "events": {
    "shape": {
      "round": { "obs": ["a", "e", "c", "a"] },
      "rectangle": { "obs": ["a", "e", "c", "b"] }
    },
    "angular rotation": { "obs_value": ["b", "a", "j", "c"] }
  },
  "running": [
    {
      "start": {
        "sand": { "obs": ["b", "b", "c", "a"] },
        "rocks": { "obs": ["b", "b", "c", "c"] }
      },
      "end": { "obs": ["b", "b", "c", "1"] }
    },
    {
      "start": {
        "crack": { "obs": ["b", "a", "b", "b"] }
      },
      "end": { "obs": ["b", "a", "b", "1"] }
    }
  ]
}