Compartilhar via

Início Rápido: adicionar legendas ocultas ao seu aplicativo de chamada

  • Artigo

Pré-requisitos

Observação

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

Modelos

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

Obter o recurso de legendas ocultas

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

Obter o objeto de legendas

Você precisa obter e converter o objeto de legendas para utilizar recursos específicos de legendas.

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

Assinar ouvintes

Adicionar um ouvinte para receber os status de ativo/inativo das legendas

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

Adicionar um ouvinte para os dados de legendas recebidos

Manipule o objeto de dados CaptionsInfo retornado.

Observação: o objeto contém uma propriedade resultType que indica se os dados são uma legenda parcial ou uma versão finalizada da legenda. ResultType Partial indica uma legenda dinâmica não editada, enquanto Final indica uma versão interpretada finalizada da frase (ou seja, inclui pontuação e capitalização).

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 alterado do idioma falado

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

Iniciando legendas

Depois de configurar todos os ouvintes, você poderá 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 a assinatura de ouvintes

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

Suporte para idioma falado

Obter uma lista dos idiomas falados com suporte

Obtenha uma lista dos idiomas falados com suporte que seus usuários podem selecionar ao habilitar as legendas ocultas. A propriedade retorna uma matriz de idiomas no formato BCP 47.

const spokenLanguages = captions.supportedSpokenLanguages;

Definir o idioma falado

Passe um valor na matriz de idiomas falados com suporte para garantir que o idioma solicitado tenha suporte. Por padrão, se a Contoso não fornecer nenhum idioma ou fornecer um idioma sem suporte, o idioma falado padrão será '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 de status alterado

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

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

Pré-requisitos

Observação

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

Modelos

Nome Descrição
CaptionsCallFeature Recurso de chamada de API para legendas
CommunicationCaptions API para legendas de comunicação
StartCaptionOptions Opções da legenda oculta, como o idioma falado
CommunicationCaptionsReceivedEventArgs Objeto de dados recebido para cada evento recebido de legendas de comunicação

Obter o recurso de legendas ocultas

Você precisa obter e converter o objeto de legendas para utilizar recursos específicos de legendas.

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

Assinar ouvintes

Adicionar um ouvinte para receber o status de legendas habilitadas/desabilitadas

communicationCaptions.CaptionsEnabledChanged += OnIsCaptionsEnabledChanged;

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

Adicionar um ouvinte para receber o tipo de legendas alterado

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

captionsCallFeature.ActiveCaptionsTypeChanged += OnIsCaptionsTypeChanged;

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

Adicionar ouvinte para os 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
}

Iniciando legendas

Depois de configurar todos os ouvintes, agora 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 o ouvinte recebido da legenda

communicationCaptions.CaptionsReceived -= OnCaptionsReceived;

Suporte para idioma falado

Obter lista de idiomas falados com suporte

Obtenha uma lista dos idiomas falados com suporte que seus usuários podem selecionar ao habilitar as 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)
    {
    }
}

Limpar

Saiba mais sobre como limpar os recursos aqui.

Pré-requisitos

Observação

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

Modelos

Nome Descrição
CaptionsCallFeature Recurso de chamada de API para legendas
CommunicationCaptions API para legendas de comunicação
StartCaptionOptions Opções da legenda oculta, como o idioma falado
CommunicationCaptionsListener Ouvinte para CommunicationCaptions addOnCaptionsReceivedListener
CommunicationCaptionsReceivedEvent Objeto de dados recebido para cada evento CommunicationCaptionsListener

Obter o recurso de legendas ocultas

Você precisa obter e converter o objeto de legendas para utilizar recursos específicos de legendas.

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

Assinar ouvintes

Adicionar um ouvinte para receber o status de legendas habilitadas/desabilitadas

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

Adicionar um ouvinte para receber o tipo de legendas alterado

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

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

Adicionar ouvinte para os 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()
    });
}

Iniciando legendas

Depois de configurar todos os ouvintes, agora 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 o ouvinte recebido da legenda

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

Suporte para idioma falado

Obter lista de idiomas falados com suporte

Obtenha uma lista dos idiomas falados com suporte que seus usuários podem selecionar ao habilitar as legendas ocultas.

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

Definir o 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) {
        }
    });
}

Limpar

Saiba mais sobre como limpar os recursos aqui.

Pré-requisitos

Observação

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

Modelos

Nome Descrição
CaptionsCallFeature Recurso de chamada de API para legendas
CommunicationCaptions API para legendas de comunicação
StartCaptionOptions Opções da legenda oculta, como o idioma falado
CommunicationCaptionsDelegate Delegar para legendas de comunicação
CommunicationCaptionsReceivedEventArgs Objeto de dados recebido para cada evento recebido de legendas de comunicação

Obter o recurso de legendas ocultas

Você precisa obter e converter o objeto de legendas para utilizar recursos específicos de legendas.

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

Assinar ouvintes

Adicione um ouvinte para receber legendas habilitadas/desabilitadas, tipo, idioma falado, status da linguagem de legenda alterado e dados recebidos

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

Iniciando legendas

Depois de configurar todos os ouvintes, agora 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 o ouvinte recebido da legenda

communicationCaptions?.delegate = nil

Suporte para idioma falado

Obter lista de idiomas falados com suporte

Obtenha uma lista dos idiomas falados com suporte que seus usuários podem selecionar ao habilitar as legendas ocultas.

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

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

Limpar

Saiba mais sobre como limpar os recursos aqui.

Limpar os recursos

Se quiser limpar e remover uma assinatura dos Serviços de Comunicação, exclua o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele. Saiba mais sobre como limpar recursos.

Próximas etapas

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