pyliblo 0.10 API Documentation

Homepage: https://github.com/mididings/pyliblo/

The latest version of this manual can be found at https://mididings.github.io/pyliblo/.

For the most part, pyliblo is just a thin wrapper around liblo, which does all the real work. For questions not answered here, also see the liblo documentation and the OSC spec.

Module-level Functions

send(target, *messages)
send(target, path, *args) → None

Send messages to the the given target, without requiring a server. Arguments may be one or more Message or Bundle objects, or a single message given by its path and optional arguments.

Parameters:

  • target – the address to send the message to; an Address object, a port number, a (hostname, port) tuple, or a URL.

  • messages – one or more objects of type Message or Bundle.

  • path – the path of the message to be sent.

Raises:

  • AddressError – if the given target is invalid.

  • IOError – if the message couldn’t be sent.

time()

Return the current time as a floating point number (seconds since January 1, 1900).

OSC Server Classes

class Server

A server that can receive OSC messages using a simple single-threaded polling model. Use ServerThread for an OSC server that runs in its own thread and never blocks.

__init__()

Server(port[, proto])

Create a new Server object.

Parameters:

  • port – a decimal port number or a UNIX socket path. If omitted, an arbitrary free UDP port will be used.

  • proto – one of the constants UDP, TCP, or UNIX; default is UDP.

  • reg_methods – False if you don’t want the init function to automatically register callbacks defined with the make_method() decorator (keyword argument only).

Exceptions: ServerError

recv(timeout=None)

Receive and dispatch one OSC message. Blocking by default, unless timeout is specified.

Parameters:

timeout – Time in milliseconds after which the function returns if no messages have been received. timeout may be 0, in which case the function always returns immediately, whether messages have been received or not.

Returns:

True if a message was received, otherwise False.

send(target, *messages)
send(target, path, *args) → None

Send a message or bundle from this server to the the given target. Arguments may be one or more Message or Bundle objects, or a single message given by its path and optional arguments.

Parameters:

  • target – the address to send the message to; an Address object, a port number, a (hostname, port) tuple, or a URL.

  • messages – one or more objects of type Message or Bundle.

  • path – the path of the message to be sent.

Raises:

  • AddressError – if the given target is invalid.

  • IOError – if the message couldn’t be sent.

add_method(path, typespec, func, user_data=None)

Register a callback function for OSC messages with matching path and argument types.

Parameters:

  • path – the message path to be handled by the registered method. None may be used as a wildcard to match any OSC message.

  • typespec – the argument types to be handled by the registered method. None may be used as a wildcard to match any OSC message.

  • func – the callback function. This may be a global function, a class method, or any other callable object, pyliblo will know what to do either way.

  • user_data – An arbitrary object that will be passed on to func every time a matching message is received.

del_method(path, typespec)

Delete a callback function. For both path and typespec, None may be used as a wildcard.

New in version 0.9.2.

register_methods(obj=None)

Call add_method() for all methods of an object that are decorated with make_method().

Parameters:

obj – The object that implements the OSC callbacks to be registered. By default this is the server object itself.

This function is usually called automatically by the server’s constructor, unless its reg_methods parameter was set to False.

add_bundle_handlers(start_handler, end_handler, user_data=None)

Add bundle notification handlers.

Parameters:

  • start_handler – a callback which fires when at the start of a bundle. This is called with the bundle’s timestamp and user_data.

  • end_handler – a callback which fires when at the end of a bundle. This is called with user_data.

  • user_data – data to pass to the handlers.

New in version 0.10.0.

url

The server’s URL.

port

The server’s port number.

protocol

The server’s protocol (one of the constants UDP, TCP, or UNIX).

fileno()

Return the file descriptor of the server socket, or -1 if not supported by the underlying server protocol.

free()

Free the underlying server object and close its port. Note that this will also happen automatically when the server is deallocated.

class ServerThread

Unlike Server, ServerThread uses its own thread which runs in the background to dispatch messages. ServerThread has the same methods as Server, with the exception of Server.recv(). Instead, it defines two additional methods start() and stop().

