Partilhar via

Guia de início rápido: adicionar legendas ocultas ao seu aplicativo de chamadas

  • Artigo

Pré-requisitos

Nota

Observe que você precisará ter um aplicativo de chamada de voz usando SDKs de chamada dos Serviços de Comunicação do Azure para acessar o recurso de legendas ocultas descrito neste guia.

Modelos

Nome Descrição
CaptionsCallFeature API para legendas
LegendasComum Classe base para legendas
StartCaptionOptions Opções de legenda oculta, como idioma falado
CaptionsHandler Definição de retorno de chamada para manipular o evento CaptionsReceivedEventType
LegendasInfo Estrutura de dados recebida para cada evento CaptionsReceivedEventType

Obter recurso de legendas ocultas

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

Obter objeto captions

Você precisa obter e transmitir o objeto Captions para utilizar recursos específicos de Captions.

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

Inscreva-se para ouvintes

Adicionar um ouvinte para receber legendas status ativo/inativo

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

Adicionar um ouvinte para dados de legendas recebidos

Manipule o objeto de dados CaptionsInfo retornado.

Nota: O objeto contém um prop resultType que indica se os dados são uma legenda parcial ou uma versão finalizada da legenda. ResultType Partial indica legenda ao vivo não editada, enquanto Final indica uma versão interpretada finalizada da frase (ou seja, inclui pontuação e maiúsculas).

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

Adicionar um ouvinte para receber o status de idioma falado alterado

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

Legendas iniciais

Depois de configurar todos os seus ouvintes, você pode começar a adicionar legendas.

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

Parar legendas

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

Cancelar inscrição para ouvintes

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

Suporte a idiomas falados

Obter uma lista de idiomas falados suportados

Obtenha uma lista de idiomas falados suportados que seus usuários podem selecionar ao ativar legendas ocultas. A propriedade retorna uma matriz de idiomas no formato bcp 47.

const spokenLanguages = captions.supportedSpokenLanguages;

Definir idioma falado

Passe um valor da matriz de idiomas falados suportados para garantir que o idioma solicitado seja suportado. Por padrão, se a contoso não fornecer nenhum idioma ou um idioma sem suporte, o idioma falado assumirá como padrão '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 */
}

Adicionar um ouvinte para receber legendas tipo status alterado

O tipo de legendas pode mudar de Captions para TeamsCaptions se um usuário do Teams/CTE ingressar na chamada ou se a chamada mudar para um tipo de chamada de interoperabilidade. É necessária uma nova subscrição dos ouvintes do Teams Captions para continuar a experiência do Captions. O tipo TeamsCaptions não pode ser alternado ou alterado de volta para o tipo Captions em uma chamada depois que TeamsCaptions for utilizado na chamada.

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

Pré-requisitos

Nota

Observe que você precisará ter um aplicativo de chamada de voz usando SDKs de chamada dos Serviços de Comunicação do Azure para acessar o recurso de legendas ocultas descrito neste guia.

Modelos

Nome Descrição
CaptionsCallFeature API para recurso de chamada de legendas
ComunicaçãoLegendas API para legendas de comunicação
StartCaptionOptions Opções de legenda oculta, como idioma falado
ComunicaçãoCaptionsReceivedEventArgs Objeto de dados recebido para cada evento de legendas de comunicação recebidas

Obter recurso de legendas ocultas

Você precisa obter e transmitir o objeto Captions para utilizar recursos específicos de Captions.

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

Inscreva-se para ouvintes

Adicionar um ouvinte para receber legendas ativadas/desativadas

communicationCaptions.CaptionsEnabledChanged += OnIsCaptionsEnabledChanged;

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

Adicionar um ouvinte para receber legendas tipo alterado

Esse evento será acionado quando o tipo de legenda mudar de para TeamsCaptions ao convidar usuários do CommunicationCaptions Microsoft 365 para chamadas somente ACS.

captionsCallFeature.ActiveCaptionsTypeChanged += OnIsCaptionsTypeChanged;

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

Adicionar ouvinte para dados de legendas recebidos

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
}

Adicionar um ouvinte para receber o status alterado do idioma falado ativo

communicationCaptions.ActiveSpokenLanguageChanged += OnIsActiveSpokenLanguageChanged;

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

Legendas iniciais

Depois de configurar todos os ouvintes, você pode começar a adicionar legendas.


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

Parar legendas

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

