Skip to content

Commit d4aed5d

Browse files
adrianZahraadrianZahra
authored
Merge pull request #26 from adrianZahra/npmdocupdates
SPS Documentation updates base around the Library and Example restructure
2 parents 4c61a01 + 2b0b3dd commit d4aed5d

File tree

2 files changed

+129
-57
lines changed

2 files changed

+129
-57
lines changed

‎docs/api_transition_guide.md‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -60,13 +60,4 @@ pixelStreaming.addEventListener("videoInitialized", ()=> { /* Do something */ })
6060

6161
(More details [here](https://github.com/EpicGames/PixelStreamingInfrastructure/pull/110))
6262

63-
------
64-
65-
### NPM Packages
66-
The old [`libspsfrontend`](https://www.npmjs.com/package/@tensorworks/libspsfrontend) package is now deprecated in favour of [`spsfrontend`](https://www.npmjs.com/package/@tensorworks/spsfrontend).
67-
68-
Add `spsfrontend` to your project like so:
69-
70-
```
71-
npm i @tensorworks/spsfrontend
72-
```
63+
------

‎docs/frontend_utilisation_guide.md‎

Lines changed: 128 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
# Utilising the Frontend
22
## Overview
3-
The Scalable Pixel Streaming Frontend is a library of HTML, CSS and TypeScript code that runs in client web browsers to help users connect to Scalable Pixel Streaming applications and interact with them. It is able to achieve this by consuming the Pixel Streaming Frontend and UI libraries and by extending their signalling server and websocket packages the Pixel Streaming Fronted can be configured to work with Scalable Pixel Streaming signalling severs.
3+
The Scalable Pixel Streaming Frontend is a library of HTML, CSS and TypeScript code that runs in client web browsers to help users connect to Scalable Pixel Streaming applications and interact with them. It is able to achieve this by consuming the Pixel Streaming Frontend and UI libraries and by extending their signalling server and WebSocket packages the Pixel Streaming Frontend can be configured to work with Scalable Pixel Streaming signalling severs.
44

5-
## Epic Games Pixel Streaming libraries
5+
## Epic Games Pixel Streaming Frontend and UI Frontend
66
For the base functionality for Pixel Streaming and its UI capabilities the Scalable Pixel Streaming Frontend consumes the Epic Games Pixel Streaming Frontend and UI Frontend:
77
- [Pixel Streaming Frontend](https://www.npmjs.com/package/@epicgames-ps/lib-pixelstreamingfrontend-ue5.2)
88
- [Pixel Streaming Frontend UI](https://www.npmjs.com/package/@epicgames-ps/lib-pixelstreamingfrontend-ui-ue5.2)
99

1010
### Pixel Streaming Frontend
1111
The Pixel Streaming Frontend contains all the base functionality:
12-
- Websocket handling
12+
- WebSocket handling
1313
- Data channel handling
1414
- UE message handling
1515
- Mouse and keyboard interaction handling
@@ -24,48 +24,92 @@ The Pixel Streaming Frontend UI contains all the functionality for UI components
2424

2525
---
2626

27-
## Getting Started
28-
### Installing the Scalable Pixel Streaming Frontend
27+
## Scalable Pixel Streaming Frontend packages
28+
### The Scalable Pixel Streaming Frontend Library
29+
The library is the part of the Scalable Pixel Streaming Frontend that consumes the Epic Games Pixel Streaming Frontend and UI Frontend. It includes all of the custom signalling server logic that Scalable Pixel Streaming signalling servers require to work. The library can be either obtained through [GitHub](https://github.com/ScalablePixelStreaming/Frontend) or [NPM](https://www.npmjs.com/package/@tensorworks/libspsfrontend). To make use of the library it must be initialised via HTML and Javascript. The library is written in TypeScript but configured to export as a UMD module and can be consumed by plain JavaScript and most JavaScript frameworks.
30+
31+
### The Scalable Pixel Streaming Frontend TypeScript example
32+
The [TypeScript example](https://github.com/ScalablePixelStreaming/Frontend/tree/main/examples/typescript) is a simple HTML, CSS and TypeScript implementation of what a user could create to initialize the Scalable Pixel Streaming Frontend Library. Its role is to instantiate the library's components and help start the Scalable Pixel Streaming connection to the signalling server.
33+
34+
## Getting Started; installation and consumption
35+
### Building for Development vs Production
36+
The Scalable Pixel Streaming Frontend packages contain several NPM scripts that can be used to build the library and example for either development or production. When building for development this will enable source maps for debugging. When building for production this will disable source maps, reduce console output and minify the distributed JavaScript files. Below are a list of npm scripts for both the library and example and what each command does:
37+
38+
#### library scripts
39+
Please ensure that all library scripts are executed from the `library` directory and a user must first run `npm install` to install all the Libraries dependencies.
40+
- `npm run build-dev`: Build the library in development mode
41+
- `npm run build-prod`: Build the library in production mode
42+
43+
#### example scripts
44+
Please ensure that all example scripts are executed from the `examples/typescript` directory. In general, it is recommended that a user installs the library first as the example requires the library. On the contrary, `build-all-dev` and `build-all-prod` do not require the library to be installed and built first, as these scripts will install and build the library, example and all dependencies.
45+
- `npm run build-dev`: Build the library in development mode
46+
- `npm run build-prod`: Build the library in production mode
47+
- `npm run serve-dev`: Serve the example locally using the library in development mode
48+
- `npm run serve-prod`: Serve the example locally using the library in production mode
49+
- `npm run symlink`: Links the library to the example for consumption
50+
- `npm run build-all-dev`: Build the library and the example in development mode and link the library to the example for consumption
51+
- `npm run build-all-prod`: Build the library and the example in production mode and link the library to the example for consumption
52+
53+
### Installing the Scalable Pixel Streaming Frontend Library from GitHub
54+
Please note the following installation will be done with `dev` NPM scripts however, it can also be done with `prod` build scripts.
55+
2956
1) Download the [Scalable Pixel Streaming Frontend source code from GitHub](https://github.com/ScalablePixelStreaming/Frontend)
3057

31-
2) Run the following command in the base directory of the source tree:
58+
2) To build the library run the following commands in the `library` directory of the source tree:
3259
```bash
33-
# Install the frontend library's dependencies
34-
npm install .
60+
# Install the Frontend library's dependencies
61+
npm install
62+
63+
# Build the Frontend library
64+
npm run build-dev
3565
```
36-
This will install both the Pixel Streaming Frontend and Frontend UI along with other dependencies which the Scalable Pixel Streaming Frontend consumes.
66+
These commands and scripts will install and build the library.
3767

38-
### Running the Scalable Pixel Streaming Frontend locally
39-
1) To run the Frontend locally after installing simply run the following command from the base directory of the source tree:
68+
3) Run the following commands in the `examples/typescript` directory of the source tree:
4069
```bash
41-
# Build the frontend library
42-
npm run build
70+
# Install the examples' dependencies
71+
npm npm install
72+
73+
# Symlink the library to the example
74+
npm run symlink
75+
76+
# Build the example
77+
npm run build-dev
4378
```
79+
These commands and scripts will install the example, link the library to the example and build the example.
80+
81+
#### Installing and building with the build-all script
82+
1) Download the [Scalable Pixel Streaming Frontend source code from GitHub](https://github.com/ScalablePixelStreaming/Frontend)
4483

45-
### Building the Scalable Pixel Streaming Frontend
46-
1) Run the following command in the base directory of the source tree:
84+
2) Run the following script in the `examples/typescript` directory of the source tree:
4785
```bash
48-
# Install the frontend library's dependencies
49-
npm install .
86+
# Install, link and build the example and library
87+
npm run build-all-dev
5088
```
51-
This will transpile the TypeScript source files to JavaScript and generate the UMD module in the dist subdirectory.
89+
This will install, link and build the Scalable Pixel Streaming Frontend example and library all-in-one.
5290

53-
### Implementing the Scalable Pixel Streaming Frontend in a custom webpage
54-
The Scalable Pixel Streaming Frontend comes with a base index.ts file which is the entry point. In a custom webpage this file can be left out and a custom entry point can be implemented:
91+
### Installing the Scalable Pixel Streaming Frontend through NPM
92+
If your project includes a `package.json` file run the following command in the same directory
93+
1) Run the following command: `npm i @tensorworks/libspsfrontend`
5594

