Freigeben über

Schnellstart: Hinzufügen von Untertiteln zu Ihrer Anruf-App

  • Artikel

Voraussetzungen

Hinweis

Bitte beachten Sie, dass Sie über eine Sprachanruf-App mit Azure Communication Services-Anruf-SDKs verfügen müssen, um auf das Feature für Untertitel zuzugreifen, das in diesem Handbuch beschrieben wird.

Modelle

Name Beschreibung
CaptionsCallFeature API für Beschriftungen
CaptionsCommon Basisklasse für Beschriftungen
StartCaptionOptions Untertiteloptionen wie gesprochene Sprache
CaptionsHandler Rückrufdefinition für die Behandlung des CaptionsReceivedEventType-Ereignisses
CaptionsInfo Datenstruktur, die für jedes CaptionsReceivedEventType-Ereignis empfangen wird

Feature Untertitel abrufen

let captionsCallFeature: SDK.CaptionsCallFeature = call.feature(SDK.Features.Captions);

Abrufen des Captions-Objekts

Sie müssen das Captions-Objekt abrufen und umwandeln, um bestimmte Features von Captions zu nutzen.

let captions: SDK.Captions;
if (captionsCallFeature.captions.kind === 'Captions') {
    captions = captionsCallFeature.captions as SDK.Captions;
}

Abonnieren von Listenern

Hinzufügen eines Listeners zum Empfangen von Beschriftungen mit aktivem/inaktivem Status

const captionsActiveChangedHandler = () => {
    if (captions.isCaptionsFeatureActive) {
        /* USER CODE HERE - E.G. RENDER TO DOM */
    }
}
captions.on('CaptionsActiveChanged', captionsActiveChangedHandler);

Hinzufügen eines Listeners für empfangene Beschriftungsdaten

Behandeln Sie das zurückgegebene CaptionsInfo-Datenobjekt.

Hinweis: Das Objekt enthält eine resultType-Eigenschaft, die angibt, ob es sich bei den Daten um eine Teilbeschriftung oder eine endgültige Version der Beschriftung handelt. ResultType Partial gibt live unbearbeitete Beschriftung an, während Final eine endgültige interpretierte Version des Satzes (d. h. Interpunktion und Großschreibung) angibt.

