back to home

MobMuPlat Guide

a project of Iglesia Intermedia

MobMuPlat is a set of tools for creating music apps for iOS devices. (No text coding required!)

0. Get the MobMuPlat iOS app here, or the Android app here, and the development package (which includes the MobMuPlat Editor and sample files), from the download links on the front page. You'll also need to have Pure Data vanilla (version .46 and above) installed on your computer. Get that here.
1. Create a user interface in the MobMuPlat Editor
2. Create an audio engine in PureData
3. Get those two files onto your mobile device. (Drag those two files into the MobMuPlat Documents folder in iTunes, or use Android File Transfer, or email/Dropbox/Google Drive/etc them into your device.)
4. Play your app on your mobile device!

Check out the provided tutorials and example files for lots of ways to do things...probably a faster way to learn than reading this page.

Making something on your computer

Open up the MobMuPlatEditor

Click the "Doc" tab to set document-wide properties

Screen Size determines the aspect ratio and size of the canvas, but this interface will still run on any device.
Specify the name of the Pd file you'll be using; while this can communicate with any open Pd patch on your computer, this entry tells MobMuPlat app which pd patch to load when you open the interface on the device.

Click the "Add" tab to add some GUI controls!

Move them around, resize them, copy/paste, etc...

Click the "Prop" tab to set properties for individual GUI controls

All controls have an address, color, and highlight color. Most controls have additional type-specific parameters.
Give each control a unique address.

Click the "Lock" tab to disable editing, and interact with the controls

The console will show what OSC messages you are sending in and out of the interface

Now launch PureData vanilla (.46 and above), open "PdWrapper.pd", and create a new patch.

The wrapper file simulates the message routing that the MobMuPlat app does, which will send/receive GUI messages between the editor and the Pd patch. These use an OSC-style address to be routed to/from a particular widget with that address.

Here's all the ways to get info in/out of the PureData patch.

look at "MobMuPlatTemplate.pd" for this.
The possible "system" messages (sensors, GPS, etc) are specified below

Loading it onto your device

MobMuPlat finds whatever files it is looking for (.mmp, .pd, audio, images) in its documents folder. All files must be at the top level, there is no folder structure. MobMuPlat will also automatically decompress zip files for you (BUT make sure the zip file has no folders).

There are two ways to get files in there.

1) Via iTunes or Android File Transfer

connect your device to your computer, open iTunes, click on your device on the left sidebar, then click "apps" along the top, scroll down to "File Sharing", click MobMuPlat, and drag your .mmp and .pd file (or anything else) into the "MobMuPlat Documents" pane
If you dragged in a zip, you'll have to go to the app, go to the file list, hit "show all files", and touch the zip in order to decompress it.

For Android File Transfer, just drag the files into the MobMuPlat folder (which is automatically created the first time you run MobMuPlat).

2) Via any other way to get files onto your device

MobMuPlat is associated with .mmp, .pd, and .zip files. So if you can get a hold of those files on the device (via Mail, Dropbox, Mobile Safari, etc), click on it, and you should be able to "open in MobMuPlat". This copies the file into the documents folder (but does not launch the interface). Zip files will automatically be unzipped and its files copied into the documents folder.

GUI Widgets

  • "attributes" describe properties of the widget defined in the editor.
  • "output" is messages that the GUI widget sends to the Pd patch, via [receive fromGUI].
  • "input" is messages that the Pd patch can send to the GUI widget, via [send toGUI].



All GUI widgets:

  • attributes:
    • color
    • highlight color
    • address: a string that names the object as a source or destination of OSC messages. Multiple widgets may have the same address.
  • input:
    • "enable 1" or "enable 0" to enable/disable the widget. (Defaults to enabled.)

Slider

  • attributes:
    • range
    • horizontal or vertical
  • output:
    • 0.0-1.0 float if range is 2
    • 0 to (N-1) int for range N (if N is greater than 2)
  • input:
    • float or int to set and output value
    • send "set x" to set value x without triggering output

Knob

  • attributes: range
  • output:
    • 0.0-1.0 float if range is 2
    • 0 to (N-1) int for range N (if N is greater than 2)
  • input:
    • float or int to set and output value
    • send "set x" to set value x without triggering output

