Open Arsenal

See the stars

KeyMod Specification

Home / KeyMod / KeyMod Specification

KeyMod

Turn Any Input Into Any Action.

KeyMod is a universal input remapping and macro automation specification designed to transform keyboard keys, mouse buttons, and other supported inputs into programmable actions. It provides a modular framework for temporary and permanent input assignments, macro recording, automated execution, timing control, loops, layers, profiles, and cross-device automation.

Purpose

KeyMod defines a vendor-neutral system for intercepting supported physical input, determining whether that input has an active assignment, suppressing its default behavior when required, and executing the assigned action. Inputs without an active assignment remain unchanged and pass through normally.

The specification is designed to support gaming, productivity, accessibility, automation, specialized workflows, and general human-computer interaction. KeyMod separates the definition of input behavior from the underlying implementation so that compatible systems can provide consistent programmable input capabilities across supported devices and environments.

Design Principles

  • Universal input programmability
  • Temporary and permanent remapping
  • Modular architecture
  • Vendor-neutral operation
  • Device independence
  • Low-latency input processing
  • Precise macro timing
  • Human-controlled automation
  • Fail-safe operation
  • Privacy-first recording
  • Extensible functionality
  • Portable specifications
  • Application-aware behavior
  • Cross-device automation
  • Interoperable macro definitions

Core Input System

The Core Input System provides the foundation for detecting, normalizing, tracking, and processing physical input.

Requirements

  • Detect keyboard input.
  • Detect mouse input.
  • Detect mouse buttons.
  • Detect mouse wheel and horizontal scrolling.
  • Detect supported controller input.
  • Detect supported HID input.
  • Detect extended keyboard keys and buttons.
  • Identify individual physical devices.
  • Support multiple connected input devices.
  • Detect device connection and disconnection.
  • Track input press and release states.
  • Track held inputs.
  • Track input timestamps.
  • Normalize supported input events.
  • Preserve input ordering.
  • Preserve timing information where supported.
  • Maintain current input state.
  • Support device-specific input handling.

Input Assignment Engine

The Input Assignment Engine determines what action should occur when a supported input is received.

Requirements

  • Assign any supported keyboard key to an action.
  • Assign any supported mouse button to an action.
  • Assign supported wheel inputs to actions.
  • Assign supported controller inputs to actions.
  • Assign combinations of inputs to actions.
  • Assign one input to multiple actions.
  • Assign multiple inputs to one action.
  • Replace the default behavior of assigned inputs.
  • Preserve default behavior for unassigned inputs.
  • Support permanent assignments.
  • Support temporary assignments.
  • Enable and disable individual assignments.
  • Detect assignment conflicts.
  • Resolve conflicting assignments according to defined priority.
  • Support device-specific assignments.
  • Support layer-specific assignments.
  • Support profile-specific assignments.
  • Support application-specific assignments.
  • Support fallback behavior.

Temporary Remapping

Temporary Remapping allows users to change the behavior of physical inputs for a limited period or under specific conditions.

Requirements

  • Temporarily replace the normal function of a key.
  • Temporarily replace the normal function of a mouse button.
  • Temporarily replace supported wheel actions.
  • Temporarily replace supported device inputs.
  • Restore the original behavior when temporary mode ends.
  • Activate temporary mappings through a trigger.
  • Support hold-based activation.
  • Support toggle-based activation.
  • Support one-shot activation.
  • Support timed activation.
  • Support conditional activation.
  • Support application-specific activation.
  • Support profile-specific activation.
  • Support cancellation.
  • Support automatic expiration.
  • Support emergency deactivation.

Input Layers

Input Layers provide alternate sets of assignments that can be activated without changing the underlying physical device.

Requirements

  • Create multiple input layers.
  • Enable and disable layers.
  • Activate layers by holding an input.
  • Activate layers by toggling an input.
  • Activate layers for a specified duration.
  • Activate layers through conditions.
  • Support one-shot layers.
  • Support temporary layers.
  • Assign keys and buttons independently within each layer.
  • Assign macros to layer inputs.
  • Define layer priority.
  • Support layer inheritance.
  • Support multiple active layers.
  • Resolve overlapping assignments by priority.
  • Lock a layer when required.
  • Automatically restore the previous layer state.
  • Provide an emergency layer deactivation mechanism.

