Command Reference

Complete documentation of all available PTHKD actions

Every hotkey is a JSON object with a trigger (key or MIDI), optional filters, and a command. This page documents the structure and every available command.

Beta Software Disclaimer

PTHKD is beta software provided "AS IS" without warranty of any kind. Use at your own risk. This software is in active development and may contain bugs, cause unexpected behavior, or interfere with other applications.

While we make every effort to ensure stability, we provide no technical support, warranties, or guarantees regarding this beta release. Users should exercise caution and test thoroughly in non-critical environments before relying on PTHKD in production workflows.

By downloading and using PTHKD, you acknowledge that this is experimental software and agree to use it at your own discretion and risk.

Default Keymap Quick Reference

The hotkeys PTHKD ships with out of the box. Click any column header to sort, or type in the box to filter. Everything here is fully customizable — these entries live in your config.json once you export it, and you can edit, remove, or add to them freely.

KeyModifiersAppsName
wcmd, opt, shiftGlobalPrint Current Window
icmd, opt, ctrl, shiftGlobalImport Config File
wcmd, opt, ctrl, shiftGlobalExport Config File
acmd, opt, shiftGlobalPrint Current App
ecmd, shiftGlobalEject All Drives
f17ProtoolsMinimize All Tracks
scmd, shiftProtoolsSolo Only Selected Tracks
sopt, shiftProtoolsClear All Track Solos
keypad_pluscmd, opt, ctrlProtoolsConform Insertion
keypad_minuscmd, opt, ctrlProtoolsConform Deletion
tcmd, opt, ctrl, shiftProtoolsTrim Backgrounds
vcmd, opt, ctrl, shiftProtoolsPaste Backgrounds
ccmd, opt, ctrl, shiftProtoolsCopy Backgrounds
xcmd, opt, ctrl, shiftProtoolsRemove Backgrounds
fProtoolsCrossfade with Automation
fcmd, ctrlProtoolsCrossfade Adjust
hcmd, shiftProtoolsHeal
tcmdProtoolsTrim to Match Selection
upcmd, opt, ctrlProtoolsPro Tools Version Up Session
scmd, opt, ctrlProtoolsExport Selection
scmd, opt, ctrl, shiftProtoolsExport Selection with Copy
keypad_minusshiftProtoolsSelect to Previous Marker
keypad_plusshiftProtoolsSelect to Next Marker
keypad_7shiftProtoolsSelect to Previous Marker BG
keypad_8shiftProtoolsSelect BG
keypad_9shiftProtoolsSelect to Next Marker BG
keypad_multiplyshiftProtoolsSelect Between Markers
tabctrlProtoolsGo To Next Marker
tabopt, ctrlProtoolsGo To Previous Marker
keypad_0shiftProtoolsGo To Quickmarker 0
keypad_0ctrl, shiftProtoolsUpdate Quickmarker 0
keypad_1shiftProtoolsGo To Quickmarker 1
keypad_1ctrl, shiftProtoolsUpdate Quickmarker 1
keypad_2shiftProtoolsGo To Quickmarker 2
keypad_2ctrl, shiftProtoolsUpdate Quickmarker 2
keypad_3shiftProtoolsGo To Quickmarker 3
keypad_3ctrl, shiftProtoolsUpdate Quickmarker 3
spacectrlProtoolsPreview Audiosuite
keypad_enterctrlProtoolsRender Audiosuite
keypad_divide (MIDI 77)ctrlProtoolsReverse Clip
keypad_multiply (MIDI 80)ctrlProtools, RxiZotope RX 11 Connect
keypad_1 (MIDI 83)ctrlProtoolsReverb Selector
keypad_2 (MIDI 82)ctrlProtoolsDelay Selector
keypad_4 (MIDI 79)ctrlProtoolsDynamics Selector
keypad_6 (MIDI 75)ctrlProtoolsDoppler Selector
keypad_7 (MIDI 75)ctrlProtoolsPitch Shift Selector
keypad_0 (MIDI 81)ctrlProtoolsNoise Reduction Selector
escapeProtoolsView Toggle
sctrlSoundminerSpot to DAW
sctrlProtoolsSpot to Pro Tools
bcmd, opt, ctrl, shiftProtools, SoundminerBG Spot to Pro Tools
f1SoundminerSend to Pro Tools
f1cmd, opt, ctrl, shiftSoundminerSend Selection to Pro Tools
f3SoundminerSend to RX 11
f12SoundminerCopy Files
f11SoundminerSelect Spotting Folder
f10SoundminerSelect No DAW
0cmd, opt, ctrlGlobalLaunch SM TF
9cmd, opt, ctrlGlobalLaunch SM Skysound
8cmd, opt, ctrlGlobalLaunch SM Formosa
7cmd, opt, ctrlGlobalLaunch Embedadata
taboptGlobalToggle Protools/Soundminer
tabcmd, optGlobalToggle Protools/Reaper
ycmd, opt, ctrl, shiftProtools, MatchboxToggle New Old Timeline