const captionsReceivedHandler : CaptionsHandler = (data: CaptionsInfo) => { 
    /** USER CODE HERE - E.G. RENDER TO DOM 
     * data.resultType
     * data.speaker
     * data.spokenLanguage
     * data.spokenText
     * data.timeStamp
    */
   // Example code:
   // Create a dom element, i.e. div, with id "captionArea" before proceeding with the sample code
    let mri: string;
    switch (data.speaker.identifier.kind) {
        case 'communicationUser': { mri = data.speaker.identifier.communicationUserId; 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.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(outgoingCaption);

        captionArea.appendChild(captionContainer);
    } else {
        foundCaptionContainer.textContent = captionText;

        if (captionData.resultType === 'Final') {
            foundCaptionContainer.setAttribute('isNotFinal', 'false');
        }
    }
}; 
captions.on('CaptionsReceived', captionsReceivedHandler);

Hinzufügen eines Listeners zum Empfangen des Status Gesprochene Sprache geändert

// set a local variable currentSpokenLanguage to track the current spoken language in the call
let currentSpokenLanguage = ''
const spokenLanguageChangedHandler = () => {
    if (captions.activeSpokenLanguage !== currentSpokenLanguage) {
        /* USER CODE HERE - E.G. RENDER TO DOM */
    }
}
captions.on('SpokenLanguageChanged', spokenLanguageChangedHandler)

Starten von Untertiteln

Nachdem Sie alle Ihre Listener eingerichtet haben, können Sie jetzt mit dem Hinzufügen von Untertiteln beginnen.

try {
    await captions.startCaptions({ spokenLanguage: 'en-us' });
} catch (e) {
    /* USER ERROR HANDLING CODE HERE */
}

Beenden von Beschriftungen

try {
    captions.stopCaptions(); 
} catch (e) {
    /* USER ERROR HANDLING CODE HERE */
}

Kündigen des Abonnements für Listener

captions.off('CaptionsActiveChanged', captionsActiveChangedHandler);
captions.off('CaptionsReceived', captionsReceivedHandler);

Sprachunterstützung

Abrufen einer Liste der unterstützten gesprochenen Sprachen

Rufen Sie eine Liste der unterstützten gesprochenen Sprachen ab, aus denen Ihre Benutzer auswählen können, wenn Untertitel aktiviert werden. Die Eigenschaft gibt ein Array von Sprachen im bcp 47-Format zurück.

const spokenLanguages = captions.supportedSpokenLanguages;

Festlegen der gesprochenen Sprache

Übergeben Sie einen Wert aus dem Array mit den unterstützten gesprochenen Sprachen, um sicherzustellen, dass die angeforderte Sprache unterstützt wird. Wenn contoso standardmäßig keine Sprache oder eine nicht unterstützte Sprache bereitstellt, wird die gesprochene Sprache standardmäßig auf "en-us" festgelegt.

// bcp 47 formatted language code
const language = 'en-us'; 

// Alternatively, pass a value from the supported spoken languages array
const language = spokenLanguages[0]; 

try {
    captions.setSpokenLanguage(language);
} catch (e) {
    /* USER ERROR HANDLING CODE HERE */
}

Hinzufügen eines Listeners zum Empfangen des geänderten Status der Untertitelvariante

Die Untertitelvariante kann sich von „Captions“ zu „TeamsCaptions“ ändern, wenn ein Teams/CTE-Benutzer dem Anruf beitritt oder sich der Anruf in einen Interop-Anruftyp ändert. Ein erneutes Abonnieren des Teams Untertitel-Listeners ist erforderlich, um die Untertitelerfahrung fortzusetzen. Die Variante „TeamsCaptions“ kann in einem Anruf nicht gewechselt oder wieder in die Variante „Captions“ geändert werden, sobald TeamsCaptions im Anruf verwendet wird.

const captionsKindChangedHandler = () => {
    /* USER CODE HERE - E.G. SUBSCRIBE TO TEAMS CAPTIONS */
}
captions.on('CaptionsKindChanged', captionsKindChangedHandler)

Voraussetzungen

Hinweis

Bitte beachten Sie, dass Sie über eine Sprachanruf-App mit Azure Communication Services-Anruf-SDKs verfügen müssen, um auf das Feature für Untertitel zuzugreifen, das in diesem Handbuch beschrieben wird.

Modelle

Name Beschreibung
CaptionsCallFeature API für Feature zum Aufrufen von Untertiteln
CommunicationCaptions API für Kommunikationsuntertitel
StartCaptionOptions Untertiteloptionen wie gesprochene Sprache
CommunicationCaptionsReceivedEventArgs Datenobjekt empfangen für jedes Ereignis „Kommunikationsuntertitel empfangen“

Feature Untertitel abrufen

Sie müssen das Captions-Objekt abrufen und umwandeln, um bestimmte Features von Captions zu nutzen.

CaptionsCallFeature captionsCallFeature = call.Features.Captions;
CallCaptions callCaptions = await captionsCallFeature.GetCaptionsAsync();
if (callCaptions.CaptionsKind == CaptionsKind.CommunicationCaptions)
{
    CommunicationCaptions communicationCaptions = callCaptions as CommunicationCaptions;
}

Abonnieren von Listenern

Hinzufügen eines Listeners zum Empfangen des Untertitelstatus „aktiviert/deaktiviert“

communicationCaptions.CaptionsEnabledChanged += OnIsCaptionsEnabledChanged;

private void OnIsCaptionsEnabledChanged(object sender, PropertyChangedEventArgs args)
{
    if (communicationCaptions.IsEnabled)
    {
    }
}

Hinzufügen eines Listeners zum Empfangen des geänderten Untertiteltyps

Dieses Ereignis wird ausgelöst, wenn sich der Untertiteltyp von CommunicationCaptions zu TeamsCaptions bei der Einladung von Microsoft 365-Benutzern zu Nur-ACS-Anrufen ändert.

captionsCallFeature.ActiveCaptionsTypeChanged += OnIsCaptionsTypeChanged;

private void OnIsCaptionsTypeChanged(object sender, PropertyChangedEventArgs args)
{
    // get captions
}

Hinzufügen eines Listeners für empfangene Untertiteldaten

communicationCaptions.CaptionsReceived += OnCaptionsReceived;

private void OnCaptionsReceived(object sender, CommunicationCaptionsReceivedEventArgs eventArgs)
{
    // Information about the speaker.
    // eventArgs.Speaker
    // The original text with no transcribed.
    // eventArgs.SpokenText
    // language identifier for the speaker.
    // eventArgs.SpokenLanguage
    // 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
}

Hinzufügen eines Listeners zum Empfangen des geänderten Status der aktiv gesprochenen Sprache

communicationCaptions.ActiveSpokenLanguageChanged += OnIsActiveSpokenLanguageChanged;

private void OnIsActiveSpokenLanguageChanged(object sender, PropertyChangedEventArgs args)
{
    // communicationCaptions.ActiveSpokenLanguage
}

Starten von Untertiteln

Nachdem Sie alle Ihre Listener eingerichtet haben, können Sie jetzt mit dem Hinzufügen von Untertiteln beginnen.


private async void StartCaptions()
{
    var options = new StartCaptionsOptions
    {
        SpokenLanguage = "en-us"
    };
    try
    {
        await communicationCaptions.StartCaptionsAsync(options);
    }
    catch (Exception ex)
    {
    }
}

Beenden von Beschriftungen

private async void StopCaptions()
{
    try
    {
        await communicationCaptions.StopCaptionsAsync();
    }
    catch (Exception ex)
    {
    }
}

Listener des empfangenen Untertitels entfernen

communicationCaptions.CaptionsReceived -= OnCaptionsReceived;

Sprachunterstützung

Liste der unterstützten gesprochenen Sprachen abrufen

Rufen Sie eine Liste der unterstützten gesprochenen Sprachen ab, aus denen Ihre Benutzer auswählen können, wenn Untertitel aktiviert werden.

// bcp 47 formatted language code
IReadOnlyList<string> sLanguages = communicationCaptions.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 communicationCaptions.SetSpokenLanguageAsync("en-us");
    }
    catch (Exception ex)
    {
    }
}

