Skip to content

Api Reference

Peer

class Peer(address: str, port: int, mode: OSCModes, framing: OSCFraming, UDP_bind_address: str)
  • address: The IP address or hostname of the remote peer.
  • port: The port number on which the remote peer is listening.
  • mode: The transport mode, either OSCModes.UDP or OSCModes.TCP.
  • framing: The OSC framing protocol, OSCFraming.OSC10 or OSCFraming.OSC11.
  • UDP_bind_address: (Optional) The local IP address to bind the UDP socket for receiving messages. Required if mode is OSCModes.UDP.

Returns a Peer object that can send and receive OSC messages.

The Peer object also returns the following attributes:

  • dispatcher: A Dispatcher object responsible for routing incoming messages to the appropriate handlers.

Decorators

The Peer class provides a decorator for defining event handlers that respond to specific events within the library, such as when a connection is established or when an error occurs. See Event Handlers for more information on how to use this feature.

@peer.event

Methods

start_listening()

peer.start_listening()
Starts a background thread to listen for incoming OSC messages.

send_message(message: OSCMessage)

peer.send_message(message: OSCMessage)

Sends an OSC message to the remote peer.

  • message: An OSCMessage object representing the message to be sent.

stop_listening()

peer.stop_listening()
Stops the background thread that listens for incoming OSC messages.

OSCMesssage

class OSCMessage(address: str, args: tuple(OSCArg(value=xxx), ...))
  • address: The OSC address pattern for the message (Not to be confused with the Peers IP address).
  • args: A tuple of OSCArg objects representing the arguments of the message.

OSCArgs

class OSCArg

Base class for all OSC argument types. Subclasses include:

  • OSCInt
  • OSCFloat
  • OSCString
  • OSCInt64
  • OSCTimeTag
  • OSCDouble
  • OSCBlob
  • OSCChar
  • OSCSymbol
  • OSCNil
  • OSCRGBA
  • OSCMidi
  • OSCImpulse
  • OSCArray
  • OSCFalse
  • OSCTrue

Dispatcher

class Dispatcher()
The Dispatcher class is responsible for routing incoming OSC messages to the appropriate handler functions based on their address patterns.

Methods

add_handler(address: str, handler: Callable, validator: Optional)

dispatcher.add_handler(address: str, handler: Callable, validator: Optional)
Registers a handler function for a specific OSC address pattern.

  • address: The OSC address pattern to match.
  • handler: A callable function that will be invoked when a message with the specified address is received.
  • validator: (Optional) A Pydantic model class used to validate and parse the incoming message.

remove_handler(address: str)

dispatcher.remove_handler(address: str)
Unregisters the handler function for a specific OSC address pattern.

  • address: The OSC address pattern whose handler should be removed.

Dispatch(message: OSCMessage)

dispatcher.dispatch(message: OSCMessage)
Not to be called directly, this method is called by a background thread when a message is received. It routes the incoming message to the appropriate handler based on its address.

  • message: An OSCMessage object representing the incoming message.

CallHandler

caller = CallHandler(peer)
The CallHandler class is a specialized handler that facilitates sending OSC messages and waiting for responses

  • peer: A Peer object used to send and receive messages.

Warning

The CallHandler will likely change in a future version of PyOSC, and will likely be the initialized as the default handler when a Peer object is created.

Methods

call(message: OSCMessage, return_addr: str, timeout: float, validator: Optional)

response = caller.call(
    message: OSCMessage,
    return_addr: str,
    timeout: float,
    validator: Optional
)
Sends an OSC message and waits for a response on a specified return address.

  • message: An OSCMessage object representing the message to be sent.
  • return_addr: The OSC address pattern where the response is expected.
  • timeout: The maximum time to wait for a response, in seconds.
  • validator: (Optional) A Pydantic model class used to validate and parse the incoming response message.
  • Returns: A BaseModel object containing the response message, or None if the timeout is reached without receiving a response.
Response

The response returned by the call method is an instance of the Pydantic model specified by the validator parameter. This model will contain the parsed arguments of the response message, allowing for easy access to the data contained within the OSC message.

If no validator is provided, the raw OSCMessage object will be returned.

Validators

Validators are Pydantic models used to validate and parse incoming OSC messages before they are processed by handler functions. They ensure that the messages conform to expected formats and types.

Creating a Validator

To create a validator, define a Pydantic model that specifies the expected structure of the OSC message. Each field in the model corresponds to an argument in the OSC message. 

from pydantic import BaseModel
from pyosc import OSCInt, OSCString
class PingResponse(BaseModel):
    args: tuple[OSCString]

    @property
    def message(self) -> str:
        return self.args[0].value

In this example, we define a PingResponse model that expects a single string argument in the OSC message. The message property provides a convenient way to access the string value.

Using a Validator

When registering a handler with the Dispatcher, you can specify a validator to ensure that incoming messages are validated before being passed to the handler function.

peer.dispatcher.add_handler("/test/out/ping", ping_handler, validator=PingResponse)

OSCModes Enum

There are two transport modes supported by OSC, and by extension PyOSC.

  • OSCModes.UDP: User Datagram Protocol, a connectionless protocol that is faster but does not guarantee message delivery.
  • OSCModes.TCP: Transmission Control Protocol, a connection-oriented protocol that guarantees message delivery but is slower due to the overhead of establishing and maintaining a connection.

TCP is generally preferred for applications where message delivery is critical, while UDP may be suitable for applications that require low latency and can tolerate some message loss. TCP is also simpler to work with, as you know when a connection is established, and you don't have to manage ports for receiving messages separately.

OSCFraming Enum

OSC messages can be framed in different ways depending on the version of the OSC protocol being used. - OSCFraming.OSC10: The original OSC 1.0 framing protocol. - OSCFraming.OSC11: The updated OSC 1.1 framing protocol,

The two versions of the specification can be found here:

When using version 1.1 and UDP transport, messages are actually exactly the same as version 1.0, however when using TCP transport, this are a little bit different.