Client

The client allows you to connect and exchange messages with an OSC server. Client classes are available for UDP and TCP protocols. The base client class send method expects an OSCMessage object, which is then sent out over TCP or UDP. Additionally, a simple client class exists that constructs the OSCMessage object for you.

See the examples folder for more use cases.

Examples

from pythonosc.udp_client import SimpleUDPClient

ip = "127.0.0.1"
port = 1337

client = SimpleUDPClient(ip, port)  # Create client

client.send_message("/some/address", 123)   # Send float message
client.send_message("/some/address", [1, 2., "hello"])  # Send message with int, float and string

# Alternatively, use a context manager to automatically close the socket
with SimpleUDPClient(ip, port) as client:
    client.send_message("/some/address", 123)

from pythonosc.tcp_client import SimpleTCPClient

ip = "127.0.0.1"
port = 1337

client = SimpleTCPClient(ip, port)  # Create client

client.send_message("/some/address", 123)   # Send float message
client.send_message("/some/address", [1, 2., "hello"])  # Send message with int, float and string

Client Module Documentation

UDP Clients for sending OSC messages to an OSC server

class pythonosc.udp_client.DispatchClient(address: str, port: int, allow_broadcast: bool = False, family: AddressFamily = AddressFamily.AF_UNSPEC, timeout: float | None = None)[source]

OSC Client that includes a Dispatcher for handling responses and other messages from the server

handle_messages(timeout: float | None = None) → None[source]

Wait :int:`timeout` seconds for a message from the server and process each message with the registered handlers. Continue until a timeout occurs.

Parameters:

timeout – Time in seconds to wait for a message. If None, uses the default timeout set in __init__.

class pythonosc.udp_client.SimpleUDPClient(address: str, port: int, allow_broadcast: bool = False, family: AddressFamily = AddressFamily.AF_UNSPEC, timeout: float | None = None)[source]

Simple OSC client that automatically builds OscMessage from arguments

get_messages(timeout: float | None = None) → Generator[source]

Wait :int:`timeout` seconds for a message from the server and convert it to a OscMessage

Parameters:

timeout – Time in seconds to wait for a message. If None, uses the default timeout set in __init__.

send_message(address: str, value: str | bytes | bool | int | float | Tuple[int, int, int, int] | List[Any] | Tuple[Any, ...] | None | Iterable[str | bytes | bool | int | float | Tuple[int, int, int, int] | List[Any] | Tuple[Any, ...] | None]) → None[source]

Build OscMessage from arguments and send to server

Parameters:

  • address – OSC address the message shall go to

  • value – One or more arguments to be added to the message

class pythonosc.udp_client.UDPClient(address: str, port: int, allow_broadcast: bool = False, family: AddressFamily = AddressFamily.AF_UNSPEC, timeout: float | None = None)[source]

OSC client to send OscMessage or OscBundle via UDP

__init__(address: str, port: int, allow_broadcast: bool = False, family: AddressFamily = AddressFamily.AF_UNSPEC, timeout: float | None = None) → None[source]

Initialize client

As this is UDP it will not actually make any attempt to connect to the given server at ip:port until the send() method is called.

Parameters:

  • address – IP address of server

  • port – Port of server

  • allow_broadcast – Allow for broadcast transmissions

  • family – address family parameter (passed to socket.getaddrinfo)

  • timeout – Default timeout in seconds for socket operations

close() → None[source]

Close the socket

receive(timeout: float | None = None) → bytes[source]

Wait :int:`timeout` seconds for a message an return the raw bytes

Parameters:

timeout – Number of seconds to wait for a message. If None, uses the default timeout set in __init__.

send(content: OscMessage | OscBundle) → None[source]

Sends an OscMessage or OscBundle via UDP

Parameters:

content – Message or bundle to be sent

TCP Clients for sending OSC messages to an OSC server

class pythonosc.tcp_client.AsyncDispatchTCPClient(address: str, port: int, family: AddressFamily = AddressFamily.AF_INET, mode: str = '1.1', timeout: float | None = 30.0)[source]

