Skip to content

Commit 614ad1a

Browse files
foltra-ncfoltra-nc
committed
Merge branch 'feat/47121-nmessenger-connect-client-instructions' into 'main'
feat: Client instructions how to retrieve captions from our nmessenger See merge request doc/nano-docs!114
2 parents f3ff29b + 58a63e0 commit 614ad1a

File tree

2 files changed

+192
-1
lines changed

2 files changed

+192
-1
lines changed

‎docs/cloud/live_captions_nmessenger_connect_for_clients.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
id: live_captions_retrieve
3+
title: Retrieve Live Captions in Your Playback System
4+
sidebar_label: Retrieve Captions
5+
---
6+
7+
Implement the following steps to **connect, authenticate, and display live captions** provided by our transcription service in your web player or application.
8+
9+
:::info
10+
This guide assumes **Live Captions** are already enabled for your organization.
11+
If you still need to enable the feature, please contact our **[Sales team](https://www.nanocosmos.net/contact/)** or send an email to sales(at)nanocosmos.net.
12+
:::
13+
14+
### 1. Load the Caption Library
15+
16+
Include the [nanoStream Messenger](https://bintu-nmessenger.autodevops-prod.nanostream.cloud/nmessenger.js) JavaScript library in your HTML page or application:
17+
18+
```html
19+
<script src="https://bintu-nmessenger.autodevops-prod.nanostream.cloud/client/nmessenger.js"></script>
20+
```
21+
22+
This library handles the WebSocket connection to the caption channel and outputs live text.
23+
24+
### 2. Create a Caption Overlay
25+
Add a `<div>` in your player page or application where the captions will be written:
26+
27+
```html
28+
<div id="caption-text" class="overlay-text"></div>
29+
```
30+
31+
This element will act as the container for live captions.
32+
33+
#### 2.1 Optional styling
34+
Adjust to your UI as needed:
35+
36+
37+
```html
38+
<style>
39+
.overlay-text {
40+
position: absolute;
41+
left: 0; right: 0; bottom: 5%;
42+
margin: 0 auto;
43+
padding: 0.5rem 0.75rem;
44+
max-width: 80%;
45+
font-family: system-ui, sans-serif;
46+
font-size: 1rem;
47+
line-height: 1.4;
48+
text-align: center;
49+
background: rgba(0,0,0,0.55);
50+
color: #fff;
51+
border-radius: 6px;
52+
pointer-events: none;
53+
z-index: 9999;
54+
}
55+
</style>
56+
```
57+
58+
### 3. Initialize the Messenger Client
59+
After loading the library, create a new Messenger object and configure it with your channel and secure token:
60+
61+
```html
62+
<script>
63+
const messenger = new NanoMessenger({
64+
channel: "your-caption-channel-id",
65+
token: "your-secure-caption-token",
66+
target: "caption-text" // the ID of the div where captions should appear
67+
});
68+
69+
messenger.connect();
70+
</script>
71+
```
72+
73+
**Parameters**
74+
75+
- **channel**: The caption channel you receive from us.
76+
77+
- **token**: Your secure JWT token (required for authentication).
78+
79+
- **target**: The id of the element where the text should be displayed.
80+
81+
:::tip Security best practice
82+
Generate JWTs server-side and use short-lived tokens.
83+
Avoid hard-coding long-lived tokens in public code, your playback system.
84+
:::
85+
86+
### 4. Display Captions
87+
Once connected, the Messenger library automatically writes incoming captions into the target element.
88+
89+
Example when a caption `Hello world` arrives:
90+
```html
91+
<div id="caption-text" class="overlay-text">Hello world</div>
92+
```
93+
94+
No extra rendering logic is required.
95+
96+
### 5. Use the Reference Implementation (Optional)
97+
If you prefer a ready-to-use solution:
98+
99+
- Use the iframe caption player provided as a reference implementation or embed the example HTML snippet in your system.
100+
- If you want a custom UI, you can still use the same Messenger library — just style the overlay `<div>` as you like.
101+
102+
That’s it — load the library, create an overlay, initialize Messenger with channel, token and captions will appear.
103+
104+
<details>
105+
<summary> See receive-captions.html </summary>
106+
107+
```html
108+
<!DOCTYPE html>
109+
<html lang="en">
110+
<head>
111+
<meta charset="utf-8" />
112+
<meta name="viewport" content="width=device-width,initial-scale=1" />
113+
<title>Your player</title>
114+
<link rel="stylesheet" href="https://bintu-nmessenger.autodevops-prod.nanostream.cloud/client/nmessenger.css" />
115+
<style>
116+
html,
117+
body {
118+
height: 100%;
119+
margin: 0;
120+
font-family: Inter, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial;
121+
}
122+
#playerDiv {
123+
width: 100vw;
124+
height: 100vh;
125+
position: relative;
126+
background: #000;
127+
}
128+
/* Messenger target div */
129+
#captionText {
130+
display: inline-block;
131+
padding: 10px 16px;
132+
border-radius: 12px;
133+
background: rgba(0, 0, 0, 0.55);
134+
color: #fff;
135+
font-size: 20px;
136+
font-weight: 500;
137+
line-height: 1.4;
138+
max-width: 80%;
139+
word-break: break-word;
140+
-webkit-backdrop-filter: blur(6px);
141+
backdrop-filter: blur(6px);
142+
}
143+
</style>
144+
</head>
145+
<body>
146+
<div id="playerDiv">
147+
<!-- nmessenger writes messages here -->
148+
<div class="overlayText">
149+
<div id="captionText" aria-live="polite" role="log"></div>
150+
</div>
151+
</div>
152+
<script src="https://bintu-nmessenger.autodevops-prod.nanostream.cloud/client/nmessenger.js"></script>
153+
<script>
154+
function nmessengerMain(options = {}) {
155+
const CAPTION_SERVER = "bintu-nmessenger.autodevops-prod.nanostream.cloud";
156+
const CAPTION_PORT = 443;
157+
const params = new URLSearchParams(window.location.search);
158+
const channel = params.get("caption.channel");
159+
if (!channel) {
160+
console.info("caption.channel not specified. Not initializing caption.");
161+
return;
162+
}
163+
const token = params.get("caption.token");
164+
messenger = new NanoMessenger(CAPTION_SERVER, CAPTION_PORT, options);
165+
messenger.connect(
166+
token,
167+
null,
168+
channel,
169+
() => {
170+
console.info("connect success");
171+
messenger.receiveMessage({ user: "system", text: "<receiving messages>" });
172+
},
173+
(err) => {
174+
console.error("Error:", err);
175+
messenger.receiveMessage({ user: "system", text: "Connection error" });
176+
}
177+
);
178+
}
179+
document.addEventListener("DOMContentLoaded", function () {
180+
const captionOptions = {
181+
overlayDiv: "captionText",
182+
};
183+
nmessengerMain(captionOptions);
184+
});
185+
</script>
186+
</body>
187+
</html>
188+
```
189+
190+
</details>

‎typesense-setup/config.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@
1010
"https://docs.nanocosmos.de/docs/samples"
1111
],
1212
"stop_urls": [
13-
"/blog"
13+
"/blog",
14+
"/docs/cloud/live_captions_retrieve"
1415
],
1516
"selectors": {
1617
"lvl0": {

0 commit comments

Comments
 (0)