View Source OSCx (OSCx v0.1.1)
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:
- accessing the README file
- taking the Livebook tour
- browsing the simple Examples
- reading the
OSCx.Message
orOSCx.Bundle
module documentation - reading about OSC arguments and types
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
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]}
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.