Condividi tramite

Guida introduttiva: Aggiungere sottotitoli all'app chiamante

  • Articolo

Prerequisiti

Nota

Si noti che è necessario disporre di un'app per chiamate vocali usando Servizi di comunicazione di Azure gli SDK per chiamare gli SDK per accedere alla funzionalità dei sottotitoli chiusi descritta in questa guida.

Modelli

Nome Descrizione
CaptionsCallFeature API per didascalie
CaptionsCommon Classe di base per le didascalie
StartCaptionOptions Opzioni di sottotitoli come la lingua parlata
CaptionsHandler Definizione di callback per la gestione dell'evento CaptionsReceivedEventType
CaptionsInfo Struttura dei dati ricevuta per ogni evento CaptionsReceivedEventType

Funzionalità Get closed captions (Ottieni sottotitoli)

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

Ottenere l'oggetto captions

È necessario ottenere ed eseguire il cast dell'oggetto Captions per utilizzare funzionalità specifiche di Captions.

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

Sottoscrivere listener

Aggiungere un listener per ricevere i sottotitoli attivi/inattivi

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

Aggiungere un listener per i dati dei sottotitoli ricevuti

Gestire l'oggetto dati CaptionsInfo restituito.

Nota: l'oggetto contiene una proprietà resultType che indica se i dati sono una didascalia parziale o una versione finale della didascalia. ResultType Partial indica la didascalia non modificata dal vivo, mentre Final indica una versione interpretata finalizzata della frase (ad esempio include punteggiatura e maiuscola).

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

Aggiungere un listener per ricevere lo stato della lingua parlata modificata

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

Avviare le didascalie

Dopo aver configurato tutti i listener, è ora possibile iniziare ad aggiungere didascalie.

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

Interrompi didascalie

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

Annullare la sottoscrizione ai listener

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

Supporto per la lingua parlata

Ottenere un elenco delle lingue parlate supportate

Ottenere un elenco delle lingue parlate supportate che gli utenti possono selezionare quando si abilitano i sottotitoli chiusi. La proprietà restituisce una matrice di lingue in formato bcp 47.

const spokenLanguages = captions.supportedSpokenLanguages;

Impostare la lingua parlata

Passare un valore dalla matrice di lingue parlate supportate per assicurarsi che la lingua richiesta sia supportata. Per impostazione predefinita, se contoso non fornisce alcuna lingua o una lingua non supportata, per impostazione predefinita la lingua parlata è "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 */
}

Aggiungere un listener per ricevere il tipo di didascalie modificato stato

Il tipo di sottotitoli può cambiare da Captions a TeamsCaptions se un utente teams/CTE partecipa alla chiamata o se la chiamata cambia in un tipo di chiamata di interoperabilità. Per continuare l'esperienza Captions, è necessaria la reinscrizione ai listener Didascalie di Teams. Il tipo TeamsCaptions non può essere modificato o modificato di nuovo in Tipo sottotitoli in una chiamata quando TeamsCaptions viene utilizzato nella chiamata.

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

Prerequisiti

Nota

Si noti che è necessario disporre di un'app per chiamate vocali usando Servizi di comunicazione di Azure gli SDK per chiamare gli SDK per accedere alla funzionalità dei sottotitoli chiusi descritta in questa guida.

Modelli

Nome Descrizione
CaptionsCallFeature API per la funzionalità di chiamata delle didascalie
CommunicationCaptions API per le didascalie di comunicazione
StartCaptionOptions Opzioni di sottotitoli come la lingua parlata
CommunicationCaptionsReceivedEventArgs Oggetto dati ricevuto per ogni evento ricevuto da didascalie di comunicazione

Funzionalità Get closed captions (Ottieni sottotitoli)

È necessario ottenere ed eseguire il cast dell'oggetto Captions per utilizzare funzionalità specifiche di Captions.

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

Sottoscrivere listener

Aggiungere un listener per ricevere sottotitoli abilitati/disabilitati

communicationCaptions.CaptionsEnabledChanged += OnIsCaptionsEnabledChanged;

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

Aggiungere un listener per ricevere il tipo di sottotitoli modificati

Questo evento verrà attivato quando il tipo di didascalia cambia da CommunicationCaptions a TeamsCaptions quando si invitano gli utenti di Microsoft 365 alle chiamate solo ACS.

captionsCallFeature.ActiveCaptionsTypeChanged += OnIsCaptionsTypeChanged;

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

Aggiungere il listener per i dati dei sottotitoli ricevuti

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
}

Aggiungere un listener per ricevere lo stato attivo della lingua parlata modificata

communicationCaptions.ActiveSpokenLanguageChanged += OnIsActiveSpokenLanguageChanged;

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

Avviare le didascalie

Dopo aver configurato tutti i listener, è ora possibile iniziare ad aggiungere didascalie.


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

Interrompi didascalie

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

