With this Visual Studio Code extension, you can record and playback your keyboard inputs.
Ctrl+Alt+R : Start/Stop Recording
Ctrl+Alt+P : Playback
IMPORTANT NOTE
- If you are using a keymap extension or any other kind of extension that has keyboard shortcuts or you have custom keybindings in your
keybindings.json
, you will need some additional work to enable them to be recorded. See the sections below.
YOU CAN RECORD (basically):
- Characters that you type in a text editor
- including ones via code completion or IME as well.
- Editor keyboard shortcuts in VS Code default keybindings
- such as cursor movement, selection, scroll, delete, cut/copy/paste, search/replace, undo/redo, indent, comment, and so on.
YOU CANNOT RECORD (mainly due to the lack of capabilities of VS Code API to capture them):
- Mouse inputs
- Command execution via Command Palette
- Menu navigation (even if you use accelerator keys)
- Widget/Popup UI navigation (e.g. Quick Picks, Find and replace widget, IntelliSense popup)
- Typing on the find/replace input box is not recorded, but shortcut keys like Enter/F3 (Find Next) hit on the widget are recorded.
- Selecting items in the suggest widget (even with arrow keys) are not recorded, however, once you accept one of the items and the text is inserted into the document, that is recorded as if you typed it directly.
- IME navigation
- IME navigation is not recorded directly, however, the characters that are inserted into the document as output from IME are recorded as if they are typed directly.
If you found your favorite keyboard shortcuts are not supported to be recorded, you could make them recordable by adding corresponding wrappers to your keybindings.json
.
If you have a keyboard shortcut like:
{
"key": "ctrl+shift+a",
"command": "editor.action.selectToBracket",
"when": "editorTextFocus"
}
the corresponding wrapper should look like below.
{
"key": "ctrl+shift+a",
"command": "kb-macro.wrap",
"args": {
"command": "editor.action.selectToBracket"
},
"when": "kb-macro.active && editorTextFocus"
}
Add this keybinding rule below the original one in the keybindings.json
.
The following are the details:
- The
kb-macro.wrap
command is the wrapper that executes the target command specified in theargs.command
parameter and records it on the sequence. - The
when
clause of a wrapper keybinding should contain additional contextkb-macro.active
, which evaluates totrue
when the recording mechanism is active. - If you have an
args
parameter for the target command, you could write it inargs.args
. - If the target command is not a built-in command of VS Code, in other words, it is provided by an extension, likely you may need to add an
args.await
parameter in the wrapper. See below.
See Keymap Wrappers.
When this extension performs playback of a recorded command sequence, the commands should be executed one by one exactly. Specifically, each command in the sequence should end its execution and all the side effects of the command such as document change should be completed before the subsequent command is invoked. Otherwise, it may cause an unexpected result.
The mechanism of this extension to playback recorded command sequence relies on a VS Code API vscode.commands.executeCommand
. Unfortunately, this API doesn't seem to provide a Promise that resolves when the target command ends its execution. Especially, if the target command is provided by an extension, the API seems to ensure only the start of the command execution. And I found the same thing happens with some built-in commands.
So, we don't have a proper way to execute commands one by one, without any knowledge of target commands.
We need to know the true timing of the end of command execution, especially for commands with side effects. The args.await
parameter is the way to tell this extension the set of possible side effects of a target command.
{
"key": "ctrl+alt+z",
"command": "kb-macro.wrap",
"args": {
"command": "some.extension.command",
"await": "document selection"
},
"when": "kb-macro.active && editorTextFocus"
}
The value of an args.await
parameter is a space-separated keyword list. Possible keywords are shown below.
Keyword | Event to wait for to happen |
---|---|
'document' |
Changes in the text document of the active editor |
'selection' |
Changes of the selection (typically, cursor movement) in the active editor |
'clipboard' |
Changes of the clipboard text |
If multiple keywords are specified in an args.await
parameter, it means all of them are expected to happen.
If a target command does not always reproduce the specified side effects, it is okay since the playback mechanism has a timeout, which is 300 milliseconds.
This is the default keybinding set for recording/playback of this extension. Copy and paste this into your keybindings.json
and modify it as you like.
{
"key": "ctrl+alt+r",
"command": "kb-macro.startRecording",
"when": "!kb-macro.recording"
},
{
"key": "ctrl+alt+r",
"command": "kb-macro.finishRecording",
"when": "kb-macro.recording"
},
{
"key": "ctrl+alt+p",
"command": "kb-macro.playback",
"when": "!kb-macro.recording"
},
{
"key": "ctrl+alt+p",
"command": "kb-macro.cancelRecording",
"when": "kb-macro.recording"
},
{
"key": "escape",
"command": "kb-macro.abortPlayback",
"when": "kb-macro.playing"
}
After you have successfully recorded a sequence, you may also save it for future use in another VS Code session.
- Open the Command Palette by
ctrl+shift+p
(cmd+shift+p
for Mac). - Search for the command
Keyboard Macro: Copy Macro as Keybinding
and execute it. It copies the sequence in keybinding JSON format to the clipboard. - Open your
keybindings.json
(Keyboard Shortcuts JSON). - Paste the JSON at the appropriate location (typically the last in the file).
- Fill the
key
property which is left blank with a new keystroke (e.g."key": "ctrl+alt+z"
).
Task | Recordable ways to do it |
---|---|
Move focus to editor | Instead of mouse, use ctrl+1 (cmd+1 for Mac) |
Switch editor tabs | Instead of ctrl+tab , use ctrl+pageup /ctrl+pagedown (alt+cmd+left /alt+cmd+right for Mac) |
Command name | Command ID | Function |
---|---|---|
Start Recording |
kb-macro.startRecording |
Start recording |
Finish Recording |
kb-macro.finishRecording |
Stop recording |
Cancel Recording |
kb-macro.cancelRecording |
Stop recording and discard the recorded sequence |
Copy Macro as Keybinding |
kb-macro.copyMacroAsKeybinding |
Copy the last recorded macro as keybinding JSON format to the clipboard |
Command name | Command ID | Function |
---|---|---|
Playback |
kb-macro.playback |
Perform playback of the last recorded sequence |
Abort Playback |
kb-macro.abortPlayback |
Abort currently-running playback |
Repeat Playback |
kb-macro.repeatPlayback |
Perform playback specified number of times |
Repeat Playback Till End of File |
kb-macro.repeatPlaybackTillEndOfFile |
Repeat playback until the cursor reaches the end of the file |
The kb-macro.repeatPlayback
command shows an input box to specify the number of times.
The kb-macro.playback
command has an optional repeat
argument to specify the number of times to repeat.
{
// Example: Repeat playback 5 times.
"key": "ctrl+alt+5",
"command": "kb-macro.playback",
"args": {
"repeat": 5
}
}
The kb-macro.playback
command has an optional sequence
argument to specify a command sequence to playback instead of the last recorded sequence.
{
// Example: Duplicate current line as a comment
"key": "ctrl+alt+up",
"command": "kb-macro.playback",
"args": {
"sequence": [
{ "command": "editor.action.addCommentLine" },
{ "command": "editor.action.copyLinesUpAction" },
{ "command": "editor.action.removeCommentLine" }
]
}
}
when clause context |
True when |
---|---|
kb-macro.recording |
The macro recording is ongoing |
kb-macro.playing |
The macro playback is ongoing |
kb-macro.active |
The recording mechanism is active. If true, all wrapper keybindings should be enabled. |
- As this extension will take a few days to catch up with each release of VS Code, keyboard shortcuts that are newly introduced or modified in the release may not work properly with this extension during that time.
- This extension is designed to work with VS Code on Windows, Linux, and macOS, but is tested mainly on Windows.
See DESIGN.md.
See CHANGELOG.md.