Button

  • attributes:none
  • output: 1 on press down, 0 on press up
  • input: any float or int will trigger button press and immedate release

Toggle

  • attributes:
    • border thickness
  • output:
    • 1 for toggle on, 0 for toggle off
  • input:
    • 0 or 1 to toggle on/off
    • send "set x" to set value x without triggering output

Label

  • attributes:
    • font size
    • font family
    • font type
  • output:none
  • input:
    • "highlight" + 0 or 1, to toggle highlight color
    • any message will set the text

XY Slider

  • attributes:none
  • output:
    • pair of floats 0.0-1.0 for x + y position
  • input:
    • pair of floats 0.0-1.0 to set value
    • send "set x y" to set values without triggering output

Grid

  • attributes:
    • mode: toggle (default), momentary (like buttons), or hybrid (like a button, unless you drag your finger away).
    • x dimension of grid
    • y dimension of grid
    • thickness of cell border
    • padding between grid cell
  • output:
    • on toggle cell, output three element list: cellX, cellY, value (0 or 1)
    • on receiving "getcolumn N", output: "column" followed by values of column N
    • on receiving "getrow N", output: "row" followed by values of row N
  • input:
    • trio of numbers to set a grid cell: cellX, cell Y, value (0 or 1)
    • prepend above message with "set" to set values without triggering output
    • "clear" to clear grid

Multi Slider

  • attributes:
    • number of sliders
  • output:
    • list of values 0.0-1.0
  • input:
    • list of values
    • length of input list will resize number of sliders

Panel

  • attributes:
    • image path
    • allow touches to scroll: default is off, which blocks touches from scrolling the interface. When on, touches "pass through" and scroll the interface.
  • output: none
  • input:
    • to set a new image: "image" + pathname
    • "highlight" + 0 or 1, to toggle higlight color

LCD (see 2Dgraphics example for better info)

  • attributes:
    • image path
  • output: on touch, sends out three-float list.
    • first element is "1" on touch down, "2" on drag, "0" on touch up
    • second and third elements are x and y touch position, normalized 0.-1.
    • input:
    • (all values below are 0.-1. except penwidth)
      • "framerect" + 4 floats (left x, top y, right x, bottom y) - uses widget's highlight color
      • "framerect" + 8 floats (left x, top y, right x, bottom y, red, green, blue, alpha)
      • "paintrect" + 4 floats (left x, top y, right x, bottom y) - uses widget's highlight color
      • "paintrect" + 8 floats (left x, top y, right x, bottom y, red, green, blue, alpha)
      • "frameoval" + 4 floats (left x, top y, right x, bottom y) - uses widget's highlight color
      • "frameoval" + 8 floats (left x, top y, right x, bottom y, red, green, blue, alpha)
      • "paintoval" + 4 floats (left x, top y, right x, bottom y) - uses widget's highlight color
      • "paintoval" + 8 floats (left x, top y, right x, bottom y, red, green, blue, alpha)
      • "framepoly" + N floats (specify N/2 points as a list of x/y pairs) - uses widget's highlight color
      • "framepolyRGBA" + N+4 floats (specify N/2 points as a list of x/y pairs, red, green, blue, alpha)
      • "paintpoly" + N floats (specify N/2 points as a list of x/y pairs) - uses widget's highlight color
      • "paintpolyRGBA" + N+4 floats (specify N/2 points as a list of x/y pairs, red, green, blue, alpha)
      • moveto + 2 floats (x,y)
      • lineto + 2 floats (x,y)
      • lineto + 6 floats (x,y,red,green,blue.alpha)
      • penwidth + 1 float (width in pixels)

Multitouch

  • output: on every touch and move, these messages are sent, each followed by three elements per touch: voice index, x position, y position.
    • "touchesByTime", followed by three-elements-per-touch, sorted by recency
    • "touchesByVox", followed by three-elements-per-touch, sorted by voice index
    • "touchesByX", followed by three-elements-per-touch, sorted by x position
    • "touchesByY", followed by three-elements-per-touch, sorted by y position

Menu

  • attributes:
    • Title
  • output: on touch, sends out two element list.
    • first element is index
    • second element is string value
  • input: a list of strings to populate the menu.

