Quick example:

sh: sendOSC -h localhost 9999

/video/play
/clip/select 2
/effect_key/enable 8
/effect_key/enable 3
/clip/select 1
/effect_key/disable 8
/video/reverse
/video/speed 10
/video/stop
/lives/quit


-------------------------

OSC in LiVES. 

LiVES now implements a standard version of Open Sound Control (http://www.opensoundcontrol.org)
which is being extended to OMC (Open Media Control) by members of Piksel.

LiVES currently supports libOSC and sendOSC from here:

http://www.cnmat.berkeley.edu/OpenSoundControl/index.html

LiVES is now compiled with OSC support by default. There are several
ways to activate it:

start up LiVES with, e.g.: lives -oscstart 9999

this will start up LiVES with OSC enabled on port 9999.

Or, start up LiVES normally and go to Tools/Preferences/Streaming. Here
you can ask LiVES to open a UDP port (default 9999, this can be changed). You can also ask LiVES to open an 
OSC port every time it starts up (doing this can be a security risk, please check your firewall settings 
first !)

You can then send commands using sendOSC. The autolives.pl script shows a sample implementation of it.
If using the default port (9999) you can just type: autolives.pl, for other ports, use 
autolives.pl localhost <port> where <port> is the UDP port number in Preferences.
You can also run autolives.pl from another host using autolives.pl <host> <port>

Note that there is a default latency of up to 40ms for OSC commands to be processed in LiVES.
Depending on what the application is doing, commands could be processed slower than that.



INCOMING MESSAGES
-----------------
This is actually implemented now using the keyboard timer, so there is a default maximum latency of 40 ms.

Currently timecodes are ignored.

Floats are now supported, but be aware that pd (pure data) will
sometimes send a float as an int (for example (float)1.0 is sent as (int)1).








=============================================================================
Current implemented commands:

Variables are shown as <variable> in angle brackets,


/lives/open_status_socket,<host>,<port_number> ::
/app/open_status_socket,<host>,<port_number>  ::

command lives to open a status socket to (string)host on UDP port (int)port_number

If host is omitted, "localhost" is assumed.


/lives/open_notify_socket,<host>,<port_number> ::

command lives to open a notify socket to (string)host on UDP port (int)port_number

The notify socket will send various message numbers and strings. See
the file osc_notify.h for details.

If host is omitted, "localhost" is assumed.


/lives/ping
/app/ping  :: return "pong" on the status socket


/clip/open/file,<file_name>
causes LiVES to open/import file_name as a new clip


/lives/clipset/save,"set_name"
/lives/clipset/load,"set_name"


/video/play :: begin playback (video and audio)
/video/stop :: stop playback (video and audio)
/video/set/fps,<fps> :: set playback fps of current clip (fps can be
float or int)
/video/reverse :: reverse direction (video only)


/clip/select,<clip_number> :: switch clips to <clip_number>

switch to (int)clip_number. If clip does not exist, no switching 
will occur. LiVES will return an error code no_such_clip [not yet implemented]. 
Clip numbers start at 1 and go up, sometimes there may be gaps.


/clip/get/current  ::
return the number of the current clip on status socket

/clip/get/frames,<clip>  ::
return number of frames in (int) clip on status socket
if ,clip is omitted, the current clip is used
if -1 is returned, the clip is not valid [ni]

/clip/get/start,<clip>  ::
return selection start in (int) clip on status socket
if ,clip is omitted, the current clip is used
if -1 is returned, the clip is probably not valid [ni]

/clip/get/end,<clip>  ::
return selection end in (int) clip on status socket
if ,clip is omitted, the current clip is used
if -1 is returned, the clip is probably not valid [ni]

/clip/goto,<frame> ::
jump to frame in current clip. Only works if LiVES is playing

/clip/set/start,<frame>  ::
set selection start of current clip

/clip/set/end,<frame>  ::
set selection end of current clip

/clip/select_all ::
select all frames in current clip

/clip/play_selection ::
play just the current selection of the current clip
beware of clip switching [ni]

/clip/is_valid,<clip>  ::
return 1 if (int)clip is a valid clip, 0 otherwise
[LiVES NOTE: clips can be closed asynchronously by the user or
automatically at any time]


/effect_key/count ::
return the number of keys which can be bound to real time effects


/effect_key/get/userkeys ::
return the number of keys which can be bound to real time effects and are controllable from the keyboard


/effect_key/enable,<effect_key_number> ::

switch on realtime effect number (int)effect_key_number for the foreground frame.
effects start at 1 in LiVES. If the effect number is invalid nothing will happen but an error code will be 
returned on the status socket. In LiVES, real time effects are mapped from effect_keys.


/effect_key/disable,<effect_key_number> ::
Switch off realtime effect key.

[LiVES NOTE: some effects will auto-disable themselves: after a cetain time, when playback ends, or when a clip is switched.]


/effect_key/reset ::
reset all effect keys [LiVES NOTE : generators/sources in the foreground are not stopped]

/effect_key/is_userkey,<effect_key>  ::
return 1 if (int)effect_key is a user key, 0 otherwise [ni]

/effect_key/get/maxmode,<effect_key>  :: return number of modes for (int)effect_key. returns 0 for invalid keys


/effect_key/get/mode,<effect_key> :: get current mode for (int)effect_key. modes start at 1
                                     a mode of zero means invalid key


/effect_key/set/mode,<effect_key>,<mode> :: switch (int)mode for (int)key. If the effect key is enabled, 
                                 the old effect will be disabled, the new one enabled. modes start at 1
                                 a mode of zero or > maxmodes will be ignored


/effect_key/get/name,<effect_key>,<mode> :: return name of realtime effect bound to (int)key,(int)mode
                                        :: returns empty string if invalid

/output/fullscreen/enable  :: switch to fullscreen/separate window, activate any playback plugins
/output/fullscreen/disable :: switch to in-gui playback, deactivate any playback plugins


/output/set/fps,<fps>  :: set display fps to (int)fps. will become float
/output/nodrop/enable :: disallow frame dropping (can cause a/v sync problems)
/output/nodrop/disable :: allow frame dropping (better a/v sync)


/broadcast/quit :: 
/app/quit :: 
/lives/quit :: quit the app [LiVES NOTE: this will preserve any VJ set which was loaded]


/effect_key/map/clear :: clear mapping of all effects from all keys

/effect_key/map,<key_number>,<hashname> :: map effect to next free
mode on key <key_number> - hashname is a concatenation of
package,author,filter (and optionally version)


/effect_key/set/parameter,<key_number>,<parameter_number>,<value(s)>
:: set <value(s)> for <parameter_number> on key <key_number>



/record/start :: start recording performance (or if not playing,
prepare to record)

/record/stop :: stop recording performance (or if not playing, cancel recording)






=====================================================================================================



To be added soon:

/lives/autowarn/enable  :: dismiss all warnings
/lives/autowarn/disable :: do not dismiss warnings



/video/freeze :: freeze video only (audio continues)

/video/skip_forward :: skip forwards a little (audio continues normally)
/video/skip_backwards :: skip backwards a little (audio continues normally)


/effect_key/get/effect,key,mode   :: return number of effect bound to this key/mode, or 0
/effect_key/get/mode,key :: get current mode for key. By default this is 0
/effect_key/map,key,mode,effect :: map a realtime effect to a key/mode pair (key>userkeys)
/effect_key/unmap,key,mode :: unmap a realtime effect from a key/mode pair (key>userkeys)
/effect_key/get_type/param,key,paramnumber :: get a parameter type for the key/current mode, only works if effect is enabled  :: types use OSC tags, eg. i for int, f for float, s for string
/effect_key/get/param,key,paramnumber :: get a parameter for the key/current mode, only works if effect is enabled


/effect/count
/effect/list

/clip/fg_select clip_number :: not implemented yet
/clip/bg_select clip_number :: not implemented yet


/effect/bg/enable effect_number :: not implemented
/effect/bg/disable effect_number :: not implemented
/effect/bg/reset                 :: not implemented

/effect/fg/enable :: synonym for /effect/enable [not implemented]

/app/fullscreen/enable
/app/fullscreen/disable

/lives/sepwin/enable
/lives/sepwin/disable


====================================================================
Planned but not implemented:



/effect/rendered/enable,1  ::  Apply rendered effect to current selection
/effect/rendered/list  :: returns list of rendered effects, name;number
/effect/rendered/count  :: returns count of rendered effects
 



/clip/restore,/usr/local/backup.lv1
/lives/status
                                                   HOLD|12345678|msg
/lives/status
                                                   READY|12345678|msg

/lives/status
                                                   WAIT|12345678|msg
                                                   HOLD|12345678|msg





Queries
-------
/

returns:
"/name"
"/video"
"/clip"
"/effect_key"
"/app"
"/broadcast"


In LiVES:

/name/
sets last status message:

"lives"

/effect/

sets last status message:

"/effect/rendered"
"/effect/enable"

etc.


/app/

sets last status message:

"/app/quit"

etc.

/broadcast/

sets last status message:

"/broadcast/quit" (be careful not to send this on a broadcast command port !)

etc.






/lives/open_notify_socket port_number
invite lives to open a separate notification socket on UDP port (int) port_number
[not yet implemented]
Can also be set by user in prefs (not impl.)

/lives/disable_external_sync :: Normal playback (default) [not implemented]

/lives/enable_external_sync  :: Ask LiVES to wait for a /lives/sync message before sending a frame. LiVES will also send SYNC messages when it is recording and is ready for the next frame. Currently, if your app returns SET_SYNC as a possible command, LiVES will try to set this ON in your app when you connect.  [not implemented]



/stream/new/y4m ::
------
Ask LiVES to stream yuv4mpeg on stdout. Only works if LiVES was compiled with mjpegtools). [not implemented] To pause the stream currently you can enable/disable fullscreen/and or sepwin modes.


