# Initialization and Configuration

## The `StreamPixelApplication` Function

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

{% hint style="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.
{% endhint %}

### The `appId` Parameter

{% hint style="success" %}
The `appId` is the only required parameter. Everything else is optional and falls back to your dashboard configuration.
{% endhint %}

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

{% hint style="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.
{% endhint %}

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

{% code lineNumbers="true" %}

```javascript
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,
  });
```

{% endcode %}