啟用隱藏式輔助字幕以達到 Teams 互通性
了解在使用者可能參與 Azure 通訊服務使用者與 Teams 用戶端使用者之間會議,或使用者透過其 Microsoft 365 身分識別使用 Azure 通訊服務通話 SDK 的 Teams 互通性案例中,如何讓使用者啟用隱藏式輔助字幕。
必要條件
- 包含使用中訂用帳戶的 Azure 帳戶。如需詳細資料,請參閱建立免費帳戶。
- Azure 通訊服務資源。 請參閱建立 Azure 通訊服務資源。 儲存此資源的連接字串。
- 具有語音和視訊通話的應用程式,請參閱我們的語音和視訊通話快速入門。
- Microsoft 365 使用者的存取權杖。
- 外部身分識別使用者的存取權杖。
- 對於翻譯字幕,您必須擁有 Teams 進階授權。
注意
請注意,您必須具有語音通話應用程式,才能使用 Azure 通訊服務通話 SDK 來存取本指南中所述的隱藏式輔助字幕功能。
模型
名稱 | 描述 |
---|---|
CaptionsCallFeature | 適用於字幕呼叫功能的 API |
TeamsCaptions | 適用於 Teams 字幕的 API |
StartCaptionOptions | 口語語言等隱藏式輔助字幕選項 |
TeamsCaptionsReceivedEventArgs | 針對每個已接收 Teams 字幕的事件接收的資料物件 |
取得隱藏式輔助字幕功能
外部身分識別使用者和 Microsoft 365 使用者
如果您要建置可讓 Azure 通訊服務使用者加入 Teams 會議的應用程式
CaptionsCallFeature captionsCallFeature = call.Features.Captions;
CallCaptions callCaptions = await captionsCallFeature.GetCaptionsAsync();
if (callCaptions.CaptionsKind == CaptionsKind.TeamsCaptions)
{
TeamsCaptions teamsCaptions = callCaptions as TeamsCaptions;
}
訂閱接聽程式
新增接聽程式以接收字幕已啟用/已停用狀態
teamsCaptions.CaptionsEnabledChanged += OnIsCaptionsEnabledChanged;
private void OnIsCaptionsEnabledChanged(object sender, PropertyChangedEventArgs args)
{
if (teamsCaptions.IsEnabled)
{
}
}
新增所接收字幕資料的接聽程式
teamsCaptions.CaptionsReceived += OnCaptionsReceived;
private void OnCaptionsReceived(object sender, TeamsCaptionsReceivedEventArgs eventArgs)
{
// Information about the speaker.
// eventArgs.Speaker
// The original text with no transcribed.
// eventArgs.SpokenText
// language identifier for the captions text.
// eventArgs.CaptionLanguage
// language identifier for the speaker.
// eventArgs.SpokenLanguage
// The transcribed text.
// eventArgs.CaptionText
// Timestamp denoting the time when the corresponding speech was made.
// eventArgs.Timestamp
// CaptionsResultKind is Partial if text contains partially spoken sentence.
// It is set to Final once the sentence has been completely transcribed.
// eventArgs.ResultKind
}
新增接聽程式以接收作用中口語語言已變更狀態
teamsCaptions.ActiveSpokenLanguageChanged += OnIsActiveSpokenLanguageChanged;
private void OnIsActiveSpokenLanguageChanged(object sender, PropertyChangedEventArgs args)
{
// teamsCaptions.ActiveSpokenLanguage
}
新增接聽程式以接收作用中字幕語言已變更狀態
teamsCaptions.ActiveCaptionLanguageChanged += OnIsActiveCaptionLanguageChanged;
private void OnIsActiveCaptionLanguageChanged(object sender, PropertyChangedEventArgs args)
{
// teamsCaptions.ActiveCaptionLanguage
}
啟動字幕
設定所有接聽程式後,您現在可以開始新增字幕。
private async void StartCaptions()
{
var options = new StartCaptionsOptions
{
SpokenLanguage = "en-us"
};
try
{
await teamsCaptions.StartCaptionsAsync(options);
}
catch (Exception ex)
{
}
}
停止字幕
private async void StopCaptions()
{
try
{
await teamsCaptions.StopCaptionsAsync();
}
catch (Exception ex)
{
}
}
移除字幕接收的接聽程式
teamsCaptions.CaptionsReceived -= OnCaptionsReceived;
口語語言支援
取得支援的口語語言清單
取得支援的口語語言清單,以便使用者在啟用隱藏式輔助字幕時從中選取。
// bcp 47 formatted language code
IReadOnlyList<string> sLanguages = teamsCaptions.SupportedSpokenLanguages;```
### Set spoken language
When the user selects the spoken language, your app can set the spoken language that it expects captions to be generated from.
``` cs
public async void SetSpokenLanguage()
{
try
{
await teamsCaptions.SetSpokenLanguageAsync("en-us");
}
catch (Exception ex)
{
}
}
字幕語言支援
取得支援的字幕語言
如果您的組織擁有有效的 Teams 進階授權,則只要會議的召集人具有 Teams 進階授權,Azure 通訊服務使用者就可以啟用翻譯字幕。 至於具有 Microsoft 365 身分識別的使用者,如果會議召集人沒有 Teams 進階授權,則會針對自己的使用者帳戶進行此檢查。
// ISO 639-1 formatted language code
IReadOnlyList<string> cLanguages = teamsCaptions.SupportedCaptionLanguages;
設定字幕語言
public async void SetCaptionLanguage()
{
try
{
await teamsCaptions.SetCaptionLanguageAsync("en");
}
catch (Exception ex)
{
}
}
必要條件
- 包含使用中訂用帳戶的 Azure 帳戶。如需詳細資料,請參閱建立免費帳戶。
- Azure 通訊服務資源。 請參閱建立 Azure 通訊服務資源。 儲存此資源的連接字串。
- 具有語音和視訊通話的應用程式,請參閱我們的語音和視訊通話快速入門。
- Microsoft 365 使用者的存取權杖。
- 外部身分識別使用者的存取權杖。
- 對於翻譯字幕,您必須擁有 Teams 進階授權。
注意
請注意,您必須具有語音通話應用程式,才能使用 Azure 通訊服務通話 SDK 來存取本指南中所述的隱藏式輔助字幕功能。
模型
名稱 | 描述 |
---|---|
CaptionsCallFeature | 適用於字幕的 API |
CaptionsCommon | 字幕的基底類別 |
StartCaptionOptions | 口語語言等隱藏式輔助字幕選項 |
TeamsCaptionHandler | 處理 CaptionsReceivedEventType 事件的回呼定義 |
TeamsCaptionsInfo | 針對每個 CaptionsReceivedEventType 事件接收的資料結構 |
取得隱藏式輔助字幕功能
外部身分識別使用者
如果您要建置可讓 Azure 通訊服務使用者加入 Teams 會議的應用程式。
let captionsCallFeature: SDK.CaptionsCallFeature = call.feature(SDK.Features.Captions);
Microsoft 365 使用者
let captionsCallFeature: SDK.CaptionsCallFeature = teamsCall.feature(SDK.Features.Captions);
取得 Teams 字幕物件
您需要取得並轉換 Teams 字幕物件,才能利用 Teams 字幕特定功能
let teamsCaptions: SDK.TeamsCaptions;
if (captionsCallFeature.captions.kind === 'TeamsCaptions') {
teamsCaptions = captionsCallFeature.captions as SDK.TeamsCaptions;
}
訂閱接聽程式
新增接聽程式以接收字幕作用中/非作用中狀態
const captionsActiveChangedHandler = () => {
if (teamsCaptions.isCaptionsFeatureActive) {
/* USER CODE HERE - E.G. RENDER TO DOM */
}
}
teamsCaptions.on('CaptionsActiveChanged', captionsActiveChangedHandler);
新增所接收字幕資料的接聽程式
處理傳回的 TeamsCaptionsInfo 資料物件。
注意:物件包含 resultType 屬性,該屬性指出資料是部分字幕或最終的字幕版本。 ResultType partial
表示未經過編輯的即時字幕,而 final
表示句子的最終解譯版本 (即包括標點符號和大小寫)。
let currentCaptionLanguage : string;
const captionsReceivedHandler : TeamsCaptionsHandler = (data: TeamsCaptionsInfo) => {
/** USER CODE HERE - E.G. RENDER TO DOM
* data.captionLanguage
* data.captionText
* data.resultType
* data.speaker
* data.spokenText
* data.timeStamp
*/
// Example code:
// Create a dom element, i.e. div, with id "captionArea" before proceeding with the sample code
if (!this._currentCaptionLanguage || this._currentCaptionLanguage === data.captionLanguage) {
let mri: string;
switch (data.speaker.identifier.kind) {
case 'communicationUser': { mri = data.speaker.identifier.communicationUserId; break; }
case 'microsoftTeamsUser': { mri = data.speaker.identifier.microsoftTeamsUserId; break; }
case 'phoneNumber': { mri = data.speaker.identifier.phoneNumber; break; }
}
const outgoingCaption = `prefix${mri.replace(/:/g, '').replace(/-/g, '')}`;
let captionArea = document.getElementById("captionArea");
const captionText = `${data.timestamp.toUTCString()}
${data.speaker.displayName}: ${data.captionText ?? data.spokenText}`;
let foundCaptionContainer = captionArea.querySelector(`.${outgoingCaption}[isNotFinal='true']`);
if (!foundCaptionContainer) {
let captionContainer = document.createElement('div');
captionContainer.setAttribute('isNotFinal', 'true');
captionContainer.style['borderBottom'] = '1px solid';
captionContainer.style['whiteSpace'] = 'pre-line';
captionContainer.textContent = captionText;
captionContainer.classList.add(newClassName);
captionArea.appendChild(captionContainer);
} else {
foundCaptionContainer.textContent = captionText;
if (captionData.resultType === 'Final') {
foundCaptionContainer.setAttribute('isNotFinal', 'false');
}
}
}
};
teamsCaptions.on('CaptionsReceived', captionsReceivedHandler);
新增接聽程式以接收口語語言已變更狀態
const spokenLanguageChangedHandler = () => {
if (teamsCaptions.activeSpokenLanguage !== currentSpokenLanguage) {
/* USER CODE HERE - E.G. RENDER TO DOM */
}
}
teamsCaptions.on('SpokenLanguageChanged', spokenLanguageChangedHandler)
新增接聽程式以接收字幕語言已變更狀態
const captionLanguageChangedHandler = () => {
if (teamsCaptions.activeCaptionLanguage !== currentCaptionLanguage) {
/* USER CODE HERE - E.G. RENDER TO DOM */
}
}
teamsCaptions.on('CaptionLanguageChanged', captionLanguageChangedHandler)
啟動字幕
設定所有接聽程式後,您現在可以開始新增字幕。
try {
await teamsCaptions.startCaptions({ spokenLanguage: 'en-us' });
} catch (e) {
/* USER ERROR HANDLING CODE HERE */
}
停止字幕
try {
teamsCaptions.stopCaptions();
} catch (e) {
/* USER ERROR HANDLING CODE HERE */
}
取消訂閱接聽程式
teamsCaptions.off('CaptionsActiveChanged', captionsActiveChangedHandler);
teamsCaptions.off('CaptionsReceived', captionsReceivedHandler);
口語語言支援
取得支援的口語語言清單
取得支援的口語語言清單,以便使用者在啟用隱藏式輔助字幕時從中選取。 此屬性會傳回 bcp 47 格式的語言陣列。
const spokenLanguages = teamsCaptions.supportedSpokenLanguages;
設定口語語言
從支援的口語語言陣列傳入值,以確保支援所要求的語言。 根據預設,如果 contoso 未提供任何語言或提供不支援的語言,則口語語言會預設為 'en-us'。
// bcp 47 formatted language code
const language = 'en-us';
// Altneratively, pass a value from the supported spoken languages array
const language = spokenLanguages[0];
try {
teamsCaptions.setSpokenLanguage(language);
} catch (e) {
/* USER ERROR HANDLING CODE HERE */
}
字幕語言支援
取得支援的字幕語言清單
如果您的組織有作用中的 Teams 進階授權,您可讓使用者使用 Teams 字幕所提供的翻譯字幕。 至於具有 Microsoft 365 身分識別的使用者,如果會議召集人沒有作用中的 Teams 進階授權,則會針對 Microsoft 365 使用者帳戶進行字幕語言檢查。
此屬性會傳回 ISO 639-1
標準中雙字母語言代碼的陣列。
const captionLanguages = teamsCaptions.supportedCaptionLanguages;
設定字幕語言
// ISO 639-1 formatted language code
const language = 'en';
// Altneratively, pass a value from the supported caption languages array
const language = captionLanguages[0];
try {
teamsCaptions.setCaptionLanguage(language);
} catch (e) {
/* USER ERROR HANDLING CODE HERE */
}
必要條件
- 包含使用中訂用帳戶的 Azure 帳戶。如需詳細資料,請參閱建立免費帳戶。
- Azure 通訊服務資源。 請參閱建立 Azure 通訊服務資源。 儲存此資源的連接字串。
- 具有語音和視訊通話的應用程式,請參閱我們的語音和視訊通話快速入門。
- Microsoft 365 使用者的存取權杖。
- 外部身分識別使用者的存取權杖。
- 對於翻譯字幕,您必須擁有 Teams 進階授權。
注意
請注意,您必須具有語音通話應用程式,才能使用 Azure 通訊服務通話 SDK 來存取本指南中所述的隱藏式輔助字幕功能。
模型
名稱 | 描述 |
---|---|
CaptionsCallFeature | 適用於字幕呼叫功能的 API |
TeamsCaptions | 適用於 Teams 字幕的 API |
StartCaptionOptions | 口語語言等隱藏式輔助字幕選項 |
TeamsCaptionsListener | TeamsCaptions addOnCaptionsReceivedListener 的接聽程式 |
TeamsCaptionsReceivedEvent | 針對每個 TeamsCaptionsListener 事件收到的資料物件 |
取得隱藏式輔助字幕功能
外部身分識別使用者和 Microsoft 365 使用者
如果您要建置可讓使用者加入 Teams 會議的應用程式
CaptionsCallFeature captionsCallFeature = call.feature(Features.CAPTIONS);
captionsCallFeature.getCaptions().whenComplete(
((captions, throwable) -> {
if (throwable == null) {
CallCaptions callCaptions = captions;
if (captions.getCaptionsType() == CaptionsType.TEAMS_CAPTIONS) {
// teams captions
TeamsCaptions teamsCaptions = (TeamsCaptions) captions;
}
} else {
// get captions failed
// throwable is the exception/cause
}
}));
訂閱接聽程式
新增接聽程式以接收字幕已啟用/已停用狀態
public void addOnIsCaptionsEnabledChangedListener() {
teamsCaptions.addOnCaptionsEnabledChangedListener( (PropertyChangedEvent args) -> {
if(teamsCaptions.isEnabled()) {
// captions enabled
}
});
}
新增所接收字幕資料的接聽程式
TeamsCaptionsListener captionsListener = (TeamsCaptionsReceivedEvent args) -> {
// Information about the speaker.
// CallerInfo participantInfo = args.getSpeaker();
// The original text with no transcribed.
// args.getSpokenText();
// language identifier for the captions text.
// args.getCaptionLanguage();
// language identifier for the speaker.
// args.getSpokenLanguage();
// The transcribed text.
// args.getCaptionText();
// Timestamp denoting the time when the corresponding speech was made.
// args.getTimestamp();
// CaptionsResultType is Partial if text contains partially spoken sentence.
// It is set to Final once the sentence has been completely transcribed.
// args.getResultType() == CaptionsResultType.FINAL;
};
public void addOnCaptionsReceivedListener() {
teamsCaptions.addOnCaptionsReceivedListener(captionsListener);
}
新增接聽程式以接收作用中口語語言已變更狀態
public void addOnActiveSpokenLanguageChangedListener() {
teamsCaptions.addOnActiveSpokenLanguageChangedListener( (PropertyChangedEvent args) -> {
// teamsCaptions.getActiveSpokenLanguage()
});
}
新增接聽程式以接收作用中字幕語言已變更狀態
public void addOnActiveCaptionLanguageChangedListener() {
teamsCaptions.addOnActiveCaptionLanguageChangedListener( (PropertyChangedEvent args) -> {
// teamsCaptions.getActiveCaptionLanguage()
});
}
啟動字幕
設定所有接聽程式後,您現在可以開始新增字幕。
public void startCaptions() {
StartCaptionsOptions startCaptionsOptions = new StartCaptionsOptions();
startCaptionsOptions.setSpokenLanguage("en-us");
teamsCaptions.startCaptions(startCaptionsOptions).whenComplete((result, error) -> {
if (error != null) {
}
});
}
停止字幕
public void stopCaptions() {
teamsCaptions.stopCaptions().whenComplete((result, error) -> {
if (error != null) {
}
});
}
移除字幕接收的接聽程式
public void removeOnCaptionsReceivedListener() {
teamsCaptions.removeOnCaptionsReceivedListener(captionsListener);
}
口語語言支援
取得支援的口語語言清單
取得支援的口語語言清單,以便使用者在啟用隱藏式輔助字幕時從中選取。
// bcp 47 formatted language code
teamsCaptions.getSupportedSpokenLanguages();
設定口語語言
當使用者選取口語語言時,您的應用程式可以設定其預期要用來產生字幕的口語語言。
public void setSpokenLanguage() {
teamsCaptions.setSpokenLanguage("en-us").whenComplete((result, error) -> {
if (error != null) {
}
});
}
字幕語言支援
取得支援的字幕語言
如果您的組織擁有有效的 Teams 進階授權,則只要會議的召集人具有 Teams 進階授權,Azure 通訊服務使用者就可以啟用翻譯字幕。 至於具有 Microsoft 365 身分識別的使用者,如果會議召集人沒有 Teams 進階授權,則會針對自己的使用者帳戶進行此檢查。
// ISO 639-1 formatted language code
teamsCaptions.getSupportedCaptionLanguages();
設定字幕語言
public void setCaptionLanguage() {
teamsCaptions.setCaptionLanguage("en").whenComplete((result, error) -> {
if (error != null) {
}
});
}
必要條件
- 包含使用中訂用帳戶的 Azure 帳戶。如需詳細資料,請參閱建立免費帳戶。
- Azure 通訊服務資源。 請參閱建立 Azure 通訊服務資源。 儲存此資源的連接字串。
- 具有語音和視訊通話的應用程式,請參閱我們的語音和視訊通話快速入門。
- Microsoft 365 使用者的存取權杖。
- 外部身分識別使用者的存取權杖。
- 對於翻譯字幕,您必須擁有 Teams 進階授權。
注意
請注意,您必須具有語音通話應用程式,才能使用 Azure 通訊服務通話 SDK 來存取本指南中所述的隱藏式輔助字幕功能。
模型
名稱 | 描述 |
---|---|
CaptionsCallFeature | 適用於字幕呼叫功能的 API |
TeamsCaptions | 適用於 Teams 字幕的 API |
StartCaptionOptions | 口語語言等隱藏式輔助字幕選項 |
TeamsCaptionsDelegate | Teams 字幕的委派 |
TeamsCaptionsReceivedEventArgs | 針對每個已接收 Teams 字幕的事件接收的資料物件 |
取得隱藏式輔助字幕功能
外部身分識別使用者和 Microsoft 365 使用者
如果您要建置可讓 Azure 通訊服務使用者加入 Teams 會議的應用程式
if let call = self.call {
@State var captionsCallFeature = call.feature(Features.captions)
captionsCallFeature.getCaptions{(value, error) in
if let error = error {
// failed to get captions
} else {
if (value?.type == CaptionsType.teamsCaptions) {
// teams captions
@State var teamsCaptions = value as? TeamsCaptions
}
}
}
}
訂閱接聽程式
新增接聽程式以接收字幕已啟用/已停用、口語語言、變更的字幕語言狀態,以及接收的資料
extension CallObserver: TeamsCaptionsDelegate {
// listener for receive captions enabled/disabled status
public func teamsCaptions(_ teamsCaptions: TeamsCaptions, didChangeCaptionsEnabledState args: PropertyChangedEventArgs) {
// teamsCaptions.isEnabled
}
// listener for active spoken language state change
public func teamsCaptions(_ teamsCaptions: TeamsCaptions, didChangeActiveSpokenLanguageState args: PropertyChangedEventArgs) {
// teamsCaptions.activeSpokenLanguage
}
// listener for active caption language state change
public func teamsCaptions(_ teamsCaptions: TeamsCaptions, didChangeActiveCaptionLanguageState args: PropertyChangedEventArgs) {
// teamsCaptions.activeCaptionLanguage
}
// listener for captions data received
public func teamsCaptions(_ teamsCaptions: TeamsCaptions, didReceiveCaptions:TeamsCaptionsReceivedEventArgs) {
// Information about the speaker.
// didReceiveCaptions.speaker
// The original text with no transcribed.
// didReceiveCaptions.spokenText
// language identifier for the captions text.
// didReceiveCaptions.captionLanguage
// language identifier for the speaker.
// didReceiveCaptions.spokenLanguage
// The transcribed text.
// didReceiveCaptions.captionText
// Timestamp denoting the time when the corresponding speech was made.
// didReceiveCaptions.timestamp
// CaptionsResultType is Partial if text contains partially spoken sentence.
// It is set to Final once the sentence has been completely transcribed.
// didReceiveCaptions.resultType
}
}
teamsCaptions.delegate = self.callObserver
啟動字幕
設定所有接聽程式後,您現在可以開始新增字幕。
func startCaptions() {
guard let teamsCaptions = teamsCaptions else {
return
}
let startCaptionsOptions = StartCaptionsOptions()
startCaptionsOptions.spokenLanguage = "en-us"
teamsCaptions.startCaptions(startCaptionsOptions: startCaptionsOptions, completionHandler: { (error) in
if error != nil {
}
})
}
停止字幕
func stopCaptions() {
teamsCaptions.stopCaptions(completionHandler: { (error) in
if error != nil {
}
})
}
移除字幕接收的接聽程式
teamsCaptions?.delegate = nil
口語語言支援
取得支援的口語語言清單
取得支援的口語語言清單,以便使用者在啟用隱藏式輔助字幕時從中選取。
// bcp 47 formatted language code
let spokenLanguage : String = "en-us"
for language in teamsCaptions?.supportedSpokenLanguages ?? [] {
// choose required language
spokenLanguage = language
}
設定口語語言
當使用者選取口語語言時,您的應用程式可以設定其預期要用來產生字幕的口語語言。
func setSpokenLanguage() {
guard let teamsCaptions = self.teamsCaptions else {
return
}
teamsCaptions.set(spokenLanguage: spokenLanguage, completionHandler: { (error) in
if let error = error {
}
})
}
字幕語言支援
取得支援的字幕語言
如果您的組織擁有有效的 Teams 進階授權,則只要會議的召集人具有 Teams 進階授權,Azure 通訊服務使用者就可以啟用翻譯字幕。 至於具有 Microsoft 365 身分識別的使用者,如果會議召集人沒有 Teams 進階授權,則會針對自己的使用者帳戶進行此檢查。
// ISO 639-1 formatted language code
let captionLanguage : String = "en"
for language in teamsCaptions?.supportedCaptionLanguages ?? [] {
// choose required language
captionLanguage = language
}
設定字幕語言
func setCaptionLanguage() {
guard let teamsCaptions = self.teamsCaptions else {
return
}
teamsCaptions.set(captionLanguage: captionLanguage, completionHandler: { (error) in
if let error = error {
}
})
}
清除資源
如果您想要清除並移除通訊服務訂用帳戶,您可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。 深入了解如何清除資源。
下一步
如需詳細資訊,請參閱下列文章: