CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-python-osc

Open Sound Control server and client implementations in pure Python for networked music and multimedia applications

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Python-OSC

Open Sound Control server and client implementations in pure Python for networked music and multimedia applications. Python-OSC provides a comprehensive implementation of the OSC protocol enabling real-time communication between audio applications, digital art installations, music software, and distributed multimedia systems.

Package Information

  • Package Name: python-osc
  • Language: Python
  • Installation: pip install python-osc
  • Requirements: Python >= 3.10

Core Imports

import pythonosc

Common usage patterns:

# UDP client for sending messages
from pythonosc import udp_client

# UDP server for receiving messages
from pythonosc import osc_server
from pythonosc.dispatcher import Dispatcher

# TCP clients and servers
from pythonosc import tcp_client
from pythonosc import osc_tcp_server

# For async servers and clients
import asyncio

# Message building
from pythonosc.osc_message_builder import OscMessageBuilder

# Message parsing
from pythonosc.osc_message import OscMessage
from pythonosc.osc_bundle import OscBundle

Basic Usage

Simple UDP Client

from pythonosc import udp_client
import time

# Create client
client = udp_client.SimpleUDPClient("127.0.0.1", 5005)

# Send messages
client.send_message("/filter", 0.5)
client.send_message("/volume", [0.8, "stereo"])

Simple UDP Server

from pythonosc.dispatcher import Dispatcher
from pythonosc import osc_server
import threading

def print_handler(address, *args):
    print(f"Received {address}: {args}")

# Set up dispatcher
dispatcher = Dispatcher()
dispatcher.map("/filter", print_handler)
dispatcher.map("/volume", print_handler)

# Create and start server
server = osc_server.ThreadingOSCUDPServer(("127.0.0.1", 5005), dispatcher)
server_thread = threading.Thread(target=server.serve_forever)
server_thread.daemon = True
server_thread.start()

Message Building and Parsing

from pythonosc.osc_message_builder import OscMessageBuilder

# Build a message
builder = OscMessageBuilder("/synth/freq")
builder.add_arg(440.0)
builder.add_arg("sine")
message = builder.build()

# Access message properties
print(message.address)  # "/synth/freq"
print(message.params)   # [440.0, "sine"]

Architecture

Python-OSC implements the complete OSC 1.0 and 1.1 specifications with support for:

  • Protocol Layers: UDP and TCP transport with OSC 1.0/1.1 message formats
  • Message Types: Individual OSC messages and timed bundles
  • Data Types: All standard OSC types (int, float, string, blob, arrays, timestamps, MIDI, etc.)
  • Server Patterns: Blocking, threading, forking, and asyncio implementations
  • Client Patterns: Synchronous and asynchronous UDP/TCP clients
  • Address Matching: Flexible pattern matching system for message routing

The library provides both high-level convenience classes and low-level building blocks, making it suitable for simple automation tasks and complex distributed multimedia systems.

Capabilities

Message Handling

Core OSC message and bundle construction, parsing, and manipulation. Includes builders for creating messages/bundles and parsers for processing incoming data with support for all standard OSC data types.

class OscMessage:
    def __init__(self, dgram: bytes): ...
    @property
    def address(self) -> str: ...
    @property  
    def params(self) -> List[Any]: ...

class OscMessageBuilder:
    def __init__(self, address: Optional[str] = None): ...
    def add_arg(self, arg_value: ArgValue, arg_type: Optional[str] = None): ...
    def build(self) -> OscMessage: ...

def build_msg(address: str, value: ArgValue = "") -> OscMessage: ...

Message Handling

UDP Networking

UDP clients and utilities for sending OSC messages and bundles over UDP with broadcast support, timeout handling, and message reception capabilities.

class SimpleUDPClient:
    def __init__(self, address: str, port: int, allow_broadcast: bool = False): ...
    def send_message(self, address: str, value: ArgValue): ...

class UDPClient:
    def __init__(self, address: str, port: int, allow_broadcast: bool = False): ...
    def send(self, content: Union[OscMessage, OscBundle]): ...
    def receive(self, timeout: int = 30) -> bytes: ...

UDP Networking

TCP Networking

TCP clients for reliable OSC communication with support for both OSC 1.0 and 1.1 protocols, SLIP encoding, synchronous and asynchronous patterns, and connection management.

class SimpleTCPClient:
    def __init__(self, address: str, port: int, mode: str = "1.1"): ...
    def send_message(self, address: str, value: ArgValue = ""): ...
    def close(self): ...

class TCPClient:
    def __init__(self, address: str, port: int, mode: str = "1.1"): ...
    def send(self, content: Union[OscMessage, OscBundle]): ...
    def receive(self, timeout: int = 30) -> Generator: ...

TCP Networking

Server Implementations

Complete OSC server implementations supporting UDP and TCP protocols with multiple concurrency models (blocking, threading, forking, asyncio) and flexible message dispatching.

class ThreadingOSCUDPServer:
    def __init__(self, server_address: Tuple[str, int], dispatcher: Dispatcher): ...
    def serve_forever(self): ...

class AsyncIOOSCUDPServer:
    def __init__(self, server_address: Tuple[str, int], dispatcher: Dispatcher): ...
    def serve(self): ...

class Dispatcher:
    def map(self, address: str, handler: Callable, *args): ...
    def unmap(self, address: str, handler: Callable): ...

Server Implementations

Data Types and Parsing

Low-level OSC data type encoding/decoding, NTP timestamp handling, and SLIP protocol implementation for reliable TCP communication.

# OSC type conversion functions
def write_string(val: str) -> bytes: ...
def get_string(dgram: bytes, start_index: int) -> Tuple[str, int]: ...
def write_int(val: int) -> bytes: ...
def get_int(dgram: bytes, start_index: int) -> Tuple[int, int]: ...

# NTP timestamp handling
def ntp_to_system_time(timestamp: bytes) -> float: ...
def system_time_to_ntp(seconds: float) -> bytes: ...

# SLIP protocol
def encode(msg: bytes) -> bytes: ...
def decode(packet: bytes) -> bytes: ...

Data Types and Parsing

Types

from typing import Union, List, Tuple, Any, Callable, Optional

ArgValue = Union[str, bytes, bool, int, float, MidiPacket, list]
MidiPacket = Tuple[int, int, int, int]

class ParseError(Exception): ...
class BuildError(Exception): ...
class ProtocolError(Exception): ...
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/python-osc@1.9.x
Publish Source
CLI
Badge
tessl/pypi-python-osc badge