Download the example Max patches and sample JSON files for this tutorial.

An example Max patch, a JSON file describing its OSC routing and the OSCQuery Helper utility.

One of the most powerful tools for working with MIDI and OSC control data is Max, which is widely known for its easy to use interface for “patching” and working with data streams. While Max does not yet support OSCQuery natively, it is a great example of how the free OSCQuery Helper and MIDI OSCQuery Helper tools can be used to publish OSC and MIDI parameters from Max patches so that they can be remotely accessed by other software like VDMX and the OSCQuery Browser.

In this set of tutorials we’ll look at the process for adding basic MIDI and OSC inputs in a simple Max patch and then creating a JSON file that describes the routings. Once those are prepared we can see how to access these parameters using other software in the OSCQuery ecosystem.

Using the MIDI OSCQuery Helper with Max

The MIDI OSCQuery Helper app is a free utility that receives incoming OSC messages and converts them into MIDI to be passed off to other software such as Max. It also has the ability to publish its provided OSC address space as OSCQuery information that can be remotely browsed by tools like VDMX for rapid setup of network control between systems.

To prepare an OSC to MIDI mapping, a JSON file is created that describes each parameter, including the following information:

OSC Address Path: The path that OSC will be received on for this mapping.
OSC Data Type: The type of data to be expected, such as ‘f’ for float or ‘i’ for integer.
OSC Data Range: The expected range of data to be received; usually 0.0 to 1.0 for floating values.
MIDI Channel: The MIDI channel to output on.
MIDI Type: The type of MIDI to send, such as NOTE or CC to be used for the mapping..
MIDI Voice: The MIDI voice number to be used for the mapping.
Description: An optional brief description of what the control is used for.

When you first launch the MIDI OSCQuery Helper it will automatically create a default sample document that can be used as a starting point for creating your own mapping templates.

This technique can be used with both the MIDI mapping and ctlin / notein objects within Max, though in this video tutorial we will focus on using the quick mapping route.

Tip: When creating MIDI channel mappings, Max considers ‘1’ to be the first channel but the MIDI OSCQuery Helper starts at ‘0’ – you may need to subtract 1 for channel numbers when creating your JSON files.

Using the OSCQuery Helper with Max

The OSCQuery Helper app is a free utility can read in a template file that describes an OSC address space for a piece of software, such as a Max patch, and published it as OSCQuery information that can be remotely browsed by tools like VDMX for rapid setup of network control between systems.

To prepare an OSC address space template, a JSON file is created that describes each parameter, including the following information:

OSC Address Path: The path that OSC will be received on for this mapping.
OSC Data Type: The type of data to be expected, such as ‘f’ for float, ‘i’ for integer, or ‘s’ for string.
OSC Data Range: The expected range of data to be received; usually 0.0 to 1.0 for floating values.
Description: An optional brief description of what the control is used for.
The OSCQuery Proposal contains a list of optional extensions and conventions that can be used.

When you first launch the OSCQuery Helper it will automatically create a default sample document that can be used as a starting point for creating your own mapping templates. You can also use the examples provided for this tutorial.

We begin this tutorial by taking an existing Max patch and using the “udpreceive” object to capture OSC messages. Make sure that whatever setting you use for the “port” is also set to the same value in the OSCQuery Helper panel.

Next the JSON file is prepared and loaded into OSCQuery Helper. Using the OSCQuery Browser on the second computer we can see the published parameters and immediately start sending test messages that show up in the Max console.

Finally within our Max patch we can add the local OSC routings using the “route” for each of the parameters and connect them to the appropriate inputs.

After watching these video demonstrations, move on to see the other capabilities of OSCQuery in VDMX.