transcribe_app

Aplicação de transcrição de áudio/vídeo com OpenAI. Divide ficheiros em blocos (chunks) com sobreposição, transcreve via API (modelos gpt-4o-transcribe, gpt-4o-transcribe-diarize, whisper-1, etc.), aplica heurísticas (e validação opcional por LLM) para detetar transcrições degeneradas e exporta resultados agregados.

• Entrada: pasta audios/ (por omissão).
• Saídas:
  • audios/chunks/… – WAVs gerados por chunk.
  • audios/Transcrits/<ficheiro>.txt – transcrição por ficheiro.
  • audios/transcricao_AGREGADA.txt – agregação de todas as transcrições.
  • audios/logs/run_transcricao.log – log textual da execução.

Requisitos

• Windows (script run.bat usa winget). Em macOS/Linux, ver Secção “Execução manual”.
• Python 3.10+ (o run.bat instala 3.13 via winget se faltar).
• FFmpeg e ffprobe (o run.bat instala via winget se faltar).
• Chave OpenAI (OPENAI_API_KEY).

Instalação e execução (Windows)

Tens duas formas simples:

1. Pelo .bat (recomendado para primeira vez)

• Clica duas vezes em run.bat ou corre-o no terminal.
• O script:
  • Garante Python via winget.
  • Cria venv ./venv e instala requirements.txt.
  • Garante FFmpeg via winget.
  • Executa a app (python -u transcribe.py).

2. Pelo VS Code com run.py

• Abre a pasta no VS Code.
• Corre run.py (usa o run.bat nos bastidores para ver saída no terminal integrado).

Na primeira execução, a app cria transcribe.ini com valores por omissão e pedirá a tua API key se não encontrar OPENAI_API_KEY no ambiente.

Configuração (transcribe.ini)

O ficheiro é criado automaticamente com defaults (ver constants.py). Secções principais:

• [transcribe]

  • input_folder: pasta de entrada (default audios).
  • output_root: raiz de saídas (mantida por compatibilidade; a app escreve dentro de audios/).
  • model_name: por ex. gpt-4o-transcribe-diarize, gpt-4o-transcribe, gpt-4o-mini-transcribe, whisper-1.
  • chunk_minutes: tamanho do chunk em minutos (default 15).
  • overlap_seconds: sobreposição entre chunks em segundos (default 5).
  • max_retries: tentativas por chunk (default 5).
  • recursive: procurar ficheiros nas subpastas (yes/no).
  • media_exts: extensões elegíveis (áudio/vídeo).
  • api_key: opcional; se vazio e sem OPENAI_API_KEY, a app pede e guarda aqui.
  • clean_outputs: limpar pastas de saída antes de correr (yes/no).
  • run_subfolder: reservado; atualmente a app escreve sempre dentro de audios/.
  • use_llm_validation: usar LLM para validar “degeneração” (yes/no).
  • log_path: caminho do log (por omissão dentro de audios/logs/).

• [llm]

  • enabled: ativa/desativa validação LLM.
  • model_name: p.ex. gpt-5-nano (curto e barato, formato JSON).
  • temperature, max_tokens: parâmetros da validação.

Dica sobre modelos de transcrição:

• gpt-4o-transcribe-diarize: separa falantes, com timestamps; ideal p/ entrevistas/reuniões.
• gpt-4o-transcribe: texto simples, alta qualidade.
• gpt-4o-mini-transcribe: mais leve/rápido.
• whisper-1: económico e fiável; sem diarização.

Se usares um modelo “-diarize”, a saída tenta formatar por falante: SPEAKER_X: texto….

Como usar

1. Coloca os teus ficheiros áudio/vídeo na pasta audios/ (ou ajusta input_folder no INI).
2. Define a variável de ambiente OPENAI_API_KEY ou deixa a app pedir e gravar no INI.
3. Corre:

• Windows: run.bat (ou python run.py dentro do VS Code).
• Direto em Python: python main.py ou python transcribe.py (com venv ativo e deps instaladas).

No fim, consulta:

• audios/Transcrits/<ficheiro>.txt
• audios/transcricao_AGREGADA.txt
• audios/logs/run_transcricao.log

Execução manual (macOS/Linux)

• Garante Python 3.10+ e FFmpeg (ffmpeg/ffprobe no PATH).
• Cria e ativa venv, instala deps:

  python -m venv .venv
  source .venv/bin/activate
  pip install -r requirements.txt

• Exporta a API key (ou deixa em branco e a app pedirá):

  export OPENAI_API_KEY="sk-..."

• Corre a app:

  python main.py

Estrutura do código (sumário)

• main.py – arranque; carrega config e chama Orchestrator.
• orchestrator.py – valida FFmpeg, resolve API key, gere fluxo e reporting.
• processing/ – chunker.py (FFmpeg split), transcriber.py, whisper_client.py (OpenAI), degeneracy_analyzer.py (heurísticas+LLM).
• input/ – config_manager.py (INI), media_scanner.py, user_interactor.py.
• output/ – reporter.py, logger.py, notifier.py, report_aggregator.py.
• constants.py – defaults e nomes de pastas/ficheiros.

Resolução de problemas

• FFmpeg não encontrado: instala e garante ffmpeg/ffprobe no PATH. No Windows, usa run.bat (winget).
• API key inválida: define OPENAI_API_KEY ou coloca api_key no transcribe.ini. A chave deve começar por sk-.
• Permissões de escrita: verifica permissões na pasta audios/ e subpastas.
• Winget indisponível: instala “App Installer” (Microsoft Store) ou faz setup manual (Python/FFmpeg) e corre python main.py.

Licença

Sem licença explícita. Se precisares de uma licença específica, abre um issue/solicitação.