Table of Contents

Mapping tools for digital musical instruments

Authors: Joseph Malloch, Stephen Sinclair

The mapping tools provide a framework and GUI designed to aid collaborative development of a digital musical instrument mapping layer. The goal was to create a system that allows mapping between controller and sound parameters without requiring a high level of technical knowledge, and which needs minimal manual intervention for tasks such as configuring the network and assigning identifiers to devices. Ease of implementation was also considered, to encourage future developers of devices to adopt a compatible protocol. (See the Mapping Tools project page for more information and a screenshot.)

The version available here for download has been implemented in Max/MSP. In the future, we will try to have other versions available here also - the documentation is all freely available, so if you feel like porting the max version, or including compatibility in your own software, please feel free :)

You will need to download the Digital Orchestra Toolbox of Max/MSP abstractions (linked below).

Mapping Musical Instruments using the Digital Orchestra Tools from IDMIL on Vimeo.

Download

License: LGPL

Download:

Current Dependencies:

  • jcom.oscroute from the Jamoma project
  • aka.mouse - optional, will function without this external

Extras:

Using the mapping tools

Integrating the mapping tools with existing patches is usually extremely easy, and really consists of only two steps:

  1. create a device definition file - In order for the mapping system to inform other devices and GUIs of the mappable parameters of your device, you need to create an XML device definition file in the following simple format. The OSC address string of each parameter is given, along with some useful but optional information specifying the parameter's data type, associated unit, and minimum and maximum values (if any). If your device parameters are not known initially, they can be added dynamically by sending messages to the dot.admin object.
<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
 
<dot>
    <device name = "/example" class = "example.xml" numInputs = "2" numOutputs = "2">
        <inputs>
            <parameter name = "/in1">
                <type>f</type>
                <units>normalized</units>
                <minimum>0</minimum>
                <maximum>1</maximum>
            </parameter>
            <parameter name = "/in2">
                <type>i</type>
                <units>na</units>
                <minimum>0</minimum>
                <maximum>256</maximum>
            </parameter>
        </inputs>
        <outputs>
            <parameter name = "/out1">
                <type>f</type>
                <units>percent</units>
                <minimum>0</minimum>
                <maximum>100</maximum>
            </parameter>
            <parameter name = "/out2">
                <type>f</type>
                <units>na</units>
            </parameter>
        </outputs>
    </device>
</dot>
  1. create an instance of dot.admin in your patch - Use the name of the device definition file from step 1 as an argument. At this point, the instance of dot.admin will negotiate with other instances for a unique name and port, and announce itself on the mapping admin bus. Any OSC traffic mapped to the instance will emerge from the left outlet of the dot.admin object, and OSC messages routed to the left inlet of the dot.admin will become available for mapping across the entire system. The system takes care of device enumeration and network connections - you can map between human-readable OSC parameter names, rather than IPs and ports. Also, controller and synthesizer programs can transparently be run on different (or multiple) computers.

For more detailed documentation, please refer to the published papers linked below. If you have questions or find a bug, please contact Joseph Malloch or Stephen Sinclair.

Publications

 
Copyright © IDMIL, McGill University, All rights reserved.