Compartir a través de

Inicio rápido: Incorporación de subtítulos a una aplicación de llamadas

  • Artículo

Requisitos previos

Nota:

Tenga en cuenta que deberá tener una aplicación de llamada de voz con el uso de los SDK de llamada de Azure Communication Services para acceder a la característica de subtítulos que se describe en esta guía.

Modelos

Nombre Descripción
CaptionsCallFeature API para subtítulos
CaptionsCommon Clase base para subtítulos
StartCaptionOptions Opciones de subtítulos como idioma hablado
CaptionsHandler Definición de devolución de llamada para controlar el evento CaptionsReceivedEventType
CaptionsInfo Estructura de datos recibida para cada evento CaptionsReceivedEventType

Obtener característica de subtítulos

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

Obtener objeto de subtítulos

Debe obtener y convertir el objeto de títulos para usar características específicas de subtítulos.

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

Suscribirse a agentes de escucha

Agregar un agente de escucha para recibir el estado activo o inactivo de los subtítulos

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

Agregar un agente de escucha para los datos de subtítulos recibidos

Controle el objeto de datos CaptionsInfo devuelto.

Nota: El objeto contiene una propiedad resultType que indica si los datos son un subtítulo parcial o una versión finalizada del subtítulo. ResultType Partial indica un subtítulo sin editar activo, mientras que Final indica una versión interpretada finalizada de la oración (es decir, incluye signos de puntuación y mayú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);

Agregar un agente de escucha para recibir el estado de cambio de idioma hablado

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

Inicio de subtítulos

Una vez configurados todos los agentes de escucha, ahora puede empezar a agregar subtítulos.

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

Detener subtítulos

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

Cancelar la suscripción a los agentes de escucha

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

Compatibilidad con idiomas hablados

Obtener una lista de idiomas hablados admitidos

Obtenga una lista de los idiomas hablados admitidos entre los que los usuarios pueden seleccionar al habilitar subtítulos. La propiedad devuelve una matriz de idiomas en formato bcp 47.

const spokenLanguages = captions.supportedSpokenLanguages;

Establecer el Idioma hablado

Pase un valor desde la matriz de idiomas hablados admitidos para asegurarse de que se admite el idioma solicitado. De forma predeterminada, si contoso no proporciona ningún idioma o un idioma no admitido, el idioma hablado tiene como valor predeterminado "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 */
}

Se ha cambiado el estado de Agregar un cliente de escucha para recibir tipos de subtítulos

El tipo de títulos puede cambiar de Subtítulos a TeamsCaptions si un usuario de Teams/CTE se une a la llamada, o bien si la llamada cambia a un tipo de llamada de interoperabilidad. Es necesario volver a suscribirse a Clientes de escucha de subtítulos de Teams para continuar con la experiencia de subtítulos. El tipo TeamsCaptions no se puede cambiar ni devolver al tipo Subtítulos en una llamada una vez que TeamsCaptions se usa en la llamada.

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

Requisitos previos

Nota:

Tenga en cuenta que deberá tener una aplicación de llamada de voz con el uso de los SDK de llamada de Azure Communication Services para acceder a la característica de subtítulos que se describe en esta guía.

Modelos

Nombre Descripción
CaptionsCallFeature API para la característica de llamada de subtítulos
CommunicationCaptions API para subtítulos de comunicación
StartCaptionOptions Opciones de subtítulos como idioma hablado
CommunicationCaptionsReceivedEventArgs Objeto de datos recibido para cada evento recibido de subtítulos de comunicación

Obtener característica de subtítulos

Debe obtener y convertir el objeto de títulos para usar características específicas de subtítulos.

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

Suscribirse a agentes de escucha

Agregar un agente de escucha para recibir el estado habilitado o deshabilitado de los subtítulos

communicationCaptions.CaptionsEnabledChanged += OnIsCaptionsEnabledChanged;

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

Se ha cambiado el tipo de Agregar un agente de escucha para recibir subtítulos

Este evento se desencadenará cuando el tipo de subtítulo cambie de CommunicationCaptions a TeamsCaptions al invitar a los usuarios de Microsoft 365 a llamadas solo de ACS.

captionsCallFeature.ActiveCaptionsTypeChanged += OnIsCaptionsTypeChanged;

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

Agregar agente de escucha para los datos de subtítulos recibidos

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
}

Agregar un agente de escucha para recibir el estado de cambio de idioma hablado activo

communicationCaptions.ActiveSpokenLanguageChanged += OnIsActiveSpokenLanguageChanged;

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

Inicio de subtítulos

Una vez configurados todos los agentes de escucha, ahora puede empezar a agregar subtítulos.


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