Rimuovere il listener ricevuto dalla didascalia

communicationCaptions.CaptionsReceived -= OnCaptionsReceived;

Supporto per la lingua parlata

Ottenere l'elenco delle lingue parlate supportate

Ottenere un elenco delle lingue parlate supportate che gli utenti possono selezionare quando si abilitano i sottotitoli chiusi.

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

Eseguire la pulizia

Altre informazioni sulla pulizia delle risorse sono disponibili qui.

Prerequisiti

Nota

Si noti che è necessario disporre di un'app per chiamate vocali usando Servizi di comunicazione di Azure gli SDK per chiamare gli SDK per accedere alla funzionalità dei sottotitoli chiusi descritta in questa guida.

Modelli

Nome Descrizione
CaptionsCallFeature API per la funzionalità di chiamata delle didascalie
CommunicationCaptions API per le didascalie di comunicazione
StartCaptionOptions Opzioni di sottotitoli come la lingua parlata
CommunicationCaptionsListener Listener per CommunicationCaptions addOnCaptionsReceivedListener
CommunicationCaptionsReceivedEvent Oggetto dati ricevuto per ogni evento CommunicationCaptionsListener

Funzionalità Get closed captions (Ottieni sottotitoli)

È necessario ottenere ed eseguire il cast dell'oggetto Captions per utilizzare funzionalità specifiche di Captions.

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

Sottoscrivere listener

Aggiungere un listener per ricevere sottotitoli abilitati/disabilitati

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

Aggiungere un listener per ricevere il tipo di sottotitoli modificati

Questo evento verrà attivato quando il tipo di didascalia cambia da CommunicationCaptions a TeamsCaptions quando si invitano gli utenti di Microsoft 365 alle chiamate solo ACS.

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

Aggiungere il listener per i dati dei sottotitoli ricevuti

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

Aggiungere un listener per ricevere lo stato attivo della lingua parlata modificata

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

Avviare le didascalie

Dopo aver configurato tutti i listener, è ora possibile iniziare ad aggiungere didascalie.

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

Interrompi didascalie

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

Rimuovere il listener ricevuto dalla didascalia

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

Supporto per la lingua parlata

Ottenere l'elenco delle lingue parlate supportate

Ottenere un elenco delle lingue parlate supportate che gli utenti possono selezionare quando si abilitano i sottotitoli chiusi.

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

Impostare la lingua parlata

Quando l'utente seleziona la lingua parlata, l'app può impostare la lingua parlata da cui prevede la generazione di didascalie.

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

Eseguire la pulizia

Altre informazioni sulla pulizia delle risorse sono disponibili qui.

Prerequisiti

Nota

Si noti che è necessario disporre di un'app per chiamate vocali usando Servizi di comunicazione di Azure gli SDK per chiamare gli SDK per accedere alla funzionalità dei sottotitoli chiusi descritta in questa guida.

Modelli

Nome Descrizione
CaptionsCallFeature API per la funzionalità di chiamata delle didascalie
CommunicationCaptions API per le didascalie di comunicazione
StartCaptionOptions Opzioni di sottotitoli come la lingua parlata
CommunicationCaptionsDelegate Delega per i sottotitoli di comunicazione
CommunicationCaptionsReceivedEventArgs Oggetto dati ricevuto per ogni evento ricevuto da didascalie di comunicazione

Funzionalità Get closed captions (Ottieni sottotitoli)

È necessario ottenere ed eseguire il cast dell'oggetto Captions per utilizzare funzionalità specifiche di Captions.

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

Sottoscrivere listener

Aggiungere un listener per ricevere sottotitoli abilitati/disabilitati, tipo, lingua parlata, stato della lingua della didascalia modificata e dati ricevuti

L'evento didChangeActiveCaptionsType verrà attivato quando il tipo di didascalia cambia da CommunicationCaptions a TeamsCaptions quando si invitano gli utenti di Microsoft 365 alle chiamate solo ACS.

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

Avviare le didascalie

Dopo aver configurato tutti i listener, è ora possibile iniziare ad aggiungere didascalie.

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

Interrompi didascalie

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

Rimuovere il listener ricevuto dalla didascalia

communicationCaptions?.delegate = nil

Supporto per la lingua parlata

Ottenere l'elenco delle lingue parlate supportate

Ottenere un elenco delle lingue parlate supportate che gli utenti possono selezionare quando si abilitano i sottotitoli chiusi.

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

Impostare la lingua parlata

Quando l'utente seleziona la lingua parlata, l'app può impostare la lingua parlata da cui prevede la generazione di didascalie.

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

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

Eseguire la pulizia

Altre informazioni sulla pulizia delle risorse sono disponibili qui.

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di comunicazione, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate. Altre informazioni sulla pulizia delle risorse.

Passaggi successivi

Per altre informazioni, vedere gli articoli seguenti: