多拉OSC
使用CLI和库接口通过UDP/TCP发送和接收OSC（开放式声音控制）消息。专为与MaxMSP和其他支持OSC的应用程序通信而设计。
特性
- 双接口：用作Python库或命令行工具
- 协议支持UDP和TCP传输协议
- 灵活的消息处理：基于回调的消息处理
- 类型自动检测：OSC值的自动类型推断
- 配置管理：保存和加载连接设置
- MCP服务器就绪：为未来的模型上下文协议集成而构建
- 清洁API：简单直观的发送和接收界面
安装
使用紫外线（推荐）：
# Clone or navigate to the project directory
cd dora-osc
# Install the package
uv sync
# Install in editable mode for development
uv pip install -e .快速开始
命令行界面
启动OSC服务器
# Listen on all interfaces (UDP)
dora-osc server --host 0.0.0.0 --port 5005
# Listen using TCP
dora-osc server --protocol tcp --port 5006
# Listen for specific OSC addresses
dora-osc server --address /button --address /fader发送OSC消息
# Send a simple message (UDP)
dora-osc send /button 1
# Send to a specific host
dora-osc send --host 192.168.1.100 --port 5005 /fader 0.5
# Send via TCP
dora-osc send --protocol tcp /position 0.5 0.75
# Send multiple values (auto-typed)
dora-osc send /data 42 3.14 "hello" truePython库
接收消息
from dora_osc import OSCServer
def message_handler(address, *args):
"""Handle incoming OSC messages."""
print(f"Received: {address}")
print(f"Values: {args}")
# Create and configure server
server = OSCServer(host="0.0.0.0", port=5005, protocol="udp")
# Add handler for all messages
server.add_default_handler(message_handler)
# Or add specific handlers
server.add_handler("/button", lambda addr, *args: print(f"Button: {args}"))
server.add_handler("/fader/*", lambda addr, *args: print(f"Fader: {args}"))
# Start server (blocking)
server.start()
# Or start in background
server.start(blocking=False)
# ... do other work ...
server.stop()发送消息
from dora_osc import OSCClient
# Create client
client = OSCClient(host="127.0.0.1", port=5005, protocol="udp")
# Send messages with automatic type detection
client.send("/button", 1)
client.send("/fader", 0.5)
client.send("/position", 0.5, 0.75)
client.send("/label", "Hello MaxMSP")
client.send("/trigger", True)
# Close connection (important for TCP)
client.close()
# Or use context manager
with OSCClient(host="127.0.0.1", port=5005) as client:
client.send("/message", "Hello")
# Connection automatically closed完整示例
from dora_osc import OSCServer, OSCClient
import time
# Start server in background
server = OSCServer(host="0.0.0.0", port=5005)
def handler(address, *args):
print(f"[{address}] {args}")
server.add_default_handler(handler)
server.start(blocking=False)
# Send some messages
client = OSCClient(host="127.0.0.1", port=5005)
client.send("/test", 1, 2, 3)
client.send("/hello", "world")
time.sleep(1) # Let messages process
# Cleanup
server.stop()
client.close()MaxMSP集成
在MaxMSP中接收
在MaxMSP中，使用 udpreceive 对象：
[udpreceive 5005]
|
[print received]从MaxMSP发送
使用 udpsend 对象：
[message /button 1(
|
[udpsend 127.0.0.1 5005]对于TCP，使用 tcpreceive 和 tcpsend 相反，对象。
测试补丁
全面的MaxMSP测试补丁包含在 max-patches/dora-osc-test.maxpat。此补丁提供：
- 完整的OSC发送/接收演示
- 通过OSC控制的FM合成器
- 所有消息类型的视觉反馈
- 所有软件包功能的测试界面
要使用：
- 打开
max-patches/dora-osc-test.maxpat在MaxMSP 8中+ - 启动Python服务器：
dora-osc server --port 5006 - 点击补丁中的“连接”
- 发送测试消息：
dora-osc send /fader 0.5
看 max-patches/README.md 详细说明。
配置管理
保存并加载默认连接设置：
from dora_osc.config import OSCConfig
# Create config
config = OSCConfig(
server_host="0.0.0.0",
server_port=5005,
server_protocol="udp",
client_host="192.168.1.100",
client_port=5005,
client_protocol="udp"
)
# Save to default location (~/.config/dora-osc/config.json)
config.save()
# Load config
config = OSCConfig.load()
print(f"Server: {config.server_host}:{config.server_port}")MCP服务器
该项目包括完整的MCP（模型上下文协议）集成，允许像克劳德这样的人工智能助手直接作为工具发送和接收OSC消息。
特性
- send_osc_消息 -将OSC发送到任何主机/端口
- start_osc_server -开始接收OSC消息
- get_received_message -检索收到的消息
- stop_osc_server -停止服务器
- list_active_connections -查看所有活动服务器/客户端
快速设置
- 使启动器脚本可执行:
cd /path/to/dora-osc
chmod +x run-mcp.sh- 配置Claude桌面 (
~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"dora-osc": {
"command": "/ABSOLUTE/PATH/TO/dora-osc/run-mcp.sh",
"args": []
}
}
}替换 /ABSOLUTE/PATH/TO/dora-osc 根据您的实际项目路径。
- 重新启动克劳德桌面
- 开始与Claude一起使用OSC:
User: Send an OSC message to /fader with value 0.5 on port 5005
User: Start an OSC server on port 5006 to receive messages from Max
User: Check what messages have been received看 MCP-SERVER.md 获取完整的文档、示例和故障排除。
项目结构
dora-osc/
├── src/
│ └── dora_osc/
│ ├── __init__.py # Main package exports
│ ├── server.py # OSC server (receiver)
│ ├── client.py # OSC client (sender)
│ ├── cli.py # Command-line interface
│ ├── config.py # Configuration management
│ └── mcp_server.py # MCP integration (future)
├── examples/
│ ├── basic_server.py # Simple OSC receiver
│ ├── basic_client.py # Simple OSC sender
│ ├── bidirectional.py # Two-way communication
│ ├── maxmsp_integration.py # MaxMSP integration example
│ └── README.md # Examples documentation
├── max-patches/
│ ├── dora-osc-test.maxpat # MaxMSP test patch with FM synth
│ └── README.md # Max patches documentation
├── pyproject.toml # UV/pip configuration
└── README.md # This file
## API Reference
### OSCServer
OSCServer(host="0.0.0.0", port=5005, protocol="udp")
方法：
- `add_handler(address, callback)` -为特定OSC地址模式添加处理程序
- `add_default_handler(callback)` -为所有不匹配的消息添加处理程序
- `start(blocking=True)` -启动服务器
- `stop()` -停止服务器
- `is_running()` -检查服务器是否正在运行
### OSC客户端
OSCClient(host="127.0.0.1", port=5005, protocol="udp")
方法：
- `send(address, *values)` -发送OSC消息
- `close()` -关闭连接（仅TCP）
## 发展
### 运行测试
Install development dependencies
uv add --dev pytest pytest-asyncio
Run tests (when implemented)
uv run pytest
### 类型检查
该包包括类型提示和 `py.typed` 类型检查标记：
uv add --dev mypy uv run mypy src/dora_osc
## 故障排除
### 未收到消息
1. 检查防火墙设置是否允许在指定端口上使用UDP/TCP
1. 验证端口是否尚未使用： `lsof -i :
`
1. 对于网络通信，确保两台设备位于同一网络上
1. 尝试使用 `0.0.0.0` 作为服务器主机，监听所有接口
### TCP连接问题
TCP需要活动连接。确保：
1. 在客户端连接之前启动服务器
1. 客户端在发送后正确关闭连接
1. 防火墙允许在指定端口上进行TCP连接
### MaxMSP未收到
1. 验证MaxMSP是否使用了正确的端口
1. 检查协议是否匹配（UDP与TCP）
1. 使用 `print` MaxMSP中的对象，用于调试接收到的消息
1. 首先使用CLI进行测试，以验证服务器是否正常工作
## 许可证
MIT许可证-有关详细信息，请参阅许可证文件
## 贡献
欢迎投稿！需要改进的领域：
- \[\]添加全面的测试套件
- \[\]实现OSC捆绑包支持
- \[\]完成MCP服务器的实施
- \[\]添加消息过滤和路由
- \[\]实现消息记录/回放
- \[\]添加用于监控的web界面
## 作者
托马斯·萨顿(tommy.sutton@live.com)