Legendas em tempo real, moderação e gravação com Python e Vonage

Ao final desta postagem no blog, você terá uma compreensão mais profunda do SDK em Python para a Video API da Vonage, além de alguns exemplos de código que poderá usar como base para criar experiências de videoconferência ricas em recursos e baseadas em navegador.

Introdução

A pandemia de 2020 acelerou a adoção da videoconferência como ferramenta padrão de comunicação. Hoje, as videoconferências pela web fazem parte do dia a dia de empresas, educadores e consumidores. Os desenvolvedores podem usar a Video API da Vonage e SDK do Python para criar aplicativos de videoconferência seguros e em tempo real, com recursos de moderação, transcrição e gravação.

Com o passar do tempo, a tecnologia evoluiu significativamente, assim como as exigências impostas a ela. Soluções que antes pareciam de ponta são agora consideradas recursos básicos. Espera-se que as plataformas modernas de videoconferência ofereçam áudio e vídeo de alta qualidade, conectividade confiável e comunicação de baixa latência.

Esta postagem do blog aborda o SDK em Python para a Video API da Vonage e demonstra como integrar recursos de moderação e arquivamento em um aplicativo de videoconferência. Cada um dos recursos abordados é demonstrado em um aplicativo de exemplo que acompanha este artigo. Se você ainda não conhece a Video API, talvez seja melhor começar com este tutorial sobre como criar um aplicativo de videoconferência. Se quiser pular direto para o código, você pode colocar o aplicativo de exemplo em funcionamento seguindo o README no repositório.

Mais especificamente, esta postagem do blog aborda:

• Legendas em tempo real

• Silenciar participantes

• Excluindo participantes

• Sessões de gravação

• Visualização de sessões gravadas

Integrate live interactive video directly into your web, mobile, and desktop applications with the Vonage global video platform.

Entendendo o Flask e o tunelamento

The example application presented in this blog post relies on technical concepts and external tools not associated with Vonage that may be useful in other areas of software development.

O que é um aplicativo Flask em Python?

O aplicativo de exemplo desta postagem do blog utiliza o Flask, um framework web leve, porém poderoso, para Python. Como framework, ele permite que os desenvolvedores criem rapidamente um aplicativo web. Nós o escolhemos para este tutorial devido à sua facilidade de uso e abordagem minimalista. Ao contrário de outros frameworks de desenvolvimento web em Python, ele nos oferece apenas o essencial de que precisamos para criar uma solução simples de videoconferência.

O que é o tunelamento?

Como o aplicativo de exemplo é executado localmente, ele não está acessível pela internet pública. Se o seu aplicativo local não estiver acessível publicamente, os participantes remotos não poderão se conectar à sessão de vídeo. É aí que entra o tunelamento. O tunelamento expõe servidores locais à internet pública por meio de URLs públicas temporárias ou estáticas. O ngrok é uma plataforma de software que oferece esse serviço. Você pode saber mais sobre o ngrok em nossa postagem do blog sobre o assunto.

Concepts básicos da Video API

Os usuários finais esperam videochamadas fluidas e ininterruptas, com desempenho impecável. No entanto, alcançar esse nível de confiabilidade envolve uma complexidade considerável nos bastidores.

A comunicação por vídeo em tempo real apresenta vários desafios técnicos. Os usuários se conectam por meio de diversos tipos de hardware, operam em diferentes infraestruturas de conectividade e estão espalhados por várias regiões geográficas. Além disso, as condições da rede variam durante as sessões ativas: um smartphone pode alternar da conexão Wi-Fi para dados móveis, protocolos de segurança corporativos podem restringir determinado tráfego do Protocolo de Datagrama do Usuário (UDP) ou um computador mais antigo pode apresentar gargalos de processamento.

A Video API da Vonage permite que os desenvolvedores integrem vídeo em tempo real de alta qualidade, mensagens instantâneas, compartilhamento de tela e recursos relacionados em aplicativos web e móveis. Para oferecer essa funcionalidade, a Video API utiliza WebRTC como base para a transmissão de fluxos de áudio e vídeo. Os Concepts a seguir são importantes ao trabalhar com a Video API:

• Sessão: Uma sessão é um grupo lógico de conexões e fluxos. As conexões dentro da mesma sessão podem trocar mensagens. Uma sessão funciona como uma sala virtual onde os participantes se comunicam.

• Conexão: Um ponto de extremidade que participa de uma sessão e é capaz de enviar e receber mensagens. Uma conexão pode estar conectada e, portanto, capaz de receber mensagens, ou desconectada e, portanto, incapaz de receber mensagens.

• Fluxo: Um fluxo de mídia circula entre duas conexões. Isso se refere aos bytes reais que contêm a mídia que está sendo trocada. A mídia pode consistir apenas em áudio ou em áudio e Video. Você também pode criar fluxos de compartilhamento de tela e fluxos personalizados.