Macro Engine

The Macro Engine executes programmable sequences of actions.

Requirements

  • Create sequential macros.
  • Create single-action macros.
  • Create multi-action macros.
  • Combine keyboard and mouse actions.
  • Call other macros.
  • Chain macros.
  • Nest macros where supported.
  • Group macros.
  • Duplicate macros.
  • Rename macros.
  • Edit macros.
  • Enable and disable macros.
  • Pause macro execution.
  • Resume macro execution.
  • Restart macros.
  • Cancel individual macros.
  • Cancel all active macros.
  • Queue macros.
  • Assign macro priority.
  • Support concurrent macro execution where permitted.
  • Support exclusive macro execution where required.
  • Synchronize macro actions.
  • Track macro execution state.
  • Detect macro execution errors.

Keyboard Automation

Keyboard Automation provides programmable control over keyboard actions.

Requirements

  • Press keys.
  • Release keys.
  • Hold keys.
  • Release held keys.
  • Press modifier keys.
  • Release modifier keys.
  • Create key combinations.
  • Create simultaneous key presses.
  • Create sequential key presses.
  • Repeat keystrokes.
  • Insert text.
  • Preserve required keyboard state.
  • Restore keyboard state after macro completion.
  • Define custom key sequences.
  • Control individual press and release timing.

Mouse Automation

Mouse Automation provides programmable control over mouse actions.

Requirements

  • Press mouse buttons.
  • Release mouse buttons.
  • Hold mouse buttons.
  • Perform single clicks.
  • Perform double clicks.
  • Perform repeated clicks.
  • Perform extended-button actions.
  • Move the mouse.
  • Perform relative movement where supported.
  • Perform absolute movement where supported.
  • Scroll vertically.
  • Scroll horizontally where supported.
  • Perform drag operations.
  • Combine mouse actions with keyboard actions.
  • Preserve required mouse state.
  • Restore mouse state after macro completion.

Mouse Movement Recording

Mouse Movement Recording captures movement information for later playback.

Requirements

  • Record relative mouse movement.
  • Record absolute mouse movement where supported.
  • Record movement timing.
  • Record movement direction.
  • Record movement velocity where available.
  • Record clicks during movement.
  • Record scrolling.
  • Record movement paths.
  • Replay recorded paths.
  • Adjust playback speed.
  • Scale recorded movement.
  • Offset recorded movement.
  • Mirror recorded movement.
  • Smooth recorded movement.
  • Simplify recorded paths.
  • Interpolate movement where appropriate.
  • Preserve recorded timing when requested.
  • Modify recorded timing during playback.
  • Loop recorded movement.

Macro Recording

Macro Recording allows users to capture physical input and convert it into editable automation.

Requirements

  • Record keyboard input.
  • Record mouse buttons.
  • Record mouse movement.
  • Record scrolling.
  • Record modifier keys.
  • Record combined keyboard and mouse input.
  • Record input from selected devices.
  • Record raw input where supported.
  • Record filtered input.
  • Record timing intervals.
  • Pause recording.
  • Resume recording.
  • Cancel recording.
  • Preview recordings.
  • Edit recordings.
  • Delete recorded actions.
  • Insert new actions.
  • Reorder actions.
  • Modify timing.
  • Normalize timing.
  • Compress unnecessary events.
  • Test recorded macros.

Macro recording must only capture input after the user explicitly starts a recording session or another clearly defined capture operation.

Recording Filters

Recording Filters control which inputs are captured during a recording session.

Requirements

  • Keyboard-only recording.
  • Mouse-only recording.
  • Button-only recording.
  • Movement-only recording.
  • Wheel-only recording.
  • Modifier filtering.
  • Device filtering.
  • Key filtering.
  • Button filtering.
  • Movement thresholds.
  • Timing thresholds.
  • Duplicate-event filtering.
  • Idle-event filtering.
  • Noise filtering.
  • Application-specific recording filters.
  • Recording exclusions.

Timing Engine

The Timing Engine controls the temporal behavior of input and macro execution.