Bereinigung

Weitere Informationen zum Bereinigen von Ressourcen finden Sie hier.

Voraussetzungen

Hinweis

Bitte beachten Sie, dass Sie über eine Sprachanruf-App mit Azure Communication Services-Anruf-SDKs verfügen müssen, um auf das Feature für Untertitel zuzugreifen, das in diesem Handbuch beschrieben wird.

Modelle

Name Beschreibung
CaptionsCallFeature API für Feature zum Aufrufen von Untertiteln
CommunicationCaptions API für Kommunikationsuntertitel
StartCaptionOptions Untertiteloptionen wie gesprochene Sprache
CommunicationCaptionsListener Listener für CommunicationCaptions addOnCaptionsReceivedListener
CommunicationCaptionsReceivedEvent Datenobjekt empfangen für jedes Ereignis „CommunicationCaptionsListener“

Feature Untertitel abrufen

Sie müssen das Captions-Objekt abrufen und umwandeln, um bestimmte Features von Captions zu nutzen.

CaptionsCallFeature captionsCallFeature = call.feature(Features.CAPTIONS);
captionsCallFeature.getCaptions().whenComplete(
    ((captions, throwable) -> {
        if (throwable == null) {
            CallCaptions callCaptions = captions;
            if (captions.getCaptionsType() == CaptionsType.COMMUNICATION_CAPTIONS) {
            // communication captions
            CommunicationCaptions communicationCaptions = (CommunicationCaptions) captions;
            }
        } else {
        // get captions failed
        // throwable is the exception/cause
        }
    }));

Abonnieren von Listenern

Hinzufügen eines Listeners zum Empfangen des Untertitelstatus „aktiviert/deaktiviert“

public void addOnIsCaptionsEnabledChangedListener() {
    communicationCaptions.addOnCaptionsEnabledChangedListener( (PropertyChangedEvent args) -> {
        if(communicationCaptions.isEnabled()) {
            // captions enabled
        }
    });
}