/stream/pause/y4m ::
Pause the y4m stream (not implemented)




/lives/enable_noshow ::
---------------
If ON, LiVES will not show frames in its GUI when playing or recording. [not impleemented]

/lives/disable_noshow ::
---------------
default [n/i]
















/clip/isvalid clip_number ::
sets last status message to number of clips loaded. Could be used to determine if a user has loaded or closed additional clips. [n/i]



Possible stuff to be implemented:




OPEN_FILE_SELECTION FILENAME START_TIME NUMBER_OF_FRAMES ::
--------------------------------------------------------
Opens an audio or video file. Set START and NUMBER_OF_FRAMES to 0 to load a whole file/directory. Sets the status for this clip to WAIT, until loading is complete.



RESTORE_BACKUP BACKUP_FILE_NAME  ::
------------------------
Restore a LiVES (.lv1) backup file. LiVES cannot currently play or switch clips whilst restoring. Sets the status to HOLD.




CLOSE_CURRENT_CLIP ::
------------------



SET_LOOP_CONTINUOUS (BOOLEAN)



SET_LOOP_PING_PONG (BOOLEAN)::
-------------


SET_SELECTION_START FRAME


SET_SELECTION_END FRAME


GET_SELECTION_START


GET_SELECTION_END


PLAY_SELECTION :: play from selection_start to selection_end

