Skip to content

Commit 2a24d63

Browse files
manzil-infinity180manzil-infinity180
authored
docs: removed the colibri1 from debugging and added rest-colibri2.md (#2318)
* docs: removed the colibri1 endpoints from debugging and added rest-colibri2.md * added Patch colibri v2 example
1 parent 7df2029 commit 2a24d63

File tree

2 files changed

+318
-8
lines changed

2 files changed

+318
-8
lines changed

‎doc/debugging.md‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -20,17 +20,12 @@ Returns the currently running version.
2020
GET /about/version
2121
```
2222

23-
### List conferences
24-
Returns a list of running conferences.
23+
### Get Dominant speaker
24+
Returns a dominant speaker identification
2525
```
26-
GET /colibri/conferences
26+
GET /colibri/v2/conferences/{meetingId}/dominant-speaker-identification
2727
```
2828

29-
### Describe a conference
30-
Returns the COLIBRI description of a conference.
31-
```
32-
GET /colibri/conferences/<CONFERENCE_ID>
33-
```
3429

3530
### Overall statistics
3631
Returns overall bridge statistics. These include number of current and total conferences and endpoints, number of packets/bytes received/sent, current packet rate and bit rate. They are generally suitable for storing as timeseries in order to monitor a service.

‎doc/rest-colibri2.md‎

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
# Introduction
2+
3+
This document describes the Colibri2 REST APIs
4+
5+
See [this document](rest.md) for how to configure the HTTP(S) interfaces of jitsi-videobridge.
6+
7+
We envision using the HTTP/JSON version of the colibri2 protocol you can see some examples [here](https://github.com/jitsi/jitsi-xmpp-extensions/blob/master/src/test/kotlin/org/jitsi/xmpp/extensions/colibri2/json/Colibri2JSONSerializerTest.kt).
8+
9+
# Implementation
10+
11+
<table>
12+
<tr>
13+
<th>HTTP Method</th>
14+
<th>Resource</th>
15+
<th>Response</th>
16+
</tr>
17+
<tr>
18+
<td>GET</td>
19+
<td>/colibri/v2/conferences/{meetingId}/dominant-speaker-identification</td>
20+
<td>
21+
200 OK with JSON objects which represents <code>endpointsBySpeechActivity</code>,<code>dominantEndpoint</code>, <code>endpointsInLastNOrder</code>,<code> dominantSpeakerIdentification</code> <br />
22+
For example:
23+
<pre>
24+
{
25+
"endpointsBySpeechActivity": [
26+
"79f0273d"
27+
],
28+
"dominantSpeakerIdentification": null,
29+
"endpointsInLastNOrder": [
30+
"79f0273d"
31+
],
32+
"dominantEndpoint": "null"
33+
}</pre>
34+
</td>
35+
</tr>
36+
<tr>
37+
<td>POST</td>
38+
<td>/colibri/v2/conferences/</td>
39+
<td>
40+
200 OK with a JSON object which represents the created conference if the request was with <code>Content-Type: application/json</code> and was a JSON object which
41+
consist field like <code> meeting-id</code>, <code>endpoints</code>, media types, media payloads<br />
42+
See the test example
43+
<a href="https://github.com/jitsi/jitsi-xmpp-extensions/blob/master/src/test/kotlin/org/jitsi/xmpp/extensions/colibri2/json/Colibri2JSONSerializerTest.kt">
44+
Colibri2JSONSerializerTest
45+
</a> <br />
46+
For example, a request could look like:
47+
<pre>
48+
{
49+
"meeting-id":"beccf2ed-5441-4bfe-96d6-f0f3a6796378",
50+
"name":"hardencounterssinkright@muc.meet.jitsi",
51+
"create":true,
52+
"endpoints":[
53+
{
54+
"create":true,
55+
"id":"79f0273d",
56+
"stats-id":"Garett-w1o",
57+
"muc-role":"moderator",
58+
"medias":[
59+
{
60+
"type":"audio",
61+
"payload-types":[
62+
{
63+
"name": "red", "id": "112", "channels": "2", "clockrate": "48000",
64+
"parameters": { "null": "111/111" }
65+
},
66+
{
67+
"name": "opus", "id": "111", "channels": "2", "clockrate": "48000",
68+
"parameters": {"useinbandfec": "1", "minptime": "10" },
69+
"rtcp-fbs": [{"type": "transport-cc"}]
70+
}
71+
],
72+
"rtp-hdrexts":[
73+
{ "uri":"urn:ietf:params:rtp-hdrext:ssrc-audio-level", "id":1 },
74+
{ "uri":"http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01", "id":5 }
75+
],
76+
"extmap-allow-mixed":true
77+
},
78+
{
79+
"type": "video",
80+
"payload-types":[
81+
{
82+
"name": "VP8", "id": "100", "clockrate": "90000",
83+
"parameters": {"x-google-start-bitrate": "800"},
84+
"rtcp-fbs":[
85+
{ "type": "ccm", "subtype": "fir" },
86+
{ "type": "nack" },
87+
{ "type": "nack", "subtype": "pli" },
88+
{ "type": "transport-cc" }
89+
]
90+
},
91+
{
92+
"name": "VP9", "id": "101", "clockrate": "90000",
93+
"parameters": {"x-google-start-bitrate": "800"},
94+
"rtcp-fbs":[
95+
{ "type": "ccm", "subtype": "fir" },
96+
{ "type": "nack" },
97+
{ "type": "nack", "subtype": "pli" },
98+
{ "type": "transport-cc" }
99+
]
100+
}
101+
],
102+
"rtp-hdrexts":[
103+
{ "uri":"http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time", "id":3 },
104+
{ "uri":"http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01", "id":5 }
105+
],
106+
"extmap-allow-mixed":true
107+
}
108+
],
109+
"transport": { "ice-controlling": true },
110+
"capabilities": [ "source-names" ]
111+
}
112+
],
113+
"connects": [
114+
{ "url": "wss://example.com/audio", "protocol": "mediajson", "type": "transcriber", "audio": true },
115+
{ "url": "wss://example.com/video", "protocol": "mediajson", "type": "recorder", "video": true }
116+
]
117+
}</pre>
118+
119+
The respective response could look like:
120+
121+
<pre>
122+
{
123+
"endpoints": [
124+
{
125+
"id": "79f0273d",
126+
"transport": {
127+
"transport": {
128+
"candidates": [
129+
{
130+
"generation": "0",
131+
"component": "1",
132+
"protocol": "udp",
133+
"port": "10000",
134+
"ip": "172.18.0.4",
135+
"foundation": "1",
136+
"id": "5bbb5d5e101f870f0ffffffffdf286239",
137+
"priority": "2130706431",
138+
"type": "host",
139+
"network": "0"
140+
},
141+
{
142+
"generation": "0",
143+
"rel-port": "10000",
144+
"component": "1",
145+
"protocol": "udp",
146+
"port": "10000",
147+
"ip": "192.168.1.1",
148+
"foundation": "2",
149+
"id": "56f8f898101f870f0fffffffff3be6336",
150+
"rel-addr": "172.18.0.4",
151+
"priority": "1694498815",
152+
"type": "srflx",
153+
"network": "0"
154+
},
155+
{
156+
"generation": "0",
157+
"rel-port": "10000",
158+
"component": "1",
159+
"protocol": "udp",
160+
"port": "10000",
161+
"ip": "152.58.154.133",
162+
"foundation": "2",
163+
"id": "c6ac5101f870f0ffffffffcb50fcba",
164+
"rel-addr": "172.18.0.4",
165+
"priority": "1694498815",
166+
"type": "srflx",
167+
"network": "0"
168+
}
169+
],
170+
"xmlns": "urn:xmpp:jingle:transports:ice-udp:1",
171+
"ufrag": "26ant1ioqu7qnr",
172+
"rtcp-mux": true,
173+
"pwd": "9q8uj7tg6j4rc4i6ulc1pmsq9",
174+
"web-sockets": [
175+
"wss://localhost:8443/colibri-ws/172.18.0.4/7e441eda3701676e/79f0273d?pwd=9q8uj7tg6j4rc4i6ulc1pmsq9"
176+
],
177+
"fingerprints": [
178+
{
179+
"fingerprint": "F1:05:72:F8:F3:F4:B4:65:5B:9A:FC:81:24:11:23:78:D5:42:54:B1:F2:66:2F:82:CC:2B:01:1C:DB:98:BE:C0",
180+
"setup": "actpass",
181+
"hash": "sha-256"
182+
}
183+
]
184+
}
185+
}
186+
}
187+
],
188+
"sources": [
189+
{
190+
"sources": [
191+
{
192+
"ssrc": 3191927963,
193+
"name": "jvb-a0"
194+
}
195+
],
196+
"id": "jvb-a0",
197+
"type": "audio"
198+
},
199+
{
200+
"sources": [
201+
{
202+
"ssrc": 1863439907,
203+
"name": "jvb-v0"
204+
}
205+
],
206+
"id": "jvb-v0",
207+
"type": "video"
208+
}
209+
]
210+
}</pre>
211+
</td>
212+
</tr>
213+
<tr>
214+
<td>PATCH</td>
215+
<td>/colibri/v2/conferences/{mettingId}</td>
216+
<td>
217+
Expire conference <br />
218+
200 OK which represents success. <br />
219+
For example:
220+
<pre>
221+
The Request body to expire conference:
222+
{
223+
"expire":true
224+
}
225+
</pre>
226+
</td>
227+
</tr>
228+
<tr>
229+
<td>PATCH</td>
230+
<td>/colibri/v2/conferences/{mettingId}</td>
231+
<td>
232+
200 OK which represents success. <br />
233+
Here, I am doing it for
234+
<a href="https://github.com/jitsi/jitsi-xmpp-extensions/blob/master/src/test/kotlin/org/jitsi/xmpp/extensions/colibri2/json/Colibri2JSONSerializerTest.kt#L326">
235+
Conference-modified with transport for an endpoint and feedback sources
236+
</a> <br />
237+
In the same way you can do it for
238+
<a href="https://github.com/jitsi/jitsi-xmpp-extensions/blob/master/src/test/kotlin/org/jitsi/xmpp/extensions/colibri2/json/Colibri2JSONSerializerTest.kt#L388C17-L388C59">
239+
Update endpoint with transport and sources
240+
</a> <br />
241+
For example, a request could look like:
242+
<pre>
243+
{
244+
"endpoints": [
245+
{
246+
"id":"79f0273e",
247+
"transport": {
248+
"transport": {
249+
"candidates": [
250+
{
251+
"generation": "0",
252+
"rel-port": "9",
253+
"component": "1",
254+
"protocol": "udp",
255+
"port": "10000",
256+
"ip": "129.80.210.199",
257+
"foundation": "2",
258+
"id": "653aa1ba295b62480ffffffffdc52c0d9",
259+
"rel-addr": "0.0.0.0",
260+
"priority": "1694498815",
261+
"type": "srflx",
262+
"network": "0"
263+
}
264+
],
265+
"xmlns": "urn:xmpp:jingle:transports:ice-udp:1",
266+
"ufrag": "2ivqh1fvtf0l3h",
267+
"rtcp-mux": true,
268+
"pwd": "1a5ejbent91k6io6a3fauikg22",
269+
"web-sockets": [
270+
"wss://beta-us-ashburn-1-global-2808-jvb-83-102-26.jitsi.net:443/colibri-ws/default-id/3d937bbdf97a23e0/79f0273e?pwd=1a5ejbent91k6io6a3fauikg22"
271+
],
272+
"fingerprints": [
273+
{
274+
"fingerprint": "2E:CC:85:71:32:5B:B5:60:64:C8:F6:7B:6D:45:D4:34:2B:51:A0:06:B5:EA:2F:84:BC:7B:64:1F:A3:0A:69:23",
275+
"setup": "actpass",
276+
"hash": "sha-256",
277+
"cryptex": true
278+
}
279+
]
280+
}
281+
}
282+
}
283+
],
284+
"sources": [
285+
{
286+
"type": "audio",
287+
"id": "jvb-a0",
288+
"sources": [
289+
{ "ssrc":411312308, "name": "jvb-a0", "parameters": { "msid": "mixedmslabel mixedlabelaudio0" } }
290+
]
291+
},
292+
{
293+
"type": "video",
294+
"id": "jvb-v0",
295+
"sources": [
296+
{ "ssrc":3929652146, "name": "jvb-v0", "parameters": { "msid": "mixedmslabel mixedlabelvideo0" } }
297+
]
298+
}
299+
]
300+
}</pre>
301+
302+
The respective response could look like:
303+
304+
<pre>
305+
{
306+
"endpoints": [
307+
{
308+
"id": "79f0273e"
309+
}
310+
]
311+
}</pre>
312+
</td>
313+
</tr>
314+
315+
</table>

0 commit comments

Comments
 (0)