Configuration File & Structure

All PTHKD hotkeys are configured in a single JSON file located at:

~/Library/Application Support/pthkd/config.json

Getting Started: Click the ⚡ PTHKD icon in the macOS menu bar and choose Export Config to write a starter config.json containing the built-in defaults. If a config.json already exists, PTHKD writes the defaults to config_default.json instead, so your file is never overwritten. Use Open Config in Text Editor to edit it, then Reload Config File to apply changes without restarting the daemon.

File format: The config is a JSON array of hotkey objects. Each object needs a trigger (a key and/or midi) and an action (a command or a multitap). All other fields are optional.

FieldTypeDescription
namestringOptional label (shown in logs; handy for organizing your file)
keystringTrigger key — see Keys
modifiersarrayModifier keys held with key — see Modifiers
midiobjectMIDI trigger — see MIDI
appsarrayOnly fire when one of these apps is frontmost — see Filters
windowstringOnly fire when the focused window title matches
commandobjectThe action to run (one namespace key)
multitapobjectCycle through AudioSuite plugins — see Multitap

A complete minimal file with two hotkeys looks like this:

[
    {
        "name": "Reload Config File",
        "key": "i",
        "modifiers": ["hyper"],
        "command": { "config": "Reload" }
    },
    {
        "name": "Solo Only Selected Tracks",
        "key": "s",
        "modifiers": ["cmd", "shift"],
        "apps": ["Protools"],
        "command": {
            "protools": { "track": { "solo": "Selected" } }
        }
    }
]

The command value is a tagged object: the top-level key is the namespace (config, macos, protools, soundminer, or app) and its value selects the specific action. Any field left out uses its default.

Keys & Modifiers Trigger

The key field takes a single key name. The modifiers array lists the modifiers held alongside it.

Modifiers

Accepted values for the modifiers array. hyper (alias hypr) is shorthand for all four modifiers at once.

ValueAliasesMeaning
cmdcommand⌘ Command
optoption⌥ Option / Alt
ctrlcontrol⌃ Control
shift⇧ Shift
hyperhypr⌘ + ⌥ + ⌃ + ⇧ together
Key names

Use these exact names for the key field.

GroupNames
Lettersaz
Numbers"0""9" (top row)
Functionf1f20
Keypadkeypad_0keypad_9, keypad_plus, keypad_minus, keypad_multiply, keypad_divide, keypad_enter, keypad_decimal, keypad_equals, keypad_clear
Editingreturn_key, tab, space, delete, forward_delete, escape, caps_lock
Navigationleft, right, up, down, home, end, page_up, page_down
Symbolsequal, minus, left_bracket, right_bracket, quote, semicolon, backslash, comma, slash, period, grave, section
{
    "key": "keypad_plus",
    "modifiers": ["shift"],
    "apps": ["Protools"],
    "command": {
        "protools": { "marker": { "goto": { "direction": "Next", "select": true } } }
    }
}

MIDI Triggers Trigger

Any hotkey can be triggered by a MIDI message instead of (or in addition to) a key. Add a midi object. A hotkey may specify both key and midi — either will fire it.

midi
FieldTypeDescription
msgstring"NoteOn", "NoteOff", or "CC"
noteintNote (or CC) number, 0–127
channelintMIDI channel (optional)
velocityintVelocity (optional)
devicestringMatch a specific device name (optional)
{
    "name": "Reverse Clip",
    "key": "keypad_divide",
    "modifiers": ["ctrl"],
    "midi": { "msg": "NoteOn", "note": 77 },
    "apps": ["Protools"],
    "multitap": {
        "items": [
            { "name": "Reverse", "parent_menu": "Avid", "render": true, "close": true }
        ]
    }
}