OSC Client that includes a Dispatcher for handling responses and other messages from the server

async handle_messages(timeout: float | None = None) → None[source]

Wait :int:`timeout` seconds for a message from the server and process each message with the registered handlers. Continue until a timeout occurs.

Parameters:

timeout – Time in seconds to wait for a message

class pythonosc.tcp_client.AsyncSimpleTCPClient(address: str, port: int, family: AddressFamily = AddressFamily.AF_INET, mode: str = '1.1', timeout: float | None = 30.0)[source]

Simple OSC client that automatically builds OscMessage from arguments

__init__(address: str, port: int, family: AddressFamily = AddressFamily.AF_INET, mode: str = '1.1', timeout: float | None = 30.0)[source]

Initialize client

Parameters:

  • address – IP address of server

  • port – Port of server

  • family – address family parameter (passed to socket.getaddrinfo)

  • timeout – Default timeout in seconds for socket operations

async send_message(address: str, value: str | bytes | bool | int | float | Tuple[int, int, int, int] | List[Any] | Tuple[Any, ...] | None | Iterable[str | bytes | bool | int | float | Tuple[int, int, int, int] | List[Any] | Tuple[Any, ...] | None] = '') → None[source]

Build OscMessage from arguments and send to server

Parameters:

  • address – OSC address the message shall go to

  • value – One or more arguments to be added to the message

class pythonosc.tcp_client.AsyncTCPClient(address: str, port: int, family: AddressFamily = AddressFamily.AF_INET, mode: str = '1.1', timeout: float | None = 30.0)[source]

Async OSC client to send OscMessage or OscBundle via TCP

__init__(address: str, port: int, family: AddressFamily = AddressFamily.AF_INET, mode: str = '1.1', timeout: float | None = 30.0) → None[source]

Initialize client

Parameters:

  • address – IP address of server

  • port – Port of server

  • family – address family parameter (passed to socket.getaddrinfo)

  • timeout – Default timeout in seconds for socket operations

async send(content: OscMessage | OscBundle) → None[source]

Sends an OscMessage or OscBundle via TCP

Parameters:

content – Message or bundle to be sent

class pythonosc.tcp_client.SimpleTCPClient(*args, **kwargs)[source]

Simple OSC client that automatically builds OscMessage from arguments

__init__(*args, **kwargs)[source]

Initialize client

Parameters:

  • address – IP address of server

  • port – Port of server

  • family – address family parameter (passed to socket.getaddrinfo)

  • timeout – Default timeout in seconds for socket operations

send_message(address: str, value: str | bytes | bool | int | float | Tuple[int, int, int, int] | List[Any] | Tuple[Any, ...] | None | Iterable[str | bytes | bool | int | float | Tuple[int, int, int, int] | List[Any] | Tuple[Any, ...] | None] = '') → None[source]

Build OscMessage from arguments and send to server

Parameters:

  • address – OSC address the message shall go to

  • value – One or more arguments to be added to the message

class pythonosc.tcp_client.TCPClient(address: str, port: int, family: AddressFamily = AddressFamily.AF_INET, mode: str = '1.1', timeout: float | None = 30.0)[source]

Async OSC client to send OscMessage or OscBundle via TCP

__init__(address: str, port: int, family: AddressFamily = AddressFamily.AF_INET, mode: str = '1.1', timeout: float | None = 30.0) → None[source]

Initialize client

Parameters:

  • address – IP address of server

  • port – Port of server

  • family – address family parameter (passed to socket.getaddrinfo)

  • timeout – Default timeout in seconds for socket operations

send(content: OscMessage | OscBundle) → None[source]

Sends an OscMessage or OscBundle via TCP

Parameters:

content – Message or bundle to be sent

class pythonosc.tcp_client.TCPDispatchClient(*args, **kwargs)[source]

OSC TCP Client that includes a Dispatcher for handling responses and other messages from the server

handle_messages(timeout_sec: float | None = None) → None[source]

Wait :int:`timeout` seconds for a message from the server and process each message with the registered handlers. Continue until a timeout occurs.

Parameters:

timeout – Time in seconds to wait for a message