Quick start

Simple OSC implementation in pure Python. Based on https://pypi.python.org/pypi/python-osc.

This library was developped following the specifications at http://opensoundcontrol.org/spec-1_0 and is currently in a beta state.

Features

  • UDP client and server
  • OSC arguments support - int, float, string, blob, true, false
  • Blocking/threading/forking server implementations
  • Simple API

Installation

Download library source code and unpack in your project. Download it here http://bitbucket.org/grailapp/osc

After unpacking execute in terminal following command to install a library

python setup.py install

Usage

Examples can be found in Examples section of this documentation.

Quick examples

# create osc message with address '/message/address'
message = OSCMessage(address='/message/address')

# argument can be string, int, float, bool and binary
message.add( 'Some text argument' )
message.add( 3 )
message.add( 0.75 )
message.add( True )

# create osc bundle and add a message
bundle = OSCBundle()
bundle.add( message )

# create client and send to 127.0.0.1:8000
client = OSCClient('127.0.0.1', 8000)
client.send( message )
client.send( bundle )

# bind server and listen for incoming messages at 127.0.0.1:8000
server = OSCServer('127.0.0.1', 8000)
server.serve_forever()

Table of contents

Classes

osc.__init__

OSC protocol implementation in pure python

copyright:
  1. 2018 by Oleksii Lytvyn.
license:

MIT, see LICENSE for more details.

OSCPacket

class osc.OSCPacket(dgram)

Unit of transmission of the OSC protocol.

Any application that sends OSC Packets is an OSC Client. Any application that receives OSC Packets is an OSC Server.

size

Size of datagram

OSCMessage

class osc.OSCMessage(address='/', args=None)

Builds arbitrary OSCMessage instances.

address

Returns the OSC address this message will be sent to.

args

Returns list of value added as arguments

size

Returns length of the datagram for this message.

dgram

Returns datagram from which this message was built.

add(value, _type=None)

Add a typed argument to this message.

Args:

value: The corresponding value for the argument. _type: A value in ARG_TYPE_* defined in this class,

if none then the type will be guessed.
Raises:
ValueError: if the type is not supported.
append(value, _type=None)

Add a typed argument to this message.

Args:

value: The corresponding value for the argument. _type: A value in ARG_TYPE_* defined in this class,

if none then the type will be guessed.
Raises:
ValueError: if the type is not supported.
extend(values)

Extend arguments list, all values will be added using auto type

Args:
values (list): a list of values
insert(index, value, _type=None)

Insert typed argument at specific index

Args:

index (int): index of insertion value: The corresponding value for the argument. _type: A value in ARG_TYPE_* defined in this class,

if none then the type will be guessed.
Raises:
ValueError: if the type is not supported. IndexError: if index is greater than list size
remove(value)

Remove the first item from the arguments list whose value is value.

Args:
value: argument value
Raises:
ValueError: if value is not fund in arguments list
index(value, start=0, end=False)

Find value in arguments list and return first index otherwise return -1. The returned index is computed relative to the beginning of the full sequence rather than the start argument.

clear()

Remove all arguments from message

copy()

Create copy of OSCMessage

Returns:
New OSCMessage instance
build()

Builds OSCMessage datagram and return current instance

Returns:
an OSCMessage instance.
Raises:
OSCBuildError: if the message could not be build or if the address was empty.
static parse(dgram)

Create OSCMessage from datagram

Args:
dgram (bytes): from what to build OSCMessage
Returns:
OSCMessage parsed from datagram
static is_valid(dgram)

Check datagram to be valid OSCMessage

Args:
dgram (bytes): datagram os of OSCMessage
Returns:
whether this datagram starts as an OSC message.
static is_valid_address(address)

Check if given value is valid OSC-string address pattern

Args:
address (str): OSC address pattern
Returns:
True if valid

OSCBundle

class osc.OSCBundle(timestamp=0, messages=None)

Builds arbitrary OSCBundle instances.