Stream Deck Elgato

PTHKD ships with an Elgato Stream Deck plugin, so you can fire any command from a physical button — a great fit for sound editors who'd rather tap a key on the deck than remember a keyboard shortcut. The plugin talks to the running PTHKD app, so PTHKD must be running for the buttons to work.

Installation

PTHKD installs the plugin automatically every time it launches — there's nothing to download separately. You can also reinstall it on demand from the menu bar (⚡ → Install Stream Deck Plugin).

StepDetail
1. Launch PTHKDThe plugin is installed into Stream Deck's Plugins folder on startup
2. Restart Stream DeckIf the pthkd category doesn't appear in the Stream Deck app's action list, quit and reopen Stream Deck so it picks up the new plugin
3. Add an actionDrag Run Command or Create Command onto a key

Requirements: Stream Deck software 6.6 or later, macOS 12 or later, and PTHKD running.

Run Command — trigger a preconfigured command

The simplest option. Drop this action on a key and pick a command from the dropdown — the list is populated live from the named commands in your config (the same names shown in the Default Keymap). The button runs that command by name, so it always stays in sync with your config; no parameters to set. Give a hotkey a name in your config and it shows up here automatically.

Create Command — build a command from scratch

For actions you haven't bound to a key. This action's inspector builds a form directly from PTHKD's live command schema — the exact same namespaces, actions, and fields documented on this page (protools, soundminer, macos, config). Pick a namespace, fill in the options, and the button sends that command to PTHKD. Perfect for a deck full of one-off buttons — e.g. a macos.click_menu button for any menu item in any supported app — without touching your keyboard hotkeys at all.

Tip: turn off keyboard sensing for a deck-only workflow

The menu bar has an Enable Hotkeys toggle (⚡ menu, checkmark shows the current state). It enables or disables PTHKD's keyboard hotkey sensing — but Stream Deck buttons keep working either way. So if you'd rather drive everything from the deck and not have PTHKD intercept your keyboard, switch Enable Hotkeys off: your normal keyboard shortcuts pass straight through to the app while the Stream Deck still fires PTHKD commands. The setting is remembered across restarts.

App & Window Filters Filter

Restrict a hotkey to specific applications with apps, and optionally to a specific window with window. If apps is omitted the hotkey is global.

apps

Array of application identifiers. The hotkey only fires when one of them is frontmost. These same identifiers are also used as the daw value in Soundminer commands and as app in the App namespace.

IdentifierApplication
ProtoolsAvid Pro Tools
ReaperREAPER (Soundminer Reaper Extension)
SoundminerSoundminer (v6 or v7)
RxiZotope RX 11
EmbedadataEmbedaData
MatchboxMatchbox
NoneNo DAW (used by Soundminer commands)
{
    "name": "Crossfade with Automation",
    "key": "f",
    "apps": ["Protools"],
    "window": "EDIT",
    "command": { "protools": { "edit": { "crossfade": {} } } }
}

config Namespace Daemon

Manage the config file itself. The value is a plain string. These same actions are available from the menu bar icon.

config
ValueDescription
"Reload"Re-read the config file and apply changes without restarting
"ExportJson"Write the current defaults to config.json (or config_default.json if it exists)
"Export"Same, but write the ZON variant (config.zon)
"Open"Open the config file in your default text editor
{
    "name": "Reload Config File",
    "key": "i",
    "modifiers": ["hyper"],
    "command": { "config": "Reload" }
}

macos: App Control & System macOS

The macos command is a general-purpose driver for any supported app plus a few system utilities. Set app to target an application, or omit it for a system command. This is the most powerful namespace in PTHKD: because it can click any menu item in any supported app, you're not limited to the built-in commands — you can build a hotkey (or MIDI trigger) for virtually anything the app exposes in its menus. If you can find it in a menu, you can bind it.

click_menu — bind a hotkey to any menu item

Focuses the target app and clicks a menu item by its menu_path — an array that walks from the menu bar down through any submenus to the item. This one command lets you map a key or MIDI note to almost any function in Pro Tools, Soundminer, REAPER, RX, Matchbox, etc. The example below is exactly how the built-in Toggle New Old Timeline hotkey is implemented — it drives Matchbox's Reconform → Jump DAW between Old / New menu item.