• Token: A plataforma da Video API usa tokens para autorização, então você não precisa se preocupar em criar usuários na plataforma. Neste aplicativo de exemplo, usamos tokens para criar participantes de sessões de vídeo dinamicamente.

• Editor: Refere-se ao cliente que publica um fluxo de mídia.

• Assinante: Um cliente que recebe transmissões de mídia.

• Sinalização: Refere-se ao envio de texto e dados entre clientes conectados a uma sessão na forma de mensagens. Essas mensagens permitem que os desenvolvedores criem um chat de texto básico, enviem instruções de um cliente para outro e criem outras experiências valiosas.

Para se aprofundar nesses termos e Concepts-chave, confira o Glossário da Video API ou consulte a documentação da Video API. Você também pode conferir nossa introdução à Video API no YouTube:

Qual é a diferença entre um Client SDK e um SDK do lado do servidor?

A plataforma de Video API permite incorporar vídeos interativos em tempo real e de alta qualidade, mensagens, compartilhamento de tela e muito mais em aplicativos da web e móveis. A plataforma inclui bibliotecas de cliente para a web, dispositivos móveis e computadores, bem como SDKs do lado do servidor.

O que é um SDK?

SDK significa “kit de desenvolvimento de software”. Um SDK é um pacote de ferramentas instalável, projetado para facilitar aos desenvolvedores a implementação de uma determinada plataforma ou tecnologia. O SDK em Python para a Video API facilita aos desenvolvedores de Python a integração do Vonage em seus aplicativos, pois traduz a API em padrões e estruturas específicos da linguagem. 

Tanto os SDKs do lado do cliente quanto os do lado do servidor oferecem esse tipo de ferramenta. A diferença está na localização deles dentro da arquitetura de uma aplicação. Os SDKs do lado do cliente ajudam os desenvolvedores a criar interfaces de usuário, experiências interativas e recursos de comunicação em tempo real. Por isso, os SDKs do lado do cliente são normalmente escritos em JavaScript e suas estruturas e bibliotecas, bem como para sistemas operacionais móveis e de desktop.

Por outro lado, um SDK do lado do servidor oferece ferramentas para o desenvolvimento do back-end. Essa é a parte de um aplicativo responsável por lidar com solicitações, processar dados, lógica de negócios adicional, segurança e autenticação. Como o nome indica, os SDKs do lado do servidor ajudam os desenvolvedores a escrever software que será implantado em um servidor (normalmente na nuvem) e, portanto, são geralmente escritos em Python, Java, Node.js ou PHP.

A tabela a seguir apresenta um resumo das diferenças entre os SDKs do lado do cliente e do lado do servidor:

Nesta postagem do blog, abordaremos o SDK em Python para a Video API da Vonage. Trata-se de um SDK do lado do servidor que permite criar e moderar sessões, gerar tokens e trabalhar com arquivamento. Você pode ler mais sobre como as Video APIs do lado do cliente e do lado do servidor interagem em nossa documentação.

Criação de um aplicativo de videoconferência com o SDK do Python

O aplicativo de exemplo apresentado nesta postagem do blog utiliza Python e Flask no back-end e JavaScript no front-end para criar e coordenar uma sessão de vídeo. O aplicativo oferece os seguintes recursos:

• Criação de uma sessão de Video

• Permitir que os apresentadores publiquem transmissões

• Permitindo que os apresentadores:

  • Ativar legendas em tempo real

  • Silenciar ou remover participantes

  • Iniciar o arquivamento da sessão

Se você quiser colocar o código em funcionamento, pode seguir as instruções do README no repositório do aplicativo de exemplo. A criação de sessões e a ativação do bate-papo em tempo real entre os participantes são abordadas em nossa postagem no blog sobre criação de um aplicativo de videoconferência.

Ativando as legendas em tempo real

As legendas em tempo real podem melhorar a experiência do usuário e o engajamento com o aplicativo. As legendas aumentam a pontuação de acessibilidade do seu aplicativo. As normas de acessibilidade em algumas regiões podem exigir suporte a legendas. As legendas podem facilitar a compreensão em ambientes barulhentos ou não controlados, melhorando a experiência geral do usuário.

Você pode usar a API Live Captions para transcrever fluxos de áudio e gerar legendas em tempo real para seu aplicativo. A API de legendas em tempo real para Video utiliza um serviço de transcrição para fornecer legendas em tempo real aos participantes de uma sessão.

Observação: O Live Captions é um produto cobrado por uso. A cobrança é baseada no número de fluxos de áudio dos participantes (ou IDs de fluxo) enviados ao serviço de transcrição. Para obter mais informações, consulte a página de preços da API do Live Captions.

