Live Session Utilities

Utility classes and functions for participating in Live Sessions.

Note: Nucleus is a compile-time optional feature which is required when using Live Session collaboration. These classes and functions are only available if Nucleus was enabled at compile time.

Live Session Class

The LiveSession class wraps the Live Session operations on the USD Stage, USD Layer, Info, Channel, and Config classes.

The LiveSession class contains:
- LiveSessionChannel class - handles messages between live clients (joining, leaving, merging)
- LiveSessionInfo class - collects much of the context for the live session file paths and URIs
- Live Session Config functions - reading and writing the live session configuration TOML file
- Join, merge, and leave member functions - coordinate the live session classes and USD layer details

The expected usage of this class:

Create an instance using LiveSession::create()
Browse available sessions using LiveSession::getInfo() -> LiveSessionInfo::getSessionNames()
Pick a session from the list or decide to create a new session, call LiveSession::join() - set makeEditTarget to set the stage’s edit target
At this point the root stage’s session layer now has a .live sublayer and the edit target is set to this .live layer
Changes made to the stage are directed to the .live layer. To sync with Nucleus use omniClientLiveProcess()
Changes from other clients automatically appear in the .live layer, USD Tf Notifications allow the app to reason about incoming changes to the stage
The Live Channel should be periodically processed and handled using LiveSession::getChannel() -> LiveSessionChannel::processMessages()
If the app wants to leave the session without merging, call LiveSession::leave()
The app can use either LiveSession::mergeToRoot() or LiveSession::mergeToNewLayer() to merge and leave the live session
At this point the LiveSession shared pointer can be destroyed or go out of scope

Live Session Channel Class

The LiveSessionChannel class is for connecting, sending, processing, and receiving Live Session channel messages. These messages are used to coordinate different Live Session events:

Users joining and leaving the session
Users peeking into the session to see who is connected
Users merging live changes and ending a session

Live Session Configuration File Utilities

These utilities are intended to assist in reading and writing the live session configuration TOML file. The config file is TOML-formatted and is primarily used to denote the owner, or admin of the live session.

Live Session config files are named __session__.toml and reside under the ./.live/root_stage_name.live/session_name.live/ directory (relative to the root stage location). The root.live and __session__.channel files are also stored in this directory.

The Live Session directory layout:

.live/
|__ root_stage_name.live/
    |__ session_name.live/
        |__ __session__.channel <- The live session channel
        |__ __session__.toml    <- The live session config file
        |__ root.live           <- The live session .live layer

Live Session Info Class

The LiveSessionInfo class collects much of the context for the live session file paths and URIs.

Note

These functions are all using synchronous file access with Nucleus. Further development is required to make these methods asynchronous.

Classes

omni::connect::core::LiveSession: An interface class provides Live Session lifetime management.
omni::connect::core::LiveSessionChannel: An interface class for the live session message channel.
omni::connect::core::LiveSessionInfo: An interface class that collects the URIs and strings required by a live session.

Enumerations

omni::connect::core::LiveSessionConfig: Live session configuration keys.

Functions

bool omni::connect::core::createLiveSessionConfigFile(const std::string &uri, const LiveSessionConfigMap &config): Create a Live Session configuration file.
LiveSessionConfigMap omni::connect::core::getLiveSessionConfig(const std::string &uri): Get configuration values from an existing Live Session configuration file.
bool omni::connect::core::isLiveSessionVersionCompatible(const std::string &uri): Check that the session config version is compatible.
bool omni::connect::core::setLiveSessionConfigValues(const std::string &uri, const LiveSessionConfigMap &config): Set configuration values in an existing Live Session configuration file.

Typedefs

omni::connect::core::LiveSessionConfigMap: An alias template declaration for the session configuration key-value pair map.

Variables

constexpr const char * omni::connect::core::kLiveSessionConfigVersion: The current version for the live session configuration file processing.
constexpr const char * omni::connect::core::kLiveSessionLinkKey: The uri query param used by Live Session Links ex: omniverse://helloworld.usd?live_session_name=Default.