{
    "name": "Toggle New Old Timeline",
    "key": "y",
    "modifiers": ["hyper"],
    "apps": ["Protools", "Matchbox"],
    "command": {
        "macos": {
            "app": "Matchbox",
            "command": "click_menu",
            "menu_path": ["Reconform", "Jump DAW between Old / New"]
        }
    }
}

Tip: unsure of the exact menu wording or window title? Use the system commands below (print_current_window / debug_focused_element) to inspect the app while it's focused.

macos — full reference

command is always required. app is required for the app commands and must be omitted for the system commands. The remaining fields apply only to specific commands.

FieldTypeDefaultDescription
commandstringThe action — see the two tables below (required)
appstringTarget app identifier (see apps). Omit for a system command
menu_patharray[""]Menu path for click_menu (e.g. ["View", "Other Displays", "Clip Effects"])
windowstring""Window title for button/checkbox/window commands
buttonstring""Button label for press_button
checkboxstring""Checkbox label for set_checkbox
togglebooltrueTarget state for set_checkbox
textstring""AppleScript source for applescript

App commands — require app:

commandDescription
"click_menu"Focus the app and click the menu item at menu_path
"press_button"Press button in window
"set_checkbox"Set checkbox in window to toggle
"close_window"Close window
"focus_window"Focus window
"launch"Launch the app (or focus it if already running)
"quit"Quit the app
"applescript"Run the AppleScript in text

System commands — omit app:

commandDescription
"eject_all_drives"Unmount all external drives
"print_current_app"Print the frontmost app's bundle ID (for building apps filters)
"print_current_window"Print the frontmost window title and focused UI element
"debug_focused_element"Print details of the currently focused accessibility element
{
    "name": "Launch Embedadata",
    "key": "7",
    "modifiers": ["ctrl", "opt", "cmd"],
    "command": { "macos": { "app": "Embedadata", "command": "launch" } }
}

{
    "name": "Eject All Drives",
    "key": "e",
    "modifiers": ["cmd", "shift"],
    "command": { "macos": { "command": "eject_all_drives" } }
}

Pro Tools: Edit Pro Tools

Editing, crossfades, and clip manipulation. Nest under { "protools": { "edit": { … } } }.

protools.edit.crossfade

Create fades over the selection from a preset, with optional automation and selection adjustment. All fields optional.

FieldTypeDefaultDescription
fade_presetstring"TF Default"Fade preset name
fade_automationbooltrueAlso crossfade automation
fill_selectionboolfalseTrim clips to fill the selection first
adjust_selectionfloat0.0Grow/shrink the selection by N frames
snap_to_gridboolfalseSnap the selection to the grid
{
    "name": "Crossfade Adjust",
    "key": "f",
    "modifiers": ["cmd", "ctrl"],
    "apps": ["Protools"],
    "command": {
        "protools": {
            "edit": {
                "crossfade": {
                    "snap_to_grid": true,
                    "adjust_selection": 1.0,
                    "fill_selection": true
                }
            }
        }
    }
}
protools.edit.between_markers

Copy / paste / trim / clear the region between the two markers surrounding the cursor on a given ruler — ideal for background (BG) editing. Only command is required.

FieldTypeDefaultDescription
commandstring"Copy", "Paste", "Trim", or "Clear" (required)
lanestring"BG"Ruler/lane whose markers define the region
presetstring"BG Default"Fade preset applied at the edges
adjust_selectionfloat1.0Overlap in frames for fades
snap_to_gridbooltrueSnap the selection to the grid
{
    "name": "Paste Backgrounds",
    "key": "v",
    "modifiers": ["hyper"],
    "apps": ["Protools"],
    "command": {
        "protools": { "edit": { "between_markers": { "command": "Paste" } } }
    }
}
protools.edit.conform

Insert or delete time in shuffle mode (conform edits). Value is a string.

ValueDescription
"Insert"Insert/open a gap at the selection
"Delete"Delete the selection and close the gap
{
    "name": "Conform Insertion",
    "key": "keypad_plus",
    "modifiers": ["cmd", "opt", "ctrl"],
    "apps": ["Protools"],
    "command": { "protools": { "edit": { "conform": "Insert" } } }
}
protools.edit.trim_to_selection · clear_heal · clip_reset

