SooperLooper - Documentation :: OSC Interface

#### Live Looping Sampler

#### Documentation ::: OSC Interface

The SooperLooper engine is controlled via OSC. An incomplete specification for the API is described below.

OSC interface to SooperLooper engine

    Arguments are prefixed with a letter: where  s = string, i = integer, f = float

    PING the engine

     /ping s:return_url s:return_path

     If engine is there, it will respond with to the given URL and PATH
      with an OSC message with arguments:
         s:hosturl  s:version  i:loopcount

    Loop commands and parameter gets/sets paths are all prefixed with:
      /sl/#/   where # is the loop index starting from 0.
    Specifying -1 will apply the command or operation to all loops.
    Specifying -3 will apply the command or operation to the selected loop.

    COMMANDS:

    /sl/#/down s:cmdname
      command press

    /sl/#/up s:cmdname
      command release

    /sl/#/forceup s:cmdname
      forced release to do SUS-like actions

    /sl/#/hit s:cmdname
      A single hit only, no press-release action

      Where cmdname is one of the following:

      record
      overdub
      multiply
      insert
      replace
      reverse
      mute
      undo
      redo
      oneshot
      trigger
      substitute
      undo_all
      redo_all
      mute_on
      mute_off
      solo
      pause
      solo_next
      solo_prev
      record_solo
      record_solo_next
      record_solo_prev
      set_sync_pos
      reset_sync_pos

    SET PARAMETER VALUES

    /sl/#/set  s:control  f:value
       To set a parameter for a loop.

     where control is one of:

      rec_thresh  	:: expected range is 0 -> 1
      feedback    	:: range 0 -> 1
      dry         	:: range 0 -> 1
      wet         	:: range 0 -> 1
      input_gain    :: range 0 -> 1
      rate        	:: range 0.25 -> 4.0
      scratch_pos  	 :: 0 -> 1
      delay_trigger  :: any changes
      quantize       :: 0 = off, 1 = cycle, 2 = 8th, 3 = loop
      round          :: 0 = off,  not 0 = on
      redo_is_tap    :: 0 = off,  not 0 = on
      sync           :: 0 = off,  not 0 = on
      playback_sync  :: 0 = off,  not 0 = on
      use_rate       :: 0 = off,  not 0 = on
      fade_samples   :: 0 -> ...
      use_feedback_play   :: 0 = off,  not 0 = on
      use_common_ins   :: 0 = off,  not 0 = on
      use_common_outs   :: 0 = off,  not 0 = on
      relative_sync   :: 0 = off, not 0 = on
      use_safety_feedback   :: 0 = off, not 0 = on
      pan_1        	:: range 0 -> 1
      pan_2        	:: range 0 -> 1
      pan_3        	:: range 0 -> 1
      pan_4        	:: range 0 -> 1
      input_latency :: range 0 -> ...
      output_latency :: range 0 -> ...
      trigger_latency :: range 0 -> ...
      autoset_latency  :: 0 = off, not 0 = on
      mute_quantized  :: 0 = off, not 0 = on
      overdub_quantized :: 0 == off, not 0 = on
      discrete_prefader :: 0 == off, not 0 = on

    GET PARAMETER VALUES

    /sl/#/get  s:control  s:return_url  s: return_path

      Which returns an OSC message to the given return url and path with
      the arguments:
          i:loop_index  s:control  f:value

     Where control is one of the above or:

      state   ::   -1 = unknown,
    		0 = Off
    		1 = WaitStart
    		2 = Recording
    		3 = WaitStop
    		4 = Playing
    		5 = Overdubbing
    		6 = Multiplying
    		7 = Inserting
    		8 = Replacing
    		9 = Delay
    		10 = Muted
    		11 = Scratching
    		12 = OneShot
    		13 = Substitute
    		14 = Paused

      next_state  :: same as state

      loop_len  :: in seconds
      loop_pos  :: in seconds
      cycle_len :: in seconds
      free_time :: in seconds
      total_time :: in seconds
      rate_output
      in_peak_meter  :: absolute float sample value 0.0 -> 1.0 (or higher)
      out_peak_meter  :: absolute float sample value 0.0 -> 1.0 (or higher)
      is_soloed       :: 1 if soloed, 0 if not

    SAVE/LOAD

    /sl/#/load_loop   s:filename  s:return_url  s:error_path
       loads a given filename into loop, may return error to error_path

    /sl/#/save_loop   s:filename  s:format  s:endian  s:return_url  s:error_path
       saves current loop to given filename, may return error to error_path
       format and endian currently ignored, always uses 32 bit IEEE float WAV

    /save_session   s:filename  s:return_url  s:error_path
       saves current session description to filename.

    /load_session   s:filename  s:return_url  s:error_path
       loads and replaces the current session from filename.

    GLOBAL PARAMETERS

    /set  s:param  f:value
    /get  s:param  s:return_url  s:retpath
       where param is one of:

      tempo  :: bpm
      eighth_per_cycle
      dry         	:: range 0 -> 1 affects common input passthru
      wet         	:: range 0 -> 1  affects common output level
      input_gain    :: range 0 -> 1  affects common input gain
      sync_source  :: -3 = internal,  -2 = midi, -1 = jack, 0 = none, # > 0 = loop number (1 indexed)
      tap_tempo :: any changes
      save_loop :: any change triggers quick save, be careful
      auto_disable_latency  :: when 1, disables compensation when monitoring main inputs
      select_next_loop  :: any changes
      select_prev_loop  :: any changes
      select_all_loops   :: any changes
      selected_loop_num   :: -1 = all, 0->N selects loop instances (first loop is 0, etc)

    LOOP ADD/REMOVE

    /loop_add  i:#channels  f:min_length_seconds
      adds a new loop with # channels and a minimum loop memory

    /loop_del  i:loopindex
      a value of -1 for loopindex removes last loop, and is the only
      value currently recommended.

    SHUTDOWN

    /quit
       shutdown engine

    REGISTER FOR CONTROL CHANGES

     The following messages register and unregister from update events
     which will be sent the returl and retpath specified.  The update OSC message
     has the following parameters:
         i:loop#  s:ctrl  f:control_value

     /sl/#/register_update  s:ctrl s:returl s:retpath
     /sl/#/unregister_update  s:ctrl s:returl s:retpath

         registers/unregisters to receive updates for a given input control when
         any other client changes it.

     /sl/#/register_auto_update  s:ctrl i:ms_interval s:returl s:retpath
     /sl/#/unregister_auto_update  s:ctrl s:returl s:retpath

        registers/unregisters for automatic repeated updates at the given
        interval (currently ignored, and always at 100ms intervals).
        This is handy for receiving updates for output controls such as state
        and position.  The message is only sent if the control has changed since the
        last send.

     /register_update  s:ctrl s:returl s:retpath
     /unregister_update  s:ctrl s:returl s:retpath
     /register_auto_update  s:ctrl i:ms_interval s:returl s:retpath
     /unregister_auto_update  s:ctrl s:returl s:retpath

        These are the global control equivalents to the above.

     Finally, there is the command to register for any changes in loop count:

     /register s:returl s:retpath

    When the loop count changes it will send the same message that the /ping response does.

    MIDI BINDING CONTROL

      More details forthcoming......

     /get_all_midi_bindings  s:returl  s:retpath

     /remove_midi_binding  s:binding_serialization s:options

     /add_midi_binding  s:binding_serialization s:options

     /clear_midi_bindings

     /load_midi_bindings  s:binding_filename s:options

     /save_midi_bindings  s:binding_filename s:options

     /learn_midi_binding  s:binding_serialization s:options  s:returl s:retpath

     /get_next_midi_event    s:returl  s:retpath
        return next midi event in a binding serialization

     /cancel_midi_learn    s:returl  s:retpath
        cancel learn or get next midi event in a binding serialization

     /cancel_get_next_midi  s:returl  s:retpath

© 2005 Jesse Chappell <jesse at essej dot net>