Extras script

As mentioned elsewhere, Box Of Stops uses a small but crucial Python script to achieve its real-time playback. Most customization work with Box Of Stops can be achieved with triggers or GPIO buttons, but occasionally there is a requirement to inject a note into the live playing engine.

This can be achieved with something called an Extras script. This is typically a short Python script that will be imported into the main Python script that Box Of Stops uses.

Please see https://github.com/boxofstops/boxofstops-examples for the latest examples of Extras scripts.

Using

To add an Extras script to Box Of Stops, please look for the ~/boxofstops/.python directory (see Directories for more information). By default the Extras script is called extras.py in this directory. Just add this file and restart - Box Of Stops will auto-detect the script and call it while initializing.

Renaming the script

It is possible to use a script with a different name than extras.py. Please look for the python.extras.script property in the Application properties file.

Internal API

There is a small internal API available to call back to, to register a device and inject notes or other events into the running Box Of Stops script.

• boxofstops.add_device_channel(device_name,channel) - register a new input device and channel to play to a Bank in Box Of Stops.
  The Bank will see this as new Midi input, but the point of the Extras script is to simulate a Midi input, while generating notes and events from an alternative source.
• boxofstops.midi_in_event(device_name,msg) - inject a note (or other MIDI event) into the Box Of Stops playing engine.
  This note_on/note_off will be played on the appropriate Bank for the device_name and the channel in the message.
  The msg is a MIDO Message. Again please see the examples code for an example of this being used.

Debugging

Note that any output from the Extras script is automatically sent to the Logging output.

• If no script is found, the logging output shows: <<< Not loading extras.py
• If the script is found, typically the logging output shows any print statement at the top of the script. E.g. : <<< In extras