> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperbeam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

## Initializing the SDK

`Hyperbeam(container, embedURL, options?): Promise<HyperbeamClient>`

Use `Hyperbeam(container, embedURL, options?)` to create an instance of the [HyperbeamClient](https://docs.hyperbeam.com/client-sdk/javascript/reference.md#the-hyperbeamclient-object) object. The HyperbeamClient object is your entrypoint to the rest of the Hyperbeam JavaScript SDK.

```js JavaScript theme={null}
import Hyperbeam from "@hyperbeam/web"
...
const hb = await Hyperbeam(container, embedURL, options)
```

### Method Parameters

**container** `HTMLDivElement | HTMLIFrameElement`

The container can be either a `div` or an `iframe` element, though it is
highly advised to use a `div`.

**embedURL** `string`

The embedURL is retrieved from the [REST API](https://docs.hyperbeam.com/rest-api).

**options** `HyperbeamOptions Object`

Initialization options. All properties are optional.

**adminToken** `string`

An admin token returned from the REST API that will grant this user access to managing user permissions and programmatic navigation.

**timeout** `number` (default: 2000)

Number of milliseconds until the request to the virtual browser times out. If the request times out, the returned promise will be rejected.

**volume** `number` (default: 1.0)

Starting volume of the virtual browser.

**videoPaused** `boolean` (default: false)

Starting video pause state of the virtual browser.

**hb.playoutDelay** `boolean` (default: false)

Starting playout delay state of the virtual browser. When `playoutDelay` = `true`, input lag increases but smoothness is improved and frame drops are reduced.

**delegateKeyboard** `boolean` (default: true)

Delegate global keyboard events to the embed.

**webhookUserdata** `JSONValue`

Data to be provided to your webhook endpoint if you're using webhook authentication.

**frameCb** `(frame: ImageBitmap | HTMLVideoElement) =\> void`

Callback called with the virtual computer's video frame data. For Chromium-based browsers, its type is `ImageBitmap`. For other browsers, it's an `HTMLVideoElement`. Most frameworks like Three.js and Babylon.js can handle both types automatically.

**audioTrackCb** `(track: MediaStreamTrack) =\> void`

Callback called with a `MediaStreamTrack` of the virtual computer's audio stream.

**onCursor** `(e: PeerMouseEvent) =\> void`

Callback called when another user moves their mouse cursor on top of the virtual browser. Useful for implementing multiplayer cursors.

**onDisconnect** `(e: DisconnectEvent) =\> void`

Callback called when the user disconnects from the virtual browser. `e.type` is an enum with one of the following values:
`"request"`  -> virtual browser was manually shut down.
`"inactive"` -> inactive timeout was triggered.
`"absolute"` -> absolute timeout was triggered.
`"kick"`     -> user was kicked from the session.

**onCloseWarning** `(e: CloseWarningEvent) =\> void`

Callback called when a timeout either surpasses the warning threshold, or has been reset and is no longer passed the warning threshold.
`e.type` is an enum that refers to the timeout's type tied to the event. Possible values are `"inactive"` and `"absolute"`.
`e.deadline` = `null | { delay: number, closeDate: string }`. If `e.deadline` is `null`, then the timeout was reset and is no longer passed the warning threshold. If `e.deadline` is set, `e.deadline.delay`
is the number of milliseconds until the timeout is triggered, and `e.deadline.closeDate` is an RFC3339 formatted string of when the timeout will occur.

**onConnectionStateChange** `(e: ConnectionStateEvent) =\> void`

Callback called when the connection state of the video stream has changed. `e.state` = `"connecting" | "playing" | "reconnecting"`.
You can use this to show custom reconnecting UI, and detecting if a user has a sub-optimal connection to the virtual browser.

[See initialization example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#loading-a-virtual-browser)

***

## The HyperbeamClient object

The HyperbeamClient object allows you to programmatically control the virtual browser, set user permissions, and debug connection issues among other things.

```js JavaScript theme={null}
const hb: Promise<HyperbeamClient> = await Hyperbeam(
  container,
  embedURL,
  options
);
```

### Properties

**hb.userId** `string`

The client's user ID. [See
example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#getting-user-id)

**hb.adminToken** `string`

The client’s admin token. [See
example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#setting-admin-token)

**hb.volume** `number`

The local volume of the virtual browser. [See
example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#setting-video-volume)

**hb.width** `number`

The width of the virtual browser in pixels. [See
example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#resizing-the-browser)

**hb.height** `number`

The height of the virtual browser in pixels. [See
example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#resizing-the-browser)

**hb.maxArea** `number`

The maximum virtual browser area that can be allocated in pixels. [See
example.](//client-sdk/javascript/examples#resizing-the-browser)

**hb.videoPaused** `boolean`

Pauses the video stream of the virtual browser locally. [See
example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#pausing-video-stream)

**hb.playoutDelay** `boolean`

When `playoutDelay` = `true`, input lag increases but smoothness is improved
and frame drops are reduced.

**hb.tabs** `Tabs Object`

The virtual browser Tabs object. [See
example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#control-tabs-programmatically)

### Methods

***

#### reconnect

`hb.reconnect(): void`

Useful in situations where you need to troubleshoot the browser disconnecting. [See example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#manual-reconnection)

***

#### destroy

`hb.destroy(): void`

Tears down network connections and browser events. Always call this *before* removing the container element from the page. [See example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#destroying-the-embed)

***

#### addRoles

`hb.addRoles(userIds, roles, exclusive): Promise<void>`

Adds the list of roles to all the provided user ids.

**Method parameters**

**userIds** `string[]` *required*

List of user ids

**roles** `string[]` *required*

List of roles to be assigned to the provided user ids

**exclusive** `bool` (default: false)

If set to true, the roles are assigned to all users except the provided list of user ids.

#### removeRoles

Removes the list of roles from all the provided user ids.

`hb.removeRoles(userIds, roles, exclusive): Promise<void>`

Sets the permission of a user by their ID. The client must have an admin token set to manage user permissions. [See example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#setting-permissions)

**Method parameters**

**userIds** `string[]` *required*

List of user ids

**roles** `string[]` *required*

List of roles to be removed from the provided user ids

**exclusive** `bool` (default: false)

If set to true, the roles are removed from all users except the provided list of user ids.

#### setPermissions

`hb.setPermissions(userId, permissionData): Promise<void>`

> [!WARNING]
>
> `setPermissions` is deprecated, please use `addRoles` and `removeRoles`

Sets the permission of a user by their ID. The client must have an admin token set to manage user permissions. [See example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#setting-permissions)

**Method parameters**

**userId** `string`

The user ID to set permissions for.

**permissionData** `object`

All keys can be omitted: if the key is omitted, then the existing value will
be unchanged.

**priority** `number` (default: 0)

Higher value = higher priority. Users with a higher priority will preempt
the control of lower priority users.

**idle\_timeout** `number`

Number of milliseconds until a user is considered "idle". Once a user is
considered idle, they no longer preempt lower priority users until they
interact with the virtual browser again.

**control\_disabled** `boolean` (default: \<control\_disable\_default>)

If control\_disabled = true, all control input (mouse movements, keyboard
presses) will be ignored. Note that disabling control does not restrict
access to any APIs that require admin tokens.

#### sendEvent

`hb.sendEvent(event): void`

Sends a keyboard, mouse, or mouse wheel event to the Hyperbeam browser. [See example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#send-events-programmatically)

**Method parameters**

**event** `KeyEvent | MouseEvent | WheelEvent`

#### resize

`hb.resize(width, height): void`

Resizes the virtual browser to the specified width and height, in pixels. The arguments must meet the following conditions, otherwise the function will throw a `RangeError: width * height cannot be greater than hb.maxArea`.

`hb.maxArea` is the maximum area that can be allocated in pixels.

[See example.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#resizing-the-browser)

**Method parameters**

**width** `number`

The width of the virtual browser in pixels.

**height** `number`

The height of the virtual browser in pixels.

#### ping

`hb.ping(): void`

Resets the `inactive` timeout. Useful for situations where the user is not interacting with the Hyperbeam browser, but is performing actions on other parts of your application.

***

## getRegionInfo

`getRegionInfo(): Promise<HyperbeamRegionInfo>`

The Hyperbeam Web SDK provides a function called `getRegionInfo()` that returns a [HyperbeamRegionInfo](https://docs.hyperbeam.com/client-sdk/javascript/reference.md#hyperbeamregioninfo) object. This object refers to the optimal region to spin up a virtual computer based on the client’s location.

```js JavaScript theme={null}
import {getRegionInfo} from "@hyperbeam/web"
...
const regionInfo = await getRegionInfo()
```

[How to use getRegionInfo to optimize server location.](https://docs.hyperbeam.com/client-sdk/javascript/examples.md#optimize-server-location)

### HyperbeamRegionInfo

#### Properties

**region** `string`

Two-letter region code.

**country** `string`

Country code.


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