Teleport guide.md 9.35 KB
Newer Older
Dima committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
[![](http://img.ipev.ru/2017/09/12/gitlab_cover.png)](http://teleport.media)

# About Teleport

Teleport - is the platform for decentralized delivery of video streaming content.

Using the platform can significantly reduce the load on your media server when you broadcast video content and improve the quality of the broadcasting.
This is due to the automatic deployment of the peer-to-peer network from browsers that broadcast the same video and exchange parts of this content between each other.

## How it works
Teleport consists of a server and an SDK. The solution allows browsers to connect to the p2p-network using WebRTC and switch the receiving source of each streaming chunk for each node between the media server and P2P. Teleport supports adaptive HTTP-based transport protocols only, such as HLS and DASH.

To use the Teleport SDK, you can use one of the proposed plugins. They take all the work on initializing the script and integrating it with a media player.

Plugins list:
* [Shaka Player ](https://gitlab.tlprt.cloud/teleport.media/shaka-player-p2p)
* [hls.js](https://gitlab.tlprt.cloud/teleport.media/p2p-hls.js)
18
* [Video.js HLS](https://gitlab.tlprt.cloud/teleport.media/video-js-p2p)
Dima committed
19 20 21 22 23 24 25 26 27

The list of plugins will be updated.

When initialized, the Teleport SDK establishes a connection to the tracker server. It is used for coordinating peer connections. Communication with the tracker server occurs via the WebSocket protocol using an encrypted connection. After connecting to the tracker server, the peer receives a message with unique peer IDs to establish a connection with them. After the connections are established, the peers exchange messages and make their own decisions on the exchange of segments. 

To perform resource-intensive operations, the Teleport.js client script uses Web Workers. Storage of received data in memory on user devices is organized in such a way that each piece of video, regardless of the source of receipt (P2P or server) is stored on the device, specified by the "TTL time" parameter (default TTL = 180 sec). After this time, the piece is removed from the device. Data transfer in the P2P network via the WebRTC channel occurs with the breakdown of the transmitted data into pieces of 16KB, their reassembly on the receiving side and integrity check (hash-sum from the content).

Teleport is compatible with any CAS / DRM system but requires additional integration with them.

Dima committed
28 29 30 31 32 33 34 35 36 37
# Integrating Teleport
## Domain confirmation
Sequencing:
1. Go through the signup process on https://cabinet.teleport.media
2. Proceed your domain confirmation in the "Integration" section.
3. After the domain is confirmed, in the "Domains" tab you'll get the Teleport API key for running the script.

Now you can connect Teleport in accordance with the documentation, and use the key given to you by the API.

## In-code changes
Dima committed
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
To integrate with Teleport, you need to install a JavaScript library 
```<script src="https://cdn.teleport.media/teleport.js"></script>``` 
and initialize it.

**When using ready-made plug-ins, initialization is not needed.**
 
**For correct work of the platform, it is necessary to connect teleport.js after connecting the library of the video player.**

Example of Teleport script installation:

```html
$ index.html
    <script src="//somecdn.com/shaka-player.compiled.js"></script>
    <script src="https://cdn.teleport.media/teleport.js"></script>
    <script src="https://cdn.teleport.media/shaka-player.teleport.js"></script>
```

Example of Teleport script initialization:
```html
$ index.html
    <script>
        window.teleport.init(
		{apiKey: 'TLPRT_API_KEY', // { string }  teleport.js api key. Get the TLPRT_API_KEY in your user area on cabnet.teleport.media 
      debug: true, // { boolean } 
      //Configuring the display of teleport.js system messages to the console, accessing global objects.
Dima committed
63 64 65
      // Teleport groups peers by reference to the manifest. 
      // In case if you're using different servers to distribute the manifest, 
      // place a function that turns the manifest from different URL addresses into the same form, into the value of the parameter
Dima committed
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
      manifestUrlFormatter: (manifestLink) => { //default value
        const url = new URL(manifestLink)

        return url.pathname
      },
	  
      // The same for the segments
      segmentIdFormatter: (segmentLink) => {  //default value
        const url = new URL(segmentLink)

        return url.pathname
      }
    }
)
    </script>
```

# API
## Events

To receive feedback from teleport.js in real time, you need to subscribe to the events generated in the window.teleport.events method. 
Dima committed
87

Dima committed
88 89
It takes the following parameters:

Dima committed
90 91 92 93
| Parameter | Description |
| ------------- | ------------- |
| **eventName** (string) | API event name  |
| **callback** (function)  | The function where the received result will be sent, after the event is completed.  |
Dima committed
94 95


Dima committed
96
*Example*
Dima committed
97 98 99 100 101 102 103 104 105 106
```html
$ skeleton
  <script>
    window.teleport.events.on('eventName', (...args) => {
        doSomeActions(...args)
    })
  </script>
$ To restrict an access to unauthorized media content users, initialize the script only after authorization.
```

Dima committed
107
#### Events list:
Dima committed
108

Dima committed
109 110 111 112
| Event Name | Arguments | Description |
| ------------- | ------------- | ------------- |
| **noWebrtc** | *number* **performance.now()** |The browser does not support WebRTC. |
*Example:*
Dima committed
113 114 115 116
```javascript
window.teleport.events.on('noWebrtc',(date) => console.log('change your IE', date))
```

Dima committed
117
------------
Dima committed
118

Dima committed
119 120 121 122
| Event Name | Arguments | Description |
| ------------- | ------------- | ------------- |
| **peerConnected**| *string* **userId**, *number* **performance.now()** |A WebRTC connection has been established. userId - is the unique ID of the peer. |
*Example:*
Dima committed
123 124 125 126
```javascript
window.teleport.events.on('peerConnected', (userId, date) => console.log('New peer connected.', userId, date))
```

Dima committed
127
------------
Dima committed
128

Dima committed
129 130 131 132
| Event Name | Arguments | Description |
| ------------- | ------------- | ------------- |
| **peerDisconnected**| *string* **userId**, *number* **performance.now()** |WebRTC connection is broken. |
*Example:*
Dima committed
133 134 135 136
```javascript
window.teleport.events.on('peerDisconnected', (userId, date) => console.log('peerDisconnected', userId, date))
```

Dima committed
137
------------
Dima committed
138

Dima committed
139 140 141 142
| Event Name | Arguments | Description |
| ------------- | ------------- | ------------- |
| **statSegment**| *string* **targetId**('cdn'/ PeerTargetId),  *string* **segmentId**, *int* **byteLength**,  *int* **loadTime**, *number* **performance.now()**|Video file segment is loaded. If the segment file is loaded from CDN targetId === 'cdn'. |
*Example:*
Dima committed
143 144 145 146
```javascript
window.teleport.events.on('statSegment', (targetId, segmentId, byteLength, loadTime, date) => console.log('New segment loaded:', segmentId))
```

Dima committed
147
------------
Dima committed
148 149


Dima committed
150
#### Methods list:
Dima committed
151

Dima committed
152 153 154 155 156 157 158 159
| Event Name | Arguments |
| ------------- | ------------- |
| **window.teleport.api.getSegment(url:String, quality:number, callback?:(Promise<res>)=>void):Promise** | performs a segment request, where: 'url' -  is the segment URL, 'quality' - segment quality id. |
| **window.teleport.api.getSegmentIdByUrl(url: string):string** | returns a unique segment identifier by URL.|
| **window.teleport.api.abort(url: string, callback?:()=>void):void**|cancels a segment request, where 'url' - is the URL of the segment.|
| **window.teleport.api.buffering(): void**|informs the Teleport server about the buffering events.|
| **window.teleport.api.setUploadState(true/false): void**|switches On and Off the upload of the segments in the P2P. The status of the current state can be found in the uploadState property of the getStats method.|
|**window.teleport.api.segmentInfo(url/segmentId, callback?:()=>void): string**| returns the source of segment load ('cdn' / targetId / 'Segment not loaded')|
Dima committed
160

Dima committed
161
*Example:*
Dima committed
162 163 164 165 166 167 168 169 170 171 172 173 174
```javascript
$ javascript
    ...
    window.teleport.init(opts)
    window.teleport.segmentInfo("https://somecdn.com/hd/mediaSegment1.ts")
    window.teleport.segmentInfo("any segment information")
    window.teleport.segmentInfo("other any segment information")
$ console output example
    "cdn"
    "facfdb535ac9500c"
    "Segment not loaded"
```

Dima committed
175 176 177 178 179 180
------------


| Event Name | Arguments |
| ------------- | ------------- |
|**window.teleport.api.getStats (): Object**| returns aggregated statistics on the downloaded segments from the media server and from the P2P.|
Dima committed
181

Dima committed
182
*Example:*
Dima committed
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226
```javascript
$ javascript
    ...
    window.teleport.api.getStats()
$ console output example
  {
    "uploadState": true,
    "metrics": {
      "peerCount": 2,
      "cdnTotalByteLength": 7748493,
      "cdnTotalLoadTime": 2073.6700000000005,
      "cdnDownloadCount": 5,
      "pdnTotalByteLength": 0,
      "pdnTotalLoadTime": 0,
      "pdnDownloadCount": 0,
      "uploadCount": 1,
      "cdnAvSpeed": 28.508060645921912,
      "pdnAvSpeed": 0
    },
    "peers": [
      {
        "segmentsCount": 7,
        "targetId": "d5ba30802f77e9e7",
        "accuracy": 0,
        "rating": 0
      },
      {
        "segmentsCount": 6,
        "targetId": "d5ba30805768c0f3",
        "accuracy": 16.666666666666664,
        "rating": 0
      }
    ]
  }

```
____________________________

# Teleport support

[![](http://img.ipev.ru/2017/09/12/slack.png)](https://join.slack.com/t/tlprt-support/shared_invite/MjM5ODU5MTg1NTczLTE1MDUyMTIxODktMDljMzRlZGQ1OQ)         [![](http://img.ipev.ru/2017/09/12/email3ef58.png)](mailto:support@teleport.media?subject=Teleport on Gitlab)
------------

[![](http://img.ipev.ru/2017/09/12/facebook.png)](https://www.facebook.com/teleportcdn/)