Partager via

Démarrage rapide : ajouter des sous-titres codés à votre application d’appel

  • Article

Prérequis

Remarque

Veuillez noter que vous devez avoir une application d’appel vocal utilisant des Kits de développement logiciel (SDK) d’appel Azure Communication Services pour accéder à la fonctionnalité des sous-titres décrite dans ce guide.

Modèles

Nom Description
CaptionsCallFeature API pour les sous-titres
CaptionsCommon Classe de base pour les sous-titres
StartCaptionOptions Options de sous-titre comme la langue parlée
CaptionsHandler Définition de rappel pour gérer un événement CaptionsReceivedEventType
CaptionsInfo Structure de données reçue pour chaque événement CaptionsReceivedEventType

Obtenir la fonctionnalité des sous-titres

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

Obtenir un objet des sous-titres

Vous devez obtenir et effectuer un cast de l’objet des sous-titres pour utiliser des fonctionnalités spécifiques des sous-titres.

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

S’abonner aux écouteurs

Ajouter un écouteur pour recevoir d’état actif/inactif de sous-titres

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

Ajouter un écouteur pour des données de sous-titres reçues

Gérez l’objet de données CaptionsInfo renvoyé.

Remarque : l’objet contient une propriété resultType qui indique si les données constituent un sous-titre partiel ou une version finalisée du sous-titre. ResultType Partial indique un sous-titre en direct non modifié, tandis que Final indique une version interprétée finalisée de la phrase (par exemple, inclut la ponctuation et l’utilisation de majuscules).

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);

Ajouter un écouteur pour recevoir l’état modifié de la langue parlée

// 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)

Démarrer les sous-titres

Une fois tous vos écouteurs configurés, vous pouvez désormais ajouter vos sous-titres.

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

Arrêter des sous-titres

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

Se désabonner des écouteurs

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

Prise en charge de la langue parlée

Obtenir une liste des langues parlées prises en charge

Obtenez une liste des langues parlées prises en charge que vos utilisateurs peuvent sélectionner quand ils activent les sous-titres. La propriété renvoie un tableau de langues au format BCP 47.

const spokenLanguages = captions.supportedSpokenLanguages;

Définir une langue parlée

Transmettez une valeur à partir du tableau de langues parlées prises en charge pour vérifier que la langue demandée est prise en charge. Par défaut, si Contoso ne fournit aucune langue ou fournit une langue non prise en charge, la valeur par défaut de la langue parlée est « en-us ».

// 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 */
}

Ajouter un écouteur pour recevoir l’état modifié d’un type de sous-titre

Le type de sous-titre peut passer de Sous-titres à TeamsCaptions si un utilisateur Teams/CTE rejoint l’appel ou si l’appel passe à un type d’appel d’interopérabilité. Un réabonnement aux écouteurs de Sous-titres Teams est nécessaire pour poursuivre l’expérience des sous-titres. Le type Sous-titres Teams ne peut pas être changé ou rétabli en type Sous-titres dans un appel dès lors que TeamsCaptions est utilisé dans l’appel.

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

Prérequis

Remarque

Veuillez noter que vous devez avoir une application d’appel vocal utilisant des Kits de développement logiciel (SDK) d’appel Azure Communication Services pour accéder à la fonctionnalité des sous-titres décrite dans ce guide.

Modèles

Nom Description
CaptionsCallFeature API pour la fonction d'appel de sous-titres
CommunicationCaptions API pour les légendes de communication
StartCaptionOptions Options de sous-titre comme la langue parlée
CommunicationCaptionsReceivedEventArgs Objet de données reçu pour chaque événement de réception de légendes de communication

Obtenir la fonctionnalité des sous-titres

Vous devez obtenir et effectuer un cast de l’objet des sous-titres pour utiliser des fonctionnalités spécifiques des sous-titres.

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

S’abonner aux écouteurs

Ajouter un écouteur pour recevoir d’état activée ou désactivé de sous-titres

communicationCaptions.CaptionsEnabledChanged += OnIsCaptionsEnabledChanged;

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

Ajouter un écouteur pour recevoir les légendes dont le type a été modifié

Cet événement est déclenché lorsque le type de légende passe de CommunicationCaptions à TeamsCaptions l’invitation d’utilisateurs Microsoft 365 aux appels ACS uniquement.

captionsCallFeature.ActiveCaptionsTypeChanged += OnIsCaptionsTypeChanged;

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

Ajouter un écouteur pour des données de sous-titres reçues

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
}

Ajouter un écouteur pour recevoir l’état modifié actif de la langue parlée

communicationCaptions.ActiveSpokenLanguageChanged += OnIsActiveSpokenLanguageChanged;

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

Démarrer les sous-titres

Une fois tous vos écouteurs configurés, vous pouvez désormais ajouter vos sous-titres.


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

Arrêter des sous-titres

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

Supprimer la légende reçue par l'auditeur