Hinzufügen eines Listeners zum Empfangen des geänderten Untertiteltyps

Dieses Ereignis wird ausgelöst, wenn sich der Untertiteltyp von CommunicationCaptions zu TeamsCaptions bei der Einladung von Microsoft 365-Benutzern zu Nur-ACS-Anrufen ändert.

public void addOnIsCaptionsTypeChangedListener() {
    captionsCallFeature.addOnActiveCaptionsTypeChangedListener( (PropertyChangedEvent args) -> {
        if(communicationCaptions.isEnabled()) {
            // captionsCallFeature.getCaptions();
        }
    });
}

Hinzufügen eines Listeners für empfangene Untertiteldaten

CommunicationCaptionsListener captionsListener = (CommunicationCaptionsReceivedEvent args) -> {
  // Information about the speaker.
  // CallerInfo participantInfo = args.getSpeaker();
  // The original text with no transcribed.
  // args.getSpokenText();
  // language identifier for the speaker.
  // args.getSpokenLanguage();
  // 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() {
  communicationCaptions.addOnCaptionsReceivedListener(captionsListener); 
}

Hinzufügen eines Listeners zum Empfangen des geänderten Status der aktiv gesprochenen Sprache

public void addOnActiveSpokenLanguageChangedListener() {
    communicationCaptions.addOnActiveSpokenLanguageChangedListener( (PropertyChangedEvent args) -> {
       // communicationCaptions.getActiveSpokenLanguage()
    });
}

Starten von Untertiteln

Nachdem Sie alle Ihre Listener eingerichtet haben, können Sie jetzt mit dem Hinzufügen von Untertiteln beginnen.

public void startCaptions() {
    StartCaptionsOptions startCaptionsOptions = new StartCaptionsOptions();
    startCaptionsOptions.setSpokenLanguage("en-us");
    communicationCaptions.startCaptions(startCaptionsOptions).whenComplete((result, error) -> {
        if (error != null) {
        }
    });
}

Beenden von Beschriftungen

public void stopCaptions() {
    communicationCaptions.stopCaptions().whenComplete((result, error) -> {
        if (error != null) {
        }
    });
}

Listener des empfangenen Untertitels entfernen

public void removeOnCaptionsReceivedListener() {
    communicationCaptions.removeOnCaptionsReceivedListener(captionsListener);
}

Sprachunterstützung

Liste der unterstützten gesprochenen Sprachen abrufen

Rufen Sie eine Liste der unterstützten gesprochenen Sprachen ab, aus denen Ihre Benutzer auswählen können, wenn Untertitel aktiviert werden.

// bcp 47 formatted language code
communicationCaptions.getSupportedSpokenLanguages();

Festlegen der gesprochenen Sprache

Wenn der Benutzer die gesprochene Sprache auswählt, kann Ihre App die gesprochene Sprache festlegen, in der die Untertitel generiert werden sollen.

public void setSpokenLanguage() {
    communicationCaptions.setSpokenLanguage("en-us").whenComplete((result, error) -> {
        if (error != null) {
        }
    });
}

Bereinigung

Weitere Informationen zum Bereinigen von Ressourcen finden Sie hier.

Voraussetzungen

Hinweis

Bitte beachten Sie, dass Sie über eine Sprachanruf-App mit Azure Communication Services-Anruf-SDKs verfügen müssen, um auf das Feature für Untertitel zuzugreifen, das in diesem Handbuch beschrieben wird.

Modelle

Name Beschreibung
CaptionsCallFeature API für Feature zum Aufrufen von Untertiteln
CommunicationCaptions API für Kommunikationsuntertitel
StartCaptionOptions Untertiteloptionen wie gesprochene Sprache
CommunicationCaptionsDelegate Delegat für Kommunikationsuntertitel
CommunicationCaptionsReceivedEventArgs Datenobjekt empfangen für jedes Ereignis „Kommunikationsuntertitel empfangen“

Feature Untertitel abrufen

