Streaming Control

Streaming World Guide one continuous realtime world with open-ended Events. Your application controls intent, continuity, and whether the world advances; Vivix plans the dialogue, movement, reactions, timing, and presentation together.

Connect control and media

Create a Streaming World Session first, then use the returned control and media descriptors as opaque connection details. Connect the media descriptor with the Vivix realtime media client and connect the WSS control channel with control.url and control.client_secret. Do not infer or hardcode an underlying media transport.

Read the Session capabilities and expose only the controls supported by that Session.
Connect the opaque media descriptor and begin rendering the continuous output.
Connect WSS. A new connection receives session.ready; a reconnect receives session.snapshot instead.
Send client events with a stable, client-generated event_id and wait for the corresponding server lifecycle event.

Control the world with Events

event.create guides the unpublished future of the running world. An Event is still prompt-shaped: describe the experience you want as one coherent, open-ended intent. Do not split speech and behavior into separate speaker turns, dialogue lines, actions, beats, scenes, or other orchestration objects.

Keep multi-character interaction natural. Name the relevant references, describe the dramatic or interactive direction, and let Vivix decide how many turns, pauses, reactions, and movements are needed.

event.create

{
  "event_id": "evt_world_020",
  "type": "event.create",
  "event": {
    "content": [
      { "type": "input_reference", "name": "A" },
      { "type": "input_reference", "name": "B" },
      {
        "type": "input_text",
        "text": "A notices that B keeps one hand hidden below the counter and begins to test his story. B first pretends not to understand, then accidentally reveals too much. Let the exchange develop naturally. Preserve both characters’ identities, voices, positions, and prior experience."
      }
    ],
    "handling": "steer"
  }
}

Interpret Event lifecycle messages

Event	Application meaning
`event.accepted`	Vivix validated the Event and took responsibility for processing it. Output has not necessarily changed.
`event.applied`	The first media causally influenced by the Event entered the server-side outgoing path. This is neither viewer-render confirmation nor semantic completion.
`event.superseded`	A newer Event took over the active steering frontier. Already published consequences and continuity remain in Session history.
`event.failed`	An accepted Event could not be applied. Inspect the structured error and its retry guidance.

There is no event.completed lifecycle message. An Event can influence a continuous world long after its first visible effect, so it has no reliable semantic completion boundary.

Redirect, hold, and resume

Redirect with a newer Event. Send another event.create when the user or application should change what happens next. The default steer handling preserves committed media and redirects the unpublished future at a safe boundary. Cancel only when supported. Check capabilities.event_cancel before sending event.cancel. Once an Event has been applied, its influence is part of media history; send a newer Event instead of trying to roll it back. Hold without closing. Send session.hold to stop new world progression at a safe media boundary while preserving Session continuity and the last available visual output. Resume the same world. Send session.resume and wait for media.state.updated. Creating a new Event while held also requests an implicit resume. Redirecting, cancelling, or holding never retracts media that has already been committed, published, or buffered by a client.

Maintain application state from server events

Reconnect. Use session.snapshot as the new operational baseline. Events missed while disconnected are not replayed, and the snapshot is not an authoritative semantic description of the generated world.
Ordering. Process live events in sequence order and use gaps as a connection-health signal, not as evidence about world semantics.
Captions. Append caption.delta fragments by caption id, then replace the assembled text with the authoritative caption.completed value.
Usage. Treat usage.updated as a cumulative application-level view of generated audio and video usage.
Media. Drive loading, running, held, stalled, and recovery UI from media.state.updated without depending on transport implementation details.

Recommended event flow

POST /v1/streaming-world/sessions
connect opaque media descriptor
connect control WSS
<- session.ready
-> event.create(evt_world_001)
<- event.accepted(world_event_001)
<- media.state.updated(running)
<- event.applied(world_event_001)
-> event.create(evt_world_002)  // redirect what happens next
<- event.accepted(world_event_002)
<- event.applied(world_event_002) and event.superseded(world_event_001), in sequence order
-> session.hold
<- media.state.updated(held)
[control connection reconnects]
<- session.snapshot
-> session.resume
<- media.state.updated(running)
<- caption.delta* / caption.completed
<- usage.updated*

Media, caption, and usage messages can interleave with Event lifecycle messages. Reduce them in server sequence order instead of waiting for one fixed global ordering.

API Reference. This guide explains the control model. For complete schemas, see Sessions, Client events, and Server events.

Overview

A1: Streaming Avatar

W1: Streaming World

Blazing Fast Video Generation

Connect control and media

Control the world with Events

Interpret Event lifecycle messages

Redirect, hold, and resume

Maintain application state from server events

Recommended event flow

​Connect control and media

​Control the world with Events

​Interpret Event lifecycle messages

​Redirect, hold, and resume

​Maintain application state from server events

​Recommended event flow

Connect control and media

Control the world with Events

Interpret Event lifecycle messages

Redirect, hold, and resume

Maintain application state from server events

Recommended event flow