PLAY_PREVIEW :: preview an effect with a long render time

USE_LAYER :: Tell LiVES to use LAYER (INT)LAYER if you support layers.
USE_STREAM :: A synonym for USE_LAYER

RENDER_EFFECT... :: send frames to LiVES for effects with long processing times.
                 By sending such frames to LiVES you can continue playing while 
		 LiVES performs the render.


SAVE_START_FRAME FILENAME

SAVE_END_FRAME FILENAME


SAVE_CLIP FILENAME


BACKUP_CLIP FILENAME.LV1


COPY_SELECTION

INSERT_SELECTION TIMES

REVERSE_CLIPBOARD

PASTE_AS_NEW

DELETE_SELECTION

LOAD_AUDIO

LOAD_CD_TRACK TRACK


RELOAD_SET SETNAME


DOUBLESIZE ON|OFF


RESIZE_ALL :: sets STATUS to HOLD.

CANCEL  :: If the status is HOLD or WAIT, you can send a CANCEL. You should keep checking until the status is READY. 


ENOUGH :: If the status is HOLD or WAIT you can send an ENOUGH message. You should keep checking until the status is READY. The exception is for RESTORE_BACKUP messages, which will ignore ENOUGH requests.






/lives/toy/MAD_FRAMES ON|OFF  ::  mad frames toy


/lives/status :: Not yet implemented
/app/status :: synonym
------
return a LiVES status.

STATUS will be one of:

READY|CLIP_NUMBER|LAST_MESSAGE
WAIT|CLIP_NUMBER|LAST_MESSAGE
HOLD|CLIP_NUMBER|LAST_MESSAGE

PLAYING|CLIP_NUMBER|FRAME_NUMBER|FPS|IMG_HSIZE|IMG_VSIZE|LAST_MESSAGE

CLIP_NUMBER is the current clip number. The current clip number may change asynchronously in LiVES, and a stored clip number may not be valid. You will be able to check if a clip number is valid using /clip/isvalid clip_number [not implemented]. For a freshly loaded set, clips will be numbered 1 - N. You can get N with /clip/getnumber [not implemented].

LAST_MESSAGE is the message number of the last message received from APP. 

Message returning is not yet implemented in LiVES.


