@arcware-cloud/pixelstreaming-websdk
Version:
WebSDK for easy implementation of pixel streaming with Arcware Cloud Services. Heavily based on the '@epicgames-ps' library.
278 lines (176 loc) • 12.8 kB
Markdown
# Arcware Cloud Pixel Streaming WebSDK
## Introduction
Welcome to the `-cloud/pixelstreaming-websdk`, a robust solution tailored for integrating Unreal Engine's Pixel Streaming technology into web applications via Arcware Cloud. This SDK is an extension of Epic Games' "PixelStreamingInfrastructure", enriching it with functionalities specifically designed for Arcware Cloud. It empowers developers to deliver interactive 3D experiences of exceptional quality directly to modern web browsers, eliminating the need for any plugins or downloads.
If you are not familiar with Arcware Cloud yet, check it out on [www.arcware.com](https://arcware.com/).
The WebSDK is designed to bring immersive experiences, similar to those found in native applications, to the web. It's enabled for a range of applications, from gaming and architectural visualization to interactive training. Bringing high quality real-time and ensures a seamless user experience.
This README offers an initial guide to integrating the WebSDK into your application. For comprehensive instructions, including setup, configuration, advanced features, and best practices, please refer to our detailed documentation: [Arcware Pixel Streaming WebSDK Documentation](https://docs.arcware.cloud/web-integration/new-websdk).
For an in-depth understanding of the underlying technology and infrastructure, you can explore the original "PixelStreamingInfrastructure" repository by Epic Games on GitHub: [EpicGames/PixelStreamingInfrastructure](https://github.com/EpicGames/PixelStreamingInfrastructure).
## Getting Started
### Prerequisites
Before integrating the `-cloud/pixelstreaming-websdk` into your project, please ensure the following prerequisites are met:
1. **Share ID**: You must have a valid Share ID set up for your project. This ID is crucial for establishing the connection between your application and the Arcware Cloud pixel streaming service. If you need assistance in setting up your Share ID, please refer to our detailed guide: [Setting up Share ID](https://docs.arcware.cloud/arcware-cloud-platform/getting-started/07.-preview-and-share-the-stream).
2. **Web Application Development Environment**: Ensure that your web application development environment is set up with either `yarn` or `npm`. These package managers are required for installing the WebSDK.
3. **TypeScript Recommendation**: While the SDK can be used with JavaScript, we strongly recommend using TypeScript in your development process. TypeScript offers enhanced code quality, readability, and will provide you with more intrinsic information during development, often surpassing what traditional documentation can offer.
### Installation
To integrate the Arcware Cloud Pixel Streaming WebSDK into your project, you can use either npm or yarn. Run one of the following commands in your project directory:
```bash
npm install -cloud/pixelstreaming-websdk --save
```
```bash
yarn add -cloud/pixelstreaming-websdk
```
We recommend keeping the WebSDK up to date to ensure you have the latest features and bug fixes. Regularly check for and install updates.
### Basic Usage
Below is a simple example demonstrating how to use the WebSDK in an HTML file to set up pixel streaming. This example imports the SDK and initializes it with a share ID and initial settings. It then attaches the streaming application to a div element in your HTML.
```html
<html>
<head>
<title>Arcware Cloud - Pixel Streaming</title>
<script type="module">
import * as PixelStreamingWebSdkCore from "https://unpkg.com/@arcware-cloud/pixelstreaming-websdk@latest/index.esm.js";
const { ArcwareInit } = PixelStreamingWebSdkCore;
const { Config, PixelStreaming, Application } = ArcwareInit(
{
// Replace with your actual share ID
shareId: "share-0be4620b-77aa-42b1-98cb-f7ee61be443?"
},
{
initialSettings: {
AutoConnect: false
// additional initial settings
},
settings: {
// additional settings
}
}
);
document.getElementById("videoContainer").appendChild(Application.rootElement);
</script>
</head>
<body>
<div id="videoContainer" style="height: 1000px; width: 1000px;"></div>
</body>
</html>
```
For more detailed examples and advanced usage, please refer to our documentation: [Arcware Cloud Pixelstreaming WebSDK Documentation](https://docs.arcware.cloud/web-integration/new-websdk).
# Changelog
### 1.2.13
- Replaced "moment" by "date-fns"
### 1.2.7
- "@epicgames-ps/lib-pixelstreamingcommon-ue5.5": "0.3.1",
- "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5": "1.2.1",
- "@epicgames-ps/lib-pixelstreamingfrontend-ui-ue5.5": "1.3.1",
### 1.2.6
- Added the "TextboxEntry" handler
- global CSS rule encapsulation
### 1.2.5
- Initial resolution can now be set as configuration parameter. Platform will start the instance with this resolution as startup argument for Unreal, such that Unreal will start with the web container size's resolution for fastest loading experience and screen adaptation
### 1.1.22
- Added flag to force refresh the components on ArcwareInit
- removed lodash and lottie dependencies to reduce package size significantly
### 1.1.20
- fixing ZoD error on queuing
### 1.1.19
- "@epicgames-ps/lib-pixelstreamingcommon-ue5.5": "0.2.9"
- "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5": "1.1.0"
- "@epicgames-ps/lib-pixelstreamingfrontend-ui-ue5.5": "1.2.0"
### 1.1.18
- hotfix: PixelStreaming.websocketState now returning correct state
### 1.1.17
- "@epicgames-ps/lib-pixelstreamingcommon-ue5.5": "0.2.9"
- "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5": "1.0.3"
- "@epicgames-ps/lib-pixelstreamingfrontend-ui-ue5.5": "1.0.2"
### 1.1.12
- pushing to newer versions of pixelstreaming infrastructure
- "@epicgames-ps/lib-pixelstreamingcommon-ue5.5": "0.2.8"
- "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5": "1.0.1"
- "@epicgames-ps/lib-pixelstreamingfrontend-ui-ue5.5": "1.0.0"
### 1.1.5
- removing the reconnect on successive calls to ArcwareInit if websocket was stale. If this behaviour is needed, it should be implemented outside the SDK
### 1.1.3
- reverting as the new versions of pixelstreaming infrastructure break things at least on Arcware side
- "@epicgames-ps/lib-pixelstreamingcommon-ue5.5": "0.1.7"
- "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5": "0.4.8"
- "@epicgames-ps/lib-pixelstreamingfrontend-ui-ue5.5": "0.4.8"
### 1.0.11
- reduced logging verbosity of pixel streaming infrastructure to not spam console
### 1.0.10
- Storing initialized WebSDK in global variable after calling ArcwareInit to return existing object on consecutive calls.
This prevents double websocket connections and potential failures to connect to stream
### 1.0.9
- Fixed peerDependencies in package.json
### 1.0.0
This version was created with the support of Tensorworks and is now sourcing from upstream packages
- "@epicgames-ps/lib-pixelstreamingcommon-ue5.5": "0.1.7"
- "@epicgames-ps/lib-pixelstreamingfrontend-ue5.5": "^0.4.8"
- "@epicgames-ps/lib-pixelstreamingfrontend-ui-ue5.5": "^0.4.8"
#### Added
- Support for Versions 5.1 and higher
- Support for controllers
- Experimental support for VR streaming
#### Fixed
- Random freezes on streams
#### Deprecated
- Support for Unreal 4.27 (fall back to WebRTC Plugin)
- Support for Unreal 5.0.3.0 (fall back to WebRTC Plugin)
### 0.1.\* (Initial Release)
<!-- - Upcoming changes or improvements that are currently in development can be listed here.
### [Version Number] - Release Date
#### Added
- List of new features or additions to the WebSDK in this release.
#### Changed
- Updates to existing features or overall improvements to the WebSDK.
#### Deprecated
- Features that are planned to be removed in future releases.
#### Removed
- Features or functionalities that have been removed from the WebSDK.
#### Fixed
- Bug fixes and corrections made in this release.
### [Previous Version Number] - Previous Release Date
- Changes for previous versions follow the same format. -->
# LICENSE
MIT License
Copyright 2023 Arcware GmbH
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
## Dependency Licenses
This software inherits code from several other libraries, namely:
- [zod](https://github.com/colinhacks/zod/blob/master/LICENSE)
- [moment.js](https://github.com/moment/moment/blob/develop/LICENSE)
- [-ps/lib-pixelstreamingfrontend-ue5.5](https://github.com/EpicGames/PixelStreamingInfrastructure/blob/master/LICENSE.md)
- [-ps/lib-pixelstreamingfrontend-ui-ue5.5](https://github.com/EpicGames/PixelStreamingInfrastructure/blob/master/LICENSE.md)
- [-ps/lib-pixelstreamingcommon-ue5.5](https://github.com/EpicGames/PixelStreamingInfrastructure/blob/master/LICENSE.md)
Here's a summary of these [Dependency Licenses](https://www.npmjs.com/package/@arcware-cloud/pixelstreaming-websdk?activeTab=code)/DEPENDENCY_LICENSE.md.
We appreciate the contributions of these libraries, as they are essential in supporting our development efforts.
<!-- # Configuration Options
When creating a new instance of `ArcwareConfig`, you provide an object with two main properties: `initialSettings` and `settings`.
####
`initialSettings`
This property is an object that defines the initial environment and behavior of the Pixel Streaming session. Here's a breakdown of the options used in the example:
- `ss`: This is the URL to the signalling server, which is essential for establishing the WebRTC connection. It is typically provided by your environment configuration.
- `StartVideoMuted`: A boolean that, when set to `true`, starts the video in a muted state.
- `AutoConnect`: If `true`, the client will automatically attempt to connect to the Pixel Streaming session as soon as possible.
- `AutoPlayVideo`: When set to `true`, the video will automatically play as soon as it's ready.
####
`settings`
The `settings` property is an object containing various configuration options that tailor the user interface and interaction capabilities of the streaming session:
- `shareId`: An identifier used for sharing sessions. \*Required
- `session`: The session ID, which can be used for session management and reconnection.
- `token`: An authentication token, if required by your backend.
- `infoButton`: A boolean to toggle the visibility of an information button in the UI.
- `micButton`: A boolean to control the display of a microphone toggle button.
- `audioButton`: A boolean to show or hide the audio control button.
- `fullscreenButton`: A boolean to enable a fullscreen toggle button.
- `settingsButton`: A boolean to add a settings button to the UI.
- `connectionStrengthIcon`: A boolean to display an icon indicating the connection strength.
###
Initialization Process
After configuring `ArcwareConfig`, you create an instance of `ArcwarePixelStreaming` by passing the configuration object. This instance is responsible for managing the streaming session and handling user interactions.
const pixelStreamingInstance = new ArcwarePixelStreaming(config);
Once initialized, `pixelStreamingInstance` can be used to interact with the streaming session. For example, you can retrieve the application's response or emit UI interactions:
const application = new ArcwareApplication({
stream: pixelStreamingInstance,
});
- ` application.getApplicationResponse(``string``) `: This method can be called to get a response from the application, which might include status updates or other messages.
- `application.emitUIInteraction(descriptor:` ` object | string``) `: This method allows you to send UI interaction events to the streaming application, such as button presses or command inputs. -->