Skip to content

Commit 067c47e

Browse files
oliverlazoliverlaz
committed
chore: align cookbooks
1 parent ee3720e commit 067c47e

File tree

3 files changed

+89
-111
lines changed

3 files changed

+89
-111
lines changed

‎packages/client/docusaurus/docs/javascript/02-guides/16-closed-captions.mdx

Lines changed: 33 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: closed-captions
3-
title: Closed captions
3+
title: Closed Captions
44
description: How to add closed captions to your calls
55
---
66

@@ -35,31 +35,56 @@ You can check the current value like this:
3535
console.log(call.state.settings?.transcription.closed_caption_mode);
3636
```
3737

38-
## Enabling and disabling closed caption events
38+
## Enabling, disabling and tweaking closed captions
3939

4040
If you set `closed_caption_mode` to `available` you need to enable closed caption events when you want to see captions:
4141

4242
```typescript
43-
await this.call.startClosedCaptions();
43+
await call.startTranscription(); // enable closed captions
44+
await call.stopTranscription(); // disable closed captions
4445

45-
// to disable them
46-
await this.call.stopClosedCaptions();
46+
call.updateClosedCaptionSettings({
47+
retentionTimeInMs: 2700, // the duration a caption can stay in the queue
48+
queueSize: 2, // number of captions that can be stored in the queue
49+
});
50+
```
51+
52+
## Check if closed captions are enabled
53+
54+
```tsx
55+
const call = client.call(type, id);
56+
const isCaptioningInProgress = call.state.captioning;
57+
58+
console.log(
59+
`Closed captions are ${isCaptioningInProgress ? 'enabled' : 'disabled'}`,
60+
);
61+
62+
// alternatively, you can listen to the captioning state changes
63+
call.state.captioning$.subscribe((isCaptioningInProgress) => {
64+
console.log(
65+
`Closed captions are ${isCaptioningInProgress ? 'enabled' : 'disabled'}`,
66+
);
67+
});
4768
```
4869

4970
## Displaying the captions
5071

5172
You can access the most recent captions using the call state:
5273

5374
```typescript
54-
call.state.closedCaptions$.subscribe((captions) =>
75+
import { StreamCallClosedCaption } from '@stream-io/video-client';
76+
77+
const subscription = call.state.closedCaptions$.subscribe((captions) =>
5578
updateDisplayedCaptions(captions),
5679
);
5780

58-
const updateDisplayedCaptions(captions: StreamCallClosedCaption[]) {
81+
const updateDisplayedCaptions = (captions: StreamCallClosedCaption[]) => {
5982
const innerHTML = captions
6083
.map((caption) => `<b>${caption.speaker_name}:</b> ${caption.text}`)
6184
.join('<br>');
62-
}
85+
};
86+
87+
subscription.unsubscribe(); // remember to unsubscribe
6388
```
6489

6590
This is how an example closed caption looks like:
@@ -76,19 +101,6 @@ This is how an example closed caption looks like:
76101
}
77102
```
78103

79-
## Closed caption configuration
80-
81-
You can tweak the caption display logic using `updateClosedCaptionSettings` method:
82-
83-
```typescript
84-
call.updateClosedCaptionSettings({
85-
// The maximum number of closed captions to keep in the queue, default is 2
86-
queueSize: 2,
87-
// The time in milliseconds to keep a closed caption in the queue, default is 2700ms
88-
retentionTimeInMs: 2700,
89-
});
90-
```
91-
92104
## See it in action
93105

94106
To see it all in action check out our TypeScript sample application on [GitHub](https://github.com/GetStream/stream-video-js/tree/main/sample-apps/client/ts-quickstart) or in [Codesandbox](https://codesandbox.io/p/sandbox/eloquent-glitter-99th3v).

‎packages/react-native-sdk/docusaurus/docs/reactnative/05-ui-cookbook/21-closed-captions.mdx

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,8 @@ For the purposes of this article, make sure that closed captions are either `ava
3636
## Enabling, disabling and tweaking closed captions
3737

3838
```tsx
39-
await call.startTranscription(); // enable closed captions
40-
await call.stopTranscription(); // disable closed captions
39+
await call.startClosedCaptions(); // enable closed captions
40+
await call.stopClosedCaptions(); // disable closed captions
4141

4242
call.updateClosedCaptionSettings({
4343
retentionTimeInMs: 2700, // the duration a caption can stay in the queue
@@ -48,7 +48,7 @@ call.updateClosedCaptionSettings({
4848
## Check if closed captions are enabled
4949

5050
```tsx
51-
import { useCallStateHooks } from '@stream-io/react-native-video-sdk';
51+
import { useCallStateHooks } from '@stream-io/video-react-native-sdk';
5252

5353
const { useIsCallCaptioningInProgress } = useCallStateHooks();
5454
const isCaptioningInProgress = useIsCallCaptioningInProgress();
@@ -64,7 +64,7 @@ Once enabled, the SDK will expose the closed caption events to your application
6464
This is how it can be used:
6565

6666
```tsx
67-
import { useCallStateHooks } from '@stream-io/react-native-video-sdk';
67+
import { useCallStateHooks } from '@stream-io/video-react-native-sdk';
6868

6969
export const ClosedCaptions = () => {
7070
const { useCallClosedCaptions } = useCallStateHooks();
@@ -99,5 +99,5 @@ const unsubscribe = call.on('call.closed_caption', (e: CallClosedCaption) => {
9999
console.log('Closed caption event:', e);
100100
});
101101

102-
unsubscribe(); // don't forget to unsubscribe
102+
unsubscribe(); // remember to unsubscribe
103103
```

‎packages/react-sdk/docusaurus/docs/React/06-ui-cookbook/21-closed-captions.mdx

Lines changed: 51 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
---
22
id: closed-captions
3-
title: Closed captions
3+
title: Closed Captions
44
description: How to add closed captions to your calls
55
---
66

7-
The Stream API supports adding real-time closed captions (subtitles for participants) to your calls. This guide shows you how you can build it on top of our React SDK.
7+
The Stream API supports adding real-time closed captions (subtitles for participants) to your calls.
8+
This guide shows you how you can build it on top of our React SDK.
89

910
## Prerequisites
1011

11-
Make sure that the closed caption feature is enabled in your app's dashboard. The closed caption feature can be set on the call type level, and the available options are:
12+
Make sure that the closed caption feature is enabled in your app's dashboard.
13+
The closed caption feature can be set on the call type level, and the available options are:
1214

1315
- `available`: the feature is available for your call and can be enabled.
1416
- `disabled`: the feature is not available for your call. In this case, it's a good idea to "hide" any UI element you have related to closed captions.
@@ -31,108 +33,72 @@ await call.getOrCreate({
3133

3234
For the purposes of this article, make sure that closed captions are either `available` or `auto-on`.
3335

34-
## Enabling and disabling closed caption events
36+
## Enabling, disabling and tweaking closed captions
3537

36-
TKTKTK
38+
```tsx
39+
await call.startClosedCaptions(); // enable closed captions
40+
await call.stopClosedCaptions(); // disable closed captions
3741

38-
## Subscribing to closed caption events
42+
call.updateClosedCaptionSettings({
43+
retentionTimeInMs: 2700, // the duration a caption can stay in the queue
44+
queueSize: 2, // number of captions that can be stored in the queue
45+
});
46+
```
3947

40-
Let's start by building a custom hook that subscribes to and stores closed caption events.
48+
## Check if closed captions are enabled
4149

42-
When displaying closed captions, we should make sure that they are real-time (showing a sentence from 30 seconds ago has very little use in a conversation) and visible for enough time that participants can read them. Finally, it makes sense to limit the total number of captions visible on the screen at once.
50+
```tsx
51+
import { useCallStateHooks } from '@stream-io/video-react-sdk';
4352

44-
Below is an example implementation:
53+
const { useIsCallCaptioningInProgress } = useCallStateHooks();
54+
const isCaptioningInProgress = useIsCallCaptioningInProgress();
4555

46-
```tsx
47-
import {
48-
Call,
49-
CallClosedCaption,
50-
ClosedCaptionEvent,
51-
} from '@stream-io/video-client';
52-
53-
// The maximum number of captions that can be visible on the screen
54-
const numberOfCaptionsVisible = 2;
55-
// A single caption can stay visible on the screen for this duration
56-
// This is the maximum duration, new captions can push a caption out of the screen sooner
57-
const captionTimeoutMs = 2700;
58-
59-
function useClosedCaptions() {
60-
const call = useCall();
61-
// The captions queue
62-
const [captions, setCaptions] = useState<CallClosedCaption[]>([]);
63-
64-
useEffect(() => {
65-
if (!call) return;
66-
67-
// Subscribe to call.closed_caption events
68-
return call.on('call.closed_caption', (e: ClosedCaptionEvent) => {
69-
setCaptions((prevCaptions) => {
70-
const caption = event.closed_caption;
71-
72-
// It's possible to receive the same caption twice, so make sure to filter duplicates
73-
const isDuplicate = prevCaptions.find(
74-
(c) =>
75-
c.speaker_id === caption.speaker_id &&
76-
c.start_time === caption.start_time,
77-
);
78-
79-
return isDuplicate
80-
? prevCaptions
81-
: [...prevCaptions, caption].slice(-numberOfCaptionsVisible);
82-
});
83-
});
84-
}, [call]);
85-
86-
useEffect(() => {
87-
// After a specified amount of time, the caption is removed.
88-
// This timeout restarts every time the captions update.
89-
const id = setTimeout(() => {
90-
setCaptions((prevCaptions) =>
91-
prevCaptions.length > 0 ? prevCaptions.slice(1) : prevCaptions,
92-
);
93-
}, captionTimeoutMs);
94-
return () => clearTimeout(id);
95-
}, [caption]);
96-
97-
return captions;
98-
}
56+
console.log(
57+
`Closed captions are ${isCaptioningInProgress ? 'enabled' : 'disabled'}`,
58+
);
9959
```
10060

101-
:::note
102-
Since the closed caption event contains `start_time` and `end_time` fields, you can subtract the two to know how long it took the speaker to say the caption. You can then use this duration to control how long the text is visible on the screen. This is useful to ensure the captions are as real-time as possible, but that might not leave enough time for participants to read the text.
103-
:::
104-
105-
## Displaying captions
61+
## Rendering closed captions
10662

107-
Finally, we are ready to implement a component that renders captions:
63+
Once enabled, the SDK will expose the closed caption events to your application via a special `useCallClosedCaptions` hook.
64+
This is how it can be used:
10865

10966
```tsx
110-
export const ClosedCaptions = () => {
111-
const captions = useClosedCaptions();
112-
const { useCallSession } = useCallStateHooks();
113-
const { participants } = useCallSession();
67+
import { useCallStateHooks } from '@stream-io/video-react-sdk';
11468

69+
export const ClosedCaptions = () => {
70+
const { useCallClosedCaptions } = useCallStateHooks();
71+
const closedCaptions = useCallClosedCaptions();
11572
return (
11673
<div className="closed-captions">
117-
{captions.map(({ speaker_id, text, start_time }) => (
118-
<p className="closed-caption" key={`${speaker_id}-${start_time}`}>
119-
{participants.find((p) => p.user.id === speaker_id)?.user.name ||
120-
speaker_id}
121-
: {text}
74+
{closedCaptions.map(({ speaker_name, text, start_time }) => (
75+
<p
76+
className="closed-captions__item"
77+
key={`${speaker_name}-${start_time}`}
78+
>
79+
<span className="closed-captions__speaker">{speaker_name}:</span>
80+
<span className="closed-captions__text">{text}</span>
12281
</p>
12382
))}
12483
</div>
12584
);
12685
};
12786
```
12887

129-
And now by adding this component inside of the `StreamCall`, we get closed captions:
88+
And now we can add this newly created component somewhere in our call UI.
89+
90+
## Advanced usage
91+
92+
When the SDK provided behavior isn't enough, you can always subscribe to the closed caption events and build your own logic.
93+
This is how you can do it:
94+
95+
```tsx
96+
import { type CallClosedCaption } from '@stream-io/video-react-sdk';
97+
98+
const call = client.call(type, id);
99+
const unsubscribe = call.on('call.closed_caption', (e: CallClosedCaption) => {
100+
console.log('Closed caption event:', e);
101+
});
130102

131-
```jsx
132-
<StreamVideo client={client}>
133-
<StreamCall call={call}>
134-
<SpeakerLayout />
135-
<ClosedCaptions />
136-
</StreamCall>
137-
</StreamVideo>
103+
unsubscribe(); // remember to unsubscribe
138104
```

0 commit comments

Comments
 (0)