Take no parameters — pass an empty object {}.

CommandDescription
trim_to_selectionTrim clip boundaries to match the timeline selection
clear_healHeal separations across the selection
clip_resetRemove clip gain, clip effects, and fades
{
    "name": "Trim to Match Selection",
    "key": "t",
    "modifiers": ["cmd"],
    "apps": ["Protools"],
    "command": { "protools": { "edit": { "trim_to_selection": {} } } }
}

Pro Tools: Tracks Pro Tools

Soloing and track height. Nest under { "protools": { "track": { … } } }.

protools.track.solo

Manage track solos. Value is a string.

ValueDescription
"Selected"Solo only the selected tracks (clears the rest)
"Clear"Clear all track solos
{
    "name": "Solo Only Selected Tracks",
    "key": "s",
    "modifiers": ["cmd", "shift"],
    "apps": ["Protools"],
    "command": { "protools": { "track": { "solo": "Selected" } } }
}
protools.track.minimize

Set track height to micro. Value is a string.

ValueDescription
"All"Minimize every track
"Selected"Minimize only the selected tracks
{
    "name": "Minimize All Tracks",
    "key": "f17",
    "apps": ["Protools"],
    "command": { "protools": { "track": { "minimize": "All" } } }
}

Pro Tools: Markers Pro Tools

Marker navigation and quick markers. Nest under { "protools": { "marker": { … } } }.

protools.marker.goto

Move to (or select to) the next/previous marker, optionally limited to a specific ruler.

FieldTypeDefaultDescription
directionstring"Next""Next", "Prev", or "Between"
selectboolfalseExtend the selection instead of just moving
rulerstringRestrict to a named ruler (e.g. "BG"). Omit for all markers
{
    "name": "Select to Next Marker",
    "key": "keypad_plus",
    "modifiers": ["shift"],
    "apps": ["Protools"],
    "command": {
        "protools": { "marker": { "goto": { "direction": "Next", "select": true } } }
    }
}
protools.marker.quickmarker

Go to or set a numbered "quick marker". Quick markers are stored at a high memory-location offset so they don't collide with your session markers.

FieldTypeDefaultDescription
numberint0Quick marker slot
actionstring"GoTo""GoTo" or "Set"
colorstring"magenta"Marker color (see below)
namestringMarker name when setting (defaults to "QUICKMARKER N")
offsetint31000Memory-location number offset

Colors: darkpurple, purple, pink, magenta, red, orange, darkyellow, yellow, lightgreen, green, lightblue, blue, darkblue, white, grey, black.

{
    "name": "Update Quickmarker 0",
    "key": "keypad_0",
    "modifiers": ["ctrl", "shift"],
    "apps": ["Protools"],
    "command": {
        "protools": {
            "marker": { "quickmarker": { "action": "Set", "color": "green" } }
        }
    }
}

Pro Tools: Plugins Pro Tools

AudioSuite render/preview and RX round-trip. Value is a string. For opening and cycling through AudioSuite plugins, see Multitap Selectors.

protools.plugin
ValueDescription
"Render"Click Render in the open AudioSuite window
"Preview"Click Preview in the open AudioSuite window
"RXConnect"Round-trip the selection through iZotope RX Connect
{
    "name": "Render Audiosuite",
    "key": "keypad_enter",
    "modifiers": ["ctrl"],
    "apps": ["Protools"],
    "command": { "protools": { "plugin": "Render" } }
}

Pro Tools: Session & Focus Pro Tools

Session versioning, exporting, mode toggles, and app switching. These sit directly under protools.

protools.version_up

Save, then increment the session's version number (e.g. NAME_01_TF → NAME_02_TF) and move the previous file into a zOLD/ folder. Takes no parameters — pass {}.

{
    "name": "Pro Tools Version Up Session",
    "key": "up",
    "modifiers": ["cmd", "opt", "ctrl"],
    "apps": ["Protools"],
    "command": { "protools": { "version_up": {} } }
}
protools.export_selected

Save a session copy of the selected tracks and timeline range. Value is a string.

