A big part of the engineering of my MA thesis was building an API for classifying things. This pages talks about how to use that API – you can check out Chapter 6 of the thesis text to see how it was built.
Basic Usage:
If you have a bunch of buttons you want mapped, you just need to send a POST request to http://pattern-rec.tide-pool.link/pattern-rec/analysis. The body of the request should be a string of JSON data the represents a list of buttons. Each button object needs a location parameter, which is also an object, with two fields: x and y. The button object can have any other fields.
That is to say, your data should look something like this:
[{“location”: {“x”: 450, “y”: 100}}, {“location”: {“x”: 450, “y”: 210}}, {“location”: {“x”: 450, “y”: 320}}, {“location”: {“x”: 570, “y”: 100}}]
Here’s an example curl request:
curl -X POST -H “Content-Type: application/json” -d ‘[{“location”: {“x”: 450, “y”: 100}}, {“location”: {“x”: 450, “y”: 210}}, {“location”: {“x”: 450, “y”: 320}}, {“location”: {“x”: 570, “y”: 100}}]’ http://pattern-rec.tide-pool.link/pattern-rec/analysis
The algorithm then thinks for a bit, and sends you back more JSON data. You’ll get an object with two parameters, “result” and “mapping”.
“result” tells you which of several prototypes your buttons are most like: “piano”, “piano roll”, and so on. You can use that to do your own mapping, if you like. The complete list of protoypes is: piano, xylophone, piano roll, zither, small grid, large grid, and circle – though this will hopefully soon be updated with kalimba, tonnetz, and staff
“mapping” tells you how you should map your buttons. It’s the same list of button data that you sent in, with MIDI number and the frequency of the note that each button should play added.
As an example, the result of the cURL request is below:
{“mapping”: [ {“location”: {“x”: 450, “y” 320}, “noteFreq”: 261.6255653005986, “noteMIDI”: 60},
{“location”: {“x”: 450, “y”: 210}, “noteFreq”: 277.1826309768721, “noteMIDI”: 61},
{“location”: {“x”: 450, “y”: 100, “noteFreq”: 293.6647679174076, “noteMIDI”: 62},
{“location”: {“x”: 570, “y”: 100}, “noteFreq”: 311.1269837220809, “noteMIDI”: 63}
], “result”: “small_grid”}
Advanced Usage:
For now, the only additional parameter is an”adventure” rating. This is an optional parameter that will result in less typical mappings of pitch. Adventure is an integer from 0 to 4. Calls to the API with Adventure not specified will use a default value of 0, and Adventure values of 3 and 4 give microtonal results: they will no longer return MIDI values.
To use the Adventure parameter, instead of sending a JSON array containing the button data, send a JSON object with two attributes; “buttonData” must contain the JSON array of button data, and “adventure” must contain the adventure, as an integer from 0 to 4. For example:
{“adventure”: 4, “buttonData” [{“location”: {“x”: 450, “y”: 100}}, {“location”: {“x”: 450, “y”: 210}}, {“location”: {“x”: 450, “y”: 320}}, {“location”: “x”: 570, “y”: 100}}] }
Adventure gives the following results:
- 0: Pentatonic Major, Diatonic Major, and Chromatic scales are returned.
- 1: Pentatonic and Dianotic Minor scales may be returned, as well as Major scales with additional flat thirds, sevenths, and sixths.
- 2: Hexatonic and octatonic scales may be returned.
- 3: Equal-tempered microtonal scales are returned, with a temperment equal to the number of buttons.
- 4: A microtonal mapping is returned, based on the ratio of the distance of each button from a base button (the bottom-left-most button) to the distance between that base button and the most distant other button.
Note again that an adventure rating of 3 or 4 will not return MIDI values. And here’s an example cURL and response:
curl -X POST -H “Content-Type: application/json” -d ‘{“adventure”: 4, “buttonData”: [{“location”: {“x”: 450, “y”: 100}}, {“location”: {“x”: 450, “y”: 210}}, {“location”: {“x”: 450, “y”: 320}}, {“location”: {“x”: 570, “y”: 100}}]}’ http://pattern-rec.tide-pool.link/pattern-rec/analysis
Which gets you:
{“mapping”: [
{“location”: {“x”: 450, “y”: 320}, “noteFreq”: 261.6255653005986},
{“location”: {“x”: 450, “y”: 210}, “noteFreq”: 376.4655280699081},
{“location”: {“x”: 450, “y”: 100, “noteFreq”: 491.3054908392174},
{“location”: {“x”: 570, “y”: 100}, “noteFreq”: 523.2511306011972}
], “result”: “small_grid”}
Help!
There’s a demo application at http://tide-pool.ca/pattern-recognition – check the source code there for real-world examples.
Classification can take a few seconds. In order to check the status of the server, check here. If you’re getting weird analysis, check here.
If you happen to be using this for academic work, please cite the thesis – and if things are broken, let me know.