[Requirements](#requirements) | [Usage](#usage) | [Examples](#examples) | [Building locally](#building-locally) | [Documentation](#documentation) | [Contribution](#contribution) | [License](#license)
# Ceeblue WebRTC Client
[](https://npmjs.org/package/@ceeblue/webrtc-client)
The Ceeblue WebRTC Client is a generic client library designed to simplify the implementation of WebRTC functionalities for Ceeblue customers.
The client library addresses common challenges faced by developers:
- **Unified Browser Support** - Addresses inconsistencies and variations in implementation across different browsers.
- **Firewall Traversal** - Implements our unique TURN approach to manage firewall traversal.
- **Security** - Ensures secure streaming through encryption and authentication.
- **Quality of Service (QoS)** - Handles latency, packet loss, and other optimizations.
- **Signalling** - Unifies different signalling capabilities over Websockets and WHIP/WHEP into a single, easy-to-use interface, with enhanced communication robustness.
- **Multi Bitrate Playback** - Enables the player to switch in real-time between multiple quality renditions based on network conditions and client capabilities.
- **Adaptive Bitrate Streaming** - Allows the streamer to adapt its video bitrate in real-time based on network conditions and client capabilities.
## Requirements
| Item | Description |
| --- | --- |
| **Ceeblue Account** | To create a Stream, you will need an active account with [Ceeblue Streaming Cloud](https://dashboard.ceeblue.tv).
A trial account is sufficient. If you do not have one yet, you can request one on the [Ceeblue website](https://ceeblue.net/free-trial/). |
| **Stream** | To use this library, you'll first need to create a stream either through our Rest API or on the dashboard.
Use the following steps:- Create a new stream
- Copy the **Stream name (UUID)**
- Copy the **Endpoint**
|
| **Node Package Manager (npm)** | Download and install from https://nodejs.org/en/download |
| **http-server** | (Optional) Simple, zero-configuration command-line static HTTP server
The http-server is useful to explore the WebRTC client [examples](#examples) or the [documentation](#documentation) locally when you do not have a host.
To start the server, use the following command: `http-server . -p 8081`|
## Usage
Add the library as a dependency to your npm project using:
```
npm install @ceeblue/webrtc-client
```
Then [import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) the library into your project with:
```javascript
import * as WebRTC from '@ceeblue/webrtc-client';
```
> 💡 **TIP**
>
> If your project uses [TypeScript](https://www.typescriptlang.org/), it is recommended to set `"target": "ES6"` in your configuration to align with our usage of ES6 features and ensures that your build will succeed (for those requiring a backwards-compatible [UMD](https://github.com/umdjs/umd) version, a [local build](#building-locally) is advised).
> Then defining the compiler option `"moduleResolution": "Node"` in **tsconfig.json** helps with import errors by ensuring that TypeScript uses the correct strategy for resolving imports based on the targeted Node.js version.
> ```json
> {
> "compilerOptions": {
> "target": "ES6",
> "moduleResolution": "Node"
> }
> }
> ```
### Publish a stream
To publish the stream `` to ``, use the [Streamer](./src/Streamer.ts) class and the variables you saved while setting up the stream in the dashboard [Requirements](#requirements). For a full example, see push.html in [Examples](#examples).
```javascript
import { Streamer } from '@ceeblue/webrtc-client';
const streamer = new Streamer();
streamer.onStart = stream => {
console.log('start streaming');
}
streamer.onStop = _ => {
console.log('stop streaming');
}
const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
streamer.start(stream, {
endPoint: ,
streamName: ,
iceServer: {
urls: ['turn:' + + ':3478?transport=tcp', 'turn:' + + ':3478'],
username: 'ceeblue', credential: 'ceeblue'
}
});
```
### Play a stream
To play the stream `` from ``, use the [Player](./src/Player.ts) class and the variables you saved while setting up the stream in the dashboard [Requirements](#requirements). For a full example, see play.html in [Examples](#examples).
```javascript
import { Player } from '@ceeblue/webrtc-client';
const player = new Player();
player.onStart = stream => {
videoElement.srcObject = stream;
console.log('start playing');
}
player.onStop = _ => {
console.log('stop playing');
}
player.start({
endPoint: ,
streamName: ,
iceServer: {
urls: ['turn:' + + ':3478?transport=tcp', 'turn:' + + ':3478'],
username: 'ceeblue', credential: 'ceeblue'
}
});
```
## Examples
To understand how to use the library through examples, we provide three illustrations of its implementation:
- [/examples/streamer.html](./examples/streamer.html) → Publish a stream with your webcam
- [/examples/player.html](./examples/player.html) → Play a stream
- [/examples/player-with-timed-metadata.html](./examples/player-with-timed-metadata.html) → Play a stream with timed metadata
1. In your project directory, if you have installed the [http-server service](#requirements), execute the following command from the Terminal prompt by navigating to:
```shell
http-server . -p 8081
```
2. Navigate to the specified address in your browser, making sure to replace any placeholders in the URL with the variables you have copied during the [stream setup](#requirements) in the dashboard.
```html
http://localhost:8081/examples/streamer.html?host=&stream=
```
3. Click on **Start streaming**. Upon doing so, a live stream from your webcam will initiate. Should your browser request permission to access your camera, ensure to grant it.
4. In the address bar of a separate browser window, enter the following address, making sure to replace the placeholders in the URL with the variables you have copied while configuring the [stream setup](#requirements) in the dashboard.
```html
http://localhost:8081/examples/player.html?host=&stream=
```
5. Click **Play** to start watching the live stream.
## Building locally
1. [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) this repository
2. Enter the `webrtc-client` folder and run `npm install` to install packages dependencies.
3. Execute `npm run build`. The output will be five files placed in the **/dist/** folder:
- **webrtc-client.d.ts** Typescript definitions file
- **webrtc-client.js**: Bundled JavaScript library
- **webrtc-client.js.map**: Source map that associates the bundled library with the original source files
- **webrtc-client.min.js** Minified version of the library, optimized for size
- **webrtc-client.min.js.map** Source map that associates the minified library with the original source files
```
git clone https://github.com/CeeblueTV/webrtc-client.git
cd webrtc-client
npm install
npm run build
```
> 💡 **TIP**
>
> - To build a UMD (Universal Module Definition) version compatible with older browsers, you can run the following command:
> ```
> npm run build:es5
> ```
>
> - To automatically build bundles when any modification has been applied, you can run a watch command. The watch command will continuously monitor your project files for changes and rebuild the bundles accordingly.
> ```
> npm run watch
> ```
> Or for ES5 (UMD):
> ```
> npm run watch:es5
> ```
## Documentation
This monorepo also contains built-in documentation about the APIs in the library, which can be built using the following npm command:
```
npm run build:docs
```
You can access the documentation by opening the index.html file in the docs folder with your browser (`./docs/index.html`), or if you have installed and started the [http-server service](#requirements) by navigating to:
```
http://localhost:8081/docs/
```
## Contribution
All contributions are welcome. Please see [our contribution guide](/CONTRIBUTING.md) for details.
## License
By contributing code to this project, you agree to license your contribution under the [GNU Affero General Public License](/LICENSE).