Requirements

  • Support millisecond timing.
  • Support higher precision timing where available.
  • Define fixed delays.
  • Define variable delays.
  • Define delays before actions.
  • Define delays after actions.
  • Define inter-action intervals.
  • Define key hold durations.
  • Define button hold durations.
  • Define loop intervals.
  • Preserve recorded timing.
  • Scale recorded timing.
  • Adjust playback speed.
  • Define minimum delays.
  • Define maximum delays.
  • Compensate for execution latency where possible.
  • Synchronize dependent actions.
  • Use high-resolution timers where supported.

Loop Engine

The Loop Engine provides repeated macro execution.

Requirements

  • Fixed iteration loops.
  • Infinite loops.
  • Timed loops.
  • Conditional loops.
  • While-held loops.
  • Until-release loops.
  • Until-cancelled loops.
  • Nested loops.
  • Loop counters.
  • Loop delays.
  • Loop pause and resume.
  • Loop cancellation.
  • Maximum iteration limits.
  • Maximum duration limits.
  • Loop state tracking.

Macro Triggers

Macro Triggers define the conditions that initiate automation.

Supported Triggers

  • Keyboard input.
  • Mouse buttons.
  • Mouse wheel input.
  • Key combinations.
  • Button combinations.
  • Modifier combinations.
  • Input layers.
  • Profiles.
  • Applications.
  • Timers.
  • Device connection.
  • Device disconnection.
  • Manual activation.
  • Toggle activation.
  • Hold activation.
  • One-shot activation.

Trigger Behavior

Triggers may respond to different patterns of input.

Requirements

  • Press triggers.
  • Release triggers.
  • Hold triggers.
  • Long-press triggers.
  • Double-press triggers.
  • Triple-press triggers.
  • Sequential triggers.
  • Simultaneous triggers.
  • Toggle triggers.
  • One-shot triggers.
  • Repeated triggers.
  • Cooldown periods.
  • Trigger priority.
  • Trigger conflict resolution.

Profiles

Profiles provide complete collections of input assignments, layers, macros, triggers, timing settings, and device configurations.

Requirements

  • Create profiles.
  • Delete profiles.
  • Duplicate profiles.
  • Edit profiles.
  • Import profiles.
  • Export profiles.
  • Activate profiles.
  • Deactivate profiles.
  • Define a default profile.
  • Automatically switch profiles.
  • Define device-specific profiles.
  • Define application-specific profiles.
  • Define gaming profiles.
  • Define productivity profiles.
  • Define accessibility profiles.
  • Support profile inheritance.
  • Define profile priority.

Application Awareness

Application Awareness allows input behavior to change according to the active application or environment.

Requirements

  • Detect the active application where supported.
  • Define application-specific assignments.
  • Define application-specific macros.
  • Automatically activate application profiles.
  • Activate profiles when an application launches.
  • Deactivate profiles when an application closes.
  • Support process-specific rules.
  • Support window-specific rules where supported.
  • Define application inclusion lists.
  • Define application exclusion lists.

Macro Variables

Macro Variables provide dynamic state and data within automation.

Supported Types

  • Integer.
  • Decimal.
  • Boolean.
  • String.
  • Counter.
  • Timer.
  • Runtime state.
  • Layer state.
  • Profile state.
  • Device state.

Requirements

  • Create variables.
  • Assign variables.
  • Modify variables.
  • Compare variables.
  • Reset variables.
  • Use variables in conditions.
  • Use variables in loops.
  • Use variables in timing.
  • Use variables in macro actions.
  • Define temporary variables.
  • Define persistent variables where supported.

Conditional Automation

Conditional Automation allows macros and assignments to respond to system state.

Requirements

  • If conditions.
  • Then actions.
  • Else actions.
  • Nested conditions.
  • Key state conditions.
  • Button state conditions.
  • Modifier state conditions.
  • Layer state conditions.
  • Profile state conditions.
  • Device conditions.
  • Application conditions.
  • Timer conditions.
  • Variable conditions.
  • Macro state conditions.
  • Loop state conditions.

Macro Control Flow

Macro Control Flow defines the execution structure of complex automation.

