microosc

Minimal OSC parser, server, and client for CircuitPython and CPython

  • Author(s): Tod Kurt

Implementation Notes

This is a minimal OSC library. It can parse and emit OSC packets with the following OSC data types:

  • floating point numbers (“float32”)

  • integer numbers (“int32”)

  • strings

Hardware:

To run this library you will need one of:

  • CircuitPython board with native wifi support, like those based on ESP32-S2, ESP32-S3, etc.

  • Desktop Python (CPython) computer

To send OSC messages, you will need an OSC UDP sender (aka “OSC client”). Some easy-to-use OSC clients are:

To receive OSC messages, you will need an OSC UDP receiver (aka “OSC server”). Some easy-to-use OSC clients are:

Software and Dependencies:

class microosc.OSCClient(socket_source, host, port, buf_size=128)

In OSC parlance, a “client” is a sender of OSC messages, usually UDP packets. This OSC client is an OSC UDP sender.

Create an OSCClient ready to send to a host/port.

Parameters:

  • socket_source (socket) – An object that is a source of sockets. This could be a socketpool in CircuitPython or the socket module in CPython.

  • host (str) – hostname or IP address to send to, can use multicast addresses like ‘224.0.0.1’

  • port (int) – port to send to

  • buf_size (int) – size of UDP buffer to use

send(msg)

Send an OSC Message.

Parameters:

msg (OscMsg) – the OSC Message to send

Return int:

return code from socket.sendto

class microosc.OSCServer(socket_source, host, port, dispatch_map=None)

In OSC parlance, a “server” is a receiver of OSC messages, usually UDP packets. This OSC server is an OSC UDP receiver.

Create an OSCServer and start it listening on a host/port.

Parameters:

  • socket_source (socket) – An object that is a source of sockets. This could be a socketpool in CircuitPython or the socket module in CPython.

  • host (str) – hostname or IP address to receive on, can use multicast addresses like ‘224.0.0.1’

  • port (int) – port to receive on

  • dispatch_map (dict) – map of OSC Addresses to functions, if no dispatch_map is specified, a default_map will be used that prints out OSC messages

poll()

Call this method inside your main loop to get the server to check for new incoming packets. When a packet comes in, it will be parsed and dispatched to your provided handler functions specified in your dispatch_map.

class microosc.OscMsg(addr, args, types)

Objects returned by parse_osc_packet()

addr

Alias for field number 0

args

Alias for field number 1

types

Alias for field number 2

microosc.create_osc_packet(msg, data)
Parameters:

  • msg (OscMsg) – OscMsg to convert into an OSC Packet

  • data (bytearray) – an empty data buffer to write OSC Packet into

:return size of actual OSC Packet written into data buffer

microosc.default_dispatch_map = {'/': <function <lambda>>}

Simple example of a dispatch_map

microosc.pack_string(astr, data, pos)

Pack a string s into data bytearray at position pos, returns new end pos

microosc.parse_osc_packet(data, packet_size)

Parse OSC packets into OscMsg objects.

OSC packets contain, in order

  • a string that is the OSC Address (null-terminated), e.g. “/1/faderB”

  • a tag-type string starting with ‘,’ and one or more ‘f’, ‘i’, ‘s’ types, (optional, null-terminated), e.g. “,ffi” indicates two float32s, one int32

  • zero or more OSC Arguments in binary form, depending on tag-type string

OSC packet size is always a multiple of 4

Parameters:

  • data (bytearray) – a data buffer containing a binary OSC packet

  • packet_size (int) – the size of the OSC packet (may be smaller than len(data))

microosc.read_string(data, pos)

Read padded string from a position, return string and new end pos