DOCSEARCHbyAlgolia
Submit Docs

OSC Jack Documentation

repository·main·Indexed 19 days ago

https://github.com/keijiro/oscjack

A lightweight C# implementation of the Open Sound Control (OSC) protocol for Unity (version 2.0.0). It provides high-level Unity components like OSC Event Receiver, OSC Property Sender, and OSC Monitor, as well as a low-level API via OscClient and OscServer for custom networking logic. Supports int, float, and string data types.

Tokens
1K
Snippets
3
Records
7
Agent score
18%

What's inside OSC Jack

  1. Create an OSC Connection file

    main

    OSC Jack components use OSC Connection files (ScriptableObjects) to define connection types, host addresses, and port numbers.

    To create one:

    1. In the Unity Editor, navigate to Assets > Create > ScriptableObjects > OSC Jack > Connection.
    2. Configure the host address.
      • To send messages: You must specify a target host address.
      • To receive messages only: Leave the host address empty.

  2. Use OSC Components in Unity

    main

    OSC Jack provides high-level Unity components for common tasks:

    • OSC Event Receiver: Receives incoming OSC messages and triggers a UnityEvent containing the received data.
    • OSC Property Sender: Monitors a specific property on a Unity component and automatically sends OSC messages whenever that property changes.
    • OSC Monitor: A utility window for inspecting incoming OSC messages. Open it via Window > OSC Monitor.

  3. Install OSC Jack via Keijiro scoped registry

    main

    OSC Jack is available through the Keijiro scoped registry. To install it in your Unity project, you must add the registry to your project settings using the following details:

    • Name: Keijiro
    • URL: https://registry.npmjs.com
    • Scope: jp.keijiro

    Refer to this gist for specific instructions on how to add the registry to your Unity project.

  5. Receive OSC messages with OscServer

    main

    The OscServer class is used to listen for incoming OSC messages on a specific port.

    Key Details:

    • Message Dispatching: Use server.MessageDispatcher.AddCallback to register a delegate for a specific OSC address. Passing an empty string "" will allow the callback to receive all messages.
    • Threading Warning: The server invokes callbacks on a server thread, not the Unity main thread. If you need to interact with Unity components or APIs within the callback, you must queue the event for processing on the main thread.
    • Lifecycle: OscServer implements IDisposable and should be managed within a using block or disposed of properly.

    Example usage:

    using (var server = new OscServer(9000)) // Port number
{
  server.MessageDispatcher.AddCallback(
    "/test", // OSC address
    (string address, OscDataHandle data) => {
        Debug.Log(string.Format("({0}, {1})",
            data.GetElementAsFloat(0),
            data.GetElementAsFloat(1)));
    }
  );
  yield return new WaitForSeconds(10);
}

  6. Send OSC messages with OscClient

    main

    The OscClient class is used to send OSC messages. It supports up to four arguments per message. OscClient implements IDisposable, so it should be wrapped in a using block or manually disposed of to release resources.

    Example usage:

    // IP address, port number
using (var client = new OscClient("127.0.0.1", 9000))
{
  // Send two-component float values ten times.
  for (var i = 0; i < 10; i++)
  {
    yield return new WaitForSeconds(0.5f);
    client.Send("/test",       // OSC address
                i * 10.0f,     // First element
                Random.value); // Second element
  }
}