Requirements

  • Sequential execution.
  • Conditional branching.
  • Loops.
  • Jumps.
  • Subroutines.
  • Macro calls.
  • Returns.
  • Pause.
  • Resume.
  • Cancel.
  • Restart.
  • Stop.
  • Timeouts.
  • Execution state tracking.

Pass-Through System

The Pass-Through System ensures that unassigned input retains its normal behavior.

Requirements

  • Pass through unassigned keyboard input.
  • Pass through unassigned mouse input.
  • Pass through unassigned buttons.
  • Pass through unassigned wheel input.
  • Preserve original input when no assignment is active.
  • Support selective interception.
  • Support selective suppression.
  • Support device-specific pass-through.
  • Support layer-specific pass-through.
  • Support profile-specific pass-through.
  • Support application-specific pass-through.
  • Provide emergency input bypass.

Input Suppression

Input Suppression prevents the original physical input from reaching the operating environment when an active assignment requires replacement.

Requirements

  • Suppress individual keyboard keys.
  • Suppress individual mouse buttons.
  • Suppress wheel input.
  • Suppress supported device input.
  • Suppress input only when an assignment is active.
  • Restore normal input when an assignment ends.
  • Resolve suppression according to assignment priority.
  • Prevent unintended stuck inputs.

Virtual Input Output

Virtual Input Output provides a mechanism for generating programmable input events.

Requirements

  • Generate virtual keyboard events where supported.
  • Generate virtual mouse events where supported.
  • Generate virtual controller events where supported.
  • Generate synthetic key presses.
  • Generate synthetic key releases.
  • Generate synthetic button presses.
  • Generate synthetic button releases.
  • Generate synthetic movement.
  • Generate synthetic scrolling.
  • Identify virtual output devices.
  • Track virtual input state.
  • Synchronize generated input.

Device Management

Device Management controls supported physical and virtual input devices.

Requirements

  • Enumerate devices.
  • Identify devices.
  • Name devices.
  • Create device aliases.
  • Group devices.
  • Filter devices.
  • Enable and disable devices.
  • Monitor devices.
  • Detect hotplug events.
  • Recover from device disconnection.
  • Support multiple devices simultaneously.
  • Define device-specific mappings.
  • Define device-specific macros.
  • Define device-specific layers.
  • Coordinate multiple devices.

Macro Editor

The Macro Editor provides an interface-independent model for creating and modifying macros.

Requirements

  • Action list editing.
  • Timeline editing.
  • Action insertion.
  • Action deletion.
  • Action duplication.
  • Action reordering.
  • Drag and drop where supported.
  • Timing editing.
  • Loop editing.
  • Trigger editing.
  • Condition editing.
  • Variable editing.
  • Preview.
  • Validation.
  • Testing.
  • Macro execution simulation where supported.

Macro Library

The Macro Library provides organized storage and discovery of macros.

Requirements

  • Built-in macros.
  • User-created macros.
  • Macro categories.
  • Macro tags.
  • Macro search.
  • Macro duplication.
  • Macro versioning.
  • Macro metadata.
  • Macro descriptions.
  • Macro dependencies.
  • Macro import.
  • Macro export.

Macro Execution Management

Macro Execution Management provides visibility and control over active automation.

Requirements

  • Display active macros.
  • Display macro status.
  • Display queued macros.
  • Display execution state.
  • Cancel individual macros.
  • Cancel all macros.
  • Pause macros.
  • Resume macros.
  • Assign execution priority.
  • Control concurrent execution.
  • Define exclusive execution.
  • Maintain execution history.
  • Report execution errors.
  • Record execution statistics.

Safety and Fail-Safe Controls

KeyMod must provide mechanisms that prevent automation from creating uncontrolled or persistent input states.

Requirements

  • Global emergency stop.
  • Emergency keyboard shortcut.
  • Emergency mouse shortcut where supported.
  • Stop-all function.
  • Macro timeouts.
  • Loop iteration limits.
  • Maximum macro duration.
  • Stuck-key detection.
  • Stuck-button detection.
  • Automatic input release.
  • Device disconnect recovery.
  • Application failure recovery where supported.
  • Crash recovery.
  • Safe restoration of normal mappings.
  • Pass-through recovery.
  • Startup safety controls.
  • Configuration validation.
  • Invalid macro detection.

