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

Adicionar recursos de reconhecimento de fala a um app em Python costumava ser trabalhoso. 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 fala mudaram isso.

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

Resumo

• Modelos comerciais de Speech to Text oferecem recursos como diarização de locutores, timestamps por palavra e prompting de termos-chave, que modelos básicos de reconhecimento de fala não têm. 
• A ElevenAPI adiciona recursos de reconhecimento de fala ao seu código Python com Scribe v2 e Scribe v2 Realtime. 
• 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 experimentar a API da ElevenLabs gratuitamente antes de assinar um plano pago para desenvolvimento comercial. 

O que este tutorial de reconhecimento de fala 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 fala para casos de uso empresariais.  

O reconhecimento de fala evoluiu nos últimos anos, especialmente porque grandes modelos de linguagem e redes neurais de deep learning 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 falada. 
• Suporte a vários idiomas: Captura falas em diferentes idiomas em uma única gravação ou transmissão ao vivo, com baixas taxas de erro por palavra. 
• Prompting de termos-chave: Mapeamento de palavras especiais, como marcas, nomes de produtos e termos técnicos, para evitar erros de grafia 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 hobby 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 de acordo com cada empresa. 

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

Estruturamos este tutorial em torno da ElevenAPI, uma API da ElevenLabs pronta para produção que simplifica a interação com modelos de voz no seu código. Com a 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 final, você recebe as transcrições no código ou por webhook. 

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

1. Cadastre-se na ElevenLabs.
2. Crie sua chave de API.
3. Grave uma conversa e envie-a para um armazenamento acessível publicamente. 

Quando estiver tudo pronto, siga 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 vários modelos de voz. Neste caso, você escolhe entre Scribe v2 e 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 fala líder do setor que permite transcrever arquivos de áudio em escala. Ele detecta fonemas com alta precisão mesmo quando a gravação de áudio contém ruído de fundo significativo. Para transcrever o á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 que você declarou no 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. 

Depois de obter os dados brutos de áudio, você os envia à 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 nas características de suas vozes.

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

Reconhecimento de fala por streaming em Python

O exemplo acima aborda a transcrição em lote, adequada para arquivos pré-gravados. No entanto, a ElevenLabs também oferece APIs que permitem criar reconhecimento de fala por streaming. Diferentemente do processamento em lote, esse modo executa o reconhecimento de fala 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 focada em streaming, com latência de transcrição inferior a 150 ms. Você usa o Scribe v2 Realtime para criar aplicações como agentes de reuniões, 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 apenas quando o código confirma um segmento de áudio, automaticamente ou manualmente. 

Dependendo da fonte de áudio e do tipo de aplicação, você integra o reconhecimento de fala à 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 segmentados manualmente.
• Streaming no lado do servidor direciona 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 seu 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 uma transcrição em lote, você pode escolher timestamps por palavra ou 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 incluídos em uma lista. O Scribe v2 Realtime oferece suporte a até 50 termos-chave, enquanto o Scribe v2 oferece suporte a 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 de programação com IA semelhantes, pode adicionar skills da ElevenLabs ao ambiente de programação. 

Basta executar este comando no terminal da sua 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 fala com base na documentação oficial da ElevenLabs, em vez de escrever toda a integração de API do zero. 

Depois de instalada, você pode gerar código Python para reconhecimento de fala apenas descrevendo, em linguagem natural, o que ele deve fazer. 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 fala que transcreva com diarização e timestamps por palavra” no Codex, receberá um trecho semelhante ao abaixo. 

Comece a usar a ElevenAPI para reconhecimento de fala

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

Ao usar a 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 que atendem a requisitos de nível comercial, 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