Table

  • attributes:
    • Touch Mode: "Select" allows you to drag a range; "Draw" directly changes table values.
    • Selection Color
  • output:
    • in "Select" mode, send out two element list of the selected range.
    • in "Draw" mode, no output.
  • input: "refresh" will reload the table data into the GUI widget.

System messages

[receive fromSystem]

  • "/shake (int)" - a shake gesture occured (value is always 1). Currently iOS only.
  • "/tilts (float) (float)" - "cooked" XY tilt values -1 to 1
  • "/accel (float) (float) (float)" - raw accelerometer data, x,y,z, range -1 to 1
  • "/gyro (float) (float) (float)" - gyro data, in radians per second, around roll, pitch, yaw, range -pi to +pi
  • "/motion (float) (float) (float)" - device attitude in space, at roll, pitch, yaw, range -pi to pi
  • "/accelFrequency (float)" - accelerometer and tilt data frequency, in hertz (default 10). Sent on request. Currently iOS only.
  • "/gyroFrequency (float)" - gyro data frequency, in hertz (default 10). Sent on request. Currently iOS only.
  • "/motionFrequency (float)" - device motion frequency, in hertz (default 10). Sent on request. Currently iOS only.
  • "/location (followed by 9 floats)" - device location info. See MMPExamples-GPS.pd for full explanation.
  • "/distanceFilter (float)" - GPS location update filter, in meters (default 1.0). Val <= 0 sends all updates. Sent on request. Currently iOS only.
  • "/compass (float)" - compass value, in degrees
  • "/page (int)" - sent whenever user scrolls to new page
  • "/timeList" - timestamp as a seven-element list: year, month, day, hour, minute, second, millisecond.
  • "/timeString" - timestamp as a human-readable message
  • "/hid (device index) (axis or button name) (value)" - receive a HID message from a joystick/gamepad. Currently Android only. Currently only supports one device at a time, so device index value is always zero. See HID example patch for more details.
  • "/ipAddress (ip as string)" - sent in response to sending "/getIpAddress" via [send toSystem]
  • "/textDialog (tag string) (input string)" - sent in response to user interaction with a text dialog, triggered by "/textDialog" input via [send toSystem]
  • "/confirmationDialog (tag as string) (button index as float)" - sent in response to user interaction with a confirmation dialog, triggered by "/confirmationDialog" input via [send toSystem]

[send toSystem]

  • "/flash (int)" - turn on off flash with value of one or zero.
  • "/setAccelFrequency (float)" Currently iOS only.
  • "/getAccelFrequency " - returns value via "/accelFrequency". Must be sent as a list. Currently iOS only.
  • "/setGyroFrequency (float)" Currently iOS only.
  • "/getGyroFrequency ." - returns value via "/gyroFrequency". Must be sent as a list. Currently iOS only.
  • "/setMotionFrequency (float)" Currently iOS only.
  • "/getMotionFrequency " - returns value via "/motionFrequency". Must be sent as a list. Currently iOS only.
  • "/setDistanceFilter (float)" Currently iOS only.
  • "/getDistanceFilter " - returns value via "/distanceFilter". Must be sent as a list. Currently iOS only.
  • "/vibrate 0" and "/vibrate 1" trigger two different vibrations.
    • On iOS: Proper audio state (override mic in) must be set in the MobMuPlat audio options
    • on Android, you may additionally replace the argument with a vibration duration in milliseconds, e.g. "/vibrate 500"
  • "/setPage (int)" - programatically scroll to interface page N.
  • "/getTime" - request timestamp, generates /timeList and /timeString output messages.
  • "/getIpAddress" - request IP address, returns value with "/ipAddress" via [receive fromSystem]
  • "/textDialog (tag as string) (title as string)" - Shows a text input dialog. Returns value with "/textDialog" via [receive fromSystem]
  • "/confirmationDialog (tag as string) (title as string)" - Shows a confirmation dialog. Returns value with "/confirmationDialog" via [receive fromSystem]

Networking

