Tutorial de reconhecimento de fala em Python: do arquivo de áudio à transcrição

Antes, adicionar recursos de reconhecimento de voz a um app em Python era complicado. Os desenvolvedores Python precisavam programar todo o processo de transcrição, incluindo pré-processamento de áudio, extração de recursos e integração de modelos. Além disso, as equipes de engenharia lidavam com processamento de áudio de baixo nível, qualidade de transcrição inferior e atrasos entre as palavras faladas e as legendas ao vivo. 

Os avanços nos modelos de áudio e SDKs de reconhecimento de voz mudaram esse cenário.

Neste tutorial de reconhecimento de voz em Python, você aprenderá a integrar os modelos de áudio de Speech to Text da ElevenLabs ao seu projeto em Python para criar apps de transcrição prontos para uso comercial. 

Resumo

• Os modelos comerciais de Speech to Text oferecem recursos como diarização de locutores, timestamps por palavra e prompting de termos-chave, ausentes nos modelos básicos de reconhecimento de voz. 
• O ElevenAPI adiciona recursos de reconhecimento de voz ao seu código Python com o Scribe v2 e o Scribe v2 Realtime. 
• Os desenvolvedores podem instalar skills da ElevenLabs em uma plataforma de programação com IA para gerar código Python preciso com base na documentação oficial da API. 
• Você pode testar a API da ElevenLabs gratuitamente antes de assinar um plano pago para desenvolvimento comercial. 

O que este tutorial de reconhecimento de voz em Python aborda

Este tutorial aborda pré-requisitos, integração de API e recursos avançados de transcrição que ajudam você a criar um app Python de reconhecimento de voz para casos de uso empresariais.  

O reconhecimento de voz amadureceu nos últimos anos, especialmente porque grandes modelos de linguagem e redes neurais de aprendizado profundo mudaram a forma como desenvolvedores Python usam SDKs de transcrição. Embora muitos tutoriais mostrem como criar apps básicos de transcrição, poucos abordam os recursos necessários para um produto pronto para uso comercial.

Criamos este tutorial para preencher essa lacuna. 

Por exemplo, muitas soluções empresariais de transcrição exigem estes recursos:

• Diarização de locutores: A capacidade de identificar e separar cada locutor na transcrição.
• Timestamp: A marcação precisa de cada palavra com as horas, minutos e segundos relativos em que foi pronunciada. 
• Suporte a vários idiomas: Captura falas em idiomas diferentes em uma única gravação ou transmissão ao vivo, com baixas taxas de erro por palavra. 
• Prompting de termos-chave: Mapeamento de palavras específicas, como marcas, nomes de produtos e termos técnicos, para evitar erros de ortografia nas transcrições. 
• Transcrição de baixa latência: Resposta de fala para texto em milissegundos que viabiliza apps de transcrição em tempo real. 

Observação: Este tutorial vai além da criação de scripts pessoais simples para hobbies ou projetos pessoais. Ele não inclui a lógica de aplicação construída sobre a integração da API de Speech to Text, pois ela varia conforme cada empresa. 

Pré-requisitos para integração de reconhecimento de voz em Python 

Estruturamos este tutorial em torno do ElevenAPI, uma API de nível de produção da ElevenLabs que simplifica a interação com modelos de voz no seu código. Com o ElevenAPI, você tem acesso ao Scribe v2 e ao Scribe v2 Realtime, nossos principais modelos de voz para transcrição em lote e ao vivo. 

Em vez de acessar diretamente os modelos de Speech to Text da ElevenLabs, você envia gravações de áudio, transmissões ao vivo e argumentos por chamadas de API. Em seguida, o modelo de áudio converte os dados de áudio em texto. Ao concluir, você recebe as transcrições no código ou via webhook. 

Para começar, siga estas etapas de preparação. 

1. Crie uma conta na ElevenLabs.
2. Crie sua chave de API.
3. Grave uma conversa e faça upload para um armazenamento acessível publicamente. 

Quando estiver tudo pronto, avance para a próxima seção. 

Configurando seu ambiente 

Antes de integrar os modelos da ElevenLabs, configure seu ambiente Python para proteger sua chave de API da ElevenLabs. Como acontece com todas as chaves de API, recomendamos armazená-la como uma variável de ambiente (um segredo gerenciado) no arquivo .env. 

ELEVENLABS_API_KEY=<your_api_key_here>

Ao fazer uma chamada de API, você passa a variável de ambiente. Isso evita expor acidentalmente a chave de API ao fazer solicitações de API por uma rede pública. 

Em seguida, execute um comando Bash para instalar elevenlabs, o SDK da ElevenLabs, no seu ambiente Python. O SDK permite acessar diversos modelos de voz. Neste caso, você escolhe entre o Scribe v2 e o Scribe v2 Realtime.

pip install elevenlabs
pip install python-dotenv

Você também precisará instalar python-dotenv, que permite ao seu código Python acessar as variáveis de ambiente armazenadas no arquivo .env. 

Escrevendo seu primeiro script de transcrição 

Depois de configurar o ambiente Python, você pode transcrever o arquivo de áudio usando o ElevenLabs Scribe v2. 

O ElevenLabs Scribe v2 é um modelo de reconhecimento de voz líder do setor que permite transcrever arquivos de áudio em escala. Ele detecta fonemas com alta precisão mesmo quando a gravação contém ruído de fundo significativo. Para transcrever áudio, você envia a gravação ao modelo pela API da ElevenLabs e recupera a transcrição concluída. 

Abaixo está um trecho de código Python que converte um arquivo de áudio em uma transcrição com timestamps e diarização. 

# example.py
import os
from dotenv import load_dotenv
from io import BytesIO
import requests
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)

