Overview#

The omni.services.livestream.session extension provides REST API endpoints to control livestream sessions in Omniverse Kit applications. It manages session lifecycle, streaming credentials, and health checks for streaming-ready status.

Purpose#

This extension serves as a bridge between external session management systems (like NVCF) and Omniverse applications by:

  1. Exposing REST endpoints for session management

  2. Handling session lifecycle events (ready, connected, ended)

  3. Managing streaming credentials for WebRTC connections

  4. Providing health check endpoints for streaming readiness

  5. Supporting graceful session termination and resumption

Architecture#

The extension consists of these key components:

  • FastAPI Router: Defines REST API endpoints for session management

  • Event System: Handles the communication of session events between components

  • Session State Management: Tracks application, RTX, and session readiness

  • Session Lifecycle Handlers: Manages session start, end, and resume workflows

Configuration Settings#

The extension provides the following configurable settings:

# Settings path and default values
exts."omni.services.livestream.session".quitOnSessionEnded = true        # Whether to quit the application when a session ends
exts."omni.services.livestream.session".resumeTimeoutSeconds = 30        # Number of seconds to wait for session resumption (0 = no resumption)
exts."omni.services.livestream.session".waitForSessionReadyEvent = false # Whether to wait for an explicit session ready event
exts."omni.services.transport.server.http".port = 8011                   # HTTP port for the REST API server

These settings can be configured in your application’s .kit file:

[settings]
exts."omni.services.livestream.session".quitOnSessionEnded = true
exts."omni.services.livestream.session".resumeTimeoutSeconds = 30
exts."omni.services.livestream.session".waitForSessionReadyEvent = true
exts."omni.services.transport.server.http".port = 8011

Or by using command line arguments:

--/exts/omni.services.livestream.session/quitOnSessionEnded=true
--/exts/omni.services.livestream.session/resumeTimeoutSeconds=30
--/exts/omni.services.livestream.session/waitForSessionReadyEvent=true
--/exts/omni.services.transport.server.http/port=8011

Or programmatically:

import carb.settings

settings = carb.settings.get_settings()
settings.set_bool("exts/omni.services.livestream.session/quitOnSessionEnded", True)
settings.set_int("exts/omni.services.livestream.session/resumeTimeoutSeconds", 30)
settings.set_bool("exts/omni.services.livestream.session/waitForSessionReadyEvent", True)
settings.set_int("exts/omni.services.transport.server.http/port", 8011)

Events#

The extension both listens for and dispatches events to communicate session state changes:

Events Listened For#

Event Name

Description

omni.kit.app.GLOBAL_EVENT_APP_READY

Indicates that the Kit application is ready

omni.usd.StageRenderingEventType.NEW_FRAME

Indicates that RTX rendering is ready

omni.services.livestream.session.ready

Indicates that the application is ready for streaming (when waitForSessionReadyEvent=true)

omni.kit.livestream.client_connected:immediate

Fired when a streaming client connects

omni.kit.livestream.client_disconnected:immediate

Fired when a streaming client disconnects

Events Dispatched#

Event Name

Description

omni.services.livestream.session.ended

Indicates the streaming session has ended

omni.services.livestream.session.stun_credentials

Delivers STUN and optional TURN credentials to streaming components

Event Usage Example#

import carb.eventdispatcher
from omni.services.livestream.session.services.api import SESSION_READY_EVENT

# Dispatch session ready event
carb.eventdispatcher.get_eventdispatcher().dispatch_event(SESSION_READY_EVENT)

# Listen for session ended event
def on_session_ended(event):
    print("Session ended, performing cleanup...")

carb.eventdispatcher.get_eventdispatcher().observe_event(
    event_name="omni.services.livestream.session.ended",
    on_event=on_session_ended,
    observer_name="my_observer"
)

REST API Endpoints#

The extension exposes the following REST API endpoints:

POST /v1/streaming/creds#

Sets the STUN and optional TURN credentials for WebRTC streaming.

Request Body:

{
  "stunIp": "stun.example.com",
  "stunPort": 3478,
  "username": "user",
  "password": "pass",
  "privateSharedPort": 49100,
  "turnDetails": {
    "username": "turnuser",
    "password": "turnpass",
    "uris": ["turns:1.2.3.4:443?transport=tcp", "turn:1.2.3.4:3478"],
    "relayProtocol": "TCP",
    "transportPolicy": "ALL",
    "relayLocation": "CSP"
  }
}