Para usar as Legendas em Tempo Real, sua sessão deve ser criada com a opção “Media Router” e, para ativar as legendas, o participante precisa de um token com a função de “Moderador”.

No SDK do Python, essas opções são tratadas com SessionOptions e TokenOptions , respectivamente:

session_options = SessionOptions(media_mode=MediaMode.ROUTED)
video_session = vonage_client.video.create_session(options=session_options)

if presenter:
    token_options = TokenOptions(session_id=session_id, role=TokenRole.MODERATOR)
else:
    token_options = TokenOptions(session_id=session_id, role=TokenRole.PUBLISHER)
    
token = vonage_client.video.generate_client_token(token_options).decode("utf-8")

No código de exemplo, concedemos presenters a capacidade de ativar legendas por meio da geração de um token com a MODERATOR função.

Para saber mais sobre tokens, funções dos tokens e os recursos de cada função, consulte a documentação. 

Os endpoints a seguir são os que usamos para nos comunicarmos com o backend e enviar uma solicitação à API do Live Captions. O endpoint para iniciar as legendas usa um ID de sessão e um token para criar um CaptionsOption objeto que é então passado para a start_options função. A função retorna um CaptionsData objeto. 

@app.route("/captions/start", methods=["POST"])
def start_captions():
    """Endpoint to start captions"""
    data = request.get_json()
    print(f"Start captions request data: ==> {data}")
    session_id = data.get("sessionId")
    token_id = data.get("token")

    if not session.get("is_presenter"):
        return jsonify({"error": "Unauthorized"}), 403

    if not session_id or not token_id:
        return jsonify({"error": "sessionId or token is missing"}), 400

    options = CaptionsOptions(
        session_id=session_id,
        token=token_id,
    )

    captions: CaptionsData = vonage_client.video.start_captions(options)

    return jsonify({"caption_id": captions.captions_id})

O ID das legendas é enviado ao front-end e usado para exibir o áudio transcrito na interface do usuário. No aplicativo de exemplo, as legendas aparecerão abaixo do Video. Observe que pode demorar um pouco até que as legendas comecem a aparecer.

Para saber mais sobre a API do Live Captions e ver exemplos de código para implementação no front-end, consulte a documentação.

Moderação da sessão: silenciar e remover participantes

Os moderadores podem precisar controlar o áudio dos participantes ou o acesso à sessão para melhorar a experiência geral da reunião. Por exemplo, um participante pode esquecer de silenciar o microfone, o que resulta em distrações sonoras indesejadas durante a sessão; em casos extremos de moderação, pode ser necessário remover um participante da sessão à força.  Um participante com privilégios da função de moderador tem acesso a ambas as funções por meio da Video API.

Silenciar um participante

No aplicativo de exemplo, definimos um endpoint de silenciamento que faz uma chamada à API. Para que a chamada seja bem-sucedida, a API exige um ID de sessão e um ID de fluxo. 

@app.route("/mute-stream", methods=["POST"])
def mute_stream():
    data = request.json
    session_id = data.get("sessionId")
    stream_id = data.get("streamId")

    vonage_client.video.mute_stream(session_id, stream_id)
    return jsonify({"message": f"Stream {stream_id} muted successfully."}), 200

Além disso, os participantes com a função de moderador podem silenciar todas as transmissões em uma sessão e desativar o silenciamento em todas as transmissões. A implementação dessas funções está além do escopo desta postagem do blog, mas você pode encontrar exemplos de código na documentação sobre como silenciar participantes.

Ao trabalhar com os pontos finais de silenciamento, é importante lembrar alguns pontos:

• Não existe uma API para desativar o mudo um único participante. Isso ocorre porque, em um cenário típico de sessão de Video, os participantes acabariam ativando o som por conta própria quando precisassem falar.

• Ao usar mute_all_streams silencia todas as transmissões atuais, bem como todos os fluxos futuros publicados em uma sessão. Essa função também aceita uma lista de IDs de fluxos para excluir do silenciamento forçado.

• Quando uma transmissão é silenciada como resultado de mute_stream ou mute_all_streams, o Publisher objeto dispara um muteForced evento em cada cliente que esteja publicando um stream silenciado. 

• A execução disable_mute_all_streams removerá o silenciamento forçado dos novas transmissões publicadas – as transmissões existentes permanecerão silenciadas.

Excluindo um participante

É possível remover um participante chamando a disconnect_client API. No aplicativo de exemplo, definimos um /remove-participant ponto de extremidade que chama essa API. A API requer um ID de sessão e um ID de conexão para que a operação seja bem-sucedida.

@app.route("/remove-participant", methods=["POST"])
def remove_participant():
    data = request.json
    session_id = data.get("sessionId")
    connection_id = data.get("connection_id")

    vonage_client.video.disconnect_client(session_id, connection_id)
    return (
        jsonify({"message": f"Participant {connection_id} removed successfully."}),
        200,
    )

