Skip to content

Commit d74335b

Browse files
valindraevalindrae
authored
Update closed-captions-android.md
Update android quickstart
1 parent 54c5d49 commit d74335b

File tree

1 file changed

+131
-67
lines changed

1 file changed

+131
-67
lines changed

‎articles/communication-services/quickstarts/voice-video-calling/includes/closed-captions/closed-captions-android.md

Lines changed: 131 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -2,103 +2,167 @@
22
title: Get started with Azure Communication Services closed caption on Android
33
titleSuffix: An Azure Communication Services quickstart document
44
description: Learn about the Azure Communication Services Closed Captions in Android apps
5-
author: RinaRish
6-
manager: visho
5+
author: Kunaal
76
services: azure-communication-services
8-
9-
ms.author: ektrishi
10-
ms.date: 02/03/2022
7+
ms.subservice: calling
8+
ms.author: valindrae
9+
ms.date: 04/15/2024
1110
ms.topic: include
1211
ms.service: azure-communication-services
1312
---
1413

1514
## Prerequisites
1615

17-
Refer to the [Voice Calling Quickstart](../../getting-started-with-calling.md?pivots=platform-android) to set up a sample app with voice calling.
16+
## Prerequisites
17+
- Azure account with an active subscription, for details see [Create an account for free.](https://azure.microsoft.com/free/)
18+
- Azure Communication Services resource. See [Create an Azure Communication Services resource](../../../../quickstarts/create-communication-resource.md?tabs=windows&pivots=platform-azp). Save the connection string for this resource.
19+
- An app with voice and video calling, refer to our [Voice](../../../../quickstarts/voice-video-calling/getting-started-with-calling.md) and [Video](../../../../quickstarts/voice-video-calling/get-started-with-video-calling.md) calling quickstarts.
20+
21+
>[!NOTE]
22+
>Please note that you will need to have a voice calling app using Azure Communication Services calling SDKs to access the closed captions feature that is described in this guide.
1823
1924
## Models
25+
| Name | Description |
26+
| ---------------------------------- | ----------------------------------------------------------------- |
27+
| CaptionsCallFeature | API for captions call feature |
28+
| CommunicationCaptions | API for communication captions |
29+
| StartCaptionOptions | Closed caption options like spoken language |
30+
| CommunicationCaptionsListener | Listener for CommunicationCaptions addOnCaptionsReceivedListener |
31+
| CommunicationCaptionsReceivedEvent | Data object received for each CommunicationCaptionsListener event |
32+
33+
## Get closed captions feature
34+
You need to get and cast the Captions object to utilize Captions specific features.
35+
36+
``` java
37+
CaptionsCallFeature captionsCallFeature = call.feature(Features.CAPTIONS);
38+
captionsCallFeature.getCaptions().whenComplete(
39+
((captions, throwable) -> {
40+
if (throwable == null) {
41+
CallCaptions callCaptions = captions;
42+
if (captions.getCaptionsType() == CaptionsType.COMMUNICATION_CAPTIONS) {
43+
// communication captions
44+
CommunicationCaptions communicationCaptions = (CommunicationCaptions) captions;
45+
}
46+
} else {
47+
// get captions failed
48+
// throwable is the exception/cause
49+
}
50+
}));
51+
```
2052

21-
| Name | Description |
22-
| - | - |
23-
| CaptionsCallFeature | Used to start and manage closed captions. |
24-
| StartCaptionsOptions | Used for representing options to start closed captions. |
25-
| CaptionsListener | Used to handle captions events. |
26-
| CaptionsInfo | Used to representing captions data. |
53+
## Subscribe to listeners
2754

28-
## Methods
29-
### Start captions
55+
### Add a listener to receive captions enabled/disabled status
3056

31-
1. Get the ongoing call object established during the prerequisite steps.
32-
2. Get the Captions Feature object
33-
```java
34-
CaptionsCallFeature captionsCallFeature = call.api(Features.CAPTIONS);
35-
```
36-
3. Define the CaptionsListener
37-
```java
38-
CaptionsListener captionsListener = new CaptionsListener() {
39-
@Override
40-
public void onCaptions(CaptionsInfo captionsInfo) {
41-
String captionsText = captionsInfo.getText(); // get transcribed text
42-
String speakerName = captionsInfo.getSpeaker().getDisplayName; // get display name of current speaker
43-
Date timeStamp = captionsInfo.getTimestamp(); // get timestamp corresponding to caption
44-
45-
// display captionsText and information as needed...
46-
}
47-
};
57+
``` java
58+
public void addOnIsCaptionsEnabledChangedListener() {
59+
communicationCaptions.addOnCaptionsEnabledChangedListener( (PropertyChangedEvent args) -> {
60+
if(communicationCaptions.isEnabled()) {
61+
// captions enabled
62+
}
63+
});
64+
}
4865
```
49-
4. Register the `captionsListener`
50-
5. Invoke `startCaptions` with the desired options.
51-
```java
52-
public void startCallCaptions() {
53-
captionsCallFeature.addOnCaptionsReceivedListener(captionsListener);
54-
if (!captionsCallFeature.isCaptionsActive) {
55-
StartCaptionsOptions startCaptionsOptions = new StartCaptionsOptions();
56-
startCaptionsOptions.setLanguage("en-us");
57-
58-
try {
59-
captionsCallFeature.startCaptions(startCaptionsOptions);
60-
} catch (Exception e) {
61-
e.printStackTrace();
66+
67+
### Add a listener to receive captions type changed
68+
This event will be triggered when the caption type changes from `CommunicationCaptions` to `TeamsCaptions` upon inviting Microsoft 365 users to ACS-only calls.
69+
70+
``` java
71+
public void addOnIsCaptionsTypeChangedListener() {
72+
captionsCallFeature.addOnActiveCaptionsTypeChangedListener( (PropertyChangedEvent args) -> {
73+
if(communicationCaptions.isEnabled()) {
74+
// captionsCallFeature.getCaptions();
6275
}
63-
}
76+
});
77+
}
78+
```
79+
80+
### Add listener for captions data received
81+
82+
``` java
83+
CommunicationCaptionsListener captionsListener = (CommunicationCaptionsReceivedEvent args) -> {
84+
// Information about the speaker.
85+
// CallerInfo participantInfo = args.getSpeaker();
86+
// The original text with no transcribed.
87+
// args.getSpokenText();
88+
// language identifier for the speaker.
89+
// args.getSpokenLanguage();
90+
// Timestamp denoting the time when the corresponding speech was made.
91+
// args.getTimestamp();
92+
// CaptionsResultType is Partial if text contains partially spoken sentence.
93+
// It is set to Final once the sentence has been completely transcribed.
94+
// args.getResultType() == CaptionsResultType.FINAL;
95+
};
96+
public void addOnCaptionsReceivedListener() {
97+
communicationCaptions.addOnCaptionsReceivedListener(captionsListener);
98+
}
99+
```
100+
101+
### Add a listener to receive active spoken language changed status
102+
103+
``` java
104+
public void addOnActiveSpokenLanguageChangedListener() {
105+
communicationCaptions.addOnActiveSpokenLanguageChangedListener( (PropertyChangedEvent args) -> {
106+
// communicationCaptions.getActiveSpokenLanguage()
107+
});
64108
}
65109
```
66110

111+
## Start captions
112+
113+
Once you've set up all your listeners, you can now start adding captions.
67114

68-
### Stopping captions
115+
``` java
116+
public void startCaptions() {
117+
StartCaptionsOptions startCaptionsOptions = new StartCaptionsOptions();
118+
startCaptionsOptions.setSpokenLanguage("en-us");
119+
communicationCaptions.startCaptions(startCaptionsOptions).whenComplete((result, error) -> {
120+
if (error != null) {
121+
}
122+
});
123+
}
124+
```
69125

70-
Remove the previously registered `captionsListener`.
126+
## Stop captions
71127

72-
```java
128+
``` java
73129
public void stopCaptions() {
74-
captionsCallFeature.removeOnCaptionsReceivedListener(captionsListener);
130+
communicationCaptions.stopCaptions().whenComplete((result, error) -> {
131+
if (error != null) {
132+
}
133+
});
75134
}
76135
```
77136

78-
### Get available languages
79-
80-
Call the `getAvailableLanguages` method on the `CaptionsCallFeature` API.
137+
## Remove caption received listener
81138

82-
```java
83-
String[] captionsAvailableLanguages = captionsCallFeature.getAvailableLanguages();
139+
``` java
140+
public void removeOnCaptionsReceivedListener() {
141+
communicationCaptions.removeOnCaptionsReceivedListener(captionsListener);
142+
}
84143
```
85144

86-
### Update language
145+
## Spoken language support
87146

88-
Pass a value in from the available languages array to ensure that the requested language is supported.
147+
### Get list of supported spoken languages
148+
Get a list of supported spoken languages that your users can select from when enabling closed captions.
89149

90-
```java
91-
public void switchCaptionsLanguage() {
92-
if (!captionsCallFeature.isCaptionsActive) {
93-
return;
94-
}
95-
try {
96-
captionsCallFeature.select(captionsAvailableLanguages[0]);
97-
} catch (Exception e) {
98-
e.printStackTrace();
99-
}
150+
``` java
151+
// bcp 47 formatted language code
152+
communicationCaptions.getSupportedSpokenLanguages();
153+
```
154+
155+
### Set spoken language
156+
When the user selects the spoken language, your app can set the spoken language that it expects captions to be generated from.
157+
158+
``` java
159+
public void setSpokenLanguage() {
160+
communicationCaptions.setSpokenLanguage("en-us").whenComplete((result, error) -> {
161+
if (error != null) {
162+
}
163+
});
100164
}
101165
```
102166

103167
## Clean up
104-
Learn more about [cleaning up resources here.](../../../create-communication-resource.md?pivots=platform-azp&tabs=windows#clean-up-resources)
168+
Learn more about [cleaning up resources here.](../../../create-communication-resource.md?pivots=platform-azp&tabs=windows#clean-up-resources)

0 commit comments

Comments
 (0)