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

# Test locally

> Stream from Unreal on your own machine into a Streampixel Web SDK page with the dev option: start a Test Locally session, connect Unreal, pass the session ID, and know what differs from a released stream.

Advanced For developers who build a page while the Unreal app is still changing. After this page you can stream from Unreal on your own machine into your page, without packaging or uploading a build.

Test locally streams from Unreal on your own machine instead of an uploaded build. Nothing is uploaded and no Streampixel GPU is used: your machine renders, and Streampixel connects the browser to it. The SDK joins such a session with the `dev` option.

```ts highlight={4} theme={"dark"}
const stream = await Streampixel.create({
  appId: 'YOUR_PROJECT_ID',
  container,
  dev: { sessionId: 'dev-1a2b3c' }, // from the dashboard's Test Locally tab
});
```

> [!NOTE]
>
> Test locally is in beta: the dashboard tab is labelled BETA. The `dev` option is part of `@streampixel/web-sdk` 2.0.0-beta.2.

## When to use it

| Use it to | Do not use it for |
| - | - |
| Build your page before the project has a build. | Viewers of a released app: they use the normal options, without `dev`. |
| Try a change in Unreal against your page without packaging and uploading a build. | Measuring start time, bitrate or resolution limits: the app runs on your machine and your network, not on Streampixel's GPU servers. |
| Work on the [messages between your page and your app](https://docs.streampixel.io/resources/web-sdk-v2/messaging.md): `emitUIInteraction()` or `send()` one way, `addResponseEventListener()` or the `ueMessage` event the other way. | The last check before a release: test the uploaded build. |

## How it works

A dev session is a meeting point for one Unreal process and your browser.

Streampixel connects the two: your page shows what Unreal renders on your machine.

You do three things, in three places:

1. **Dashboard**: start a session. It has an ID (`dev-` and six characters) and lasts 2 hours.
2. **Unreal**: connect to the session with its signalling URL or its launch argument.
3. **Your page**: pass the session ID to `create()`.

Steps 2 and 3 can be done in either order: the page waits for Unreal.

## Before you start

* A Streampixel project and its project ID. The project needs no build, and it may be switched off.
* Unreal Engine with the **Pixel Streaming** plugin enabled. It is already on if you have uploaded a build to Streampixel.
* A network that lets your machine reach Streampixel's dev streamer: outbound access to `dev-streamer.streampixel.io` on port `8888`. See [Test Locally](https://docs.streampixel.io/resources/dashboard/test-locally.md#before-you-start) in the dashboard guide.
* A page with the SDK [installed](https://docs.streampixel.io/resources/web-sdk-v2/installation.md), served over https or from `localhost`.
* A project whose access is public, password or single sign-on. A "Your app only" project (not available yet) cannot be opened with `dev`.

## Set it up

**1. Start a session in the dashboard**

Open the project, then the **Test Locally** tab, and start a session. The session's row shows:

| Shown | Use |
| - | - |
| The session ID: `dev-` and six characters, for example `dev-1a2b3c` | Pass it to the SDK as `dev.sessionId`. |
| **Signalling server URL** | For streaming the Level Editor. |
| **Launch argument**, in a Pixel Streaming 1 and a Pixel Streaming 2 form | For a Standalone Game or a packaged build. |
| **Preview link** | Streampixel's own player on the same session. The SDK does not need it. It is useful to tell a problem in your page from a problem in Unreal. |

A session lasts **2 hours**. The row shows the time left. After that, start a new session and use its ID: the old launch argument stops working.

> [!WARNING]
>
> The launch argument contains a token that identifies your session. Treat it like a password: do not commit it or paste it into a shared channel.

The dashboard side is described step by step in [Test Locally](https://docs.streampixel.io/resources/dashboard/test-locally.md).

**2. Connect Unreal**

There are three ways to connect Unreal to the session. Use one.

> [tab] Level Editor
>
> Paste the session's **Signalling server URL** into the **Signalling Server URL** field of the Pixel Streaming toolbar menu. Then choose **Stream Level Editor**.
>
> This streams what the editor shows. It needs no launch argument and no restart.

> [tab] Standalone Game
>
> Paste the session's **Launch argument** into **Editor Preferences → Level Editor → Play → Additional Launch Parameters**. Then choose **Standalone Game** from the Play dropdown.
>
> This starts a separate game process, launched the way Streampixel's servers launch a build. It renders off-screen, so no game window opens on your machine: you see it in your page.
>
> > [!WARNING]
> >
> > Play In Editor (selected viewport or new window) does not stream. Use **Standalone Game**.

> [tab] Packaged build
>
> Start the build with the **Launch argument** on its command line:
>
> ```text theme={"dark"}
> MyProject.exe <launch argument>
> ```

> [!TIP]
>
> The session's row in the dashboard shows **Connected** when Unreal has reached Streampixel.

> [accordion] PS1 or PS2: which launch argument?
>
> The launch argument comes in two forms, because Unreal renamed the plugin's settings in 5.5. Choose the one that matches the plugin your project uses:
>
> | Your plugin | Form | Flags it carries |
> | - | - | - |
> | Pixel Streaming (Unreal Engine 5.4 and earlier) | **PS1** | `-PixelStreamingURL=…` with `MinQP` / `MaxQP` |
> | Pixel Streaming 2 (Unreal Engine 5.5 and later) | **PS2** | `-PixelStreamingConnectionURL=…` with `MinQuality` / `MaxQuality` |
>
> With the wrong form the flags are ignored. See [PS1 or PS2?](https://docs.streampixel.io/resources/dashboard/test-locally.md#ps1-or-ps2).

**3. Pass the session ID to create()**

Add `dev` to the options, with the project's `appId` as usual. Everything else in your page stays as it is.

```ts main.ts highlight={6} theme={"dark"}
import { Streampixel } from '@streampixel/web-sdk';

const stream = await Streampixel.create({
  appId: 'YOUR_PROJECT_ID',
  container: document.getElementById('stream')!,
  dev: { sessionId: 'dev-1a2b3c' }, // from the dashboard's Test Locally tab
});
```

> [!TIP]
>
> Your page shows what Unreal renders. If Unreal is not connected yet, the state stays `connecting` until it is.

### Keep the session ID out of your code

A session, and with it its ID, lasts 2 hours, so do not write the ID into your code. A common pattern is to read it from the page address during development. The released page then has no `dev` option:

```ts main.ts highlight={2,7} theme={"dark"}
// https://localhost:5173/?dev=dev-1a2b3c
const devSession = new URLSearchParams(location.search).get('dev');

const stream = await Streampixel.create({
  appId: 'YOUR_PROJECT_ID',
  container: document.getElementById('stream')!,
  ...(devSession ? { dev: { sessionId: devSession } } : {}),
});
```

**dev.sessionId** `string`

The dev session ID from the dashboard: `dev-` and six characters. Requires `appId`.

## What is different in a dev session

| In a dev session | Detail |
| - | - |
| No build needed | The project may have no build and may be switched off. |
| Access still applies | A password project asks for the password and a single sign-on project sends the viewer to sign in, as usual. See [Access](https://docs.streampixel.io/resources/web-sdk-v2/access.md). |
| Waits for Unreal | Start the page before or after Unreal. The state stays `connecting` until Unreal connects, with no time limit. |
| Stopping or restarting Unreal | The state becomes `reconnecting` with `waitingForHost: true`, and the stream comes back by itself when Unreal connects again, for up to 10 minutes. After that the session ends with code `4007`: call `create()` again. |
| No idle timeout | The idle countdown is off. |
| No fresh session | When no video arrives for 10 seconds, the SDK rejoins the same session, up to 3 times, instead of starting a new app process: there is only your Unreal. |
| `stream.streamerId` | The dev session ID. |
| Ticket | Always sent in the signalling URL, also when `advanced.ticketInUrl` is `false`. |
| Not allowed with | `shared`, or `auth: { mode: 'ticket' }`: both are refused with a `TypeError`. A dev session cannot be a [shared session](https://docs.streampixel.io/resources/web-sdk-v2/shared-sessions.md) and cannot use a ticket from your server. `appId` is required. |

To tell the two waiting cases apart in your own screens:

```ts theme={"dark"}
stream.on('state', (s) => {
  if (s.kind === 'connecting') setStatus('Waiting for Unreal to connect…');
  else if (s.kind === 'reconnecting' && s.waitingForHost) setStatus('Unreal stopped. Waiting for it to come back…');
  else if (s.kind === 'streaming') setStatus('');
});
```

> [!TIP]
>
> The ready-made screens of `@streampixel/ui` do this for you: in a dev session the loading screen says "Waiting for your Unreal Editor…". See [Ready-made screens](https://docs.streampixel.io/resources/web-sdk-v2/ui-overlays.md).

> [!WARNING]
>
> A dev session does not tell you how the uploaded build behaves. The app runs on your machine and your network, so start time, bitrate, resolution limits and behaviour on Streampixel's GPU servers are not the same. Test the uploaded build before you release.

## Errors

`create()` rejects before the stream starts:

| Error | Meaning | What to do |
| - | - | - |
| `AuthError`, kind `dev-session-not-found` | No such dev session, or the session was started for another project than `appId`. | Check the ID against the session's row, and that `appId` is the project the session belongs to. |
| `AuthError`, kind `dev-session-expired` | The dev session has expired. | Start a new session in the dashboard, use its ID, and connect Unreal with the new session's URL or launch argument. |
| `AuthError`, kind `server-ticket-required` | The project is set to "Your app only" (not available yet), which cannot be opened with `dev`. | Switch the project to another access mode while you test locally, or use a second project. |
| `TypeError` | `dev` together with `shared` or `auth: { mode: 'ticket' }`, a `dev.sessionId` that is not a dev session ID, or `dev` without `appId`. The message names the option. | Correct the option. |

After the stream started, the session ends with the `ended` event:

| Code | When | What to do |
| - | - | - |
| `4007` | Unreal stopped and did not come back within 10 minutes. | Start Unreal, then call `create()` again. |
| `4102`, or `4101` when the video connection never came up | No video arrived, also after the SDK rejoined the session three times. | Check that Unreal is rendering and still connected, then call `create()` again. |
| `1008` | The session expired while the page was open. The stream that was running continued. The next reconnect was refused. The message says to start a new dev session. | Start a new session and use its ID. |

All other errors and end codes are the same as for a normal session: see [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md).

## Troubleshooting

> [accordion] The state stays connecting
>
> Unreal has not connected to the session. The page waits without a time limit.
>
> Look at the session's row in the dashboard. If it does not say **Connected**, one of these is the cause: the PS1 / PS2 form does not match the plugin, the Pixel Streaming plugin is disabled, port `8888` is blocked, or the session has expired.

> [accordion] The row says Connected, and the page still waits
>
> The page uses the ID of another session than the one Unreal joined. Use the ID from the same row as the URL or launch argument you gave Unreal.

> [accordion] The preview link shows the stream, my page does not
>
> The problem is in the page, not in Unreal. Check the `appId` and `dev.sessionId` passed to `create()`, and what `create()` rejected with.

> [accordion] Nothing appears on my screen after Standalone Game
>
> That is expected: the game renders off-screen. Open your page, or the preview link.

> [accordion] Selected Viewport or New Editor Window does not stream
>
> Play In Editor ignores the launch argument. Use **Standalone Game**.

> [accordion] The page asks for a password, or goes to a sign-in page
>
> The project's access mode applies to dev sessions too. Enter the password or sign in, as a viewer would.

> [accordion] consoleCommand() returns false while streaming
>
> The app was not launched with `-AllowPixelStreamingCommands`. The launch argument carries it: paste the launch argument exactly as the dashboard shows it. This applies to `stream.consoleCommand()` and to `stream.emitConsoleCommand()`, which are the same call.

> [accordion] dev-session-not-found for an ID I just copied
>
> The session belongs to another project than `appId`. Start the session from the project whose ID you pass as `appId`.

> [accordion] It worked, and now create() rejects with dev-session-expired
>
> The 2 hours are over. Start a new session. Unreal needs the new session's URL or launch argument as well.

> [accordion] The session ended with 4007 after I closed Unreal
>
> More than 10 minutes passed without Unreal. Start Unreal and call `create()` again.

> [accordion] The dashboard says Local dev mode is temporarily unavailable
>
> The dev service is being updated. Try again in a few minutes.

## Next steps

> [card] [Talk to your Unreal app](https://docs.streampixel.io/resources/web-sdk-v2/messaging.md)
>
> Send and receive messages: the work a dev session is made for.

> [card] [Test Locally in the dashboard](https://docs.streampixel.io/resources/dashboard/test-locally.md)
>
> Start, revoke and read a dev session; the editor and Standalone Game steps in detail.

> [card] [Reliability](https://docs.streampixel.io/resources/web-sdk-v2/reliability.md)
>
> One level up: the timings behind waiting, reconnecting and rejoining.

> [card] [Options](https://docs.streampixel.io/resources/web-sdk-v2/options.md#dev-test-locally)
>
> Reference: everything `create()` accepts, `dev` included.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.