The Blake Robinson Synthetic Orchestra - Tutorials » Articulate

Tutorials » Articulate » HTTP JSON API

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.

How do I turn on the HTTP JSON API?!

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.

Aces! And how do I access the API

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

So what can I do with it?

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.

Modifying an instance

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

Editing the articulations and controllers

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

Can I configure the piano roll keys remotely?

NOT YET, but this will be coming. Stay tuned and this blog will update once you can!

Okay, I've got the hang of the GETs. Can I do something more advanced?

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);
});

Full list of GET commands

Finally, here's a full list of the GET commands currently supported in the API:

To wrap things up

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.