Note

Because liblo creates its own thread to receive and dispatch messages, callback functions will not be run in the main Python thread!

__init__()

ServerThread(port[, proto])

Create a new ServerThread object, which can receive OSC messages. Unlike Server, ServerThread uses its own thread which runs in the background to dispatch messages. Note that callback methods will not be run in the main Python thread!

Parameters:

  • port – a decimal port number or a UNIX socket path. If omitted, an arbitrary free UDP port will be used.

  • proto – one of the constants UDP, TCP, or UNIX; default is UDP.

  • reg_methods – False if you don’t want the init function to automatically register callbacks defined with the make_method decorator (keyword argument only).

Raises:

ServerError – if creating the server fails, e.g. because the given port could not be opened.

start()

Start the server thread. liblo will now start to dispatch any messages it receives.

stop()

Stop the server thread.

class make_method(path, types, user_data=None)

A decorator that serves as a more convenient alternative to Server.add_method().

__init__(path, types, user_data=None)

make_method(path, typespec[, user_data])

Set the path and argument types for which the decorated method is to be registered.

Parameters:

  • path – the message path to be handled by the registered method. None may be used as a wildcard to match any OSC message.

  • typespec – the argument types to be handled by the registered method. None may be used as a wildcard to match any OSC message.

  • user_data – An arbitrary object that will be passed on to the decorated method every time a matching message is received.

Utility Classes

class Address
__init__()

Address(hostname, port[, proto]) Address(port) Address(url)

Create a new Address object from the given hostname/port or URL.

Parameters:

  • hostname – the target’s hostname.

  • port – the port number on the target.

  • proto – one of the constants UDP, TCP, or UNIX.

  • url – a URL in liblo notation, e.g. 'osc.udp://hostname:1234/'.

Raises:

AddressError – if the given parameters do not represent a valid address.

url

The address’s URL.

hostname

The address’s hostname.

port

The address’s port number.

protocol

The address’s protocol (one of the constants UDP, TCP, or UNIX).

class Message

An OSC message, consisting of a path and arbitrary arguments.

__init__()

Message(path, *args)

Create a new Message object.

deserialise(buf)

Create a new Message object from its on-the-wire byte string representation.

serialise()

Serialise this Message object to its on-the-wire byte string representation.

path

The path of this Message

args

A list of the argument values of this Message

types

A string of the typetags of the arguments of this Message

add(*args)

Append the given arguments to the message. Arguments can be single values or (typetag, data) tuples.

args

A list of the argument values of this Message

deserialise(buf)

Create a new Message object from its on-the-wire byte string representation.

path

The path of this Message

serialise()

Serialise this Message object to its on-the-wire byte string representation.

types

A string of the typetags of the arguments of this Message

class Bundle

A bundle of one or more messages to be sent and dispatched together.

__init__()

Bundle([timetag, ]*messages)

Create a new Bundle object. You can optionally specify a time at which the messages should be dispatched (as an OSC timetag float), and any number of messages to be included in the bundle.

add(*messages)
add(path, *args) → None

Add one or more messages to the bundle.

exception ServerError(num, msg, where)

Raised when creating a liblo OSC server fails.

exception AddressError(msg)

Raised when trying to create an invalid Address object.

Mapping between OSC and Python data types

When constructing a message, pyliblo automatically converts arguments to an appropriate OSC data type. To explicitly specify the OSC data type to be transmitted, pass a (typetag, data) tuple instead. Some types can’t be unambiguously recognized, so they can only be sent that way.

The mapping between OSC and Python data types is shown in the following table:

typetag

OSC data type

Python data type

'i'

int32

int

'h'

int64

long (Python 2.x), int (Python 3.x)

'f'

float

float

'd'

double

float

'c'

char

str (single character)

's'

string

str

'S'

symbol

str

'm'

midi

tuple of four ints

't'

timetag

float

'T'

true

'F'

false

'N'

nil

'I'

infinitum

'b'

blob

list of ints (Python 2.x), bytes (Python 3.x)