communicationCaptions.CaptionsReceived -= OnCaptionsReceived;

Prise en charge de la langue parlée

Obtenir une liste des langues parlées prises en charge

Obtenez une liste des langues parlées prises en charge que vos utilisateurs peuvent sélectionner quand ils activent les sous-titres.

// 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)
    {
    }
}

Nettoyage

Apprenez-en davantage sur le nettoyage des ressources.

Prérequis

Remarque

Veuillez noter que vous devez avoir une application d’appel vocal utilisant des Kits de développement logiciel (SDK) d’appel Azure Communication Services pour accéder à la fonctionnalité des sous-titres décrite dans ce guide.

Modèles

Nom Description
CaptionsCallFeature API pour la fonction d'appel de sous-titres
CommunicationCaptions API pour les légendes de communication
StartCaptionOptions Options de sous-titre comme la langue parlée
CommunicationCaptionsListener Écouteur pour CommunicationCaptions addOnCaptionsReceivedListener
CommunicationCaptionsReceivedEvent Objet de données reçu pour chaque événement CommunicationCaptionsListener

Obtenir la fonctionnalité des sous-titres

Vous devez obtenir et effectuer un cast de l’objet des sous-titres pour utiliser des fonctionnalités spécifiques des sous-titres.

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
        }
    }));

S’abonner aux écouteurs

Ajouter un écouteur pour recevoir d’état activée ou désactivé de sous-titres

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

Ajouter un écouteur pour recevoir les légendes dont le type a été modifié

Cet événement est déclenché lorsque le type de légende passe de CommunicationCaptions à TeamsCaptions l’invitation d’utilisateurs Microsoft 365 aux appels ACS uniquement.

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

Ajouter un écouteur pour des données de sous-titres reçues

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); 
}

Ajouter un écouteur pour recevoir l’état modifié actif de la langue parlée

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

Démarrer les sous-titres

Une fois tous vos écouteurs configurés, vous pouvez désormais ajouter vos sous-titres.

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

Arrêter des sous-titres

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

Supprimer la légende reçue par l'auditeur

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

Prise en charge de la langue parlée

Obtenir une liste des langues parlées prises en charge

Obtenez une liste des langues parlées prises en charge que vos utilisateurs peuvent sélectionner quand ils activent les sous-titres.

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

Définir une langue parlée

Lorsque l'utilisateur sélectionne la langue parlée, votre application peut définir la langue parlée à partir de laquelle elle s'attend à ce que les sous-titres soient générés.

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

Nettoyage

Apprenez-en davantage sur le nettoyage des ressources.

Prérequis

Remarque

Veuillez noter que vous devez avoir une application d’appel vocal utilisant des Kits de développement logiciel (SDK) d’appel Azure Communication Services pour accéder à la fonctionnalité des sous-titres décrite dans ce guide.

Modèles

Nom Description
CaptionsCallFeature API pour la fonction d'appel de sous-titres
CommunicationCaptions API pour les légendes de communication
StartCaptionOptions Options de sous-titre comme la langue parlée
CommunicationCaptionsDelegate Délégué pour les légendes de communication
CommunicationCaptionsReceivedEventArgs Objet de données reçu pour chaque événement de réception de légendes de communication

Obtenir la fonctionnalité des sous-titres

Vous devez obtenir et effectuer un cast de l’objet des sous-titres pour utiliser des fonctionnalités spécifiques des sous-titres.

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
            }
        }
    }
}

S’abonner aux écouteurs

Ajouter un auditeur pour recevoir les sous-titres activés ou désactivés, le type, la langue parlée, le changement d'état de la langue des sous-titres et les données reçues

L’événement didChangeActiveCaptionsType est déclenché lorsque le type de légende passe de CommunicationCaptions à TeamsCaptions l’invitation d’utilisateurs Microsoft 365 aux appels ACS uniquement.

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

Démarrer les sous-titres

Une fois tous vos écouteurs configurés, vous pouvez désormais ajouter vos sous-titres.

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 {
            
        }
    })
}

Arrêter des sous-titres

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

Supprimer la légende reçue par l'auditeur

communicationCaptions?.delegate = nil

Prise en charge de la langue parlée

Obtenir une liste des langues parlées prises en charge

Obtenez une liste des langues parlées prises en charge que vos utilisateurs peuvent sélectionner quand ils activent les sous-titres.

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

Définir une langue parlée

Lorsque l'utilisateur sélectionne la langue parlée, votre application peut définir la langue parlée à partir de laquelle elle s'attend à ce que les sous-titres soient générés.

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

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

Nettoyage

Apprenez-en davantage sur le nettoyage des ressources.

Nettoyer les ressources

Si vous voulez nettoyer et supprimer un abonnement Communication Services, vous pouvez supprimer la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées. Apprenez-en davantage sur le nettoyage des ressources.

Étapes suivantes

Pour plus d’informations, consultez les articles suivants :