Note: The turnDetails field is optional. When provided, it enables TURN server support for TCP streaming fallback via relay servers when direct UDP connections fail.

TURN Transport Policies:

  • ALL: Attempt both direct (UDP) and relay (TCP via TURN) connections

  • RELAY: Only use relay connections via TURN servers

  • DIRECT: Only use direct UDP connections (no TURN)

TURN Relay Locations:

  • CSP: Cloud Service Provider relay servers

  • GFN: GeForce NOW relay servers

Response:

{
  "success": true,
  "errorMessage": null
}

POST /v1/streaming/endsession#

Ends the current streaming session.

Request Body:

{
  "sessionId": "session-uuid",
  "gracefulShutdown": true
}

Response:

{
  "sessionStatus": "COMPLETE"
}

Possible sessionStatus values:

  • COMPLETE: Session has ended

  • AWAITING_RESUME: Session is waiting for resumption

GET /v1/streaming/ready#

Health check endpoint to determine if the application is ready for streaming.

Response:

{
  "statusMessage": "Status: Ready for connection"
}

Possible status messages:

  • Status: App not ready (503)

  • Status: Rtx not ready (503)

  • Status: Session ready event not received (503)

  • Status: Waiting for previous client to disconnect (503)

  • Status: Streaming session ended (recycle instance) (503)

  • Status: Awaiting session resume (keep alive) (200)

  • Status: Streaming session active (keep alive) (200)

  • Status: Ready for connection (200)

GET /v1/streaming/startup#

Startup health check endpoint that always returns 200 OK, regardless of streaming service state.

Response:

{
  "statusMessage": "Status: Startup endpoint OK"
}

This endpoint is used for container startup health checks that should always succeed regardless of the streaming service’s readiness state. Unlike /v1/streaming/ready, this endpoint does not check application or RTX readiness.

Session Lifecycle#

The session lifecycle is managed as follows:

  1. Initialization Phase:

    • Application startup

    • RTX initialization

    • Session ready event (if waitForSessionReadyEvent=true)

  2. Active Phase:

    • Client connection

    • Streaming

    • Client interactions

  3. Termination Phase:

    • Graceful shutdown or connection loss

    • Session end event

    • Optional wait for session resumption

    • Application quit (if quitOnSessionEnded=true)

Integration with Other Extensions#

The omni.services.livestream.session extension:

  • Depends on omni.kit.livestream.app for application streaming capabilities

  • Depends on omni.services.core for REST API framework

  • Depends on omni.services.transport.server.http for HTTP transport

  • Works with omni.kit.livestream.webrtc for WebRTC streaming

Usage Examples#

Configuring the Session Service#

# Configure session settings
import carb.settings

settings = carb.settings.get_settings()
settings.set_bool("exts/omni.services.livestream.session/waitForSessionReadyEvent", True)
settings.set_int("exts/omni.services.livestream.session/resumeTimeoutSeconds", 30)

Signaling Session Readiness#

# Signal that the application is ready for streaming
import carb.eventdispatcher
from omni.services.livestream.session.services.api import SESSION_READY_EVENT

# App-specific initialization code
# ...

# Signal readiness
carb.eventdispatcher.get_eventdispatcher().dispatch_event(SESSION_READY_EVENT)

Handling Session End#

# Handle session end event
import carb.eventdispatcher
from omni.services.livestream.session.services.api import SESSION_ENDED_EVENT

def on_session_ended(event):
    # Perform cleanup
    # ...

    # Signal readiness for a new session
    from omni.services.livestream.session.services.api import SESSION_READY_EVENT
    carb.eventdispatcher.get_eventdispatcher().dispatch_event(SESSION_READY_EVENT)

# Register for session end events
carb.eventdispatcher.get_eventdispatcher().observe_event(
    event_name=SESSION_ENDED_EVENT,
    on_event=on_session_ended,
    observer_name="my_session_handler"
)

Version History#

The extension follows semantic versioning and maintains a detailed changelog. Prior to version 8.0.0, this extension was named omni.services.livestream.nvcf.

For detailed change history, refer to the CHANGELOG.md file.