Usage
Prerequisites
Register Domain
Register your domain to activate P2P service.
Localhost is always whitelisted. This means that you do not have to configure anything to perform tests locally.
Host Service Worker (Optional)
Click me
- If you don't have a Service Worker
- If you already have a Service Worker
Copy sw.js to your server and make it available at https://your_website.com/sw.js . Alternatively, download hls-proxy.js then rename to sw.js .
Integrate hls-proxy.js into your existing Service Worker by adding this code to the beginning of your Service Worker's root JavaScript file:
self.importScripts('https://cdn.jsdelivr.net/npm/@swarmcloud/hls/hls-proxy.js')
Then set the correct path to sw.js for p2pConfig:
var p2pConfig = {
swFile: PATH_TO_SW_FILE
}
Once added, 1) your existing Service Worker will continue to be installed, and 2) SwarmCloud's imported Service Worker script will handle CDN 'fetch' events to intercept HLS request. All 'fetch' events not handled by SwarmCloud's Service Worker will fall through to your existing Service Worker's 'fetch' event handler(s).
You don't need to secure your site with HTTPS or host Service Worker if only hls.js is used.
Install P2P Engine
Script
Include the pre-built script of latest version bundled with hls.js, Or include the latest version without hls.js:
- P2pEngine standalone
- P2pEngine built in
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<script src="https://cdn.jsdelivr.net/npm/@swarmcloud/hls/p2p-engine.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@swarmcloud/hls/hls.min.js"></script>
File
Click me
This needs to be included before your player code. You can either prepend it to your compiled code or include it in a <script>
before it.
Browserify / Webpack
npm install --save @swarmcloud/hls
To include @swarmcloud/hls you need to require it in the player module:
- P2pEngine standalone
- P2pEngine built in
var Hls = require('hls.js');
var P2pEngineHls = require('@swarmcloud/hls').default;
var Hls = require('@swarmcloud/hls/hls.min');
If you are using ES6's import syntax:
- P2pEngine standalone
- P2pEngine built in
import Hls from 'hls.js';
import P2pEngineHls from '@swarmcloud/hls';
import Hls from '@swarmcloud/hls/hls.min';
Usage
- P2pEngine standalone
- P2pEngine built in
Create hls.js instance passsing hlsjsConfig as parameter. Create P2pEngineHls instance passing p2pConfig as parameter.
var p2pConfig = {
// Other p2pConfig options if applicable
}
var engine;
if (P2pEngineHls.isMSESupported()) {
var hls = new Hls();
p2pConfig.hlsjsInstance = hls; // set hlsjs instance to SDK
engine = new P2pEngineHls(p2pConfig);
// Use hls just like your usual hls.js…
hls.loadSource(contentUrl);
hls.attachMedia(video);
hls.on(Hls.Events.MANIFEST_PARSED,function() {
video.play();
});
} else {
engine = new P2pEngineHls(p2pConfig); // equal to new P2pEngineHls.ServiceWorkerEngine(p2pConfig);
engine.registerServiceWorker().catch(() => {}).finally(() => {
// native video playback here
});
}
Add p2pConfig as a property of hlsjsConfig, then Create hls.js instance passing hlsjsConfig as constructor param.
var p2pConfig = {
logLevel: 'debug',
// Other p2pConfig options if applicable
}
if(Hls.isSupported()) {
var hlsjsConfig = {
debug: true,
// Other hlsjsConfig options provided by hls.js
p2pConfig
};
// Hls constructor is overriden by included bundle
var hls = new Hls(hlsjsConfig);
// Use hls just like the usual hls.js ...
hls.loadSource(contentUrl);
hls.attachMedia(video);
} else {
// use ServiceWorker based p2p engine if hls.js is not supported
var engine = new Hls.P2pEngine(p2pConfig); // equal to new Hls.P2pEngine.ServiceWorkerEngine(p2pConfig);
engine.registerServiceWorker().catch(() => {}).finally(() => {
// native video playback here
});
}
If the media segment is generated by multiple servers, please add this configuration:
var p2pConfig = {
strictSegmentId: true,
}
How it works
When the SDK is instantiated, it will give priority to trying to use hls.js based engine (hereinafter referred to as MSE Engine). If failed, try the ServiceWorker based engine (hereinafter referred to as SW Engine), as follows:
- If the browser does not support webrtc datachannel, no engine will be enabled
- If the browser supports MSE && hlsjsInstance is passed in && proxyOnly is not set, try to enable the MSE Engine
- Otherwise, enable the SW Engine if ServiceWorker is supported
Player Integration
See players demo .
File Explanation
@swarmcloud/hls/
├── hls.min.d.ts # Typescript type information about hls.min.js and hls.light.min.js
├── hls.min.js # Hls.js with P2pEngine built in
└── hls.light.min.js # Hls.light.js with P2pEngine built in
└── p2p-engine.min.d.js # Typescript type information about p2p-engine.min.js
└── p2p-engine.min.js # P2pEngine that supports both Hls.js and ServiceWorker
└── p2p-engine.es.min.js # P2pEngine that supports both Hls.js and ServiceWorker for ES Module
└── hlsjs-p2p-engine.min.js # P2pEngine that supports Hls.js only
└── sw-p2p-engine.min.js # P2pEngine that supports ServiceWorker only
└── hls-proxy.js # The file that be imported by sw.js
Electron
Electron is also supported, you just need to register AppId and get a token from dashboard:
var hlsjsConfig = {
p2pConfig: {
token: YOUR_TOKEN,
appName: YOUR_APP_NAME,
appId: YOUR_APP_ID,
// Other p2pConfig options if applicable
}
};
Learn more here