56-
1) Import all the required packages from the Epic Games Pixel Streaming Frontend and Frontend UI libraries
57-
```typescript
58-
import { Config, PixelStreaming } from '@epicgames-ps/lib-pixelstreamingfrontend-ue5.2';
59-
import { PixelStreamingApplicationStyle } from '@epicgames-ps/lib-pixelstreamingfrontend-ui-ue5.2';
60-
```
61-
2) Import SPSApplication from the Scalable Pixel Streaming Frontend Library
95+
2) Import your desired components from the library package `"@tensorworks/libspsfrontend"`
96+
97+
#### Basics to initialising and consuming the library
98+
The following example for initialising the library is based on the TypeScript example Provided on GitHub.
99+
100+
1) Import all the required objects, types and packages from the Scalable Pixel Streaming Frontend Library
62101
```typescript
63-
import { SPSApplication } from "./SPSApplication";
102+
import {Config, PixelStreaming, SPSApplication, TextParameters, PixelStreamingApplicationStyle} from "@tensorworks/libspsfrontend";
64103
```
65-
3) Create `PixelStreamingApplicationStyles` variable so we have access to the Epic Games Pixel Streaming CSS:
104+
2) Apply default styling from Epic Games Pixel Streaming Frontend
66105
```typescript
67106
export const PixelStreamingApplicationStyles = new PixelStreamingApplicationStyle();
107+
PixelStreamingApplicationStyles.applyStyleSheet();
68108
```
109+
3) Create a `webSocketAddress` variable so the WebSocket URL can be modified if a user wishes to inject their own WebSocket address at load time
110+
```typescript
111+
let webSocketAddress = "";
112+
```
69113
4) Create a `document.body.onload` function to automate the activation and creation of steps 5-8
70114
```typescript
71115
document.body.onload = function () {
@@ -76,15 +120,21 @@ document.body.onload = function () {
76120
```typescript
77121
const config = new Config({ useUrlParams: true, initialSettings: { OfferToReceive: true, TimeoutIfIdle: true } });
78122
```
79-
6) Create the `stream` object and pass in the new `config` object
123+
6) Create an if statement that will make use of the `webSocketAddress` variable if one is included
80124
```typescript
81-
const stream = new PixelStreaming(config);
125+
if(webSocketAddress != ""){
126+
config.setTextSetting(TextParameters.SignallingServerUrl, webSocketAddress)
127+
}
82128
```
83-
7) Create the `spsApplication` object and pass in the `stream` object enclosed in curly braces
129+
7) Create an instance of the `PixelStreaming` object called `stream` and an instance of the `SPSApplication` object called `spsApplication`.
84130
```typescript
85-
const spsApplication = new SPSApplication({ stream });
131+
const stream = new PixelStreaming(config);
132+
const spsApplication = new SPSApplication({
133+
stream,
134+
onColorModeChanged: (isLightMode) => PixelStreamingApplicationStyles.setColorMode(isLightMode) /* Light/Dark mode support. */
135+
});
86136
```
87-
8) Place `spsApplication.rootElement` inside a DOM Element of your choice or inject directly into the body of the web page
137+
8) Append the `spsApplication.rootElement` inside a DOM Element of your choice or inject directly into the body of the web page like in the TypeScript example
88138
```typescript
89139
document.body.appendChild(spsApplication.rootElement);
90140
//OR
@@ -93,35 +143,66 @@ document.getElementById("myElementId").appendChild(spsApplication.rootElement);
93143