timestamp

Returns timestamp associated with this bundle.

length

Returns number of messages in bundle.

size

Returns length of the datagram for this bundle.

dgram

Returns datagram from which this bundle was built.

append(content)

Add a new content to this bundle.

Args:
content: Either an OSCBundle or an OSCMessage
Raises:
OSCBuildError: if we could not build the bundle.
add(content)

Same as append method

build()

Build an OSCBundle with the current state of this builder.

Raises:
OSCBuildError: if we could not build the bundle.
classmethod is_valid(dgram)

Returns whether this datagram starts like an OSC bundle.

Args:
dgram: datagram of OSCBundle
Returns:
weather datagram is OSCBundle
static parse(dgram)

Parse OSCBundle from datagram

Args:
dgram: datagram of OSCBundle
Returns:
OSCBundle instance

OSCServer

Subclass OSCServer and override handle method

class osc.OSCServer(address='127.0.0.1', port=9000)

Superclass for different flavors of OSCServer

You can change server logic by extending from both OSCServer and socketserver.ThreadingMixIn or socketserver.ForkingMixIn

handle(address, message, date)

Handle receiving of OSCMessage or OSCBundle

Args:
address: typle (host, port) message: OSCMessage or OSCBundle date: int number which represents time of message
Raises:
NotImplementedError if you don’t override it

OSCClient

Subclass from OSCClient if you want to send something custom

class osc.OSCClient(address='127.0.0.1', port=False)

Send OSCMessage’s and OSCBundle’s to multiple servers

clients

Returns list of receipts

add(address, port)

Add a recipient

Args:
address (str): ip address of server port (int): port of server
Raises:
ValueError if one of arguments is invalid
remove(address, port)

Remove a recipient

Args:
address (str): ip address of server port (int): port of server
clear()

Clear list of receipts

send(message)

Sends an OSCBundle or OSCMessage to the servers.

Args:
message (OSCMessage, OSCBundle): a OSCMessage or OSCBundle to send
close()

Close socket connection

OSCSender

OSCReceiver

Examples

Simple Server and Client applications

Server

This server will print all incoming messages and bundles

import argparse
import math

from osc import OSCServer


class SimpleServer(OSCServer):

  def handle(self, address, message, time):
    if message.is_bundle():
      for msg in message:
        print(time, address, msg.address, msg.args)
    else:
      print(time, address, message.address, message.args)

if __name__ == "__main__":
  parser = argparse.ArgumentParser()
  parser.add_argument("--ip",
      default="127.0.0.1", help="The ip to listen on")
  parser.add_argument("--port",
      type=int, default=8000, help="The port to listen on")
  args = parser.parse_args()

  server = SimpleServer(args.ip, args.port)

  print("Serving on {}".format(server.server_address))
  server.serve_forever()

Client

Client will send OSCBundle and OSCMessages

import argparse
import random
import time

from osc import OSCMessage, OSCClient, OSCBundle


if __name__ == "__main__":
  parser = argparse.ArgumentParser()
  parser.add_argument("--ip", default="127.0.0.1",
      help="The ip of the OSC server")
  parser.add_argument("--port", type=int, default=8000,
      help="The port the OSC server is listening on")
  args = parser.parse_args()

  client = OSCClient(args.ip, args.port)

  for value in ["Lorem ipsum dolore sit amet", 123, True, bytes( "utf-8 text", "utf-8" )]:
    msg = OSCMessage(address = "/debug")
    msg.add( value )

    client.send(msg)

  msg1 = OSCMessage(address = "/bundle/a")
  msg1.add( 123 )

  msg2 = OSCMessage(address = "/bundle/b")
  msg2.add( False )

  bun = OSCBundle()
  bun.add( msg1 )
  bun.add( msg2 )

  client.send( bun )

  for x in range(10):
    msg = OSCMessage(address = "/filter")
    msg.add(random.random())

    client.send(msg)
    time.sleep(1)