Configuration

Configuration defines the persistent and temporary behavior of KeyMod.

Requirements

  • Human-readable configuration.
  • Machine-readable configuration.
  • Configuration validation.
  • Configuration versioning.
  • Configuration backup.
  • Configuration restoration.
  • Configuration import.
  • Configuration export.
  • Configuration migration.
  • Default configuration values.
  • Device-specific configuration.
  • Profile-specific configuration.
  • Layer-specific configuration.
  • Temporary session configuration.

Persistence

KeyMod must distinguish between persistent configuration and temporary runtime state.

Persistent Data

  • Profiles.
  • Assignments.
  • Macros.
  • Layers.
  • Timing settings.
  • Device mappings.
  • Macro libraries.
  • User preferences.

Temporary Data

  • Session assignments.
  • Active layers.
  • Runtime variables.
  • Active macros.
  • Temporary mappings.
  • Temporary recording sessions.

Import and Export

KeyMod must provide portable mechanisms for transferring configuration and automation.

Requirements

  • Macro import.
  • Macro export.
  • Profile import.
  • Profile export.
  • Device configuration import.
  • Device configuration export.
  • Layer import.
  • Layer export.
  • Full configuration import.
  • Full configuration export.
  • Version compatibility checking.
  • Configuration migration.

Accessibility

KeyMod should support input customization for users who require alternative interaction methods.

Requirements

  • Alternative input mappings.
  • One-button automation.
  • Simplified combinations.
  • Hold-to-toggle conversion.
  • Toggle-to-hold conversion.
  • Repeated-input automation.
  • Accessibility-specific layers.
  • Custom activation timing.
  • Custom input sensitivity.
  • Reduced-combination interaction.
  • Extended hold support.

Advanced Input Features

Advanced Input Features extend programmable input beyond simple key replacement.

Requirements

  • Chorded input.
  • Sequential input detection.
  • Key sequences.
  • Mouse gestures.
  • Tap-versus-hold detection.
  • Double-tap detection.
  • Multi-key chords.
  • Multi-button chords.
  • Timing pattern recognition.
  • Context-sensitive mappings.
  • Gesture recognition where supported.

Automation Scheduling

Scheduling allows automation to begin or end according to time-based conditions.

Requirements

  • Delayed execution.
  • Scheduled execution.
  • Repeating schedules.
  • Timed sessions.
  • Start triggers.
  • Stop triggers.
  • Session duration.
  • Scheduled profile activation.
  • Scheduled layer activation.
  • Scheduled macro execution.

Logging and Diagnostics

Logging and Diagnostics provide visibility into system behavior while respecting privacy controls.

Requirements

  • Input event diagnostics.
  • Macro execution logs.
  • Recording session logs.
  • Error logs.
  • Device logs.
  • Profile logs.
  • Layer logs.
  • Timing diagnostics.
  • Performance diagnostics.
  • Latency measurements.
  • Execution statistics.
  • Configurable logging levels.
  • Debug mode.

Privacy

KeyMod must provide explicit controls over input capture and stored information.

Requirements

  • Local-first operation.
  • Optional event logging.
  • Configurable retention.
  • Automatic log deletion.
  • Sensitive-input exclusions.
  • Device exclusions.
  • Application exclusions.
  • Recording pause.
  • Recording termination.
  • Explicit recording state.
  • Local recording storage.
  • User-controlled deletion.
  • Clear indication when input capture is active.

Optional Keylogger Plugin

KeyMod may provide an optional Keylogger Plugin for controlled keyboard event capture. This functionality must remain separate from the core macro system and must require explicit user activation.

Requirements

  • Capture keyboard events.
  • Capture key-down events.
  • Capture key-up events.
  • Capture modifier state.
  • Capture timing.
  • Capture device identity.
  • Define recording sessions.
  • Selectively capture input.
  • Define application exclusions.
  • Define device exclusions.
  • Pause capture.
  • Terminate capture.
  • Delete captured data.
  • Store captured data locally.
  • Provide an explicit capture indicator.
  • Define retention controls.

