# Configuration

This section explains the configuration options that can be passed to the **Arcware Pixel Streaming WebSDK** during initialization.

The most common way to initialize the SDK is through the `ArcwareInit` function.

```typescript
export function ArcwareInit(
  ids: ConnectionInfo,
  configuration?: ArcwareInitConfiguration,
  forceRefresh: boolean = false
): ArcwareInitResult
```

`ArcwareInit` initializes the WebSDK and returns the main SDK components required to interact with the stream.

```typescript
interface ArcwareInitResult {
  Config: ArcwareConfig
  PixelStreaming: ArcwarePixelStreaming
  Application: ArcwareApplication
}
```

These components represent different layers of the SDK:

| Component          | Purpose                                                             |
| ------------------ | ------------------------------------------------------------------- |
| **Config**         | Holds configuration and connection parameters                       |
| **PixelStreaming** | Manages the WebRTC stream and player                                |
| **Application**    | Handles interaction with Unreal Engine (messages, commands, events) |

***

## ArcwareInit vs CoreSetup

Most integrations should use **`ArcwareInit`**.

`ArcwareInit` is a **high-level helper function** that:

* creates the internal SDK objects
* connects them together
* guards against accidental reinitialization
* simplifies integration with frameworks such as React, Vue, or Angular

It also prevents multiple instances of the stream from being created during page re-renders.

If you intentionally need fresh SDK objects, you can force reinitialization:

```typescript
ArcwareInit(ids, configuration, true)
```

***

### CoreSetup (Advanced Usage)

For advanced integrations, the SDK also exposes a **lower-level initialization method** called **`CoreSetup`**.

`CoreSetup` allows developers to manually create and connect the SDK components:

* `ArcwareConfig`
* `ArcwarePixelStreaming`
* `ArcwareApplication`

This approach is useful if you need:

* complete lifecycle control
* smaller footprint
* custom UI implementations
* multiple streaming instances
* deeper integration with application architecture

Most applications **do not need CoreSetup**, and `ArcwareInit` is recommended for typical use cases.

***

## Configuration Options

The `ArcwareInit` function takes three parameters:

1. `ids: ConnectionInfo`
2. `configuration: ArcwareInitConfiguration`
3. `forceRefresh: boolean`

***

## 1. ConnectionInfo

This parameter defines the **connection information required to start a streaming session**.

```typescript
interface ConnectionInfo {
  shareId: string
  projectId?: string
}
```

#### shareId

The **Share ID** is required and identifies the project that should be streamed.

It can be considered a temporary access token that can be revoked or updated at any time from the Arcware Cloud Platform.

#### projectId

This is only required if a Share ID is linked to **multiple projects**.

If the Share ID uniquely identifies a project, this parameter can be omitted.

***

## 2. ArcwareInitConfiguration

The second parameter configures the behavior of the WebSDK.

```typescript
export type ArcwareInitConfiguration = Partial<ArcwareConfigParams>
```

```typescript
export interface ArcwareConfigParams extends ConfigParams {
  settings: Settings
  envName?: string
}
```

This configuration extends the **Epic Games Pixel Streaming frontend configuration** with additional Arcware-specific options.

***

### Top-Level Configuration Parameters

| Parameter              | Description                                                           |
| ---------------------- | --------------------------------------------------------------------- |
| **settings**           | Arcware-specific configuration options                                |
| **envName**            | Internal Arcware testing environment parameter (ignore in production) |
| **initialSettings**    | Pixel Streaming frontend configuration                                |
| **useUrlParams**       | Allows configuration via URL parameters                               |
| **webSocketProtocols** | Optional WebSocket protocol configuration                             |

***

### 2.1 initialSettings

The `initialSettings` object exposes configuration parameters from the **Epic Games Pixel Streaming frontend**.

These settings are forwarded directly to the underlying Pixel Streaming infrastructure used by the WebSDK.

