> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vivix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<h2 id="streaming-world-control-connection">
  Connect control and media
</h2>

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.

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

<h2 id="streaming-world-control-events">
  Control the world with Events
</h2>

`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.

<Note>
  **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.
</Note>

```json event.create theme={null}
{
  "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"
  }
}
```

<h2 id="streaming-world-control-lifecycle">
  Interpret Event lifecycle messages
</h2>

| 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. |

<Note>
  **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.
</Note>

<h2 id="streaming-world-control-continuity">
  Redirect, hold, and resume
</h2>

**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.

<h2 id="streaming-world-control-application-state">
  Maintain application state from server events
</h2>

* **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.

<h2 id="streaming-world-control-flow">
  Recommended event flow
</h2>

```text theme={null}
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.

<Note>
  **API Reference.** This guide explains the control model. For complete schemas, see [Sessions](/streaming-world/api-references/sessions), [Client events](/streaming-world/api-references/client-events), and [Server events](/streaming-world/api-references/server-events).
</Note>