MobMuPlat sends OSC messages on a network via UDP. There are three ways to do it. Go to the "Networking" settings page. In all cases, a local router is recommended. In all cases, the PureData message examples are connected to a [send toNetwork] object. See the tutorial and example patches for more information.

  • "Multicast & Direct" : This sends a message to an IP address. This may be a single unicast address (e.g., the address of your laptop on your wifi network, to send messages to your laptop), or a multicast address (to send messages to all devices on the network). The default is via multicast at 224.0.0.1, but you may specify a direct connection to a single IP address. You need to use a local WiFi router to send to local machines, this will not send information over the internet. You may also set the input and output port numbers.

    You can send/receive OSC messages to/from any OSC-enabled software or language, such as Max/MSP, Abelton Live, etc. You may also send/receive from other apps on the device (e.g. TouchOSC, etc.).

    Example puredata messages: [list /myParameter myValue (


  • "Ping & Connect" : This is a custom networking protocol for improved many-to-many communication. All devices must be "Ping & Connect" enabled to be aware of other devices and receive messages from them. Each client pings out its player number and IP address via multicast. Each client keeps track of other clients on the network, and may send unicast messages to all clients, or to individual clients by player number.

    All messages are prefixed by 1) the symbol "/send", and 2) the player number to send to (or the symbol "all" or "allButMe"). (A client may also specify itself as the server.) The messages then show up at the destination (without the first two elements).

    Example PureData messages:
    • Send a message to all clients (including back to the sender): [list /send all /myParameter myValue (
    • Send a message to player #4: [list /send 4 /myParameter myValue (

    You can also use these messages (via [send toNetwork]) to query or affect the state of Ping & Connect networking:
    • "/playerCount" - returns "/pingandconnect/playerCount (float)" via [receive fromNetwork]
    • "/playerNumberSet" - returns "/pingandconnect/playerNumberSet (list of float)" via [receive fromNetwork]
    • "/myPlayerNumber" - returns "/pingandconnect/myPlayerNumber (float)" via [receive fromNetwork]
    • OR "/pingandconnect/myPlayerNumber" - returns "/pingandconnect/myPlayerNumber (float)" via [receive fromNetwork]
    • "/pingandconnect/enable (1 or 0)" - enable/disable protocol programatically from the patch
    • "/pingandconnect/isEnabled" - returns "/pingandconnect/isEnabled (1 or 0 float)" via [receive fromNetwork]


  • "LANdini" : A custom networking protocol for many-to-many communication, with guaranteed delivery and ordering. See the "LANdini" example for more info on LANdini. All devices must be LANdini enabled to be aware of other devices and receive messages from them. Each client pings out its name and other information, and every client keeps a record of the other clients' states.

    All messages are prefixed by 1) sending protocol ("/send", "/sendGD", or "/sendOGD"), 2) a destination ("all", "allButMe", or a user's name), 3) the rest of the user message. The messages then show up at the destination (without the first two elements).

    Example PureData messages:
    • Send a guaranteed-to-be-delivered message to all clients except the sender:
      [list /sendGD allButMe /myParameter myValue (


    You can also use these messages (via [send toNetwork]) to query or affect the state of Ping & Connect networking:
    • "/numUsers" - returns "/landini/numUsers (float)" via [receive fromNetwork]
    • "/userNames" - returns "/landini/userNames (list of strings)" via [receive fromNetwork]
    • "/networkTime" - returns "/landini/networkTime (float)" via [receive fromNetwork]
    • "/myName" - returns "/landini/myName (string)" via [receive fromNetwork]
    • "/landini/enable (1 or 0)" - enable/disable protocol programatically from the patch
    • "/landini/isEnabled" - returns "/landini/isEnabled (1 or 0)" via [receive fromNetwork]

Audio and MIDI

Audio is sent to the speakers within PureData via the [dac~] object, which is routed to the proper hardware (device speakers, headphones, etc). Mic input is via the [adc~] object; use headphones to avoid feedback. In iOS, external class compliant USB interfaces are supported. Note that multichannel audio is supported, but must be enabled with a switch in the Audio & Midi settings page.

MIDI: In the app, select a MIDI input device. MIDI messages will then be routed to the appropriate MIDI PureData object ([notein], etc). You can send MIDI from other apps; in order to keep the MobMuPlat audio engine running, go to the app's Audio & Midi settings page and enable background audio.

Contact

questions? bug reports? email: info -AT- mobmuplat.com
How to find iOS crash logs