The core macro recorder must not function as an unrestricted keylogger. Keyboard capture for macro creation must occur only during an explicitly initiated recording session.

Performance

KeyMod should minimize the latency introduced between physical input and resulting action.

Requirements

  • Low-latency input processing.
  • High-frequency mouse support.
  • High polling-rate device support.
  • Efficient event queues.
  • Precise timing.
  • Controlled CPU usage.
  • Controlled memory usage.
  • Performance monitoring.
  • Latency diagnostics.
  • High-priority execution where supported.
  • Efficient event batching where appropriate.

Extensibility

KeyMod must support optional extensions without requiring changes to the core specification.

Extension Types

  • Input plugins.
  • Output plugins.
  • Action plugins.
  • Trigger plugins.
  • Condition plugins.
  • Variable plugins.
  • Device adapter plugins.
  • Profile plugins.
  • Automation plugins.
  • Integration plugins.
  • Scripting plugins.

Plugins must operate through defined interfaces and must not bypass KeyMod safety, privacy, permission, or cancellation mechanisms.

Scripting Plugin

An optional Scripting Plugin may provide advanced automation capabilities.

Requirements

  • Custom actions.
  • Variables.
  • Conditions.
  • Loops.
  • Timers.
  • Functions.
  • Macro calls.
  • Event handlers.
  • Input state queries.
  • Profile queries.
  • Layer queries.
  • Device queries.
  • Application queries.
  • Macro state queries.

Scripts must remain subject to the same execution controls, safety requirements, permissions, cancellation mechanisms, and resource limits as native macros.

API Plugin

An optional API Plugin may expose KeyMod functionality to authorized local applications and automation systems.

Requirements

  • Start and stop macros.
  • Query active macros.
  • Activate profiles.
  • Activate layers.
  • Create assignments.
  • Modify assignments.
  • Query devices.
  • Query input state.
  • Start recording.
  • Stop recording.
  • Import configuration.
  • Export configuration.
  • Query diagnostics.
  • Control approved automation functions.

API access must require appropriate authorization and must not bypass security or safety controls.

CLI Plugin

An optional Command Line Plugin may provide administrative and automation control.

Requirements

  • Start KeyMod.
  • Stop KeyMod.
  • Start recording.
  • Stop recording.
  • Run macros.
  • Cancel macros.
  • Activate profiles.
  • Deactivate profiles.
  • Activate layers.
  • Deactivate layers.
  • List devices.
  • List assignments.
  • List profiles.
  • Import configuration.
  • Export configuration.
  • Run diagnostics.

Multi-Device Automation Plugin

An optional Multi-Device Automation Plugin may coordinate input and output across multiple devices.

Requirements

  • Keyboard-to-mouse automation.
  • Mouse-to-keyboard automation.
  • Keyboard-to-controller automation.
  • Controller-to-keyboard automation.
  • Cross-device triggers.
  • Synchronized actions.
  • Multi-device recording.
  • Device-specific timing.
  • Device-specific layers.
  • Coordinated macro execution.

User Interface

Implementations may provide a graphical interface for managing KeyMod.

Recommended Capabilities

  • Dashboard.
  • Profile manager.
  • Layer manager.
  • Macro manager.
  • Macro recorder.
  • Macro editor.
  • Assignment editor.
  • Timing editor.
  • Loop editor.
  • Trigger editor.
  • Device manager.
  • Active macro monitor.
  • Event viewer.
  • Configuration manager.
  • Diagnostics interface.
  • Emergency stop control.

Service Architecture

Implementations may operate KeyMod as a background service responsible for persistent input processing.

Responsibilities

  • Monitor physical devices.
  • Receive input events.
  • Intercept assigned input.
  • Pass through unassigned input.
  • Suppress replaced input.
  • Execute macros.
  • Manage profiles.
  • Manage layers.
  • Manage configuration.
  • Manage logging.
  • Manage plugins.
  • Manage authorized API access.
  • Recover from supported failures.
  • Gracefully shut down.
  • Restore safe input state.

Security

KeyMod must protect the ability to intercept and generate input from unauthorized access.

