From 7dfb5a0f35c7d663116bc805203e214b80a943fe Mon Sep 17 00:00:00 2001 From: Mikhail Kot Date: Mon, 11 Aug 2025 00:12:14 +0100 Subject: [PATCH] initial --- MANUAL.md | 404 ++++++++++++++++++++++++++++++++ README.md | 84 ++++--- docs/README.md | 1 - docs/_config.yml | 4 - docs/action_composition.md | 33 --- docs/configuration.md | 20 -- docs/configuration/actions.md | 63 ----- docs/configuration/advanced.md | 113 --------- docs/configuration/behaviour.md | 26 -- docs/configuration/bindings.md | 77 ------ docs/macros.md | 17 -- docs/marks.md | 24 -- docs/modes.md | 73 ------ 13 files changed, 455 insertions(+), 484 deletions(-) create mode 100644 MANUAL.md delete mode 100644 docs/README.md delete mode 100644 docs/_config.yml delete mode 100644 docs/action_composition.md delete mode 100644 docs/configuration.md delete mode 100644 docs/configuration/actions.md delete mode 100644 docs/configuration/advanced.md delete mode 100644 docs/configuration/behaviour.md delete mode 100644 docs/configuration/bindings.md delete mode 100644 docs/macros.md delete mode 100644 docs/marks.md delete mode 100644 docs/modes.md diff --git a/MANUAL.md b/MANUAL.md new file mode 100644 index 00000000..b958c6c0 --- /dev/null +++ b/MANUAL.md @@ -0,0 +1,404 @@ +--- +title: Action Composition +nav_order: 1 +--- + +# Action Composition + +The main feature reaper-keys provides is the ability to compose actions of different types to create new commands. + +How one can compose action types (i.e. the available _action sequences_) and their behaviour when joined is dependant on the [mode](modes) of reaper-keys. + +Take as an example the `timeline motion` type as well as the `timeline operator` type. In normal mode, any `timeline motion` may precede any `timeline operator`. When this action sequence is entered, it will result in the `timeline operator` being called on the timeline section between the cursor position before the motion and after the motion. + +So one could enter sL, to create `(s = "SelectItems", L = "NextMeasure")`, and select the items up to the next measure. + +There are various action types in reaper-keys. + +## Action Types + +| Action Type | Description | +| ------ | ---- | +| `command` | A generic command. Does not compose, accessible from every mode | +| `timeline motion` | Moves the edit cursor somewhere on the timeline | +| `timeline selector` | Sets the timeline selection | +| `timeline operator` | Executes a command that operates on the timeline selection | +| `track motion` | Changes the last touched track | +| `track selector` | Selects a track or multiple tracks | +| `track operator` | Executes a command that operates on a track selection | +| `visual timeline command` | A command only available in visual timeline mode | +| `visual track command` | A command only available in visual track mode | + + +Check out the [modes](modes) documentation to learn about how these types compose together. + + +--- +layout: default +title: Actions +nav_order: 2 +parent: Configuration +--- + +# Actions + +## Relevant Files + + ├── definitions + ├── actions.lua + └── defaults + └── actions.lua + + +## Configuration + +The `actions` file contains reaper-keys action definitions. + +If a reaper-keys action does not exist for a reaper command you want to create a binding for, you may add an entry into this file. You just need to come up with a name for the action and get it's command id (available in reapers action list). + +Here is an example entry that creates the reaper-keys action `SelectFoldersChildren` that contains the command id of the SWS command to select a folders children. + +``` lua +SelectFoldersChildren = "_SWS_SELCHILDREN2", +``` + +Reaper-keys actions may also be a sequence of command id's, reaper-key +action names, provided 'lib' functions, provided 'custom' functions, or any combination of them. + +Here is a variety of action definitions that demonstrate this functionality. + +``` lua +SelectOnlyCurrentTrack = custom.select.onlyCurrentTrack, +UnselectItems = 40289, +UnselectEnvelopePoints = 40331, +UnselectAllEvents = {40214, midiCommand=true}, +ResetSelection = {"SelectOnlyCurrentTrack", "UnselectItems", "UnselectEnvelopePoints", "UnselectAllEvents"}, +Stop = 40667, +SetModeNormal = lib.setModeNormal, +SetRecordModeNormal = 40252, +Reset = {"Stop", "SetModeNormal", "SetRecordModeNormal", "ResetSelection"}, +``` + + +## Action Options +You may have noticed that this action had an option set: +``` lua +UnselectAllEvents = {40214, midiCommand=true}, +``` + +There are various other options one can use as well. + +| Option | Use | +| ------ | --- | +| repetitions | Specifies the number of times to run the action | +| prefixRepetitionCount | Indicates a number may prefix the actions key binding which will indicate repetitions. | +| setTimeSelection | Used with timeline operator actions to indicate it to keep the time selection it operated on, not restore the previous. | +| setTrackSelection | Used with track operator actions to indicate it to keep the track selection it operated on, not restore the previous. | +| midiCommand | Indicates that the action id is from Reaper's 'MidiEditor' section | + + +--- +layout: default +title: Advanced Configuration +nav_order: 4 +parent: Configuration +--- + +# Advanced Configuration +{: .no_toc} + +1. TOC +{:toc} + + +## Action Sequences and Modes + +### Relevant Files + + internal + ├── command + │   ├── action_sequence_functions + │   │   ├── global.lua + │   │   ├── main.lua + │   │   └── midi.lua + + +### Configuration + +If you are interested in changing or creating modes, action types, or action action sequences, take a look at `action_sequence_functions` directory. + +There you will find all the functions that execute composed actions (excluding +meta actions). There is a file for each context, and a section for each mode. + +Here is an example entry that defines the sequence `'timeline_operator' +timeline_motion'`, with the accompanying 'glue' function that composes the actions. + +``` lua +-- in global.lua +normal = { + { + { 'timeline_operator', 'timeline_selector' }, + function(timeline_operator, timeline_selector) + local start_sel, end_sel = reaper.GetSet_LoopTimeRange(false, false, 0, 0, false) + runner.runAction(timeline_selector) + runner.runAction(timeline_operator) + + -- check if we were passed a table so we don't break when checking an option + if type(timeline_operator) ~= 'table' or not timeline_operator['setTimeSelection'] then + reaper.GetSet_LoopTimeRange(true, false, start_sel, end_sel, false) + end + end + }, + -- ... more action sequence functions +``` + +When a key binding sequence triggers the action, it will be passed the values of +the actions used to trigger it. + +So in this case, if one types `tl` + +Reaper keys will find the entries "PlayAndLoop" and "NextBeat" in it's search in the definitions. + +``` lua +-- in definitions/global.lua the + timeline_operator = { + ["t"] = "Play", + }, + timeline_motion = { + ["l"] = "NextBeat", + }, +``` + +And find the value of the action in actions.lua + +``` lua +-- in definitions/actions.lua +PlayAndLoop = {"SetLoopSelectionToTimeSelection", "LoopStart", "Play", setTimeSelection=true}, +NextBeat = 40841, +``` + +and execute the function with + +``` lua +function({"SetLoopSelectionToTimeSelection", "LoopStart", "Play", setTimeSelection=true}, 40841) +``` + +Reaper keys prioritizes entries in order of context, then index in the list. + +It is enough to define an entry like the above, with a new action type or key +type sequence, to create a new action type. + +To create a new mode, add an entry at the level of 'normal' in the example. Then +populate it with entries alike the above. + + +## Custom Actions + +### Relevant Files + + internal + ├── custom_actions + │   ├── custom_actions.lua + │   ├── movement.lua + │   ├── selection.lua + │   └── utils.lua + +### Configuration + +To create a custom action, follow the examples in the `custom_actions` directory. This directory contains all the actions available via the `custom` import in the `actions` file. + +`reaper` is a global which provides access to the [reaper api](https://www.reaper.fm/sdk/reascript/reascripthelp.html#l) + + + + +--- +layout: default +title: Reaper-Keys Behaviour +nav_order: 3 +parent: Configuration +--- + +# Reaper-Keys Behaviour + +## Relevant Files + + ├── definitions + └── config.lua + + +## Configuration + +The `config` file has a table of options that tweaks reaper-keys behaviour. + +| Option | Values | Use | +| --- | --- | --- | +| `log_level` | [trace debug info warn user error fatal] | sets log verbosity | +| `persist_visual_timeline_selection` | [true false] | controls if timeline operators in visual timeline mode reset the timeline selection | +| `persist_visual_track_selection` | [true false] | controls if track operators in visual track mode reset the track selection | +| `allow_visual_track_timeline_movement` | [true false] | controls if timeline movement in `visual track` mode is allowed | +| `repeatable_commands_action_type_match` | table of action type match strings | controls which commands are considered repeatable by specifying the action type it should contain in its action sequence | + + +--- +layout: default +title: Bindings +nav_order: 1 +parent: Configuration +--- + +# Bindings + +## Relevant Files + + + ├── definitions + ├── bindings.lua + └── defaults + ├── global.lua + ├── main.lua + └── midi.lua + + + +## Configuration + +```lua +-- add a binding by specifying a key sequence and an action name + +-- remove a binding by specifying an action with no name +[""] = "", + +-- overwrite an entire folder by changing the name +[""] = { "+new folder name", { + [""] = "ShowBindingList" +}}, + +-- overwrite or add a binding in a folder by keeping the name the same +[""] = { "+leader commannds", { + [""] = "ShowBindingList" + ["b"] = "", +}}, +``` + +The `global`, `main`, and `midi` files contain default binding definitions (i.e. 'key sequence -> action' mappings) + + +You may define or change key sequences for a specific context (in `main` or `midi`) or for all contexts (in `global`). + +The entries in these files are organized by `action type`. + +Here is an example snippet that declares some bindings in the `timeline operator` +action type section. + +```lua +timeline_operator = { + ["r"] = "Record", + ["t"] = "PlayAndLoop", + }, +``` + +Actions may also be put into folders. To create a folder, follow this format: + +``` lua +command = { + [""] = { "+leader commands", { + [""] = "ShowBindingList", + ["b"] = "ShowBindingList", + ["m"] = { "+midi", { + ["x"] = "CloseWindow", + ["g"] = "SetMidiGridDivision", + ["q"] = "Quantize", + [","] = {"+options", { + ["g"] = "ToggleMidiEditorUsesMainGridDivision", + ["s"] = "ToggleMidiSnap", + + }}, + }}, +} +``` + + +--- +title: Configuration +nav_order: 5 +has_toc: true +has_children: true +--- + +# Configuration +For most configuration needs, check out the `definitions` directory. + + ├── definitions + ├── actions.lua + ├── config.lua + ├── global.lua + ├── main.lua + └── midi.lua + +These files contain lua tables that may be altered to change or add key bindings, actions, or tweak reaper-keys behaviour. + +Read on to learn how to configure a particular aspect of reaper-keys. + + +Reaper-keys has multiple modes. Depending on the mode one is in, the available action sequences may change. The behaviour of action sequences may change as well. + +The action sequence(s) available for all modes are: + +| Action Sequence | Behaviour | +| --- | --- | +| `command` | Just executes the action | + +## Normal Mode + +Return to normal mode via ESC by default. + +### Available Action Sequences + +| Action Sequence | Behaviour | +| ---| ---| +| `timeline motion`| Moves edit cursor to the motion end | +| `track motion` | Changes last touched track to the motion end | +| `timeline operator`->`timeline selector` | Executes the operator on the selection specified by the selector | +| `timeline operator`->`timeline motion` | Executes the operator on the region between the start and end points of the motion | +| `track operator`->`track motion` | Executes the operator on the tracks between the start and end points of the motion | +| `track operator`->`track selector` | Executes the operator on the selection specified by the selector | + + +## Visual Timeline Mode + +Enter this mode by via v by default. + +In this mode, `timeline motion` and `timeline selection` action types extend or set the current timeline selection. + +Also the `timeline operator` type does not require a `timeline motion` or `timeline selector` to come before, as in normal mode, and instead operates immediately +on the current timeline selection and then exits visual timeline mode. + +It also allows for the execution of `visual track command` types. + +### Available Action Sequences + + +| Action Sequence | Behaviour | +| --- | --- | +| `timeline selector` | Sets the timeline selection | +| `timeline motion` | Extends the timeline selection to the new edit cursor position | +| `timeline operator` | Executes the operator and exits to normal mode. | +| `visual timeline command` | Executes a visual timeline command. | + + +## Visual Track Mode + +Enter this mode by via V by default. + +This mode is the same in principle as `visual timeline` mode, just with track motions/selections and track operators instead. + +### Available Action Sequences + +| Action Sequence | Behaviour | +| --- | --- | +| `track selector` | Sets the track selection | +| `track motion` | Extends the track selection up to the new track position after the motion | +| `track operator` | Executes the operator and exits to normal mode. | +| `visual track command` | Executes a visual track command. | + diff --git a/README.md b/README.md index 0c9b2207..70b08c76 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,15 @@ -# Reaper keys +# reaper-keys

reaper-keys

-Reaper keys is an extension for the [REAPER DAW](https://www.reaper.fm/) that provides a -new action mapping system based on key sequences instead of key chords. The system is -similar to [Vim](https://en.wikipedia.org/wiki/Vim_%28text_editor%29), a modal text -editor, and by default comes with vim-like bindings. +Reaper keys is an extension for the [Reaper DAW](https://www.reaper.fm/) that +provides a new action mapping system based on key sequences instead of key +chords. The system is similar to +[vim](https://en.wikipedia.org/wiki/Vim_%28text_editor%29), a modal text editor, +and by default comes with vim-like bindings. -Click [here](https://youtu.be/ChuZswEfQuo) for a very outdated and low quality demo for v1 or jump -to [examples](#some-ideas-to-start-with). +Click [here](https://youtu.be/ChuZswEfQuo) for a very outdated and low quality +demo for v1 or jump to [examples](#some-ideas-to-start-with). ## Pros @@ -20,19 +21,20 @@ to [examples](#some-ideas-to-start-with). ## Installation -- Add `https://raw.githubusercontent.com/gwatcha/reaper-keys/master/index.xml` to Reapack. - Install [SWS](https://sws-extension.org/) by hand or from ReaTeam Extensions. +- Add `https://raw.githubusercontent.com/gwatcha/reaper-keys/master/index.xml` + to Reapack. ## Features ### Bind key sequences -With Reaper keys you may bind key sequences to actions rather then singular key presses. -This allows one to hierarchically organize many keybindings. -A completion/feedback window is provided to assist with command completion. +With Reaper keys you may bind key sequences to actions rather than singular key +presses. This allows one to hierarchically organize many keybindings. A +completion/feedback window is provided to assist with command completion. completions -### Compose actions +### Actions composition Reaper keys lets one compose actions of different types to create new commands. For example, in normal mode, any action with `timeline motion` type can follow any one with @@ -48,7 +50,7 @@ This grows the number of available actions exponentially but still preserves you as you only need to know the `timeline_motions`, `timeline_operators`, and the fact that you can compose them. -### Multi-modal +### Multiple key modes Changing modes changes the way keys compose. By default, it is in `normal` mode, but you could for example go into `visual timeline` mode by pressing `v`. @@ -62,20 +64,38 @@ commands. ### Macros -Macros are a way to save a sequence of commands, and play them back later. - -To record a macro, enter `q` and an arbitrary character to specify the `register` that the -macro will save into. Then, perform a series of actions, and finish recording by pressing -`q`. +Macros are a way to save a sequence of commands and play them back later. To +record a macro, enter `q` and an arbitrary character to specify the `register` +that the macro will save into. Then, perform a series of actions, and finish +recording by pressing `q`. macro-rec -You may play it back by entering `@` and the character you specified earlier. Optionally, -prefix it with a number to indicate the number of repetitions. +You may play it back by entering `@` and the character you specified earlier. +Optionally, prefix it with a number to indicate the number of repetitions. macro-play +### Marks + +Press `m` in any mode and then enterer a `register` key and reaper-keys will +will store a mark which will save the current track selection, time selection, +and edit cursor position. + +- In visual mode, the mark creates a visible region. +- In normal mode, the mark creates a visible marker. +- In visual track mode, the mark does not create anything apart from the mark. + +There are four key bindings that make use of stored marks: + +| Key | Action Name | Action Type | Function | +|-------| ------------------------| -----------------| ---------------------------| +| ` | `MarkedTimelinePosition`| timeline motion | Recall edit cursor position| +| ' | `MarkedTracks` | track selector | Recall selected tracks | +| ~ | `MarkedRegion` | timeline selector| Recall timeline selection | +| | `DeleteMark` | command | Delete a stored mark | + ## Some ideas to start with ``` @@ -143,7 +163,7 @@ internal/definitions/bindings.lua -> add or customise key bindings internal/definitions/config.lua -> change GUI settings ``` -## Contributing +## Development ### Running tests For running tests locally you'd need some Linux distribution with X11 and `xdotool`. @@ -164,24 +184,22 @@ emulated with Xvfb. ### Writing tests -Each test is just a sequence of keys you press to achieve some result. One notable exception is -a hotkey or a special key like "Return" (Enter) or "Backspace". In that case, prefix line with -`&` and enter the key combination after, like `&Return`. +Each test is just a sequence of keys you press to achieve some result. One +notable exception is a hotkey or a special key like "Return" (Enter) or +"Backspace". In that case, prefix line with `&` and enter the key combination +after, like `&Return`. -Project files documentation: https://github.com/ReaTeam/Doc/blob/master/State%20Chunk%20Definitions +Project files documentation: +https://github.com/ReaTeam/Doc/blob/master/State%20Chunk%20Definitions ### Reporting performance issues -1. Download "Lua profiler" from ReaTeam Scripts and "ReaImGui" from ReaTeam Extensions via -ReaPack. +1. Download "Lua profiler" from ReaTeam Scripts and "ReaImGui" from ReaTeam + Extensions via ReaPack. 2. Change "profile" to "true" in internal/definitions/config.lua -3. In Reaper, click Actions > Running script > rk.lua > Terminate instances. There may be -no "Running script", then just skip this step. +3. In Reaper, click Actions > Running script > rk.lua > Terminate instances. + There may be no "Running script", then just skip this step. 4. Press any key. A profiler window will open. 5. Click "Acquisition > Stop" in the profiler window after you're done 6. Click "Copy to clipboard". Paste in a GitHub issue. 7. When you're done, change "profile" back to false and repeat (3) - -## Further Information - -Check out the [documentation](https://gwatcha.github.io/reaper-keys) to learn more. diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 962eb6dc..00000000 --- a/docs/README.md +++ /dev/null @@ -1 +0,0 @@ -Welcome to the documentation for reaper-keys, a plugin for Reaper that improves the key binding system. diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index d64a3bc3..00000000 --- a/docs/_config.yml +++ /dev/null @@ -1,4 +0,0 @@ -title: "Reaper Keys" -remote_theme: pmarsceill/just-the-docs -color_scheme: "light" -search_enabled: true diff --git a/docs/action_composition.md b/docs/action_composition.md deleted file mode 100644 index 7b9831c8..00000000 --- a/docs/action_composition.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Action Composition -nav_order: 1 ---- - -# Action Composition - -The main feature reaper-keys provides is the ability to compose actions of different types to create new commands. - -How one can compose action types (i.e. the available _action sequences_) and their behaviour when joined is dependant on the [mode](modes) of reaper-keys. - -Take as an example the `timeline motion` type as well as the `timeline operator` type. In normal mode, any `timeline motion` may precede any `timeline operator`. When this action sequence is entered, it will result in the `timeline operator` being called on the timeline section between the cursor position before the motion and after the motion. - -So one could enter sL, to create `(s = "SelectItems", L = "NextMeasure")`, and select the items up to the next measure. - -There are various action types in reaper-keys. - -## Action Types - -| Action Type | Description | -| ------ | ---- | -| `command` | A generic command. Does not compose, accessible from every mode | -| `timeline motion` | Moves the edit cursor somewhere on the timeline | -| `timeline selector` | Sets the timeline selection | -| `timeline operator` | Executes a command that operates on the timeline selection | -| `track motion` | Changes the last touched track | -| `track selector` | Selects a track or multiple tracks | -| `track operator` | Executes a command that operates on a track selection | -| `visual timeline command` | A command only available in visual timeline mode | -| `visual track command` | A command only available in visual track mode | - - -Check out the [modes](modes) documentation to learn about how these types compose together. diff --git a/docs/configuration.md b/docs/configuration.md deleted file mode 100644 index c8fcdaeb..00000000 --- a/docs/configuration.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Configuration -nav_order: 5 -has_toc: true -has_children: true ---- - -# Configuration -For most configuration needs, check out the `definitions` directory. - - ├── definitions - ├── actions.lua - ├── config.lua - ├── global.lua - ├── main.lua - └── midi.lua - -These files contain lua tables that may be altered to change or add key bindings, actions, or tweak reaper-keys behaviour. - -Read on to learn how to configure a particular aspect of reaper-keys. diff --git a/docs/configuration/actions.md b/docs/configuration/actions.md deleted file mode 100644 index 677cd756..00000000 --- a/docs/configuration/actions.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -layout: default -title: Actions -nav_order: 2 -parent: Configuration ---- - -# Actions - -## Relevant Files - - ├── definitions - ├── actions.lua - └── defaults - └── actions.lua - - -## Configuration - -The `actions` file contains reaper-keys action definitions. - -If a reaper-keys action does not exist for a reaper command you want to create a binding for, you may add an entry into this file. You just need to come up with a name for the action and get it's command id (available in reapers action list). - -Here is an example entry that creates the reaper-keys action `SelectFoldersChildren` that contains the command id of the SWS command to select a folders children. - -``` lua -SelectFoldersChildren = "_SWS_SELCHILDREN2", -``` - -Reaper-keys actions may also be a sequence of command id's, reaper-key -action names, provided 'lib' functions, provided 'custom' functions, or any combination of them. - -Here is a variety of action definitions that demonstrate this functionality. - -``` lua -SelectOnlyCurrentTrack = custom.select.onlyCurrentTrack, -UnselectItems = 40289, -UnselectEnvelopePoints = 40331, -UnselectAllEvents = {40214, midiCommand=true}, -ResetSelection = {"SelectOnlyCurrentTrack", "UnselectItems", "UnselectEnvelopePoints", "UnselectAllEvents"}, -Stop = 40667, -SetModeNormal = lib.setModeNormal, -SetRecordModeNormal = 40252, -Reset = {"Stop", "SetModeNormal", "SetRecordModeNormal", "ResetSelection"}, -``` - - -## Action Options -You may have noticed that this action had an option set: -``` lua -UnselectAllEvents = {40214, midiCommand=true}, -``` - -There are various other options one can use as well. - -| Option | Use | -| ------ | --- | -| repetitions | Specifies the number of times to run the action | -| prefixRepetitionCount | Indicates a number may prefix the actions key binding which will indicate repetitions. | -| setTimeSelection | Used with timeline operator actions to indicate it to keep the time selection it operated on, not restore the previous. | -| setTrackSelection | Used with track operator actions to indicate it to keep the track selection it operated on, not restore the previous. | -| midiCommand | Indicates that the action id is from Reaper's 'MidiEditor' section | - diff --git a/docs/configuration/advanced.md b/docs/configuration/advanced.md deleted file mode 100644 index 72152025..00000000 --- a/docs/configuration/advanced.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -layout: default -title: Advanced Configuration -nav_order: 4 -parent: Configuration ---- - -# Advanced Configuration -{: .no_toc} - -1. TOC -{:toc} - - -## Action Sequences and Modes - -### Relevant Files - - internal - ├── command - │   ├── action_sequence_functions - │   │   ├── global.lua - │   │   ├── main.lua - │   │   └── midi.lua - - -### Configuration - -If you are interested in changing or creating modes, action types, or action action sequences, take a look at `action_sequence_functions` directory. - -There you will find all the functions that execute composed actions (excluding -meta actions). There is a file for each context, and a section for each mode. - -Here is an example entry that defines the sequence `'timeline_operator' -timeline_motion'`, with the accompanying 'glue' function that composes the actions. - -``` lua --- in global.lua -normal = { - { - { 'timeline_operator', 'timeline_selector' }, - function(timeline_operator, timeline_selector) - local start_sel, end_sel = reaper.GetSet_LoopTimeRange(false, false, 0, 0, false) - runner.runAction(timeline_selector) - runner.runAction(timeline_operator) - - -- check if we were passed a table so we don't break when checking an option - if type(timeline_operator) ~= 'table' or not timeline_operator['setTimeSelection'] then - reaper.GetSet_LoopTimeRange(true, false, start_sel, end_sel, false) - end - end - }, - -- ... more action sequence functions -``` - -When a key binding sequence triggers the action, it will be passed the values of -the actions used to trigger it. - -So in this case, if one types `tl` - -Reaper keys will find the entries "PlayAndLoop" and "NextBeat" in it's search in the definitions. - -``` lua --- in definitions/global.lua the - timeline_operator = { - ["t"] = "Play", - }, - timeline_motion = { - ["l"] = "NextBeat", - }, -``` - -And find the value of the action in actions.lua - -``` lua --- in definitions/actions.lua -PlayAndLoop = {"SetLoopSelectionToTimeSelection", "LoopStart", "Play", setTimeSelection=true}, -NextBeat = 40841, -``` - -and execute the function with - -``` lua -function({"SetLoopSelectionToTimeSelection", "LoopStart", "Play", setTimeSelection=true}, 40841) -``` - -Reaper keys prioritizes entries in order of context, then index in the list. - -It is enough to define an entry like the above, with a new action type or key -type sequence, to create a new action type. - -To create a new mode, add an entry at the level of 'normal' in the example. Then -populate it with entries alike the above. - - -## Custom Actions - -### Relevant Files - - internal - ├── custom_actions - │   ├── custom_actions.lua - │   ├── movement.lua - │   ├── selection.lua - │   └── utils.lua - -### Configuration - -To create a custom action, follow the examples in the `custom_actions` directory. This directory contains all the actions available via the `custom` import in the `actions` file. - -`reaper` is a global which provides access to the [reaper api](https://www.reaper.fm/sdk/reascript/reascripthelp.html#l) - - diff --git a/docs/configuration/behaviour.md b/docs/configuration/behaviour.md deleted file mode 100644 index 49b8ba7b..00000000 --- a/docs/configuration/behaviour.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -layout: default -title: Reaper-Keys Behaviour -nav_order: 3 -parent: Configuration ---- - -# Reaper-Keys Behaviour - -## Relevant Files - - ├── definitions - └── config.lua - - -## Configuration - -The `config` file has a table of options that tweaks reaper-keys behaviour. - -| Option | Values | Use | -| --- | --- | --- | -| `log_level` | [trace debug info warn user error fatal] | sets log verbosity | -| `persist_visual_timeline_selection` | [true false] | controls if timeline operators in visual timeline mode reset the timeline selection | -| `persist_visual_track_selection` | [true false] | controls if track operators in visual track mode reset the track selection | -| `allow_visual_track_timeline_movement` | [true false] | controls if timeline movement in `visual track` mode is allowed | -| `repeatable_commands_action_type_match` | table of action type match strings | controls which commands are considered repeatable by specifying the action type it should contain in its action sequence | diff --git a/docs/configuration/bindings.md b/docs/configuration/bindings.md deleted file mode 100644 index 99d9c6b3..00000000 --- a/docs/configuration/bindings.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -layout: default -title: Bindings -nav_order: 1 -parent: Configuration ---- - -# Bindings - -## Relevant Files - - - ├── definitions - ├── bindings.lua - └── defaults - ├── global.lua - ├── main.lua - └── midi.lua - - - -## Configuration - -```lua --- add a binding by specifying a key sequence and an action name - --- remove a binding by specifying an action with no name -[""] = "", - --- overwrite an entire folder by changing the name -[""] = { "+new folder name", { - [""] = "ShowBindingList" -}}, - --- overwrite or add a binding in a folder by keeping the name the same -[""] = { "+leader commannds", { - [""] = "ShowBindingList" - ["b"] = "", -}}, -``` - -The `global`, `main`, and `midi` files contain default binding definitions (i.e. 'key sequence -> action' mappings) - - -You may define or change key sequences for a specific context (in `main` or `midi`) or for all contexts (in `global`). - -The entries in these files are organized by `action type`. - -Here is an example snippet that declares some bindings in the `timeline operator` -action type section. - -```lua -timeline_operator = { - ["r"] = "Record", - ["t"] = "PlayAndLoop", - }, -``` - -Actions may also be put into folders. To create a folder, follow this format: - -``` lua -command = { - [""] = { "+leader commands", { - [""] = "ShowBindingList", - ["b"] = "ShowBindingList", - ["m"] = { "+midi", { - ["x"] = "CloseWindow", - ["g"] = "SetMidiGridDivision", - ["q"] = "Quantize", - [","] = {"+options", { - ["g"] = "ToggleMidiEditorUsesMainGridDivision", - ["s"] = "ToggleMidiSnap", - - }}, - }}, -} -``` diff --git a/docs/macros.md b/docs/macros.md deleted file mode 100644 index 8d392c4d..00000000 --- a/docs/macros.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Macros -nav_order: 3 ---- - -# Macros - -A macro is a sequence of actions one may record and execute later. - -Start recording a macro with q and pressing an arbitrary key to indicate the 'register' the macro will be stored into. - -Once some actions have been recorded, finish recording by pressing q - -Play back the macro later by pressing @ and the register the macro was stored into. - -You may also prefix @ with a number to indicate the number of repetitions. - diff --git a/docs/marks.md b/docs/marks.md deleted file mode 100644 index 2d8cb099..00000000 --- a/docs/marks.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Marks -nav_order: 4 ---- - -# Marks - -In any mode, the m key followed by a register key will store a mark which will save the current track selection, time selection, and edit cursor position. - -If you are in visual mode, the mark also creates a visible region. -If you are in normal mode, the mark also creates a visible marker. -If you are in visual track mode, the mark does not create anything apart from the mark. - -There are four actions that make use of stored marks. - - -| Key | Action Name | Action Type | Function | -| -------------- | ---------------------- | ------------------- | ---------------------------- | -| {% raw %}`{% endraw %} | `MarkedTimelinePosition` | `timeline motion` | Recalls edit cursor position | -| ' | `MarkedTracks` | `track selector` | Recalls selected tracks | -| ~ | `MarkedRegion` | `timeline selector` | Recalls timeline selection | -| | `DeleteMark` | `command` | Deletes a stored mark | - -These actions compose just like any other actions of their type. diff --git a/docs/modes.md b/docs/modes.md deleted file mode 100644 index 1f217360..00000000 --- a/docs/modes.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Modes -nav_order: 2 ---- - -# Modes -{: .no_toc} - -#### Table of Contents -{: .no_toc} -1. TOC -{:toc} - -Reaper-keys has multiple modes. Depending on the mode one is in, the available action sequences may change. The behaviour of action sequences may change as well. - -The action sequence(s) available for all modes are: - -| Action Sequence | Behaviour | -| --- | --- | -| `command` | Just executes the action | - -## Normal Mode - -Return to normal mode via ESC by default. - -### Available Action Sequences - -| Action Sequence | Behaviour | -| ---| ---| -| `timeline motion`| Moves edit cursor to the motion end | -| `track motion` | Changes last touched track to the motion end | -| `timeline operator`->`timeline selector` | Executes the operator on the selection specified by the selector | -| `timeline operator`->`timeline motion` | Executes the operator on the region between the start and end points of the motion | -| `track operator`->`track motion` | Executes the operator on the tracks between the start and end points of the motion | -| `track operator`->`track selector` | Executes the operator on the selection specified by the selector | - - -## Visual Timeline Mode - -Enter this mode by via v by default. - -In this mode, `timeline motion` and `timeline selection` action types extend or set the current timeline selection. - -Also the `timeline operator` type does not require a `timeline motion` or `timeline selector` to come before, as in normal mode, and instead operates immediately -on the current timeline selection and then exits visual timeline mode. - -It also allows for the execution of `visual track command` types. - -### Available Action Sequences - - -| Action Sequence | Behaviour | -| --- | --- | -| `timeline selector` | Sets the timeline selection | -| `timeline motion` | Extends the timeline selection to the new edit cursor position | -| `timeline operator` | Executes the operator and exits to normal mode. | -| `visual timeline command` | Executes a visual timeline command. | - - -## Visual Track Mode - -Enter this mode by via V by default. - -This mode is the same in principle as `visual timeline` mode, just with track motions/selections and track operators instead. - -### Available Action Sequences - -| Action Sequence | Behaviour | -| --- | --- | -| `track selector` | Sets the track selection | -| `track motion` | Extends the track selection up to the new track position after the motion | -| `track operator` | Executes the operator and exits to normal mode. | -| `visual track command` | Executes a visual track command. |