Arquivamento de sessões

Pode haver ocasiões em que você queira gravar uma sessão de Video para visualização ou processamento posterior. Você pode fazer isso com os archive métodos do SDK, que incluem as seguintes funcionalidades: 

• Iniciando uma gravação de arquivo

• Interromper uma gravação em arquivo

• Listagem de gravações de arquivo

• Recuperação de informações sobre gravações arquivadas

• Excluindo um arquivo

Nesta postagem do blog e no aplicativo de exemplo que a acompanha, vamos nos concentrar em iniciar, interromper e recuperar uma gravação arquivada.

Para utilizar os métodos de arquivamento, é necessário criar uma sessão no Modo de Mídia Enrutada. Só é possível criar um arquivo para sessões que tenham pelo menos um cliente conectado.

No aplicativo de exemplo, definimos o seguinte endpoint, que cria um CreateArchiveRequest objeto para capturar as configurações do arquivo e, em seguida, o passa para a start_archive função:

@app.route("/archive/start", methods=["POST"])
def start_archive():
    """Endpoint to start archiving"""
    data = request.get_json()
    session_id = data.get("sessionId")

    if not session_id:
        return jsonify({"error": "sessionId is required"}), 400
    if not session.get("is_presenter"):
        return jsonify({"error": "Unauthorized"}), 403

    archive_options = CreateArchiveRequest(session_id=session_id)
    archive: Archive = vonage_client.video.start_archive(archive_options)

    archive_id = archive.id

    return jsonify({"archive_id": archive_id, "status": archive.status})

Usando o ID do arquivo resultante, podemos então definir um ponto final para interromper a gravação do arquivo:

@app.route("/archive/<archive_id>/stop", methods=["POST"])
def stop_archive(archive_id):
    """Endpoint to stop archiving"""

    if not archive_id:
        return jsonify({"error": "archiveId is required"}), 400

    archive: Archive = vonage_client.video.stop_archive(archive_id)
    return jsonify({"archive_id": archive.id, "status": archive.status})

Quando você interrompe a gravação de um arquivo, a plataforma de vídeo da Vonage cria um arquivo MP4 ou — no caso de arquivos de transmissões individuais — um arquivo ZIP. Assim que o arquivo estiver pronto, seu status muda para available, e o get_archive método retorna a URL do arquivo. Esse método é usado em conjunto com a consulta no front-end do aplicativo de exemplo para definir um endpoint que exibe um link para o arquivo.

@app.get("/archive/<archive_id>/status")
def archive_status(archive_id):
    """Endpoint to check status of archive"""
    try:
        archive = vonage_client.video.get_archive(archive_id)
        return jsonify(
            {
                "status": archive.status,
                "url": archive.url,
            }
        )
    except Exception as e:
        return jsonify({"error": str(e)}), 500

Este código de exemplo demonstra apenas os conceitos básicos da gravação em arquivo com a Video API. Para saber mais sobre as possibilidades do arquivamento de vídeo, consulte a documentação.

Em resumo

O SDK em Python da Video API da Vonage facilita a criação de aplicativos de vídeo em tempo real com recursos avançados de moderação e arquivamento. Neste aplicativo de exemplo, exploramos como criar sessões, gerenciar permissões dos participantes, ativar legendas ao vivo, moderar participantes e gravar sessões de vídeo para reprodução posterior.

Esses recursos são essenciais para experiências modernas de videoconferência, especialmente em Applications que exigem acessibilidade, controles de moderação ou persistência de sessão. Ao combinar o SDK do Python com o Flask e a plataforma Video API, os desenvolvedores podem criar protótipos e implantar rapidamente fluxos de trabalho confiáveis de comunicação em tempo real.

Ao combinar um backend simples do Flask com um frontend baseado em JavaScript, você tem um modelo para um aplicativo de videoconferência funcional. É possível ampliar essa base com recursos mais avançados, como controles de moderação, gravação, compartilhamento de tela ou UI/UX aprimoradas, para se adequar ao seu caso de uso. Para uma iteração mais rápida, o Vonage Video API Playground facilita testar diferentes recursos diretamente no seu navegador!

Leituras complementares e recursos

• Melhores práticas para começar a usar o Vonage Video: Práticas recomendadas para integrar a Video API do Vonage às suas aplicações.

• Arquivamento de vídeos com a Video API da Vonage e o React: Conheça quatro modos de arquivamento de vídeo com a Video API da Vonage – incluindo o Experience Composer.

• Introdução à API Vonage Live Captions no Node.js: Aprenda a adicionar legendas em tempo real às suas chamadas de vídeo da Vonage usando a API Live Captions com o Node.js e um front-end simples.