gibberwocky.max communication spec

gibberwocky.max.websocket.spec.md

gibberwocky communicates using the websocket protocol with a max4live plugin. Theoretically any client should be able to interface with the plugin using this websocket interface.

Everytime the Abelton timeline advances a beat, the max4live plugin sends a request to the gibberwocky client for the subsequent beat's events. For example, on beat 3, the plugin will send a request for all events that should occur during beat 4. This one beat of latency ensures that all messages arrive with plenty of time to spare. Alternative interfaces to the gibberwocky client could ignore these messages and implement their own timing strategies (using Ableton Link or MIDI clock etc.)

Read more about the project here: http://www.charlie-roberts.com/pubs/Live_Coding_DAW.pdf

What browser sends to Live:

Many messages below accept a beat / phase for scheduling messages in the future. If you want to simply trigger a message immediately, omit the "add beat phase" parameters of the message. For example, to send a note immediately use "Track_id note pitch volume duration" instead of "Track_id add beat phase pitch volume duration".

• Global

  • “get_scene” Request the current LOM
  • “select_parameter param_id”
  • “select_track track_id” Select a particular track (by id)

• Send MIDI notes (pitch-velocity-duration) to a track’s device

  • “Track_id add beat phase pitch N”
  • “Track_id add beat phase velocity N”
  • “Track_id add beat phase duration N”
  • “Track_id add beat phase note P V D” sends all info at once

• Mute/solo tracks

  • “Track_id add beat phase mute 0/1”
  • “Track_id add beat phase solo 0/1”
    • The LOM docs remark: when setting this property, the exclusive solo logic is bypassed, so you have to unsolo the other tracks yourself.

• Set any device parameter (instantaneous, no limits)

  • “add beat phase set param_id N”
    • (maps 0..1 to the parameter’s min/max range)
  • “add beat phase zet param_id N”
    • (sets the parameter value directly, not mapping to min/max range)

• Map a gen~ LFO onto a device parameter (we will have limit to how many we can use, e.g. 16)

  • “add beat phase gen param_id \”GenExpr\””
    • E.g. “0 add 3 0.5 342 \”cycle(4)\””

• Change parameters on an existing gen~ graph:

  • “add beat phase genp param_id param_name N”
    • Param_name corresponds to a Param object in the GenExpr (silent error if the parameter is not mapped or the param doesn’t exist)

• send a ‘disconnect’ gen~ too, marks it as free

  • “add beat phase ungen param_id”

• Broadcast Sends a message to the max4live plugin, which then forwards it to all connected gibberwocky client

  • “*msg….” (sender will have to filter on the self_id, e.g. session id, e.g. a random number)

What live sends to browser:

• Full LOM

  • “JSON” (check if charAt(0) == “{“)
    • On patcher load, and when queried.

• Request for next beat’s events

  • “track_id seq N”

• Error messages

  • “track_id err msg...”

• Play/rewind etc.

  • “track_id ply 0/1” (play)
  • “track_id bar N”
  • “track_id bit N” (beat)

• Time signature bpm etc.

  • “track_id bpm N”
  • “track_id sig N/N”

• Gen snapshots (30 Hz)

  • “snapshot param_id value param_id value …”

Despite the filename, this is the gibberwocky for live spec, not the gibberwocky for max spec

I've placed a gibberwocky for max spec here: https://github.com/worldmaking/max_gibberwocky_package/blob/master/gibberwocky.max.websocket.spec.md