Remover a legenda recebida ouvinte

communicationCaptions.CaptionsReceived -= OnCaptionsReceived;

Suporte a idiomas falados

Obter lista de idiomas falados suportados

Obtenha uma lista de idiomas falados suportados que seus usuários podem selecionar ao ativar legendas ocultas.

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

Limpeza

Saiba mais sobre a limpeza de recursos aqui.

Pré-requisitos

Nota

Observe que você precisará ter um aplicativo de chamada de voz usando SDKs de chamada dos Serviços de Comunicação do Azure para acessar o recurso de legendas ocultas descrito neste guia.

Modelos

Nome Descrição
CaptionsCallFeature API para recurso de chamada de legendas
ComunicaçãoLegendas API para legendas de comunicação
StartCaptionOptions Opções de legenda oculta, como idioma falado
ComunicaçãoLegendasOuvinte Ouvinte para CommunicationCaptions addCaptionsReceivedListener
ComunicaçãoCaptionsReceivedEvent Objeto de dados recebido para cada evento CommunicationCaptionsListener

Obter recurso de legendas ocultas

Você precisa obter e transmitir o objeto Captions para utilizar recursos específicos de 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
        }
    }));

Inscreva-se para ouvintes

Adicionar um ouvinte para receber legendas ativadas/desativadas

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

Adicionar um ouvinte para receber legendas tipo alterado

Esse evento será acionado quando o tipo de legenda mudar de para TeamsCaptions ao convidar usuários do CommunicationCaptions Microsoft 365 para chamadas somente ACS.

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

Adicionar ouvinte para dados de legendas recebidos

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

Adicionar um ouvinte para receber o status alterado do idioma falado ativo

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

Legendas iniciais

Depois de configurar todos os ouvintes, você pode começar a adicionar legendas.

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

Parar legendas

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

Remover a legenda recebida ouvinte

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

Suporte a idiomas falados

Obter lista de idiomas falados suportados

Obtenha uma lista de idiomas falados suportados que seus usuários podem selecionar ao ativar legendas ocultas.

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

Definir idioma falado

Quando o usuário seleciona o idioma falado, seu aplicativo pode definir o idioma falado a partir do qual espera que as legendas sejam geradas.

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

Limpeza

Saiba mais sobre a limpeza de recursos aqui.

Pré-requisitos

Nota

Observe que você precisará ter um aplicativo de chamada de voz usando SDKs de chamada dos Serviços de Comunicação do Azure para acessar o recurso de legendas ocultas descrito neste guia.

Modelos

Nome Descrição
CaptionsCallFeature API para recurso de chamada de legendas
ComunicaçãoLegendas API para legendas de comunicação
StartCaptionOptions Opções de legenda oculta, como idioma falado
ComunicaçãoLegendasDelegado Delegado para legendas de comunicação
ComunicaçãoCaptionsReceivedEventArgs Objeto de dados recebido para cada evento de legendas de comunicação recebidas

Obter recurso de legendas ocultas

Você precisa obter e transmitir o objeto Captions para utilizar recursos específicos de 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
            }
        }
    }
}

Inscreva-se para ouvintes

Adicionar um ouvinte para receber legendas ativadas/desativadas, tipo, idioma falado, status do idioma da legenda alterado e dados recebidos

O evento didChangeActiveCaptionsType será acionado quando o tipo de legenda mudar de para TeamsCaptions ao convidar usuários do CommunicationCaptions Microsoft 365 para chamadas somente 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

Legendas iniciais

Depois de configurar todos os ouvintes, você pode começar a adicionar legendas.

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

Parar legendas

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

Remover a legenda recebida ouvinte

communicationCaptions?.delegate = nil

Suporte a idiomas falados

Obter lista de idiomas falados suportados

Obtenha uma lista de idiomas falados suportados que seus usuários podem selecionar ao ativar legendas ocultas.

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

Definir idioma falado

Quando o usuário seleciona o idioma falado, seu aplicativo pode definir o idioma falado a partir do qual espera que as legendas sejam geradas.

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

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

Limpeza

Saiba mais sobre a limpeza de recursos aqui.

Clean up resources (Limpar recursos)

Se quiser limpar e remover uma assinatura dos Serviços de Comunicação, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele. Saiba mais sobre a limpeza de recursos.

Próximos passos

Para obter mais informações, consulte os seguintes artigos: