The-Great-Assyr / rackcli

CLI for VCV Rack for managing your local rack installation and installed plugins

rackcli

Commandline-interface (CLI) for VCV Rack to help with managing your local rack installation, installed plugins, and patches. Additionally, it provides a complementary incubation venue for prototyping/implementing features/capabilities experimentally in consideration in the official VCV Rack environment under an alternative development model.

Check out the lab, the project incubator, and src for more mature code bits.

rackcli CLI "features" cater towards making your life easier for managing your rack installation as well as providing lots of "magic" to make your patching/wiggling/performance workflow smoother and faster than ever! Core to these features is the concept of centralized metadata for all the installed plugins and their modules which I refer to as the "catalog" -- it's actually a simple JSON file named catalog.json residing in the Rack directory. The care and feeding of the catalog depends on one of several mechanisms 1) my fork of VCV Rack, 2) my plugin module DLwigglz r4xH4x, or 3) r4xH4x CLI non-GUI partial catalog generator. The first two options leverage a running Rack instance and optional plugin. Reference/example versions of the catalog files are included in the fork directory. The additional advantage of the "fork" is that it provides several other cool workflow enhancements beyond module geometries -- check it out for details!

If you go with my Rack fork, and click the new Catalog toolbar button, a full catalog.json file will be generated. It's possible given the range of "official" and experimental plugin modules available out there, that or more modules may "misbehave" and crash Rack. If this happens, don't panic. Just look at the log.txt log file or your OS-specific crash dump facilities to identify the offending module and add it to a fresh patch along with DLwigglz r4xH4x and click the patch button. The r4xH4x module will generate a patch.json file with the important metadata for the offending patch(s). You can then run p2f from the fork directory to capture this in the faults.json file which will keep File.Catalog from tripping over the faulty modules. It's good practice to report a bug on the plugin module's developer Github site (look that up using the official VCV Rack Plugin Manager page).

Partial "catalogs" can be generated using either DLwigglz r4xH4x or the r4xH4x CLI. These differ from the full catalog generated by my fork in their inability to capture module height and width data. This may or may not be important to you. Also, the DLwigglz r4xH4x patch feature does capture module geometry, but only for modules in the current patch.

Building the r4xH4x CLI is straightforward assuming you've already cloned the rackcli project:

1. clone and build latest VCV Rack per instructions
2. export RACK_DIR="BUILD_DIR_FROM_STEP_1"
3. cd WHEREVER/rackcli/src/cpp
4. make
5. deploy built r4xh4x somewhere in your path
6. run via: r4xH4x [PLUGINS_DIR] > catalog[.partial].json

How does rackcli fit into a typical rack workflow? YMMV, but I'll be using rackcli alongside rack so I can bounce down to my shell prompt, kick off a rackcli command or two, then back to rack for a quick File+Revert to revert to the updated patch file (of course I regularly hit META-S to save my wigglz) -- walah, instant magic!

To get a sense of how the fork and plugin modules work, check out the rackcli/r4xH4x lab videos.

Here's the highlight reel for features under active development or beta-ready (see Issues marked "enhancement" for many more under serious consideration -- or add submit your own ideas/requests):

Rack Features

1. version
2. get/set rack settings
3. panic (delete autosave.vcv, etc.)
4. ...

Plugin/Module Features

1. list plugins
2. list plugin modules
3. list/install non-PluginManager plugins
4. hack module resources
5. documentation generator
6. ...

Patch Features

1. layout manager with super-easy module selection syntax for referencing parts of your patch -- like multi-select on steroids -- and the ability to move, delete, shift right/left, squeeze out empty rack space, etc.
2. insert/delete rack row
3. import/export plugins/wiring/settings
4. documentation generator
5. common fragment generator (e.g. CF module mixers, AS re* composers, Turing Machine + Quatizer + Semis composer, or even patching automation for rich modules like Phrase-Seq-16, etc.)
6. social media share
7. ...

Installation rackcli is implemented in Python 3. Once you download and install the latest Python 3 version for your OS, install the dependent libraries as follows:

pip3 install requests click

Clone the supporting VCV Rack fork and follow the installation instructions for the best workflow experience as it generates a full catalog.json, complete with plugin module widths. Don't forget to grab the v0.6 tag per the instructions (i.e. git checkout v0.6) as specified in the build installation instructions.

Alternatively, your can install the DLwigglz r4xH4x plugin module to generate a partial catalog catalog.partial.json or patch.json for the current patch.

Optionally, jq is an awesome open source tool for hacking JSON files. Here are a couple of interesting use cases with the generated catalog.json and settings.json:

export RACK_DIR=wherever-rack-is-installed

cat $RACK_DIR/catalog.json | jq
cat $RACK_DIR/catalog.partial.json | jq
cat ANY_PATCH.vcv | jq
cat $RACK_DIR/settings.json | jq '.lastPath'

Example Usage -- Live Features (beta)

alias rackcli="/path-to-rachcli/rackcli"

rackcli
rackcli --help

rackcli settings --help
rackcli settings
rackcli settings --rackdir ~/Downloads/Rack

rackcli catalog --help
rackcli catalog --share $RACK_DIR/catalog.json | jq
rackcli catalog --share $RACK_DIR/dox.vcv > proof.json
rackcli catalog --sync $RACK_DIR/catalog.partial.json

Feature Brainstorm

rackcli --version
rackcli --panic
rackcli --list
rackcli --documentation
rackcli --layout --row 1 --col 3 --shift-left ; remove empty HP beyond 3rd module
rackcli --layout --row 1:2 --shift-down 2
rackcli --layout --shift-left
rackcli --layout --row 3 --col 2 --add-hp 25 ; insert 25 HP of space before 3rd module
rackcli --share ~/Desktop/ep1cY0.vcv --to [youtube|patchstorage|twitter|instagram|etc] ; prompt for creds, no history

Again, check out the open issues marked "enhancement" for additional active conversations and please submit your own features/priorities/suggestions there as well. You can also reach out via the official VCV Rack group on Facebook or message me directly -- front there, we can bounce out to Skype or email as appropriate.

--

Licenses

All concepts and source code in this repository is licensed under BSD-3-Clause by Dirk Leas.