Module losc
High level API.
Main module of losc.
Info:
- Copyright: David Granström 2021
- License: MIT
- Author: David Granström
Functions
| new (options) | Create a new instance. |
| new_message ([args]) | Create a new Message. |
| new_bundle ([...]) | Create a new OSC bundle. |
| use (plugin) | Specify a plugin to use as transport layer. |
| now () | Get an OSC timetag with the current timestamp. |
| open ([...]) | Opens an OSC server. |
| close ([...]) | Closes an OSC server. |
| send ([...]) | Send an OSC packet. |
| add_handler (pattern, func) | Add an OSC handler. |
| remove_handler (pattern) | Remove an OSC handler. |
| remove_all () | Remove all registered OSC handlers. |
Functions
- new (options)
-
Create a new instance.
Parameters:
- options table Options.
Usage:
local osc = losc.new()local osc = losc.new {plugin = plugin.new()}
- new_message ([args])
-
Create a new Message.
Parameters:
Returns:
-
message object
See also:
Usage:
local message = losc.new_message()local message = losc.new_message('/address')
local message = losc.new_message{address = '/test', types = 'iif', 1, 2, 3}
- new_bundle ([...])
-
Create a new OSC bundle.
Parameters:
- ... arguments. (optional)
Returns:
-
bundle object
See also:
Usage:
local tt = losc:now() local bundle = losc.new_bundle() bundle:timetag(tt) -- packet can be a message or another bundle bundle:add(packet)
local tt = losc:now() local bundle = losc.new_bundle(tt) bundle:add(packet)
local tt = losc:now() local bundle = losc.new_bundle(tt, packet, packet2)
- use (plugin)
-
Specify a plugin to use as transport layer.
Parameters:
- plugin The plugin to use, pass nil to disable current plugin.
- now ()
-
Get an OSC timetag with the current timestamp.
Will fall back to
os.time()ifnow()is not implemented by the plugin in use.Usage:
local tt = losc:now()-- 0.25 seconds into the future. local tt = losc:now() + 0.25
- open ([...])
-
Opens an OSC server.
This function might be blocking depending on the plugin in use.
Parameters:
- ... Plugin specific arguments. (optional)
Returns:
-
status, plugin handle or error
Usage:
losc:open()
- close ([...])
-
Closes an OSC server.
Parameters:
- ... Plugin specific arguments. (optional)
Returns:
-
status, nil or error
Usage:
losc:close()
- send ([...])
-
Send an OSC packet.
Parameters:
- ... Plugin specific arguments. (optional)
Returns:
-
status, nil or error
Usage:
-- can be message or bundle. local packet = losc.new_message{address = '/x', types = 'i', 1} losc:send(packet) -- additional plugin arguments (can vary between plugins) losc:send(packet, 'localhost', 9000)
- add_handler (pattern, func)
-
Add an OSC handler.
Parameters:
- pattern The pattern to match on.
- func
The callback to run if a message is received.
The callback will get a single argument
datafrom where the messsage can be retrived.
Usage:
osc:add_handler('/pattern', function(data) -- message table, can be converted to Message if needed. local message = data.message -- timestamp when message was received, can be converted to Timetag if needed. local timestamp = data.timestamp -- table with remote (sender) info, can be empty depending on plugin. local remote_info = data.remote_info end)
osc:add_handler('/pattern', function(data) -- arguments can be accessed by index from the message table local arg1 = data.message[1] local arg2 = data.message[2] -- iterate over incoming OSC arguments for _, argument in ipairs(data.message) do print(argument) end end)
-- Pattern matching (groups) osc:add_handler('/param/{x,y}/123', function(data) end) -- Pattern matching (sequence) osc:add_handler('/param/[a-f]/123', function(data) end) -- Pattern matching (sequence) osc:add_handler('/param/[!a-f]/123', function(data) end) -- Pattern matching (wildcard) osc:add_handler('/param/*/123', function(data) end) osc:add_handler('*', function(data) end)
- remove_handler (pattern)
-
Remove an OSC handler.
Parameters:
- pattern The pattern for the handler to remove.
Usage:
losc:remove_handler('/handler/to/remove') - remove_all ()
-
Remove all registered OSC handlers.
Usage:
losc:remove_all()