Difference between revisions of "Extras script"
Boxofstops (Talk | contribs) (Created page with "''Under construction''") |
Boxofstops (Talk | contribs) (→Internal API) |
||
| (3 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | '' | + | 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 [[Trigger|triggers]] or [[Gpio button|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 <googa>https://github.com/boxofstops/boxofstops-examples|https://github.com/boxofstops/boxofstops-examples</googa> for the latest examples of Extras scripts. | ||
| + | |||
| + | == Using == | ||
| + | |||
| + | To add an Extras script to Box Of Stops, please look for the <tt>~/boxofstops/.python</tt> directory (see [[Directories]] for more information). By default the Extras script is called <tt>extras.py</tt> in this directory. Just add this file and [[Starting|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 <tt>extras.py</tt>. Please look for the <tt>python.extras.script</tt> 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. | ||
| + | |||
| + | * <tt>boxofstops.add_device_channel(device_name,channel)</tt> - register a new input device and channel to play to a [[Bank]] in Box Of Stops.<br/>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. | ||
| + | * <tt>boxofstops.midi_in_event(device_name,msg)</tt> - inject a note (or other MIDI event) into the Box Of Stops playing engine.<br/>This note_on/note_off will be played on the appropriate [[Bank]] for the <tt>device_name</tt> and the <tt>channel</tt> in the message.<br/>The <tt>msg</tt> is a <googa>https://mido.readthedocs.io/en/latest/messages.html|MIDO Message</googa>. Again please see the <googa>https://github.com/boxofstops/boxofstops-examples|examples code</googa> for examples of this being used. | ||
| + | boxofstops.midi_in_event('''device_name''',mido.Message(''''note_on'''', note='''60''', channel='''0''', velocity='''80''')) | ||
| + | boxofstops.midi_in_event('''device_name''',mido.Message(''''note_off'''', note='''60''', channel='''0''', velocity='''80''')) | ||
| + | |||
| + | == 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: <tt><<< Not loading extras.py</tt> | ||
| + | * If the script is found, typically the logging output shows any print statement at the top of the script. E.g. : <tt><<< In extras</tt> | ||
Latest revision as of 09:14, 27 January 2018
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 examples of this being used.
boxofstops.midi_in_event(device_name,mido.Message('note_on', note=60, channel=0, velocity=80))
boxofstops.midi_in_event(device_name,mido.Message('note_off', note=60, channel=0, velocity=80))
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
