Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Capturar o Microfone com PyAudio

Aula 11 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Do Ficheiro ao Microfone
  2. Instalar o PyAudio
  3. O Gerador do Microfone
  4. Programa Completo: Do Microfone à Transcrição
  5. Escolher o Dispositivo Correto
  6. Pontos-chave

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 por voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 e voxtral-mini-tts-3-0. Alterações principais: as marcas temporais são apenas por segmento (word devolve 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 de context_bias sã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_microphone fornece blocos de 480 ms por predefinição
  • loop.run_in_executor torna 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