94144
### Default Index Implementation
95145
```typescript
96-
import { Config, PixelStreaming } from '@epicgames-ps/lib-pixelstreamingfrontend-ue5.2';
97-
import { PixelStreamingApplicationStyle } from '@epicgames-ps/lib-pixelstreamingfrontend-ui-ue5.2';
98-
import { SPSApplication } from "./SPSApplication";
146+
import {Config, PixelStreaming, SPSApplication, TextParameters, PixelStreamingApplicationStyle} from "@tensorworks/libspsfrontend";
99147
export const PixelStreamingApplicationStyles = new PixelStreamingApplicationStyle();
148+
PixelStreamingApplicationStyles.applyStyleSheet();
149+
let webSocketAddress = "";
100150

101151
document.body.onload = function () {
102152
const config = new Config({ useUrlParams: true, initialSettings: { OfferToReceive: true, TimeoutIfIdle: true } });
153+
if(webSocketAddress != ""){
154+
config.setTextSetting(TextParameters.SignallingServerUrl, webSocketAddress)
155+
}
103156
const stream = new PixelStreaming(config);
104-
const spsApplication = new SPSApplication({ stream });
157+
const spsApplication = new SPSApplication({
158+
stream,
159+
onColorModeChanged: (isLightMode) => PixelStreamingApplicationStyles.setColorMode(isLightMode) /* Light/Dark mode support. */
160+
});
105161
document.body.appendChild(spsApplication.rootElement);
106162
}
107163
```
108164

