In this blog I'll be covering the new HTTP JSON API featured in the the 1.14 version of my Articulate plugin for FL Studio.
Just a forewarning, but if you're not sure what an API is, or does, then this blog is probably not for you. APIs are aimed more at programmer or tinkery types who want to remote, batch configure BRSO Articulate via some kind of web-based interface.
The Articulate HTTP JSON API is disabled by default. You can turn it on in the new 'Advanced' section of the configuration panel. Simply click HTTP JSON API so that it lights up. The API will now start and listen on Port 8000. The setting is remembered by Articulate. If you close FL Studio and re-open, with an instance of Articulate, the API will automatically run. To permentantly deactivate the API, simply click the HTTP JSON API option to off.
The API runs locally on port 8000 by default. With the HTTP API server on and running you can find the API at http://localhost:8000/api. If this port is inconvenient or unavailable you can also change the port that the API runs on by adding a HTTP Port REG_SZ registry key to
Computer\HKEY_CURRENT_USER\Software\BRSO\BRSO Articulate
If you have Articulate running and turn on the API and open the URL provided above in your browser, you'll be greeted with a chunk of JSON. Congratulations - this is a list of all instances of Articulate that your FL Studio is hosting:
You can drill down into a specific instance by providing the instanceid in your URL. For example, the screenshot above shows the instance with the id 118128592. You can filter the data from just this instance by going to http://localhost:8000/api/118128592.
There are two ways to modify the properties of an instance. Lets start with the easiest way, using HTTP GET calls. The general structure of an API GET call in the API is:
HTTP://LOCALHOST:8000/API /{instanceid} /{category} /{property} = {value}
Taking the above example, lets look at how we would turn releasetocc117 on and off with a GET call. You can try this in your browser or your usual go-to HTTP request tool/library/etc. Calling either of the following will return the instance data which should have updated to reflect your requested change:
Turning options.releasetoCC117 on: http://localhost:8000/api/118128592/options/releasetocc117=true
Turning options.releasetoCC117 off: http://localhost:8000/api/118128592/options/releasetocc117=false
Sometimes you may not need the {category} part of the URL. An example of this is changing the main properties such as port, channel, etc. Here's a few more example commands:
Setting the channel to 8: http://localhost:8000/api/118128592/channel=8
Setting the port to 12: http://localhost:8000/api/118128592/port=12
Sett the articulation we're editing to 3: http://localhost:8000/api/118128592/editing=12
The same GET calls can be used to modify the articulations. The format is the same as above, though with an articulation or controller index included in the path structure. Here's a few examples:
Setting articulation 0's name to "My articulation": http://localhost:8000/api/118128592/articulations/0/name=My%20articulation
Setting articulation 3's icon to 10 (Staccato): http://localhost:8000/api/118128592/articulations/3/icon=10
Setting articulation 13's keyswitch key to 7 (G-2): http://localhost:8000/api/118128592/articulations/13/note=7
Setting controller 8's type to 1 (button): http://localhost:8000/api/118128592/controllers/8/type=2
Setting the CC controller 12 controls to 1 (mod wheel): http://localhost:8000/api/118128592/controllers/12/cc=1
Setting the CC controller 4 value to 64: http://localhost:8000/api/118128592/controllers/4/value=64
NOT YET, but this will be coming. Stay tuned and this blog will update once you can!
You sure can! First lets cover a special GET call that isn't a command: HTTP://LOCALHOST:8000/API /{instanceid} /json
This command will spit out the .brsoartic export for the provided instanceid. It's the exact same JSON data you would get if you were to right click the articulation configuration panel button and select Export Articulations, just as a HTTP response:
You can also PUT to this same URL to modify this JSON data. Here's a meta-example for our original screenshot's instance:
PUT to http://localhost:8000/api/118128592/json
[ { "name": "Long", "icon": 4, "note": 0, "notevel": 127, "prog": -1, "modw": -1, "modc": -1 }, { "name": "Short", "icon": 10, "note": 1, "notevel": 127, "prog": -1, "modw": -1, "modc": -1 } ]
This will load the two articulations above into the specified instance of BRSO, completely replacing what was already there. Here's that above example as a web-based script using JQuery as an example:
var submit_instance = 118128592; var submit_instrument = [ { "name": "Long", "icon": 4, "note": 0,"notevel": 127, "prog": -1, "modw": -1, "modc": -1 }, { "name": "Short", "icon": 10, "note": 1, "notevel": 127, "prog": -1, "modw": -1, "modc": -1 } ]; $.ajax({url: "/api/" + submit_instance + "/json", type: "PUT", contentType: "application/json", data: JSON.stringify(submit_instrument)} ).done(function(data) { console.log("Data was submitted to the API"); console.log(data); });
Finally, here's a full list of the GET commands currently supported in the API:
HTTP://LOCALHOST:8000/API /{instanceid} /port = {value}
Set the instance's MIDI Port to {value} (0-255).
HTTP://LOCALHOST:8000/API /{instanceid} /channel = {value}
Set the instance's MIDI channel to {value} (0-63 or 256 for per-colour MIDI channel).
HTTP://LOCALHOST:8000/API /{instanceid} /tab = {value}
Set the instance's currently displayed UI tab to {value} (0-2).
HTTP://LOCALHOST:8000/API /{instanceid} /editing = {value}
Set the instance's current articulation to {value} (0-63).
HTTP://LOCALHOST:8000/API /{instanceid} /bankstart = {value}
Set the articulation start offset that a multi-bank instance shows to {value} (0, 16, 32 or 48).
HTTP://LOCALHOST:8000/API /{instanceid} /controllerstart = {value}
Set the controller start offset that the instance shows to {value} (0, 6, 12, 18, 24, 30, 36, 42, 48 or 54).
HTTP://LOCALHOST:8000/API /{instanceid} /options /midiextend = {value}
Set the instance's MIDIExtend option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /ccghosting = {value}
Set the instance's CC Ghosting option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /cctimingfix = {value}
Set the instance's Kontakt CC timing fix option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /allchannelomni = {value}
Set the instance's Omni CC on all channel option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /cc64release = {value}
Set the instance's CC64 Release on Stop option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /preserveport = {value}
Set the instance's Preserve Port/Channel option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /releasetocc117 = {value}
Set the instance's Rls. velocity to CC17 option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /resetstate = {value}
Set the instance's Reset state on switch option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /showuacc = {value}
Set the instance's Show UACC on CC32 option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /parameterscc = {value}
Set the instance's Parameters control CC option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /allowoverlap = {value}
Set the instance's Allow overlapping notes option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /optimiseaudio = {value}
Set the instance's Optimise automation option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /showsingle = {value}
Set the instance's Show single editor option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /options /articbanks = {value}
Set the instance's Multiple artic. banks option to {value} (true, false).
HTTP://LOCALHOST:8000/API /{instanceid} /articulations /{index} /name = {value}
HTTP://LOCALHOST:8000/API /{instanceid} /articulations /{index} /icon = {value}
HTTP://LOCALHOST:8000/API /{instanceid} /articulations /{index} /note = {value}
HTTP://LOCALHOST:8000/API /{instanceid} /articulations /{index} /notev = {value}
HTTP://LOCALHOST:8000/API /{instanceid} /articulations /{index} /modw = {value}
HTTP://LOCALHOST:8000/API /{instanceid} /articulations /{index} /modc = {value}
HTTP://LOCALHOST:8000/API /{instanceid} /articulations /{index} /prog = {value}
Set the instance's articulation {index}'s various propertes to {value}.
HTTP://LOCALHOST:8000/API /{instanceid} /controllers /{index} /name = {value}
HTTP://LOCALHOST:8000/API /{instanceid} /controllers /{index} /type = {value}
HTTP://LOCALHOST:8000/API /{instanceid} /controllers /{index} /default = {value}
HTTP://LOCALHOST:8000/API /{instanceid} /controllers /{index} /cc = {value}
HTTP://LOCALHOST:8000/API /{instanceid} /controllers /{index} /on = {value}
HTTP://LOCALHOST:8000/API /{instanceid} /controllers /{index} /value = {value}
HTTP://LOCALHOST:8000/API /{instanceid} /controllers /{index} /lock = {value}
Set the instance's controller {index}'s various propertes to {value}.
To sum it up, the HTTP JSON API allows nerdy programmers types to remotely configure their BRSO Articulate instances in FL Studio. What's your thoughts on the system? Leave your feedback in the comments below, drop me an email or ping me a twitter @syntheticorch with your thoughts and ideas!
All original content available from this site © 2024 Synthetic Orchestra™ Ltd. All Rights Reserved. Orchestrations, Covers, Remixes & Trademarks are hosted externally and © their respective copyright owners.