Because Arcware Cloud manages parts of the streaming infrastructure automatically, **not all parameters exposed by the upstream Pixel Streaming frontend are recommended or meaningful when used with Arcware Cloud**.

Settings generally fall into three categories:

1. **Recommended Settings** – safe and commonly used with Arcware Cloud
2. **Advanced Pixel Streaming Settings** – supported but rarely needed
3. **Platform Controlled Settings** – usually overridden by Arcware Cloud configuration

The upstream Pixel Streaming documentation can be found here:

<https://github.com/EpicGamesExt/PixelStreamingInfrastructure/blob/master/Frontend/Docs/Settings%20Panel.md>

The WebSDK forwards the `initialSettings` object to the Pixel Streaming frontend. Parameters introduced in newer versions of the Pixel Streaming infrastructure may work automatically even if they are not explicitly listed here.

***

### Recommended Settings

These settings are tested and commonly used with Arcware Cloud.

| Setting              | Type    | Default | Description                                                          |
| -------------------- | ------- | ------- | -------------------------------------------------------------------- |
| AutoConnect          | boolean | false   | Automatically starts the connection to a streaming instance          |
| AutoPlayVideo        | boolean | true    | Automatically starts video playback once the stream is ready         |
| StartVideoMuted      | boolean | true    | Starts the video muted to avoid browser autoplay restrictions        |
| HoveringMouse        | boolean | true    | Allows the cursor to hover instead of locking it inside the player   |
| FakeMouseWithTouches | boolean | false   | Converts touch input to mouse events                                 |
| KeyboardInput        | boolean | true    | Enables keyboard input forwarding                                    |
| MouseInput           | boolean | true    | Enables mouse input forwarding                                       |
| TouchInput           | boolean | true    | Enables touch input forwarding                                       |
| GamepadInput         | boolean | true    | Enables gamepad input forwarding                                     |
| XRControllerInput    | boolean | true    | Enables XR controller input forwarding                               |
| SuppressBrowserKeys  | boolean | true    | Prevents browser keyboard shortcuts from interfering with the stream |
| UseMic               | boolean | true    | Enables microphone input forwarding                                  |
| ForceMonoAudio       | boolean | false   | Forces mono audio output                                             |

***

### Advanced Pixel Streaming Settings

These parameters originate from the Pixel Streaming infrastructure and are available through the WebSDK. They should only be modified if their behavior and implications are fully understood.

| Setting          | Type   | Description                                             |
| ---------------- | ------ | ------------------------------------------------------- |
| WebRTCFPS        | number | Target framerate for the WebRTC stream                  |
| WebRTCMinBitrate | number | Minimum bitrate for WebRTC streaming                    |
| WebRTCMaxBitrate | number | Maximum bitrate for WebRTC streaming                    |
| MinQP            | number | Minimum encoder quantization parameter                  |
| MaxQP            | number | Maximum encoder quantization parameter                  |
| MinQuality       | number | Minimum allowed quality level                           |
| MaxQuality       | number | Maximum allowed quality level                           |
| PreferredCodec   | string | Preferred video codec used by the stream                |
| PreferredQuality | number | Preferred quality level when quality control is enabled |
| StreamerId       | string | Identifier of the streamer to connect to                |

Changing these values may affect:

* bandwidth consumption
* visual quality
* latency
* stream stability

In most Arcware Cloud deployments these parameters are automatically optimized by the platform.

***

### Platform Controlled Settings

Some parameters exist in the Pixel Streaming frontend but are typically controlled by the Arcware Cloud platform.

If configured in code, they may be overridden by platform settings.

| Setting         | Type    | Description                             |
| --------------- | ------- | --------------------------------------- |
| TimeoutIfIdle   | boolean | Enables AFK detection                   |
| AFKTimeout      | number  | Idle timeout in seconds                 |
| AFKCountdown    | number  | Countdown duration before disconnection |
| ForceTURN       | boolean | Forces TURN relay usage                 |
| WaitForStreamer | boolean | Waits for streamer availability         |