Detener subtítulos

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

Quitar el agente de escucha recibido de subtítulos

communicationCaptions.CaptionsReceived -= OnCaptionsReceived;

Compatibilidad con idiomas hablados

Obtener lista de idiomas hablados admitidos

Obtenga una lista de los idiomas hablados admitidos entre los que los usuarios pueden seleccionar al habilitar subtítulos.

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

Limpiar

Obtenga más información sobre la limpieza de recursos en este documento.

Requisitos previos

Nota:

Tenga en cuenta que deberá tener una aplicación de llamada de voz con el uso de los SDK de llamada de Azure Communication Services para acceder a la característica de subtítulos que se describe en esta guía.

Modelos

Nombre Descripción
CaptionsCallFeature API para la característica de llamada de subtítulos
CommunicationCaptions API para subtítulos de comunicación
StartCaptionOptions Opciones de subtítulos como idioma hablado
CommunicationCaptionsListener Agente de escucha para CommunicationCaptions addOnCaptionsReceivedListener
CommunicationCaptionsReceivedEvent Objeto de datos recibido para cada evento CommunicationCaptionsListener

Obtener característica de subtítulos

Debe obtener y convertir el objeto de títulos para usar características específicas de subtítulos.

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

Suscribirse a agentes de escucha

Agregar un agente de escucha para recibir el estado habilitado o deshabilitado de los subtítulos

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

Se ha cambiado el tipo de Agregar un agente de escucha para recibir subtítulos

Este evento se desencadenará cuando el tipo de subtítulo cambie de CommunicationCaptions a TeamsCaptions al invitar a los usuarios de Microsoft 365 a llamadas solo de ACS.

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

Agregar agente de escucha para los datos de subtítulos recibidos

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

Agregar un agente de escucha para recibir el estado de cambio de idioma hablado activo

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

Inicio de subtítulos

Una vez configurados todos los agentes de escucha, ahora puede empezar a agregar subtítulos.

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

Detener subtítulos

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

Quitar el agente de escucha recibido de subtítulos

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

Compatibilidad con idiomas hablados

Obtener lista de idiomas hablados admitidos

Obtenga una lista de los idiomas hablados admitidos entre los que los usuarios pueden seleccionar al habilitar subtítulos.

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

Establecer el Idioma hablado

Cuando el usuario selecciona el idioma hablado, la aplicación puede establecer el idioma hablado en el que espera que se generen subtítulos.

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

Limpiar

Obtenga más información sobre la limpieza de recursos en este documento.

Requisitos previos

Nota:

Tenga en cuenta que deberá tener una aplicación de llamada de voz con el uso de los SDK de llamada de Azure Communication Services para acceder a la característica de subtítulos que se describe en esta guía.

Modelos

Nombre Descripción
CaptionsCallFeature API para la característica de llamada de subtítulos
CommunicationCaptions API para subtítulos de comunicación
StartCaptionOptions Opciones de subtítulos como idioma hablado
CommunicationCaptionsDelegate Delegado de subtítulos de comunicación
CommunicationCaptionsReceivedEventArgs Objeto de datos recibido para cada evento recibido de subtítulos de comunicación

Obtener característica de subtítulos

Debe obtener y convertir el objeto de títulos para usar características específicas de subtítulos.

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

Suscribirse a agentes de escucha

Agregar un agente de escucha para recibir subtítulos habilitados o deshabilitados, tipo, idioma hablado, estado del idioma del subtítulo cambiado y datos recibidos

El evento didChangeActiveCaptionsType se desencadenará cuando el tipo de subtítulo cambie de CommunicationCaptions a TeamsCaptions al invitar a los usuarios de Microsoft 365 a llamadas solo de 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

Inicio de subtítulos

Una vez configurados todos los agentes de escucha, ahora puede empezar a agregar subtítulos.

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

Detener subtítulos

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

Quitar el agente de escucha recibido de subtítulos

communicationCaptions?.delegate = nil

Compatibilidad con idiomas hablados

Obtener lista de idiomas hablados admitidos

Obtenga una lista de los idiomas hablados admitidos entre los que los usuarios pueden seleccionar al habilitar subtítulos.

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

Establecer el Idioma hablado

Cuando el usuario selecciona el idioma hablado, la aplicación puede establecer el idioma hablado en el que espera que se generen subtítulos.

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

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

Limpiar

Obtenga más información sobre la limpieza de recursos en este documento.

Limpieza de recursos

Si quiere limpiar y quitar una suscripción a Communication Services, puede eliminar el recurso o grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él. Obtenga más información sobre la limpieza de recursos.

Pasos siguientes

Para más información, consulte los siguientes artículos.