Extension: omni.kit.collaboration.channel_manager-1.1.0

Documentation Generated: Mar 06, 2026

Introduction#

Extension omni.kit.collaboration.channel_manager provides interfaces for creating/managing the Nucleus Channel easily and defines standard protocol for multiple users to do communication in the same channel. At the same time, users can be aware of each other.

User Liveness Detection (Heartbeat)#

The channel manager implements a heartbeat mechanism to detect when users have disconnected or become unresponsive.

How It Works#

  1. Periodic Pings: The channel manager sends GET_USERS messages continuously between configured time intervals (default to 60 seconds) to all users in the channel.

  2. Response Tracking: When users receive a GET_USERS message, they respond with HELLO. The channel manager tracks response times.

  3. Drop Detection: Users who don’t respond within the ping interval are considered “dropped” and a LEFT event is fired.

Thread-Safe Heartbeat#

Starting from version 1.1.0, heartbeat operations run in a dedicated background thread (HeartbeatThread). This ensures that:

  • Heartbeat pings continue even when the main thread is blocked (e.g., during long USD operations, file I/O, or heavy computations).

  • Other users won’t incorrectly see this user as “dropped” during temporary main thread hangs.

  • Thread-safe communication between the main thread and heartbeat thread via queues and locks.

The heartbeat thread handles:

  • Sending periodic GET_USERS pings

  • Responding to incoming GET_USERS with HELLO

  • Tracking user response times

  • Detecting and reporting dropped users

Goal#

The Nucleus Channel only provides a way to pub/sub messages from the channel. It does not provide APIs to manage user states, nor complete application protocol for all clients to understand each other. It’s transient and stateless, so that messages that were sent before user has joined will not be sent again. It does not support P2P message, so that messages sent to the channel are broadcasted to all users. Therefore, we made the following extensions:

  • It’s able to query user states from the API, and gets notified when users joined/left.

  • It defines application protocol for all clients that support it to communicate with each other.

  • It provides robust user liveness detection that works even when the main thread is blocked.

Currently, no P2P communication is supported still.

Programming Guide#

Here is an async function that joins a channel and sends a string message hello, world to the channel.

import omni.kit.collaboration.channel_manager as cm

async def join_channel_async(channel_url, on_message: Callable[[cm.Message], None]):
    # Joins the channel, and adds subscriber to subscribe messages.
    channel = await cm.join_channel_async(channel_url)
    if channel:
        channel.add_subscriber(on_message)

        # Sends message in dict
        await channel.send_message_async({"test" : "hello world"})

As you can see, the first step is to join a channel with omni.kit.collaboration.channel_manager.join_channel_async(), which will return a handle of the channel, through which you can query its connection states, other users that joined the same channel, and send messages (see omni.kit.collaboration.channel_manager.Channel.send_message_async()) specific to your applicaton in the format of Python dict. Also, it supports adding subscribers through omni.kit.collaboration.channel_manager.Channel.add_subscriber() to subscribe to messages received from the channel. Messages received from other users are in type omni.kit.collaboration.channel_manager.Message, and depends on the value of its message_type property, message can be catagorized into the following types (see omni.kit.collaboration.channel_manager.MessageType for details):

  • JOIN: New user joined this channel.

  • HELLO: Someone said hello to me. Normally, it’s received when a new user joined the channel, and other users exist in the channel will reply HELLO so new user could be aware of them.

  • LEFT: Someone left the channel. This is also fired when a user is detected as “dropped” (no heartbeat response).

  • GET_USERS: Ping message to find out who joined this channel. Clients received this message should reply HELLO.

  • MESSAGE: Application specific message sent through API omni.kit.collaboration.channel_manager.Channel.send_message_async().