View Source OSCx (OSCx v0.1.0)

This is the main OSCx module.

OSCx is an Elixir library for encoding and decoding Open Sound Control (OSC) messages and bundles.

OSC is a flexible protocol that can be used for a wide variety of real-time tasks, such as controlling multimedia devices.

Note that this library is deliberately minimilistic and no network transport or process logic is included.

Concepts, messages and bundles

You can learn more about OSC and it's concepts and how to use this library by:

Example

To encode a basic message:

iex> my_message = %OSCx.Message{address: "/my_synth/volume", arguments: [0.25]}
%OSCx.Message{address: "/my_synth/volume", arguments: [0.25]}

iex> binary_message = OSCx.encode(my_message)
<<47, 109, 121, 95, 115, 121, 110, 116, 104, 47, 118, 111, 108, 117, 109, 101,
0, 0, 0, 0, 44, 102, 0, 0, 62, 128, 0, 0>>

To decode a binary OSC message:

iex> binary_message = <<47, 109, 121, 95, 115, 121, 110, 116, 104, 47, 118, 111, 108, 117, 109, 101, 0, 0, 0, 0, 44, 102, 0, 0, 62, 128, 0, 0>>
<<47, 109, 121, 95, 115, 121, 110, 116, 104, 47, 118, 111, 108, 117, 109, 101,
0, 0, 0, 0, 44, 102, 0, 0, 62, 128, 0, 0>>

iex> decoded_message = OSCx.decode(binary_message)
%OSCx.Message{address: "/my_synth/volume", arguments: [0.25]}

TCP

If using TCP as the transport mechanism, append the :tcp atom to the encode function:

OSCx.encode(my_message_or_bundle, :tcp)

This frames the OSC packet with the message length in the header. This isn't required by UDP. See encode/2 for more information.

Summary

Functions

Decodes a binary OSC Message or Bundle.

Encodes an %OSCx.Message{} or %OSCx.Bundle{} struct as OSC binary data.

Functions

Link to this function

decode(message_or_bundle)

View Source

Decodes a binary OSC Message or Bundle.

Example

iex> binary_msg = <<47, 115, 116, 97, 116, 117, 115, 0, 44, 105, 0, 0, 0, 0, 0, 1>>
<<47, 115, 116, 97, 116, 117, 115, 0, 44, 105, 0, 0, 0, 0, 0, 1>>

iex> binary_msg |> OSCx.decode()
%OSCx.Message{address: "/status", arguments: [0]}
Link to this function

encode(message_or_bundle)

View Source
@spec encode(map()) :: binary()
Link to this function

encode(message_or_bundle, atom)

View Source

Encodes an %OSCx.Message{} or %OSCx.Bundle{} struct as OSC binary data.

Takes as %OSCx.Message{} or %OSCx.Bundle{} as the first parameter.

Example

# Encode a message
iex> %OSCx.Message{address: "/status", arguments: [1]} |> OSCx.encode()
<<47, 115, 116, 97, 116, 117, 115, 0, 44, 105, 0, 0, 0, 0, 0, 1>>

# Encode a bundle with a message
iex> OSCx.Bundle.new(
  elements: [OSCx.Message.new()],
  time: %{seconds: 1, fraction: 100}
  )
  |> OSCx.encode()
[
  <<35, 98, 117, 110, 100, 108, 101, 0>>,
  {116, <<0, 0, 0, 1, 0, 0, 0, 100>>},
  [<<0, 0, 0, 8, 47, 0, 0, 0, 44, 0, 0, 0>>]
]

TCP

If using TCP as the transport mechansim, pass the :tcp atom as the second parameter:

OSCx.encode(my_message_or_bundle, :tcp)

This will prefix the length (byte size) of the OSC binary data in 32-bits.

This is because in stream-based protocols such as TCP, the outgoing OSC packets are required to be framed using the packet's length in the header.

This isn't needed if using UDP.