0
# Python-OSC
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: python-osc
7
- **Language**: Python
8
- **Installation**: `pip install python-osc`
9
- **Requirements**: Python >= 3.10
10

11
## Core Imports
12

13
```python
14
import pythonosc
15
```
16

17
Common usage patterns:
18

19
```python
20
# UDP client for sending messages
21
from pythonosc import udp_client
22

23
# UDP server for receiving messages
24
from pythonosc import osc_server
25
from pythonosc.dispatcher import Dispatcher
26

27
# TCP clients and servers
28
from pythonosc import tcp_client
29
from pythonosc import osc_tcp_server
30

31
# For async servers and clients
32
import asyncio
33

34
# Message building
35
from pythonosc.osc_message_builder import OscMessageBuilder
36

37
# Message parsing
38
from pythonosc.osc_message import OscMessage
39
from pythonosc.osc_bundle import OscBundle
40
```
41

42
## Basic Usage
43

44
### Simple UDP Client
45

46
```python
47
from pythonosc import udp_client
48
import time
49

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

53
# Send messages
54
client.send_message("/filter", 0.5)
55
client.send_message("/volume", [0.8, "stereo"])
56
```
57

58
### Simple UDP Server
59

60
```python
61
from pythonosc.dispatcher import Dispatcher
62
from pythonosc import osc_server
63
import threading
64

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

68
# Set up dispatcher
69
dispatcher = Dispatcher()
70
dispatcher.map("/filter", print_handler)
71
dispatcher.map("/volume", print_handler)
72

73
# Create and start server
74
server = osc_server.ThreadingOSCUDPServer(("127.0.0.1", 5005), dispatcher)
75
server_thread = threading.Thread(target=server.serve_forever)
76
server_thread.daemon = True
77
server_thread.start()
78
```
79

80
### Message Building and Parsing
81

82
```python
83
from pythonosc.osc_message_builder import OscMessageBuilder
84

85
# Build a message
86
builder = OscMessageBuilder("/synth/freq")
87
builder.add_arg(440.0)
88
builder.add_arg("sine")
89
message = builder.build()
90

91
# Access message properties
92
print(message.address)  # "/synth/freq"
93
print(message.params)   # [440.0, "sine"]
94
```
95

96
## Architecture
97

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

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

107
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.
108

109
## Capabilities
110

111
### Message Handling
112

113
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.
114

115
```python { .api }
116
class OscMessage:
117
    def __init__(self, dgram: bytes): ...
118
    @property
119
    def address(self) -> str: ...
120
    @property  
121
    def params(self) -> List[Any]: ...
122

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

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

131
[Message Handling](./message-handling.md)
132

133
### UDP Networking
134

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

137
```python { .api }
138
class SimpleUDPClient:
139
    def __init__(self, address: str, port: int, allow_broadcast: bool = False): ...
140
    def send_message(self, address: str, value: ArgValue): ...
141

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

148
[UDP Networking](./udp-networking.md)
149

150
### TCP Networking
151

152
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.
153

154
```python { .api }
155
class SimpleTCPClient:
156
    def __init__(self, address: str, port: int, mode: str = "1.1"): ...
157
    def send_message(self, address: str, value: ArgValue = ""): ...
158
    def close(self): ...
159

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

166
[TCP Networking](./tcp-networking.md)
167

168
### Server Implementations
169

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

172
```python { .api }
173
class ThreadingOSCUDPServer:
174
    def __init__(self, server_address: Tuple[str, int], dispatcher: Dispatcher): ...
175
    def serve_forever(self): ...
176

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

181
class Dispatcher:
182
    def map(self, address: str, handler: Callable, *args): ...
183
    def unmap(self, address: str, handler: Callable): ...
184
```
185

186
[Server Implementations](./servers.md)
187

188
### Data Types and Parsing  
189

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

192
```python { .api }
193
# OSC type conversion functions
194
def write_string(val: str) -> bytes: ...
195
def get_string(dgram: bytes, start_index: int) -> Tuple[str, int]: ...
196
def write_int(val: int) -> bytes: ...
197
def get_int(dgram: bytes, start_index: int) -> Tuple[int, int]: ...
198

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

203
# SLIP protocol
204
def encode(msg: bytes) -> bytes: ...
205
def decode(packet: bytes) -> bytes: ...
206
```
207

208
[Data Types and Parsing](./data-types.md)
209

210
## Types
211

212
```python { .api }
213
from typing import Union, List, Tuple, Any, Callable, Optional
214

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

218
class ParseError(Exception): ...
219
class BuildError(Exception): ...
220
class ProtocolError(Exception): ...
221
```