Capturar o Microfone com PyAudio
Nesta página
Curso atualizado a 3 de novembro de 2026 para o Voxtral 3, com base no guia Migrate from Voxtral 2 da Mistral: os modelos Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603, descontinuados a 31 de outubro de 2026 e retirados a 30 de abril de 2027) são substituídos nos exemplos porvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3evoxtral-mini-tts-3-0. Alterações principais: as marcas temporais são apenas por segmento (worddevolve um erro 400), a diarização em tempo real é suportada, as definições da sessão em tempo real ficam bloqueadas após o primeiro bloco de áudio e as entradas decontext_biassão flexíveis (frases com espaços). Fontes: Migrate from Voxtral 2 · Speech to Text.
Do Ficheiro ao Microfone
A lição anterior estabeleceu uma arquitetura onde a fonte de áudio é um gerador assíncrono simples e permutável. Vai aproveitar isso imediatamente: ao substituir o gerador de leitura de ficheiros por um que lê diretamente da sua placa de som, o seu programa começa a transcrever a sua voz em direto sem alterar uma única linha do resto do código.
A ferramenta para esta lição é o PyAudio, a biblioteca Python padrão para aceder a dispositivos de áudio. Esta biblioteca depende do PortAudio, uma camada nativa que poderá ter de instalar separadamente, dependendo do seu sistema.
Instalar o PyAudio
# Linux (Debian/Ubuntu)
sudo apt-get install portaudio19-dev
pip install pyaudio
# macOS
brew install portaudio
pip install pyaudio
# Windows
pip install pyaudio
O Gerador do Microfone
O núcleo desta lição cabe em cerca de trinta linhas. A função abre um fluxo de entrada no dispositivo predefinido, executa um ciclo infinito a ler blocos de tamanho fixo e fornece cada um deles ao motor de transcrição. O bloco finally não é decorativo: garante que o fluxo para, fecha e que o PyAudio liberta o hardware, mesmo que o programa seja interrompido abruptamente. Sem ele, o microfone pode permanecer bloqueado, impedindo o funcionamento de outras aplicações.
import asyncio
import pyaudio
async def iter_microphone(
sample_rate: int = 16000,
chunk_duration_ms: int = 480
):
"""Capturar o microfone e fornecer blocos PCM.
Args:
sample_rate: Taxa de amostragem (16000 Hz para o Voxtral)
chunk_duration_ms: Duração de cada bloco em milissegundos
Yields:
bytes: Blocos de áudio PCM mono de 16 bits
"""
p = pyaudio.PyAudio()
# Número de amostras por bloco
chunk_samples = int(sample_rate * chunk_duration_ms / 1000)
# Abrir o fluxo do microfone
stream = p.open(
format=pyaudio.paInt16, # PCM de 16 bits
channels=1, # Mono
rate=sample_rate, # 16 kHz
input=True, # Modo de captura
frames_per_buffer=chunk_samples
)
loop = asyncio.get_running_loop()
try:
print("Microfone ativo — pode falar...")
while True:
# Ler o bloco de forma não bloqueante
data = await loop.run_in_executor(
None,
stream.read,
chunk_samples,
False # exception_on_overflow
)
yield data
finally:
stream.stop_stream()
stream.close()
p.terminate()
print("Microfone fechado")
Cada parâmetro tem uma razão específica. sample_rate=16000 reflete um requisito do modelo, não uma preferência: o Voxtral espera 16 kHz, por isso não altere este valor. pyaudio.paInt16 corresponde ao formato PCM com sinal de 16 bits, exatamente equivalente ao pcm_s16le declarado no lado da API, e channels=1 impõe o mono, o que também é obrigatório. Resta chunk_duration_ms=480, a única definição verdadeiramente debatível: cada bloco representa 480 milissegundos de áudio, um bom compromisso entre capacidade de resposta e eficiência de rede. Um bloco mais curto, digamos 100 ms, melhora a capacidade de resposta, mas multiplica os pedidos de rede; um bloco mais longo poupa largura de banda, mas aumenta a latência antes de o modelo receber o áudio.
A chamada loop.run_in_executor também merece explicação. stream.read é uma função bloqueante: mantém o thread ocupado até que o número solicitado de amostras esteja disponível. Executá-la diretamente numa coroutine congelaria todo o ciclo asyncio, incluindo a receção de eventos de transcrição. Ao delegá-la para um executor, torna a leitura compatível com o resto do programa assíncrono.
O cálculo do tamanho do bloco segue mecanicamente as duas definições, para sample_rate=16000 e chunk_duration_ms=480:
chunk_samples = 16000 × 480 / 1000 = 7680 amostras
byte_size = 7680 × 2 bytes = 15360 bytes por bloco
Programa Completo: Do Microfone à Transcrição
O seguinte script combina captura e transcrição numa ferramenta de ditado pronta a usar. O novo elemento em relação ao gerador anterior é o tratamento limpo do encerramento: um manipulador de sinal interceta o Ctrl+C, altera a flag running para False, o que sai do ciclo de captura, fecha o fluxo e permite que o programa guarde o texto acumulado. Sem este mecanismo, uma interrupção de teclado mataria o processo antes da gravação e perderia o ditado.
import asyncio
import os
import signal
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
import pyaudio
# Flag para encerramento limpo
running = True
def signal_handler(sig, frame):
global running
print("\n\nA encerrar...")
running = False
signal.signal(signal.SIGINT, signal_handler)
async def iter_microphone(sample_rate=16000, chunk_duration_ms=480):
"""Capturar o microfone até ser interrompido (Ctrl+C)."""
p = pyaudio.PyAudio()
chunk_samples = int(sample_rate * chunk_duration_ms / 1000)
stream = p.open(
format=pyaudio.paInt16,
channels=1,
rate=sample_rate,
input=True,
frames_per_buffer=chunk_samples
)
loop = asyncio.get_running_loop()
try:
while running:
data = await loop.run_in_executor(
None, stream.read, chunk_samples, False
)
yield data
finally:
stream.stop_stream()
stream.close()
p.terminate()
async def main():
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
audio_format = AudioFormat(encoding="pcm_s16le", sample_rate=16000)
print("=" * 50)
print("TRANSCRIÇÃO EM DIRETO")
print("Fale para o microfone (Ctrl+C para parar)")
print("=" * 50)
print()
full_text = []
async for event in client.audio.realtime.transcribe_stream(
audio_stream=iter_microphone(),
model="voxtral-mini-transcribe-realtime-3",
audio_format=audio_format,
):
if isinstance(event, TranscriptionStreamTextDelta):
print(event.text, end="", flush=True)
full_text.append(event.text)
elif isinstance(event, TranscriptionStreamDone):
break
# Guardar
final_text = "".join(full_text)
if final_text.strip():
with open("dictee.txt", "w", encoding="utf-8") as f:
f.write(final_text)
print(f"\n\nTranscrição guardada em dictee.txt")
print(f"Tamanho: {len(final_text)} caracteres")
else:
print("\n\nNenhum texto transcrito.")
asyncio.run(main())
Execute-o, fale, pare com Ctrl+C: o texto aparece à medida que fala e acaba por ficar guardado em dictee.txt.
python dictee_vocale.py
# Fale para o seu microfone
# O texto aparece em tempo real
# Ctrl+C para parar
Experimente com cerca de trinta segundos de francês contínuo, variando o seu ritmo, e compare o que disse com o que o ficheiro contém. É a melhor forma de calibrar as suas expetativas antes de afinar a latência na próxima lição.
Escolher o Dispositivo Correto
Numa máquina com microfone integrado, auscultadores USB e uma webcam, o dispositivo predefinido nem sempre é aquele que pensa, e uma transcrição vazia deve-se geralmente a este detalhe. Primeiro, liste as entradas disponíveis com o seu índice:
def list_microphones():
"""Listar todos os dispositivos de entrada de áudio disponíveis."""
p = pyaudio.PyAudio()
print("Dispositivos de entrada disponíveis:")
for i in range(p.get_device_count()):
info = p.get_device_info_by_index(i)
if info["maxInputChannels"] > 0:
print(f" [{i}] {info['name']} "
f"(canais: {info['maxInputChannels']}, "
f"taxa: {int(info['defaultSampleRate'])} Hz)")
p.terminate()
list_microphones()
Depois, basta impor o índice escolhido ao abrir o fluxo, através do parâmetro input_device_index:
stream = p.open(
format=pyaudio.paInt16,
channels=1,
rate=sample_rate,
input=True,
input_device_index=2, # Índice do dispositivo
frames_per_buffer=chunk_samples
)
Pontos-chave
- O PyAudio captura o microfone em PCM mono de 16 bits a 16 kHz, exatamente o que o Voxtral espera
- O gerador
iter_microphonefornece blocos de 480 ms por predefinição loop.run_in_executortorna a leitura do microfone não bloqueante no asyncio- O Ctrl+C para a captura de forma limpa através de um manipulador de sinal
- Liste os dispositivos com
get_device_count()para escolher o microfone correto