MIDI OSCQuery Helper for macOS
MIDI OSCQuery Helper ("MOQH" from now on) adds OSC and OSCQuery capabilities to other applications that only support MIDI.
- This app uses JSON files loaded into it to create an OSC address space.
- This app runs an OSC query server- this query server publishes the details of the address space.
- This app runs an OSC server- this server listens on a dedicated port for OSC messages. Clients browsing the OSC query server send OSC messages to this OSC server.
- This app creates a virtual MIDI device ("From MIDI OSCQuery Helper"). This app also lets you optionally pick an existing MIDI device. The OSC messages received by this app's OSC server are converted into MIDI messages (using data from the JSON file you loaded), and these MIDI messages are sent out both the virtual MIDI device created by this app as well as the existing MIDI device you selected (if any).
Downloading MIDI OSCQuery Helper
Latest release: MIDI OSCQuery Helper v0.4.3.4
The MIDI OSCQuery Helper application can also be found on the VDMX dmg in the Extras folder.
About OSCQuery Protocol
The OSCQuery Protocol is an agreed upon specification that extends the base functionality of OSC to make it easier to construct impromptu or improvisational interfaces between different systems.
Some definitions copied from the OSC spec:
- An OSC server has a set of OSC Methods.
- OSC methods are the potential destinations of OSC messages received by the OSC server and correspond to each of the points of control that the application makes available. "Invoking" an OSC method is analgous to a procedure call; it means supplying the method with arguments and causing the method's effect to take place.
- An OSC server's OSC Methods are arranged in a tree structure called an OSC Address Space. The leaves of this tree are the OSC Methods and the branch nodes are called OSC Containers.
The OSCQuery Protocol provides a standardized way for systems to publish descriptions of their OSC Address Spaces in such a way that other environments can automatically interface with them with little or no setup.
Within OSCQuery, a "server" is a host that provides a JSON data blob that describes the hierarchy of an OSC Address Space in a format that is both easy for humans and machine to interpret. Descriptions can include the type of data that is expected, the range of values that are accepted and other information about each container and method within the address space.
Using MIDI OSCQuery Helper
How to use MIDI OSCQuery Helper
- Tell MOQH what file to use- this file will be used to populate the OSC query server with the description of another application's OSC address space. MOQH will "watch" the file and if it is updated, the query server will automatically update itself, and then notify all connected clients that it has been updated. For more information about the supported file type(s), see "FILE TYPE".
- Select a MIDI destination you want this app to send MIDI data to. This step is optional- MOQH also creates a virtual MIDI device ("From MIDI OSCQuery Helper") which other applications can listen to.
If MOQH is running, the OSC query server is running- you can check it with any OSC query client, or a web browser. The query server will stop when the app quits- if there's a problem with the file you load (if it's missing or malformed or corrupt) the query server will keep running, but its address space will be empty.
MIDI OSCQuery Helper File Format
- JSON files can be imported- a sample file demonstrating the various basic MIDI data types is already installed on your machine in "~/Documents/MIDI OSCQuery Helper/SampleDocument.json". The JSON files that you import should have a structure similar to the desired output of the OSC query server- for more information, consult the OSC query protocol, defined here https://github.com/vidvox/OSCQueryProposal. There are, however, several additional keys/values which must be used to indicate what sort of MIDI value should be sent- the query server will not publish any OSC nodes that are missing the following keys:
- "MIDI_TYPE": The value stored at the key "MIDI_TYPE" must be one of the following strings: "NOTE", "AFTERTOUCH", "CC", "PGM", or "PITCH". This value indicates what kind of MIDI message should be sent when an OSC message is received by this node.
- "MIDI_CHANNEL": The value stored at the key "MIDI_CHANNEL" must be an integer. This value describes the channel on which the MIDI message will be sent.
- "MIDI_VOICE": The value stored at the key "MIDI_VOICE" must be an integer. This value describes which controller or note will be used to send the value from the OSC message.
Notes and Troubleshooting
- MOQH only supports receiving of OSC messages and sending of MIDI messages. Bi-directional communication is not currently supported.
- Within VDMX, parameters in a Control Surface can be published with OSCQuery without using an external helper tool such as OQH.
- If the MIDI OSCQuery Helper does not appear in the list of servers in other software:
- Make sure the client trying to connect to OQH is on the same local network.
- Try using the free OSCQuery Browser utility to try to browse the address space.
- Try to load the JSON data blob in a web browser by entering the IP address / port used by the server for OSCQuery. If it does not load, then the server is not publishing its information or there is a networking problem.