Requirements

  • Local authorization.
  • Protected configuration.
  • Plugin permissions.
  • Script permissions.
  • API permissions.
  • Application restrictions.
  • Device restrictions.
  • Macro execution permissions.
  • Audit logging where enabled.
  • Secure plugin loading.
  • Optional plugin signing.
  • Permission-aware automation.

Compatibility

KeyMod is intended to remain independent of specific hardware manufacturers and implementation technologies.

Requirements

  • Support standard keyboards where possible.
  • Support standard mice where possible.
  • Support gaming keyboards where possible.
  • Support gaming mice where possible.
  • Support supported controllers.
  • Support supported HID devices.
  • Support multiple vendors.
  • Support multiple devices.
  • Support virtual input devices where available.
  • Provide platform-specific adapters where required.
  • Maintain platform-independent macro definitions.

Specification Interoperability

KeyMod definitions should be portable between compatible implementations.

Standardized Concepts

  • Input definitions.
  • Output definitions.
  • Actions.
  • Timing.
  • Loops.
  • Conditions.
  • Triggers.
  • Layers.
  • Profiles.
  • Variables.
  • Device mappings.
  • Macro metadata.
  • Version information.

Implementations should provide versioned formats and compatibility rules for transferring macros, profiles, assignments, and related configuration between compatible systems.

Conformance

A KeyMod implementation may declare conformance when it implements the required portions of the specification and correctly follows the defined behavioral requirements.

Conformance Requirements

  • Correct input detection.
  • Correct assignment behavior.
  • Correct pass-through behavior.
  • Correct input suppression.
  • Correct macro execution.
  • Correct timing behavior.
  • Correct temporary remapping.
  • Correct layer behavior.
  • Correct profile behavior.
  • Correct cancellation behavior.
  • Correct fail-safe behavior.
  • Correct configuration handling.
  • Correct privacy controls for recording.
  • Correct handling of required specification formats.

Optional plugins may declare separate conformance levels based on the capabilities they implement.

Specification Branding License (SBL)

Standard

  • Fully AGPL-3.0+ compliant system
  • Copyleft enforced for network deployments
  • Required attribution:
  • Roxanne Ardary
  • roxanneardary.com

Optional

License & Notice Requirements

KeyMod is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).

By contributing to any Open Arsenal project, you agree that your contributions will also be released under this license.

Please note the following:

  • All contributions must comply with the AGPL-3.0+ terms.
  • Under Section 7 of the license, all redistributions, forks, and derivative works must preserve attribution to Roxanne Ardary and roxanneardary.com.
  • KeyMod specifications are free to use with attribution. A Specification Branding License can be negotiated upon request.
  • The project’s notice.md file tracks attribution requirements and contributor acknowledgments. Any update that adds new contributors or modifies attribution should also update notice.md.
  • When submitting a pull request, ensure that any new files maintain the attribution headers where applicable.
  • Network-deployed versions of this software must also remain fully AGPL-3.0+ compliant, including exposure of source code modifications when applicable under the license.

For full legal details, please refer to the AGPL-3.0+ license and the project’s notice.md file.

Notice – KeyMod

Attribution Requirement: Under Section 7 of the AGPL 3.0+ license, all redistributions, forks, and derivative works, including network-deployed versions of this project, must provide attribution to Roxanne Ardary and roxanneardary.com.

Contributors

This file tracks contributors and their specific contributions to the project.

  • Roxanne Ardary, roxanneardary.com – September 4, 2026
    Created the repository for KeyMod. Developed the KeyMod specification for universal input remapping, macro automation, programmable input assignments, and customizable keyboard and mouse control.
  • [Add other contributors here] – [Date]
    [Describe contribution in one sentence]

License – KeyMod

This repository is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).

Key Points:

  • You are free to use, modify, and distribute the code.
  • All redistributions, forks, and derivative works or network-deployed versions must also be licensed under AGPL-3.0+ and provide attribution to Roxanne Ardary and roxanneardary.com as required under Section 7 of the license.
  • The software is provided “as is,” without warranty of any kind.

For the full license text, see GNU AGPL-3.0 License.

Related posts:

Domestic Economics

VeritasCode Specification

WebDetective