Initialization and configuration

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

The `StreamPixelApplication` function

import { StreamPixelApplication } from 'streampixelsdk';

const result = await StreamPixelApplication(settings);

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

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

Singleton behavior

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.

The `appId` parameter

The appId is the only required parameter. Everything else is optional and falls back to your dashboard configuration.

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

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.

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

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

Return values

Understand the five objects returned by StreamPixelApplication.

Connection lifecycle

Hook into the events fired during connection setup.

Getting started

Core concepts

Features

UI customization

API reference

Guides

Initialization and configuration

The `StreamPixelApplication` function

Singleton behavior

The `appId` parameter

Dashboard defaults

Configuration options

Connection

Codec

Resolution

Bitrate and quality

Input

Audio and camera

AFK

Example: full configuration

Next steps

Return values

Connection lifecycle

​The StreamPixelApplication function

​Singleton behavior

​The appId parameter

​Dashboard defaults

​Configuration options

​Connection

​Codec

​Resolution

​Bitrate and quality

​Input

​Audio and camera

​AFK

​Example: full configuration

​Next steps

Return values

Connection lifecycle

The `StreamPixelApplication` function

Singleton behavior

The `appId` parameter

Dashboard defaults

Configuration options

Connection

Codec

Resolution

Bitrate and quality

Input

Audio and camera

AFK

Example: full configuration

Next steps