AFK behavior and relay usage are controlled through **Arcware Cloud project or Share ID settings**.

***

### Signalling Server

The signalling server parameter is internally handled by the WebSDK.

| Setting | Type   | Description                            |
| ------- | ------ | -------------------------------------- |
| ss      | string | WebSocket URL of the signalling server |

Example:

```
wss://signalling-client.ragnarok.arcware.cloud
```

This parameter should not be modified manually when using Arcware Cloud.

## 2.2 settings (Arcware-specific settings)

The `settings` object configures **Arcware WebSDK specific features**.

Example:

```typescript
settings: {
  fullscreenButton: true,
  audioButton: true
}
```

***

## UI Controls

| Setting                | Type    | Default | Description                       |
| ---------------------- | ------- | ------- | --------------------------------- |
| fullscreenButton       | boolean | true    | Show fullscreen button            |
| settingsButton         | boolean | false   | Show settings menu                |
| infoButton             | boolean | false   | Show debug overlay                |
| audioButton            | boolean | true    | Show audio toggle                 |
| micButton              | boolean | false   | Show microphone toggle            |
| stopButton             | boolean | false   | Show stop stream button           |
| connectionStrengthIcon | boolean | false   | Show connection quality indicator |

Note: The connection strength indicator is derived from browser heuristics and may not accurately reflect network quality.

***

## Session Parameters

| Setting   | Type   | Description                                    |
| --------- | ------ | ---------------------------------------------- |
| session   | string | Manually specify session ID                    |
| token     | string | Platform authentication token                  |
| shareId   | string | Share identifier used to start a stream        |
| projectId | string | Required if Share ID maps to multiple projects |

***

## Display Settings

| Setting     | Type   | Description                     |
| ----------- | ------ | ------------------------------- |
| startWidth  | number | Preferred instance start width  |
| startHeight | number | Preferred instance start height |

***

## orientationZoom

Type:

```typescript
{
  landscape: number
  portrait: number
}
```

Example:

```javascript
orientationZoom: {
  landscape: 1,
  portrait: 1.5
}
```

This setting sends zoom hints to the Unreal application.

The Unreal application must implement support for this feature.

***

## White Labelling

The WebSDK supports branding customization via the `whiteLabelling` object.

Example:

```javascript
whiteLabelling: {
  splashScreenUrl: "/branding/splash.png",
  loadingIconUrl: "/branding/logo.png",
  splashScreenMode: "contain"
}
```

***

### White Labelling Schema

| Field                | Type    | Description                                            |
| -------------------- | ------- | ------------------------------------------------------ |
| splashScreenUrl      | string  | Image or video displayed while the stream loads        |
| splashScreenMode     | string  | Display mode (`contain`, `cover`, `stretch`, `repeat`) |
| splashScreenPosition | string  | CSS background-position value                          |
| splashScreenBgColor  | string  | Background color (CSS format)                          |
| loadingIconUrl       | string  | Custom loading icon                                    |
| loadingIconFadeMs    | number  | Fade animation duration                                |
| hideLoveLetters      | boolean | Hide loading messages                                  |
| hideAfkOverlay       | boolean | Hide AFK countdown overlay                             |

***

### URL Format

All asset URLs must be valid **absolute URLs or relative paths**.

Examples:

```
https://example.com/logo.png
/assets/logo.png
./branding/splash.jpg
```

Supported file types:

```
png
jpg
jpeg
webp
gif
bmp
tiff
mp4
webm
ogg
```

***

## Remote White Labelling

If enabled:

```
fetchRemoteWhiteLabelling: true
```

The WebSDK will request branding configuration from the Arcware backend and apply it dynamically.

***

## URL-based White Labelling

If `useUrlParams` is enabled, branding configuration can also be provided via URL:

```
?wl=<base64 encoded object>
```

Example decoded object:

```json
{
  "loadingIconUrl": "/logo.png",
  "splashScreenUrl": "/background.png"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.arcware.cloud/web-integration/new-websdk/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.