osc

package
v0.0.0-...-cdbd92c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 26, 2022 License: MIT Imports: 12 Imported by: 3

Documentation

Overview

Package osc provides a package for sending and receiving OpenSoundControl messages. The package is implemented in pure Go.

Package osc provides a client and server for sending and receiving OpenSoundControl messages.

The package is implemented in pure Go.

The implementation is based on the Open Sound Control 1.0 Specification (http://opensoundcontrol.org/spec-1_0).

Open Sound Control (OSC) is an open, transport-independent, message-based protocol developed for communication among computers, sound synthesizers, and other multimedia devices.

Features:

  • Supports OSC messages with 'i' (Int32), 'f' (Float32), 's' (string), 'b' (blob / binary data), 'h' (Int64), 't' (OSC timetag), 'd' (Double/int64), 'T' (True), 'F' (False), 'N' (Nil) types.
  • OSC bundles, including timetags
  • Support for OSC address pattern including '*', '?', '{,}' and '[]' wildcards

This OSC implementation uses the UDP protocol for sending and receiving OSC packets.

The unit of transmission of OSC is an OSC Packet. Any application that sends OSC Packets is an OSC Client; any application that receives OSC Packets is an OSC Server.

An OSC packet consists of its contents, a contiguous block of binary data, and its size, the number of 8-bit bytes that comprise the contents. The size of an OSC packet is always a multiple of 4.

OSC packets come in two flavors:

OSC Messages: An OSC message consists of an OSC address pattern, followed by an OSC Type Tag String, and finally by zero or more OSC arguments.

OSC Bundles: An OSC Bundle consists of the string "#bundle" followed by an OSC Time Tag, followed by zero or more OSC bundle elements. Each bundle element can be another OSC bundle (note this recursive definition: bundle may contain bundles) or OSC message.

An OSC bundle element consists of its size and its contents. The size is an int32 representing the number of 8-bit bytes in the contents, and will always be a multiple of 4. The contents are either an OSC Message or an OSC Bundle.

The following argument types are supported: 'i' (Int32), 'f' (Float32), 's' (string), 'b' (blob / binary data), 'h' (Int64), 't' (OSC timetag), 'd' (Double/int64), 'T' (True), 'F' (False), 'N' (Nil).

go-osc supports the following OSC address patterns: - '*', '?', '{,}' and '[]' wildcards.

Usage

OSC client example: 

client := osc.NewClient("localhost", 8765)
msg := osc.NewMessage("/osc/address")
msg.Append(int32(111))
msg.Append(true)
msg.Append("hello")
client.Send(msg)

OSC server example: 

addr := "127.0.0.1:8765"
d := osc.NewStandardDispatcher()
d.AddMsgHandler("/message/address", func(msg *osc.Message) {
    osc.PrintMessage(msg)
})

server := &osc.Server{
    Addr: addr,
    Dispatcher:d,
}
server.ListenAndServe()

Index

Constants

View Source 
const (
	MaxPacketSize int = 65535
)

Variables

This section is empty.

Functions

func GetTypeTag 

func GetTypeTag(arg interface{}) (string, error)

GetTypeTag returns the OSC type tag for the given argument.

Types

type Bundle 

type Bundle struct {
	Timetag  Timetag
	Elements []Packet
}

Bundle represents an OSC bundle. It consists of the OSC-string "#bundle" followed by an OSC Time Tag, followed by zero or more OSC bundle/message elements. The OSC-timetag is a 64-bit fixed point time tag. See http://opensoundcontrol.org/spec-1_0 for more information.

func NewBundle 

func NewBundle(time time.Time) *Bundle

NewBundle returns an OSC Bundle. Use this function to create a new OSC Bundle.

func NewBundleFromData 

func NewBundleFromData(data []byte) (b *Bundle, err error)

NewBundleFromData returns a new OSC bundle created from the parsed data.

func (*Bundle) Append 

func (b *Bundle) Append(pck Packet) error

Append appends an OSC bundle or OSC message to the bundle.

func (*Bundle) LightMarshalBinary 

func (b *Bundle) LightMarshalBinary(data *bytes.Buffer) error

LightMarshalBinary allows you to marshal a bundle into a bytes.Buffer to avoid an allocation.

func (*Bundle) MarshalBinary 

func (b *Bundle) MarshalBinary() (bb []byte, err error)

MarshalBinary implements the encoding.BinaryMarshaler

func (*Bundle) UnmarshalBinary 

func (b *Bundle) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

type Client 

type Client struct {
	IP   string
	Port int
	// contains filtered or unexported fields
}

Client enables you to send OSC packets. It sends OSC messages and bundles to the given IP address and port.

func NewClient 

func NewClient(ip string, port int) *Client

NewClient creates a new OSC client. The Client is used to send OSC messages and OSC bundles over an UDP network connection. The `ip` argument specifies the IP address and `port` defines the target port where the messages and bundles will be send to.

func (*Client) Send 

func (c *Client) Send(packet Packet) error

Send sends an OSC Bundle or an OSC Message.

func (*Client) SetLocalAddr 

func (c *Client) SetLocalAddr(ip string, port int) error

SetLocalAddr sets the local address.

type Dispatcher 

type Dispatcher interface {
	Dispatch(packet Packet)
}

Dispatcher is an interface for an OSC message dispatcher. A dispatcher is responsible for dispatching received OSC messages.

type Handler 

type Handler interface {
	HandleMessage(msg *Message)
}

Handler is an interface for message handlers. Every handler implementation for an OSC message must implement this interface.

type HandlerFunc 

type HandlerFunc func(msg *Message)

HandlerFunc implements the Handler interface. Type definition for an OSC handler function.

func (HandlerFunc) HandleMessage 

func (f HandlerFunc) HandleMessage(msg *Message)

HandleMessage calls itself with the given OSC Message. Implements the Handler interface.

type Message 

type Message struct {
	Address   string
	Arguments []interface{}
}

Message represents a single OSC message. An OSC message consists of an OSC address pattern and zero or more arguments.

func NewMessage 

func NewMessage(addr string, args ...interface{}) *Message

NewMessage returns a new Message. The address parameter is the OSC address.

func NewMessageFromData 

func NewMessageFromData(data []byte) (msg *Message, err error)

func (*Message) Append 

func (m *Message) Append(args ...interface{}) error

Append appends the given arguments to the arguments list.

func (*Message) Clear 

func (m *Message) Clear()

func (*Message) LightMarshalBinary 

func (m *Message) LightMarshalBinary(data *bytes.Buffer) error

func (*Message) MarshalBinary 

func (m *Message) MarshalBinary() (b []byte, err error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (*Message) Match 

func (m *Message) Match(addr string) bool

Match returns true, if the OSC address pattern of the OSC Message matches the given address. The match is case sensitive!

func (*Message) String 

func (m *Message) String() string

String implements the fmt.Stringer interface.

func (*Message) TypeTags 

func (m *Message) TypeTags() (string, error)

TypeTags returns the type tag string.

func (*Message) UnmarshalBinary 

func (m *Message) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler

type Packet 

type Packet interface {
	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
}

Packet is the interface for Message and Bundle.

func ReadPacket 

func ReadPacket(data []byte) (Packet, error)

ReadPacket parses an OSC packet.

type Server 

type Server struct {
	Addr        string
	Dispatcher  Dispatcher
	ReadTimeout time.Duration
	// contains filtered or unexported fields
}

Server represents an OSC server. The server listens on Address and Port for incoming OSC packets and bundles.

func (*Server) Close 

func (s *Server) Close() error

Close shuts down the server and closes it's upd connection

func (*Server) ListenAndServe 

func (s *Server) ListenAndServe() error

ListenAndServe retrieves incoming OSC packets and dispatches the retrieved OSC packets.

func (*Server) ReceivePacket 

func (s *Server) ReceivePacket(c net.PacketConn) (Packet, error)

ReceivePacket listens for incoming OSC packets and returns the packet if one is received.

func (*Server) Serve 

func (s *Server) Serve(c net.PacketConn) error

Serve retrieves incoming OSC packets from the given connection and dispatches retrieved OSC packets. If something goes wrong an error is returned.

type StandardDispatcher 

type StandardDispatcher struct {
	// contains filtered or unexported fields
}

StandardDispatcher is a dispatcher for OSC packets. It handles the dispatching of received OSC packets to Handlers for their given address.

func NewStandardDispatcher 

func NewStandardDispatcher() *StandardDispatcher

NewStandardDispatcher returns an StandardDispatcher.

func (*StandardDispatcher) AddMsgHandler 

func (s *StandardDispatcher) AddMsgHandler(addr string, handler HandlerFunc) error

AddMsgHandler adds a new message handler for the given OSC address.

func (*StandardDispatcher) Dispatch 

func (s *StandardDispatcher) Dispatch(packet Packet)

Dispatch dispatches OSC packets. Implements the Dispatcher interface.

type Timetag 

type Timetag uint64

Timetag represents an OSC Time Tag. An OSC Time Tag is defined as follows: Time tags are represented by a 64 bit fixed point number. The first 32 bits specify the number of seconds since midnight on January 1, 1900, and the last 32 bits specify fractional parts of a second to a precision of about 200 picoseconds. This is the representation used by Internet NTP timestamps.

func NewTimetagFromTime 

func NewTimetagFromTime(timeStamp time.Time) Timetag

NewTimetagFromTime returns a new OSC time tag object from a time.Time.

func (Timetag) ExpiresIn 

func (t Timetag) ExpiresIn() time.Duration

ExpiresIn calculates the number of seconds until the current time is the same as the value of the time tag. It returns zero if the value of the time tag is in the past.

func (Timetag) FractionalSecond 

func (t Timetag) FractionalSecond() uint32

FractionalSecond returns the last 32 bits of the OSC time tag. Specifies the fractional part of a second.

func (Timetag) MarshalBinary 

func (t Timetag) MarshalBinary() (b []byte, err error)

MarshalBinary converts the OSC time tag to a byte array.

func (Timetag) SecondsSinceEpoch 

func (t Timetag) SecondsSinceEpoch() uint32

SecondsSinceEpoch returns the first 32 bits (the number of seconds since the midnight 1900) from the OSC time tag.

func (*Timetag) SetTime 

func (t *Timetag) SetTime(time time.Time)

SetTime sets the value of the OSC time tag.

func (Timetag) Time 

func (t Timetag) Time() time.Time

Time returns the time.

func (Timetag) TimeTag 

func (t Timetag) TimeTag() uint64

TimeTag returns the time tag value

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.