Skip to Content
DocumentationAPI ReferenceKeys

Keys API

Key event subscription, mapping, and custom tab management.

Key State Events

dmn.keys.onKeyState(callback): Unsubscribe

Overlay window only.

Subscribes to state changes for registered keys.

interface KeyStateEvent {
  key: string; // e.g., 'KeyA', 'MouseLeft'
  state: "UP" | "DOWN";
  mode: "keyboard" | "mouse";
}
 
const unsub = dmn.keys.onKeyState(({ key, state, mode }) => {
  console.log(`[${mode}] ${key} → ${state}`);
});

dmn.keys.onRawInput(callback): Unsubscribe

Overlay window only.

Subscribes to all raw input events (including unregistered keys).

interface RawInputEvent {
  device: "KEYBOARD" | "MOUSE";
  label: string; // e.g., 'A', 'LButton'
  state: "DOWN" | "UP";
}
 
const unsub = dmn.keys.onRawInput(({ device, label, state }) => {
  console.log(`[${device}] ${label} ${state}`);
});

Counter Events

dmn.keys.onCounterChanged(callback): Unsubscribe

Overlay window only.

Subscribes to counter changes.

interface CounterEvent {
  key: string;
  count: number;
}
 
const unsub = dmn.keys.onCounterChanged(({ key, count }) => {
  console.log(`${key}: ${count}`);
});

Mode Events

dmn.keys.onModeChanged(callback): Unsubscribe

Subscribes to input mode changes (keyboard/mouse).

interface ModeEvent {
  mode: "keyboard" | "mouse";
}
 
const unsub = dmn.keys.onModeChanged(({ mode }) => {
  console.log("Mode changed:", mode);
});

Key Mapping

dmn.keys.get(): Promise<KeysState>

Returns current key mapping and counter state.

interface KeysState {
  keyboard: KeyboardMapping;
  mouse: MouseMapping;
  counter: Record<string, number>;
}
 
const keys = await dmn.keys.get();
console.log(keys.keyboard);
console.log(keys.counter);

dmn.keys.set(keys: Partial<KeysState>): Promise<void>

Updates key mapping.

await dmn.keys.set({
  keyboard: {
    /* new mapping */
  },
});

Custom Tab

Main window only.

dmn.keys.registerCustomTab(options): Unsubscribe

Registers a custom tab in the key settings panel.

interface CustomTabOptions {
  id: string;
  label: string;
  content: (container: HTMLElement) => void | (() => void);
}
 
const unsub = dmn.keys.registerCustomTab({
  id: "my-tab",
  label: "My Tab",
  content: (container) => {
    container.innerHTML = `<div>Custom tab content</div>`;
    return () => {
      /* cleanup */
    };
  },
});

Stats API

Real-time key input statistics API. Provides KPS (Keys Per Second) and total key count for the current tab.

No performance overhead when there are no subscribers - statistics calculation is only performed when subscribed.

dmn.stats.subscribe(callback): Unsubscribe

Subscribes to real-time key input statistics.

  • KPS values (kps, kpsAvg, kpsMax): Updated approximately every 50ms
  • total: Updated immediately when key counter changes
interface KeyStatsPayload {
  kps: number; // Current KPS (keys per second)
  kpsAvg: number; // Average KPS
  kpsMax: number; // Maximum KPS
  total: number; // Total key count for current tab
}
 
const unsub = dmn.stats.subscribe(({ kps, kpsAvg, kpsMax, total }) => {
  console.log(`KPS: ${kps}, AVG: ${kpsAvg}, MAX: ${kpsMax}, TOTAL: ${total}`);
});
 
// Unsubscribe
unsub();

dmn.stats.get(): KeyStatsPayload

Gets current statistics immediately.

const stats = dmn.stats.get();
console.log(`Current KPS: ${stats.kps}`);

dmn.stats.reset(): void

Resets KPS-related statistics (kps, kpsAvg, kpsMax). total is not reset as it’s based on key counters.

dmn.stats.reset();

To reset total, use dmn.keys.resetCounters() or dmn.keys.resetCountersMode(mode).

Example Usage

// KPS counter using stats API
dmn.plugin.defineElement({
  name: "KPS Counter",
  maxInstances: 1,
 
  template: (state, settings, { html }) => html`
    <div style="font-size: 24px; font-weight: bold;">
      KPS: ${state.kps ?? 0} | MAX: ${state.kpsMax ?? 0}
    </div>
  `,
 
  onMount: ({ setState }) => {
    const unsub = dmn.stats.subscribe(({ kps, kpsMax }) => {
      setState({ kps, kpsMax });
    });
 
    return () => unsub();
  },
});
AppSettings