109-
### Connecting to a WebSocket
110-
When serving the Scalable Pixel Streaming Frontend it will build a default WebSocket address to connect to based on the address of the current window of the webpage. If the WebSocket address happens to match what is created by default then no further steps are required however, this is not always the case. In the stage of creating the `config` object for our entry point it is possible to inject a WebSocket address that will override the default that is created:
111-
112-
1) After completing `Implementing the Scalable Pixel Streaming frontend in a custom webpage` steps 1-8 import the `TextParameters` package from the Pixel Streaming Frontend
165+
### Customising the WebSocket connection
166+
#### Using setTextSetting within Config to inject a custom WebSocket
167+
When serving the Scalable Pixel Streaming Frontend it will build a default WebSocket address to connect to based on the address of the current window of the webpage. If the WebSocket address matches what is created by default then no further steps are required. Users can override the default by using the `setTextSetting` method on our `config` instance. See the section: Basics to initialising and consuming the library (link) steps 3 and 6.
168+
#### The .env file for the TypeScript example
169+
In the TypeScript example there is a `.env.example` file. inside this file there is a line called `WEBSOCKET_URL` containing a filler URL. This file can be used to hard code a WebSocket address that can be consumed by the example as shown above. This example is able to work with the help of the [dotenv NPM package](https://www.npmjs.com/package/dotenv) in the `webpack.common.js` file in the TypeScript example. To implement this example follow these steps:
170+
1) Rename the `.env.example` to `.env`
171+
2) Replace the place holder URL with the WebSocket URL you wish to consume
172+
3) Rebuild the example with the `npm run build-dev` or `npm run build-prod` for the changes to take effect
173+
174+
If you wish to include this functionality in your project you will need to include the following steps:
175+
The TypeScript example makes use of these exact steps and is a good demonstration resource on this topic.
176+
1) Install `dotenv` via NPM `npm i dotenv --save-dev`
177+
2) Include `dotenv` in your webpack file and set your `.env` file path using `path:`
178+
```javascript
179+
require('dotenv').config({ path: './.env' });
180+
```
181+
3) Include a plugin in your webpack file with the environment variables' name. For this example the name will be set to `WEBSOCKET_URL`
182+
```javascript
183+
new webpack.DefinePlugin({
184+
WEBSOCKET_URL: JSON.stringify((process.env.WEBSOCKET_URL !== undefined) ? process.env.WEBSOCKET_URL : '')
185+
}),
186+
```
187+
4) Create the `.env` file in the path you set in step 3 with the variable of your choice
188+
```bash
189+
WEBSOCKET_URL=ws://example.com/your/ws
190+
```
191+
5) Declare your environment variable where you instantiate your Scalable Pixel Streaming Frontend Library
113192
```typescript
114-
import { Config, PixelStreaming, TextParameters } from '@epicgames-ps/lib-pixelstreamingfrontend-ue5.2';
193+
declare var WEBSOCKET_URL: string;
115194
```
116-
2) Beneath the line where the `config` object was created call the `setTextSetting` method and pass in `TextParameters.SignallingServerUrl` and your websocket address as a string
195+
6) Make use of the `setTextSetting` method within the `config` instance to set the `TextParameters.SignallingServerUrl` to a variable that makes use of `WEBSOCKET_URL`
117196
```typescript
118-
const config = new Config({ useUrlParams: true, initialSettings: { OfferToReceive: true, TimeoutIfIdle: true } });
119-
config.setTextSetting(TextParameters.SignallingServerUrl, "wss://your.websocket.url/ws")
197+
let webSocketAddress = WEBSOCKET_URL;
198+
if(webSocketAddress != ""){
199+
config.setTextSetting(TextParameters.SignallingServerUrl, webSocketAddress)
200+
}
120201
```
121202

122203
---
123204
## Scalable Pixel Streaming Frontend customisation
124-
By default the Scalable Pixel Streaming Frontend contains all the requirements to connect to a Scalable Pixel Streaming signalling server making it an effective starting template for further customisation rather than starting from scratch. For further ways to utilise the the Pixel Streaming Frontend refer to the [Pixel Streaming Frontend documentation](https://github.com/EpicGames/PixelStreamingInfrastructure#readme).
205+
By default the Scalable Pixel Streaming Frontend Library contains all the requirements to connect to a Scalable Pixel Streaming signalling server making it an effective starting template for further customisation rather than starting from scratch. It is able to achieve this functionality through its consumption of the Epic Games Pixel Streaming Frontend. To learn more about further utilising the Epic Games Pixel Streaming Frontend documentation can be found [here](https://github.com/EpicGames/PixelStreamingInfrastructure#readme).
125206

126207
### Scalable Pixel Streaming Frontend UI element customisation
127-
Further customisation of UI elements like Overlays or visual elements can be achieved by utilising the Pixel Streaming Frontend UI and extending its types. For further information on how to utilise the Epic Games Pixel Streaming Frontend UI refer to the [Pixel Streaming Frontend UI documentation](https://github.com/EpicGames/PixelStreamingInfrastructure#readme).
208+
Further customisation of UI elements like overlays or visual elements can also be achieved by utilising the Pixel Streaming Frontend UI and extending its types. For further information on how to utilise the Epic Games Pixel Streaming Frontend UI refer to the [Pixel Streaming Frontend UI documentation](https://github.com/EpicGames/PixelStreamingInfrastructure#readme).

0 commit comments

Comments
 (0)