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

# Session lifecycle

> What happens from the moment a viewer opens your stream — queue, connect, AFK, disconnect.

A **session** is one viewer connected to your stream. This page is the reference for what state a session is in at any moment, what happens when all your workers are busy, how AFK timeouts work, and how to handle disconnects.

## Session states

The Web SDK exposes the session's current state. Use it to drive your loading UI, queue position, and reconnect messaging.

| State          | Meaning                                                            |
| -------------- | ------------------------------------------------------------------ |
| `requesting`   | Browser is connecting to Streampixel.                              |
| `queued`       | No worker free; the viewer is waiting in line.                     |
| `connecting`   | Worker assigned; stream is being set up.                           |
| `streaming`    | Stream is live; video and audio flowing.                           |
| `idle`         | Viewer has been inactive past the AFK warning threshold.           |
| `disconnected` | Session ended cleanly.                                             |
| `failed`       | Session ended unexpectedly (network drop, app crashed, no worker). |

## Queue system

When every worker in your project's region is busy, new viewers wait in a queue. The Web SDK fires events with the viewer's position so you can render a wait UI.

<Steps>
  <Step title="Viewer opens your stream">
    Session starts in `requesting`, then moves to `queued` if no worker is free.
  </Step>

  <Step title="Position updates flow to your UI">
    The Web SDK fires events whenever the viewer's position improves. Show a queue UI with the current position.
  </Step>

  <Step title="Slot opens">
    The first viewer in line is promoted to `connecting`, and a worker is reserved for them.
  </Step>
</Steps>

<Tip>
  Increase your project's worker count to reduce queueing during peak traffic. See [configuring your project](/resources/quick-start-guide/configuring-your-project).
</Tip>

## AFK timeout

To free workers from idle viewers, Streampixel tracks the time since the viewer's last input. After a configurable threshold the viewer sees a warning; if they don't interact, the session ends.

| Setting            | Default                  | Notes                                |
| ------------------ | ------------------------ | ------------------------------------ |
| Warning timeout    | 2 minutes of inactivity  | Warning UI appears in the SDK.       |
| Disconnect timeout | 30 seconds after warning | Session ends with an AFK disconnect. |

Both thresholds are configurable from project settings or the Web SDK init options. Disable AFK only if you have a clear reason — idle sessions hold an entire GPU worker.

## Disconnect codes

Sessions end with a code that tells you whether the disconnect was normal, the viewer's choice, or a problem on your build/server.

| Code   | Meaning                                          |
| ------ | ------------------------------------------------ |
| `1000` | Normal closure.                                  |
| `1001` | Going away (tab closed, browser quit).           |
| `1006` | Abnormal closure (network drop, no close frame). |
| `4000` | Project disabled.                                |
| `4001` | No worker available.                             |
| `4002` | App not found.                                   |
| `4003` | App unable to launch.                            |
| `4004` | Max runtime reached.                             |
| `4005` | Streamer not found.                              |
| `4006` | App crashed.                                     |
| `4007` | Reconnection failed.                             |

Full reference and how to recover from each: [disconnect codes](/resources/quick-start-guide/disconnect-codes).

## Reconnection

The Web SDK has built-in reconnection for transient failures. On `1006` and `4007`, the SDK retries with exponential backoff until the viewer gives up or a connection succeeds. You can hook into reconnection events to render your own UI.

<Note>
  Reconnection is not guaranteed to land on the same worker — the new session may even be on a fresh worker, depending on availability.
</Note>

For app-level codes (`4000`–`4006`), reconnection alone won't fix the problem. Surface a meaningful error to the viewer and, where appropriate, link to a status page or a "try again" button.

## What ends a session

| Trigger                   | Code(s) | Notes                                          |
| ------------------------- | ------- | ---------------------------------------------- |
| Viewer closes tab         | `1001`  | Normal end-of-session.                         |
| Network drop              | `1006`  | SDK reconnects automatically.                  |
| AFK timeout               | `4004`  | Configurable threshold.                        |
| All workers busy at start | `4001`  | Viewer never reached `streaming`.              |
| App crashed               | `4006`  | Build-side problem; check UE logs.             |
| Project disabled          | `4000`  | Owner disabled the project from the dashboard. |

## Next steps

<CardGroup cols={2}>
  <Card title="Disconnect codes" icon="plug-circle-xmark" href="/resources/quick-start-guide/disconnect-codes">
    Full code reference and recovery patterns.
  </Card>

  <Card title="Web SDK overview" icon="code" href="/resources/web-sdk/getting-started/overview">
    Hook into session events from your frontend.
  </Card>

  <Card title="Configuring your project" icon="sliders" href="/resources/quick-start-guide/configuring-your-project">
    Tune worker count, AFK timeouts, and more.
  </Card>

  <Card title="Codec settings" icon="film" href="/resources/quick-start-guide/codec-settings">
    Pick the right codec for your audience and content.
  </Card>
</CardGroup>