Sie müssen das Captions-Objekt abrufen und umwandeln, um bestimmte Features von Captions zu nutzen.

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.communicationCaptions) {
                // communication captions
                @State var communicationCaptions = value as? CommunicationCaptions
            }
        }
    }
}

Abonnieren von Listenern

Hinzufügen eines Listeners zum Empfangen des Untertitelstatus „aktiviert/deaktiviert“, Typ, gesprochene Sprache, geänderter Status der Untertitelsprache und empfangene Daten

Das Ereignis didChangeActiveCaptionsType wird ausgelöst, wenn sich der Untertiteltyp von CommunicationCaptions zu TeamsCaptions bei der Einladung von Microsoft 365-Benutzern zu Nur-ACS-Anrufen ändert.

extension CallObserver: CommunicationCaptionsDelegate {
    // listener for receive captions enabled/disabled status
    public func communicationCaptions(_ communicationCaptions: CommunicationCaptions, didChangeCaptionsEnabledState args: PropertyChangedEventArgs) {
        // communicationCaptions.isEnabled
    }
    
    // listener for active spoken language state change
    public func communicationCaptions(_ communicationCaptions: CommunicationCaptions, didChangeActiveSpokenLanguageState args: PropertyChangedEventArgs) {
        // communicationCaptions.activeSpokenLanguage
    }
    
    // listener for captions data received
    public func communicationCaptions(_ communicationCaptions: CommunicationCaptions, didReceiveCaptions:CommunicationCaptionsReceivedEventArgs) {
            // Information about the speaker.
            // didReceiveCaptions.speaker
            // The original text with no transcribed.
            // didReceiveCaptions.spokenText
            // language identifier for the speaker.
            // didReceiveCaptions.spokenLanguage
            // 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
    }
}

communicationCaptions.delegate = self.callObserver

extension CallObserver: CaptionsCallFeatureDelegate {
    // captions type changed
    public func captionsCallFeature(_ captionsCallFeature: CaptionsCallFeature, didChangeActiveCaptionsType args: PropertyChangedEventArgs) {
        // captionsCallFeature.getCaptions to get captions
    }
}

captionsCallFeature.delegate = self.callObserver

Starten von Untertiteln

Nachdem Sie alle Ihre Listener eingerichtet haben, können Sie jetzt mit dem Hinzufügen von Untertiteln beginnen.

func startCaptions() {
    guard let communicationCaptions = communicationCaptions else {
        return
    }
    let startCaptionsOptions = StartCaptionsOptions()
    startCaptionsOptions.spokenLanguage = "en-us"
    communicationCaptions.startCaptions(startCaptionsOptions: startCaptionsOptions, completionHandler: { (error) in
        if error != nil {
            
        }
    })
}

Beenden von Beschriftungen

func stopCaptions() {
    communicationCaptions.stopCaptions(completionHandler: { (error) in
        if error != nil {
            
        }
    })
}

Listener des empfangenen Untertitels entfernen

communicationCaptions?.delegate = nil

Sprachunterstützung

Liste der unterstützten gesprochenen Sprachen abrufen

Rufen Sie eine Liste der unterstützten gesprochenen Sprachen ab, aus denen Ihre Benutzer auswählen können, wenn Untertitel aktiviert werden.

// bcp 47 formatted language code
let spokenLanguage : String = "en-us"
for language in communicationCaptions?.supportedSpokenLanguages ?? [] {
    // choose required language
    spokenLanguage = language
}

Festlegen der gesprochenen Sprache

Wenn der Benutzer die gesprochene Sprache auswählt, kann Ihre App die gesprochene Sprache festlegen, in der die Untertitel generiert werden sollen.

func setSpokenLanguage() {
    guard let communicationCaptions = self.communicationCaptions else {
        return
    }

    communicationCaptions.set(spokenLanguage: spokenLanguage, completionHandler: { (error) in
        if let error = error {
        }
    })
}

Bereinigung

Weitere Informationen zum Bereinigen von Ressourcen finden Sie hier.

Bereinigen von Ressourcen

Wenn Sie ein Communication Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind. Weitere Informationen zum Bereinigen von Ressourcen finden Sie hier.

Nächste Schritte

Weitere Informationen finden Sie in den folgenden Artikeln: