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

# Initialization and configuration

> Reference for the StreamPixelApplication function, the appId parameter, and all available configuration options.

This page documents the `StreamPixelApplication` function and the configuration options it accepts.

## The `StreamPixelApplication` function

```javascript theme={"dark"}
import { StreamPixelApplication } from 'streampixelsdk';

const result = await StreamPixelApplication(settings);
```

`StreamPixelApplication` is an async function that initializes the SDK. It:

1. Fetches your project configuration from the Streampixel API using the `appId`
2. Detects the user's device type (desktop, tablet, or mobile)
3. Negotiates the best available video codec
4. Establishes a WebSocket connection to the signaling server
5. Returns an object with all the tools you need to control the stream

### Singleton behavior

<Warning>
  `StreamPixelApplication` can only be called once per page load. If called again, it logs a warning and returns an empty object `{}`. If you need to reinitialize, reload the page.
</Warning>

### The `appId` parameter

<Tip>
  The `appId` is the only required parameter. Everything else is optional and falls back to your dashboard configuration.
</Tip>

The `appId` is your project identifier from the Streampixel dashboard. The API uses it to resolve:

* Which signaling server region to connect to
* TURN server credentials
* UE instance pool and routing
* All default settings configured in your dashboard

### Dashboard defaults

<Info>
  Every configuration option (except `appId`) is optional. When omitted, the SDK uses the values configured in your Streampixel dashboard. SDK-side settings override dashboard settings.
</Info>

## Configuration options

### Connection

| Parameter     | Type      | Default             | Description                                                |
| ------------- | --------- | ------------------- | ---------------------------------------------------------- |
| `appId`       | `string`  | **Required**        | Project ID from Streampixel dashboard                      |
| `AutoConnect` | `boolean` | `false`             | Automatically connect to the stream on initialization      |
| `streamerId`  | `string`  | Auto-generated UUID | Target a specific UE streamer instance                     |
| `sfuHost`     | `string`  | `"false"`           | Set to `"true"` to act as SFU host (one-to-many streaming) |
| `sfuPlayer`   | `string`  | `"false"`           | Set to `"true"` to act as SFU viewer                       |
| `forceTurn`   | `boolean` | `true`              | Force TURN relay for NAT traversal (recommended)           |

### Codec

| Parameter       | Type     | Default         | Description                                                   |
| --------------- | -------- | --------------- | ------------------------------------------------------------- |
| `primaryCodec`  | `string` | Dashboard value | Preferred video codec: `"H264"`, `"VP8"`, `"VP9"`, or `"AV1"` |
| `fallBackCodec` | `string` | Dashboard value | Fallback codec if primary is unavailable                      |

### Resolution

| Parameter               | Type      | Default                   | Description                                                                             |
| ----------------------- | --------- | ------------------------- | --------------------------------------------------------------------------------------- |
| `maxStreamQuality`      | `string`  | `"1080p (1920x1080)"`     | Maximum allowed resolution                                                              |
| `startResolution`       | `string`  | `"1080p (1920x1080)"`     | Initial resolution for desktop users                                                    |
| `startResolutionMobile` | `string`  | `"480p (854x480)"`        | Initial resolution for mobile users                                                     |
| `startResolutionTab`    | `string`  | `"720p (1280x720)"`       | Initial resolution for tablet users                                                     |
| `resolutionMode`        | `string`  | `"Fixed Resolution Mode"` | One of: `"Fixed Resolution Mode"`, `"Dynamic Resolution Mode"`, `"Crop on Resize Mode"` |
| `showResolution`        | `boolean` | Dashboard value           | Enable resolution selection UI control                                                  |

Resolution preset format: `"1080p (1920x1080)"`. Available presets:

* `"360p (640x360)"`
* `"480p (854x480)"`
* `"720p (1280x720)"`
* `"1080p (1920x1080)"`
* `"1440p (2560x1440)"`
* `"4K (3840x2160)"`

### Bitrate and quality

| Parameter    | Type     | Default | Description                                                   |
| ------------ | -------- | ------- | ------------------------------------------------------------- |
| `minBitrate` | `number` | `1`     | Minimum bitrate in Mbps                                       |
| `maxBitrate` | `number` | `100`   | Maximum bitrate in Mbps                                       |
| `minQP`      | `number` | `20`    | Minimum quantization parameter (1-51, lower = better quality) |
| `maxQP`      | `number` | `-1`    | Maximum quantization parameter (-1 = no limit)                |

### Input

| Parameter              | Type      | Default | Description                          |
| ---------------------- | --------- | ------- | ------------------------------------ |
| `mouseInput`           | `boolean` | `true`  | Enable mouse input                   |
| `keyBoardInput`        | `boolean` | `true`  | Enable keyboard input                |
| `touchInput`           | `boolean` | `true`  | Enable touch input                   |
| `gamepadInput`         | `boolean` | `true`  | Enable gamepad/controller input      |
| `xrInput`              | `boolean` | `true`  | Enable WebXR (VR/AR) input           |
| `hoverMouse`           | `boolean` | `true`  | Send mouse hover/move events to UE   |
| `fakeMouseWithTouches` | `boolean` | `false` | Convert touch events to mouse events |

### Audio and camera

| Parameter   | Type      | Default | Description                   |
| ----------- | --------- | ------- | ----------------------------- |
| `useMic`    | `boolean` | `true`  | Enable microphone input to UE |
| `useCamera` | `boolean` | `true`  | Enable camera input to UE     |

### AFK

| Parameter    | Type     | Default | Description                                           |
| ------------ | -------- | ------- | ----------------------------------------------------- |
| `afktimeout` | `number` | `120`   | Idle timeout in seconds before disconnecting (1-7200) |

## Example: full configuration

```javascript theme={"dark"}
const { appStream, pixelStreaming, queueHandler, UIControl, reconnectStream } =
  await StreamPixelApplication({
    // Required
    appId: 'your-project-id',

    // Connection
    AutoConnect: true,
    forceTurn: true,

    // Codec
    primaryCodec: 'H264',
    fallBackCodec: 'VP8',

    // Resolution
    maxStreamQuality: '1080p (1920x1080)',
    startResolution: '1080p (1920x1080)',
    startResolutionMobile: '480p (854x480)',
    startResolutionTab: '720p (1280x720)',
    resolutionMode: 'Fixed Resolution Mode',

    // Bitrate
    minBitrate: 5,
    maxBitrate: 50,

    // Input
    mouseInput: true,
    keyBoardInput: true,
    touchInput: true,
    hoverMouse: true,

    // Audio
    useMic: false,
    useCamera: false,

    // AFK
    afktimeout: 300,
  });
```

## Next steps

<CardGroup cols={2}>
  <Card title="Return values" href="/resources/web-sdk/core-concepts/return-values">
    Understand the five objects returned by `StreamPixelApplication`.
  </Card>

  <Card title="Connection lifecycle" href="/resources/web-sdk/core-concepts/connection-lifecycle">
    Hook into the events fired during connection setup.
  </Card>
</CardGroup>