transcription = elevenlabs.speech_to_text.convert(
    file=audio_data,
    model_id="scribe_v2", # Model to use
    tag_audio_events=True, # Tag audio events like laughter, applause, etc.
    language_code="eng", # Language of the audio file. If set to None, the model will detect the language automatically.
    diarize=True, # Whether to annotate who is speaking
)

print(transcription)

O código carrega as bibliotecas necessárias, que fornecem as funções de que ele precisa. Também carrega as variáveis de ambiente declaradas para o ambiente do programa. 

Em seguida, ele cria um cliente da ElevenLabs usando a chave de API armazenada na variável de ambiente. Depois, baixa o arquivo de áudio e o converte em dados binários. 

Quando tiver os dados brutos de áudio, você os envia para a API da ElevenLabs junto com vários parâmetros.

• model_id indica o modelo de fala para texto que você quer usar. Como você está enviando um arquivo de áudio, o Scribe v2 é a melhor opção.
• tag_audio_events permite destacar segmentos sem fala, como risadas, passos e outros ruídos de fundo.
• language_code representa o idioma das conversas no arquivo de gravação. Quando definido como None, o modelo detectará o idioma automaticamente. 
• diarize indica se você quer que o modelo identifique e separe diferentes locutores com base em suas características vocais.

Por fim, execute o código e você verá o áudio transcrito no terminal. 

Reconhecimento de voz por streaming em Python

O exemplo acima aborda a transcrição em lote, indicada para arquivos pré-gravados. Porém, a ElevenLabs também oferece APIs que permitem criar reconhecimento de voz por streaming. Diferentemente do processamento em lote, esse modo executa o reconhecimento de voz em tempo real para gerar transcrições enquanto a conversa acontece. 

Para isso, conecte seu código Python ao modelo Scribe v2 Realtime usando a API WebSocket. 

O Scribe v2 Realtime oferece uma arquitetura voltada a streaming, com latência de transcrição inferior a 150 ms. Você pode usar o Scribe v2 Realtime para criar aplicações como agentes de reunião, ferramentas de acessibilidade e automação ativada por voz. O modelo retorna uma transcrição parcial enquanto processa o fluxo de áudio. Ele retorna a transcrição final somente quando o código confirma um segmento de áudio, de forma automática ou manual. 

Dependendo da sua fonte de áudio e do tipo de aplicação, você integra o reconhecimento de voz à API da ElevenLabs no lado do servidor ou do cliente. 

• Streaming no lado do cliente permite transmitir diretamente do microfone ou por fluxos de áudio divididos manualmente em blocos.
• Streaming no lado do servidor encaminha dados de áudio de uma URL ou fonte de áudio para o modelo de voz. 

Tanto o streaming no lado do cliente quanto no lado do servidor permitem usar um workflow assíncrono. Em vez de consultar a API continuamente, use WebSockets para processar os resultados. No código, você precisa criar handlers que recebam transcrições parciais e finalizadas. 

Indo além: diarização, timestamps e vocabulário personalizado 

Além do reconhecimento automático de fala, os modelos de Speech to Text da ElevenLabs oferecem suporte a diarização, timestamps e vocabulário personalizado. 

• Diarização: Apenas a transcrição em lote oferece suporte à diarização de locutores. Você ativa a diarização definindo o argumento diarize. No entanto, a transcrição multicanal, um modo da transcrição em lote, não oferece suporte à diarização.
• Timestamps: Ao realizar transcrição em lote, você pode escolher timestamps no nível da palavra ou do caractere. Para isso, defina o parâmetro timestamps_granularity ao usar o método convert.  
• Vocabulário personalizado: Tanto a transcrição em tempo real quanto a em lote oferecem suporte a prompting de termos-chave. Esse recurso direciona o modelo para transcrever termos-chave específicos que você inclui em uma lista. O Scribe v2 Realtime aceita até 50 termos-chave, enquanto o Scribe v2 aceita 1.000 termos-chave. 

Usando a skill da ElevenLabs em assistentes de programação com IA 

Assistentes de programação com IA aceleram o desenvolvimento. Se você usa ferramentas como Claude Code, Cursor, Codex ou ferramentas similares de programação com IA, pode adicionar skills da ElevenLabs ao ambiente de programação. 

Tudo o que você precisa fazer é executar este comando no terminal da plataforma:

 npx skills add elevenlabs/skills --skill speech-to-text 

O agente de programação com IA fará o download da skill de fala para texto do repositório da ElevenLabs no GitHub e a instalará no diretório local de skills. Isso permite gerar automaticamente código Python para reconhecimento de voz com base na documentação oficial da ElevenLabs, em vez de escrever toda a integração da API do zero. 

Depois de instalada, você pode gerar código Python de reconhecimento de voz simplesmente descrevendo de forma conversacional o que ele faz. Com base na descrição, o assistente de programação gera automaticamente código usando a skill de fala para texto, com o modelo e os parâmetros corretos.

Por exemplo, se você digitar “Crie um trecho em Python para reconhecimento de voz que transcreva com diarização e timestamps no nível da palavra” no Codex, receberá um trecho semelhante ao abaixo. 

Comece a usar o ElevenAPI para reconhecimento de voz

ElevenAPI permite acessar modelos avançados de Speech to Text para criar apps de reconhecimento de voz em Python.

Ao usar o ElevenAPI, você evita escrever código de integração do zero, o que atrasa a inovação do produto. Em vez disso, você usa SDKs que disponibilizam serviços de Speech to Text capazes de atender requisitos comerciais, como prompting de termos-chave, diarização e timestamps. 

Obtenha sua chave de API da ElevenLabs agora e explore nossa documentação oficial para entender como a API funciona. 

Perguntas frequentes