ValueDescription
"SessionOnly"Export the session copy without copying audio
"CopyAudio"Also copy the audio files into the new session
{
    "name": "Export Selection with Copy",
    "key": "s",
    "modifiers": ["shift", "cmd", "opt", "ctrl"],
    "apps": ["Protools"],
    "command": { "protools": { "export_selected": "CopyAudio" } }
}
protools.toggle

Toggle a Pro Tools mode/tool, or switch focus between apps. Value is a string.

ValueDescription
"EditMode"Toggle between Grid Absolute and Slip
"EditTool"Toggle between the Selector and Grabber tools
"Soundminer"Toggle focus between Pro Tools and Soundminer
"Reaper"Toggle focus between Pro Tools and REAPER
"NewOld"Trigger Matchbox "Jump DAW between Old / New"
{
    "name": "Toggle Protools/Soundminer",
    "key": "tab",
    "modifiers": ["opt"],
    "command": { "protools": { "toggle": "Soundminer" } }
}

Soundminer Namespace Soundminer

Spotting, DAW selection, and launching Soundminer settings profiles. Nest under { "soundminer": { … } }.

soundminer.send_to_daw

Send files from Soundminer to a DAW. All fields optional.

FieldTypeDefaultDescription
dawstringTarget: "Protools", "Reaper", "Rx", "None"
commandstring"Spot To DAW"Transfer command: "Spot To DAW", "Bring Into DAW", "Send Files to DAW"
reference_originalboolfalseReference original files instead of converting
original_sample_rateboolfalseKeep the original sample rate
spot_as_regionbooltrueCreate as a region in the DAW
launchboolfalseLaunch the DAW first if it isn't running
selectionboolfalseSpot to the current BG marker selection
{
    "name": "Spot to Pro Tools",
    "key": "s",
    "modifiers": ["ctrl"],
    "apps": ["Protools"],
    "command": {
        "soundminer": { "send_to_daw": { "daw": "Protools" } }
    }
}
soundminer.select_daw

Set Soundminer's active DAW via its DAW menu.

FieldTypeDefaultDescription
dawstring"None""Protools", "Reaper", "Rx", or "None"
{
    "name": "Select No DAW",
    "key": "f10",
    "apps": ["Soundminer"],
    "command": { "soundminer": { "select_daw": { "daw": "None" } } }
}
soundminer.launch

Swap in a saved Soundminer settings profile (prefs, facility prefs, category list) and relaunch Soundminer. Value is a string.

ValueDescription
"TF"Launch with the "TF" profile
"Skysound"Launch with the "Skysound" profile
"Formosa"Launch with the "Formosa" profile
{
    "name": "Launch SM TF",
    "key": "0",
    "modifiers": ["ctrl", "opt", "cmd"],
    "command": { "soundminer": { "launch": "TF" } }
}
soundminer.select_spotting_folder

Open Soundminer's spotting-folder (Set Transfer) dialog. Takes no parameters — pass {}.

{
    "name": "Select Spotting Folder",
    "key": "f11",
    "apps": ["Soundminer"],
    "command": { "soundminer": { "select_spotting_folder": {} } }
}

Multitap Selectors AudioSuite

Use multitap (in place of command) to cycle through a list of AudioSuite plugins by tapping the same hotkey repeatedly within ~300 ms. One tap opens the first item, two taps the second, and so on. Each entry opens the AudioSuite plugin and can optionally analyze, render, and close it.

multitap.items[]
FieldTypeDefaultDescription
namestringPlugin (menu item) name — required
parent_menustringSubmenu the plugin lives in (e.g. "Reverb")
root_menustring"AudioSuite"Top-level menu to open from
analyzeboolfalseClick Analyze after opening
renderboolfalseClick Render after opening
closeboolfalseClose the plugin window when done
{
    "name": "Reverb Selector",
    "key": "keypad_1",
    "modifiers": ["ctrl"],
    "midi": { "msg": "NoteOn", "note": 83 },
    "apps": ["Protools"],
    "multitap": {
        "items": [
            { "name": "Altiverb 8", "parent_menu": "Reverb" },
            { "name": "ValhallaVintageVerb", "parent_menu": "Reverb" },
            { "name": "ValhallaSupermassive", "parent_menu": "Reverb" }
        ]
    }
}