Documentation
¶
Overview ¶
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()
Package osc provides a package for sending and receiving OpenSoundControl messages. The package is implemented in pure Go.
Index ¶
- func PrintMessage(msg *Message)
- type Bundle
- type Client
- func (c *Client) Close()
- func (c *Client) Connect() error
- func (c *Client) Connected() bool
- func (c *Client) Connection() *net.UDPConn
- func (c *Client) IP() string
- func (c *Client) ListenAndServe() error
- func (c *Client) Port() int
- func (c *Client) Send(packet Packet) error
- func (c *Client) SetConnection(conn *net.UDPConn)
- func (c *Client) SetDispatcher(d Dispatcher)
- func (c *Client) SetIP(ip string)
- func (c *Client) SetLocalAddr(ip string, port int) error
- func (c *Client) SetPort(port int)
- type Dispatcher
- type Handler
- type HandlerFunc
- type Message
- func (msg *Message) Append(args ...interface{})
- func (msg *Message) Clear()
- func (msg *Message) ClearData()
- func (msg *Message) CountArguments() int
- func (msg *Message) Equals(m *Message) bool
- func (msg *Message) MarshalBinary() ([]byte, error)
- func (msg *Message) Match(addr string) bool
- func (m *Message) SenderAddr() net.Addr
- func (msg *Message) String() string
- func (msg *Message) TypeTags() (string, error)
- type Packet
- type Server
- func (s *Server) CloseConnection() error
- func (s *Server) Listen() error
- func (s *Server) ListenAndServe() error
- func (s *Server) ReceivePacket() (Packet, error)
- func (s *Server) SendTo(packet Packet, addr net.Addr) error
- func (s *Server) Serve() error
- func (s *Server) SetConnection(c net.PacketConn)
- type StandardDispatcher
- type Timetag
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PrintMessage ¶
func PrintMessage(msg *Message)
PrintMessage pretty prints an OSC message to the standard output.
Types ¶
type Bundle ¶
type Bundle struct { Timetag Timetag Messages []*Message Bundles []*Bundle // contains filtered or unexported fields }
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 (*Bundle) MarshalBinary ¶
MarshalBinary serializes the OSC bundle to a byte array with the following format: 1. Bundle string: '#bundle' 2. OSC timetag 3. Length of first OSC bundle element 4. First bundle element 5. Length of n OSC bundle element 6. n bundle element
func (*Bundle) SenderAddr ¶
SenderAddr returns the sender address of this message. Returns nil if no address is available
type Client ¶
type Client struct {
// 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 ¶
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) Connect ¶
Connect explicitly connects to the target address. Normally you don't have to call this, as both Send and ListenAndServe establish the connection if necessary.
func (*Client) Connection ¶
Connection returns the current connection
func (*Client) ListenAndServe ¶
ListenAndServe starts the listening and dispatching loop. It listens on the same port, that was established by the client. You only need to call this if you expect responses from the server. This function only returns when there is an error, so better put it into a go routine.
func (*Client) Send ¶
Send sends an OSC Bundle or an OSC Message. If no connection exists, one will be established.
func (*Client) SetConnection ¶
SetConnection sets the connection to use
func (*Client) SetDispatcher ¶
func (c *Client) SetDispatcher(d Dispatcher)
SetDispatcher sets the dispatcher to use to handle responses.
func (*Client) SetLocalAddr ¶
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{} // contains filtered or unexported fields }
Message represents a single OSC message. An OSC message consists of an OSC address pattern and zero or more arguments.
func NewMessage ¶
NewMessage returns a new Message. The address parameter is the OSC address.
func (*Message) Append ¶
func (msg *Message) Append(args ...interface{})
Append appends the given arguments to the arguments list.
func (*Message) ClearData ¶
func (msg *Message) ClearData()
ClearData removes all arguments from the OSC Message.
func (*Message) CountArguments ¶
CountArguments returns the number of arguments.
func (*Message) Equals ¶
Equals returns true if the given OSC Message `m` is equal to the current OSC Message. It checks if the OSC address and the arguments are equal. Returns true if the current object and `m` are equal.
func (*Message) MarshalBinary ¶
MarshalBinary serializes the OSC message to a byte buffer. The byte buffer has the following format: 1. OSC Address Pattern 2. OSC Type Tag String 3. OSC Arguments
func (*Message) Match ¶
Match returns true, if the OSC address pattern of the OSC Message matches the given address. The match is case sensitive!
func (*Message) SenderAddr ¶
SenderAddr returns the sender address of this message. Returns nil if no address is available
type Packet ¶
type Packet interface { encoding.BinaryMarshaler SenderAddr() net.Addr }
Packet is the interface for Message and Bundle.
func ParsePacket ¶
ParsePacket parses the given msg string and returns a 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) CloseConnection ¶
CloseConnection forcibly closes a server's connection.
This causes a "use of closed network connection" error the next time the server attempts to read from the connection.
func (*Server) ListenAndServe ¶
ListenAndServe retrieves incoming OSC packets and dispatches the retrieved OSC packets.
func (*Server) ReceivePacket ¶
ReceivePacket listens for incoming OSC packets and returns the packet if one is received.
func (*Server) SendTo ¶
SendTo sends a message to the given address. The sender address will be the address and port the server is listening on.
func (*Server) Serve ¶
Serve retrieves incoming OSC packets from the given connection and dispatches retrieved OSC packets. If something goes wrong an error is returned.
func (*Server) SetConnection ¶
func (s *Server) SetConnection(c net.PacketConn)
SetConnection sets the connection to use for the server. This is for a case where you created the connection manually instead of using ListenAndServer.
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 struct { MinValue uint64 // Minimum value of an OSC Time Tag. Is always 1. // contains filtered or unexported fields }
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 NewTimetag ¶
NewTimetag returns a new OSC time tag object.
func NewTimetagFromTimetag ¶
NewTimetagFromTimetag creates a new Timetag from the given `timetag`.
func (*Timetag) ExpiresIn ¶
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 ¶
FractionalSecond returns the last 32 bits of the OSC time tag. Specifies the fractional part of a second.
func (*Timetag) MarshalBinary ¶
MarshalBinary converts the OSC time tag to a byte array.
func (*Timetag) SecondsSinceEpoch ¶
SecondsSinceEpoch returns the first 32 bits (the number of seconds since the midnight 1900) from the OSC time tag.