Browse files


A verbose rant on the purpose of this library, and its advantages and limitations.
  • Loading branch information...
1 parent c1dd771 commit dbf81bc82238c34f58d4b0ff5f0c6a7acb4b9465 @radarsat1 committed Nov 24, 2010
Showing with 160 additions and 4 deletions.
  1. +2 −1 AUTHORS
  2. +158 −3 README
@@ -1,3 +1,4 @@
Stephen Sinclair <>
Joseph Malloch <>
-J?r?me Nika <>
+J??rome Nika <>
+Vijay Rudraraju <>
@@ -1,5 +1,160 @@
+This library is a system for representing input and output signals on
+a network and allowing arbitrary "mappings" to be dynamically created
+between them using an external interface.
+This project began life as a tool for helping composers and performers
+to more easily play with custom-built musical instruments, such that a
+program that reads data from the instrument (e.g. from an Arduino USB
+serial port) can be connected to the inputs of a sound synthesizer.
+The first version of this software was written entirely in Cycling
+74's Max/MSP, but in ordre to make it more universally useful and
+cross-platform, we decided to re-implement the protocol in C; hence,
+We were already using Open Sound Control for this purpose, but needed
+a way to dynamically change the mappings--not only to modify the
+destinations of OSC messages, but also to change scaling, or to
+introduce derivatives, integration, frequency filter and smoothing,
+etc. Eventually this grew into the use of a multicast bus to publish
+signal metadata and administrate peer-to-peer connections between
+machines on a local subnet, with the ability to specify arbitrary
+mathematical expressions that can be used to perform signal
+It has been designed with the idea of decentralization in mind. We
+specifically wanted to avoid keeping a "master" node which is
+responsible for arbitrating connections or republishing data, and we
+also wanted to avoid needing to keep a central database of serial
+numbers or other unique identifiers for devices produced in the lab.
+Instead, common communication is performed on a multicast UDP port,
+that all nodes listen on, and this is used to implement a
+collision-handling protocol that can assign a unique ID to each device
+that appears. Actual signal data is sent directly from a sender
+device to the receiver's IP and UDP port.
+Advantages of libmapper
+This library is, on one level, our response to the widely acknowledged
+lack of a "query" protocol for Open Sound Control. We are aware for
+example of current work on using the ZeroConf protocol for publishing
+OSC services, or various efforts to standardize a certain set of OSC
+address conventions.
+However, we believe libmapper covers considerably more ground than
+simply the ability to publish namespaces, and handles a direct need
+that we experienced in our daily work. We did evaluate the use of
+ZeroConf early on in this work, but we eventually decided that sending
+OSC messages over multicast was just as easy and required the
+integration of fewer dependencies. With the addition of being able to
+control message routing and to dynamically specify signal conditioning
+equations, we feel this work represents a significant enough effort
+that it is worth making available to the general public.
+It can also be seen as an open source alternative to some commercial
+products such as Camille Troillard's Osculator and STEIM's Junxion,
+albeit certainly more "barebones" for the moment.
+A major difference in libmapper's approach to handling devices is the
+idea that each "driver" can be a separate process, on the same or
+different machines in the network. By creating a C library with a
+basic interface and by providing SWIG bindings, we hope to enable a
+very wide variety of programming language bindings, to allow any
+choice of development strategy.
+(At this time, the SWIG bindings only work for Python. Support for
+more languages, particularly Java, is in the works.)
+Known conceptual limitations
+The 'device' and 'signal' metaphor encapsulated by libmapper is of
+course not the be-all and end-all of mapping. We assume homogeneous
+vectors of floating-point or integer numbers, while in reality more
+complex structured data might be useful to transmit.
+Particular if libmapper is to be used for visual art, transmission of
+matrixes or even image formats might be interesting, although there is
+no standard way to represent this in Open Sound Control other than as
+a binary 'blob'. It's possible that in this case a protocol such as
+HTTP that supports MIME type headers is simply a more appropriate
+One impact of peer-to-peer messaging is that it may suffer from
+redundancy. In general it may be more efficient to send all data once
+to a central node, and then out once more to nodes that request it, at
+the expense of weighing down the bandwidth of that particular central
+node. In libmapper's case, if 50 nodes subscribe to a particular
+signal, it will be repeated that many times by the place where it
+originated. Dealing with this central-vs-decentralized by
+automatically optizing decisions of how messages are distributed is
+not impossible, but represents non-trivial work--for example, in
+libmapper the conception of a 'router' is actually an independent node
+that a device sends messages to, which it then translates and
+rebroadcasts; it just happens that the router is embedded in the
+sender because that was the most efficient place to have it in our
+scenario. In any case, it goes without saying that your choice of
+using libmapper should depend on what type of network you envision: if
+you need a large number of receivers for the same signal you might
+consider one of the many alternatives, such as the SenseWorld
+DataNetwork, a SuperCollider framework based on the central-server
+Future plans
+We chose to use Open Sound Control for this because of its
+compatibility with a wide variety of audio and media software. It is
+a practical way to transmit arbitrary data in a well-defined binary
+format. In practice, since the actual connections are peer-to-peer,
+they could technically be implemented using a variety of protocols.
+High-frequency data for example might be better transmitted using the
+JACK Audio Connection Kit or something similar. In addition, on
+embedded devices, it might make sense to "transmit" data between
+sensors and synthesizers through shared memory, while still allowing
+the use of the libmapper GUI to dynamically experiment with mapping.
+Although we provide a basic cross-platform GUI using Qt, the most
+advanced user interface is still the Max/MSP implementation. Although
+this works extremely well, it is limited to platforms supported by
+Max/MSP. (In other words, not Linux.) There currently are plans to
+create a web-based front-end that will be cross-platform. Better ways
+of visualizing and interacting with the network are also an active
+research topic.
+For implementing intermediate devices that "learn" mappings
+automatically, a useful feature would be to request snapshots of the
+states of all inputs on a destination device. This has already been
+implemented in the previous Max/MSP version, and we have examples of
+neural network and SVM intermediates, but this feature did not yet
+make it into the C version of libmapper.
+Currently the only supported data types are 32-bit integers and 32-bit
+floating point. This covers most of our use cases, but we hope to
+expand this catalogue eventually.
+In the syntax for mathematical expressions, we include a method for
+indexing previous values to allow basic filter construction. This is
+done by index, but we also implemented a syntax for accessing previous
+state according to time in seconds. This feature is not yet useable,
+but in the future interpolation will be performed to allow referencing
+of time-accurate values. (Currently any "filter" implemented by an
+expression will suffer somewhat from unknown jitter, particularly when
+signal updates are not regular.)
This software was written in the Input Devices and Music Interaction
-Laboratory at McGill University in Montreal, and is copyright Stephen
-Sinclair 2009. It is licensed under the GNU Lesser Public General
-License version 2.1 or later. Please see COPYING for details.
+Laboratory at McGill University in Montreal, and is copyright those
+found in the AUTHORS file. It is licensed under the GNU Lesser Public
+General License version 2.1 or later. Please see COPYING for details.
+In accordance with the LGPL, you are allowed to use it in commercial
+products provided it remains dynamically linked, such that libmapper
+always remains free to modify. If you'd like to use it in an
+outstanding context, please contact the AUTHORS to seek an agreement.

0 comments on commit dbf81bc

Please sign in to comment.