🎥 Sistema de Transcrição de Vídeo/Áudio com IA

Transcreva vídeos do YouTube, Vimeo ou ficheiros locais com inteligência artificial

Deteção automática de idioma • Resumo inteligente • Chat contextual

📋 Índice

Sobre o Projeto
Funcionalidades
Requisitos
Instalação
Como Usar
Arquitetura
Configuração Avançada
API Reference
Troubleshooting
Roadmap
Contribuir

🎯 Sobre o Projeto

Este sistema oferece uma solução completa e profissional para transcrição automática de conteúdo audiovisual, combinando o poder do Whisper (OpenAI) para transcrição precisa com Claude AI (Anthropic) para análise inteligente do conteúdo.

Por que usar este sistema?

✅ Múltiplas fontes: Suporta YouTube, Vimeo e ficheiros locais
✅ Deteção automática: Identifica o idioma do áudio automaticamente
✅ IA integrada: Resumos e chat inteligente sobre o conteúdo
✅ Flexível: Interface web bonita OU linha de comando
✅ Exportação: TXT, JSON, SRT (legendas)
✅ Open source: Código livre para usar e modificar

Casos de Uso

📚 Educação: Transcrever aulas e criar materiais de estudo
🎙️ Podcasts: Converter episódios em artigos escritos
💼 Corporativo: Documentar reuniões e webinars
🎬 Produção: Gerar legendas profissionais (SRT)
📊 Pesquisa: Analisar entrevistas e focus groups
♿ Acessibilidade: Tornar conteúdo acessível a todos

🌟 Funcionalidades

🎬 Transcrição Multi-Fonte

Fonte	Suporte	Formatos
YouTube	✅ Completo	Qualquer URL válido
Vimeo	✅ Completo	Qualquer URL válido
Ficheiros Locais	✅ Completo	MP3, MP4, WAV, M4A, WebM, AVI, MKV

🧠 IA Integrada

🔊 Transcrição com Whisper

Motor: OpenAI Whisper (state-of-the-art)
Precisão: 95%+ em condições ideais
Idiomas: Suporta 99 idiomas
Timestamps: Precisos ao milissegundo
Modelos: 5 tamanhos (tiny → large)

📝 Resumo com Claude

Análise semântica inteligente
Extração de pontos-chave
Formatação estruturada
Adaptação ao contexto
Sempre em português

💬 Chat Contextual

Perguntas sobre o conteúdo transcrito
Respostas baseadas APENAS na transcrição
Sem adicionar informação externa
Histórico de conversa mantido
Interface natural e fluida

🎨 Duas Interfaces

🌐 Interface Web

Design moderno e responsivo
Drag & drop de ficheiros
Progress bar em tempo real
Tabs organizados (Transcrição/Resumo/Chat)
Copiar texto com um clique
Funciona offline (após setup)

💻 Linha de Comando

Perfeito para automação
Batch processing
Scripts e pipelines
Sem dependências de browser
Ideal para servidores

📦 Requisitos

Sistema Operativo

✅ Linux (Ubuntu 20.04+, Debian 11+)
✅ macOS (10.15+)
✅ Windows 10/11 (com WSL recomendado)

Software Base

Python 3.8 ou superior
FFmpeg (para processamento de áudio/vídeo)
pip (gestor de pacotes Python)

Hardware Recomendado

Componente	Mínimo	Recomendado	Ideal
CPU	2 cores	4 cores	8+ cores
RAM	4 GB	8 GB	16+ GB
Disco	2 GB livre	5 GB livre	10+ GB livre
GPU	Não requerida	CUDA opcional	RTX série

💡 Nota: GPU acelera transcrição mas não é obrigatória

Dependências Python

Todas incluídas em requirements.txt:

Flask & Flask-CORS (web server)
openai-whisper (transcrição)
yt-dlp (download de vídeos)
anthropic (Claude AI)
torch & torchaudio (ML)
langdetect (deteção de idioma)

🚀 Instalação

Método 1: Instalação Automática (Recomendado)

# 1. Clonar ou descompactar o projeto
cd video-transcription-project

# 2. Executar script de instalação
chmod +x install.sh
./install.sh

# 3. Ativar ambiente virtual
source venv/bin/activate

# 4. (Opcional) Configurar Claude AI
export ANTHROPIC_API_KEY="sua-chave-aqui"

Método 2: Instalação Manual

Passo 1: Instalar FFmpeg

Ubuntu/Debian:

sudo apt update
sudo apt install ffmpeg

macOS (Homebrew):

brew install ffmpeg

Windows:

Download: https://ffmpeg.org/download.html
Extrair e adicionar ao PATH
Ou usar: choco install ffmpeg

Passo 2: Python e Dependências

# Criar ambiente virtual
python3 -m venv venv

# Ativar ambiente
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Atualizar pip
pip install --upgrade pip

# Instalar dependências
pip install -r requirements.txt

Passo 3: Configurar API (Opcional)

Para usar resumos e chat:

# Obter chave em: https://console.anthropic.com/
export ANTHROPIC_API_KEY="sk-ant-..."

# Ou criar ficheiro .env
echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env

Verificar Instalação

# Testar backend
python backend.py

# Testar CLI
python transcribe.py --help

# Verificar FFmpeg
ffmpeg -version

📖 Como Usar

🌐 Modo Web (Interface Gráfica)

1. Iniciar o Backend

# Ativar ambiente virtual (se necessário)
source venv/bin/activate

# Iniciar servidor Flask
python backend.py

Saída esperada:

==================================================
Servidor de Transcrição iniciado!
==================================================
Modelo Whisper: base
Claude API: Ativada
==================================================
 * Running on http://0.0.0.0:5000

2. Abrir Interface Web

Opção A - Abrir diretamente:

# Abrir no navegador
open index.html  # macOS
xdg-open index.html  # Linux
start index.html  # Windows

Opção B - Servir com Python:

# Em outro terminal
python -m http.server 8080

# Aceder a: http://localhost:8080

3. Usar a Interface

Escolher fonte: YouTube / Vimeo / Ficheiro Local
Inserir dados: URL ou upload de ficheiro
Clicar "Transcrever": Aguardar processamento
Explorar resultados:
- 📝 Tab "Transcrição": Texto completo
- 📋 Tab "Resumo": Pontos-chave
- 💬 Tab "Chat": Fazer perguntas

💻 Modo CLI (Linha de Comando)

Sintaxe Básica

python transcribe.py [OPTIONS]

Opções:
  -u, --url URL          URL do vídeo (YouTube/Vimeo)
  -f, --file FILE        Ficheiro local
  -m, --model MODEL      Modelo Whisper (tiny/base/small/medium/large)
  -o, --output NAME      Nome base dos ficheiros de saída
  -h, --help            Mostrar ajuda

Exemplos Práticos

Transcrever vídeo do YouTube:

python transcribe.py -u "https://youtube.com/watch?v=dQw4w9WgXcQ" -o resultado

Transcrever ficheiro local:

python transcribe.py -f podcast.mp3 -o podcast

Usar modelo maior (melhor qualidade):

python transcribe.py -f entrevista.mp4 -m large -o entrevista

Especificar output customizado:

python transcribe.py -u "URL_VIDEO" -o "reuniao_$(date +%Y%m%d)"

Ficheiros Gerados

Cada transcrição gera 3 ficheiros:

nome.txt    → Transcrição em texto simples
nome.json   → Dados completos (texto + timestamps + metadados)
nome.srt    → Legendas no formato SubRip (para editores de vídeo)

Exemplo de conteúdo:

resultado.txt:

Idioma: Português
==================================================

Esta é a transcrição do vídeo...

resultado.json:

{
  "text": "Esta é a transcrição...",
  "language": "Português",
  "language_code": "pt",
  "segments": [
    {
      "start": 0.0,
      "end": 3.5,
      "text": "Esta é a transcrição..."
    }
  ]
}

resultado.srt:

1
00:00:00,000 --> 00:00:03,500
Esta é a transcrição...

2
00:00:03,500 --> 00:00:08,200
...do vídeo completo.

🏗️ Arquitetura

Estrutura do Projeto

video-transcription-project/
├── 📄 backend.py           # Servidor Flask + API REST
├── 🌐 index.html           # Interface web (frontend)
├── 🖥️  transcribe.py        # CLI standalone
├── 📦 requirements.txt     # Dependências Python
├── 🔧 install.sh           # Script instalação automática
├── 📖 README.md            # Documentação completa
├── 🚀 QUICKSTART.md        # Guia início rápido
└── 📂 venv/                # Ambiente virtual (após instalação)

Fluxo de Funcionamento

graph TB
    A[Utilizador] --> B{Escolha de Interface}
    B -->|Web| C[Frontend HTML/JS]
    B -->|CLI| D[transcribe.py]
    
    C --> E[Backend Flask API]
    D --> F[Whisper Engine]
    E --> F
    
    F --> G{Fonte?}
    G -->|YouTube/Vimeo| H[yt-dlp Download]
    G -->|Ficheiro| I[Ficheiro Local]
    
    H --> J[Áudio Processado]
    I --> J
    
    J --> K[Whisper Transcrição]
    K --> L[Texto + Idioma + Timestamps]
    
    L --> M[Claude AI]
    M --> N[Resumo]
    
    L --> O[Resultados]
    N --> O
    
    O --> P[Exibição/Export]

Componentes Principais

1. Backend (backend.py)

Framework: Flask
Endpoints: REST API
Funções:
- Download de vídeos (yt-dlp)
- Transcrição (Whisper)
- Resumo (Claude)
- Chat contextual
Porta: 5000 (default)

2. Frontend (index.html)

Tech: HTML5, CSS3, JavaScript vanilla
Features:
- Tabs para fontes diferentes
- Upload de ficheiros
- Progress tracking
- Resultados interativos
Responsive: Mobile-friendly

3. CLI (transcribe.py)

Tipo: Script Python standalone
Funções:
- Transcrição direta
- Export automático (TXT/JSON/SRT)
- Sem servidor necessário
Uso: Automação e batch

⚙️ Configuração Avançada

Escolha do Modelo Whisper

Editar backend.py linha 20:

WHISPER_MODEL = "base"  # Alterar aqui

Comparação de Modelos

Modelo	Parâmetros	RAM Necessária	Velocidade Relativa	Precisão	Ideal Para
tiny	39M	~1 GB	⚡⚡⚡⚡⚡ (5x)	⭐⭐ (70%)	Testes rápidos
base	74M	~1 GB	⚡⚡⚡⚡ (4x)	⭐⭐⭐ (78%)	Uso geral ✅
small	244M	~2 GB	⚡⚡⚡ (3x)	⭐⭐⭐⭐ (85%)	Qualidade superior
medium	769M	~5 GB	⚡⚡ (2x)	⭐⭐⭐⭐⭐ (92%)	Produção
large	1550M	~10 GB	⚡ (1x)	⭐⭐⭐⭐⭐ (95%)	Máxima qualidade

Recomendações:

🏠 Uso pessoal: base ou small
🏢 Produção: medium ou large
🚀 Testes/Dev: tiny

Variáveis de Ambiente

Criar ficheiro .env na raiz:

# API Anthropic (para resumos e chat)
ANTHROPIC_API_KEY=sk-ant-api03-...

# Modelo Whisper
WHISPER_MODEL=base

# Porta do servidor
FLASK_PORT=5000

# Debug mode
FLASK_DEBUG=false

# Diretório temporário
TEMP_DIR=/tmp/transcriptions

Carregar no código:

from dotenv import load_dotenv
load_dotenv()

CORS e Segurança

Para produção, restringir origins no backend.py:

from flask_cors import CORS

# Desenvolvimento (permitir todos)
CORS(app)

# Produção (restringir)
CORS(app, origins=[
    'https://seu-dominio.com',
    'https://app.seu-dominio.com'
])

Otimização de Performance

1. Usar GPU (se disponível)

Instalar PyTorch com CUDA:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

Verificar no código:

import torch
print(f"CUDA disponível: {torch.cuda.is_available()}")

2. Cache de Modelos

Os modelos Whisper são cached automaticamente em:

Linux/Mac: ~/.cache/whisper/
Windows: C:\Users\<user>\.cache\whisper\

3. Processamento Paralelo

Para múltiplos ficheiros, usar multiprocessing:

from multiprocessing import Pool

files = ['video1.mp4', 'video2.mp4', 'video3.mp4']

with Pool(processes=3) as pool:
    results = pool.map(transcribe_file, files)

Integração Docker

Criar Dockerfile:

FROM python:3.10-slim

# Instalar FFmpeg
RUN apt-get update && \
    apt-get install -y ffmpeg && \
    rm -rf /var/lib/apt/lists/*

# Diretório de trabalho
WORKDIR /app

# Copiar ficheiros
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# Expor porta
EXPOSE 5000

# Comando
CMD ["python", "backend.py"]

Build e run:

docker build -t video-transcription .
docker run -p 5000:5000 -e ANTHROPIC_API_KEY=... video-transcription

📦 Requisitos

Sistema Operativo

✅ Linux (Ubuntu 20.04+, Debian 11+, Fedora 35+)
✅ macOS (10.15 Catalina ou superior)
✅ Windows 10/11 (com WSL2 recomendado para melhor performance)

Software Base Obrigatório

Software	Versão Mínima	Instalação
Python	3.8+	python.org
pip	20.0+	Incluído com Python
FFmpeg	4.0+	Ver instruções abaixo

Hardware Recomendado

Componente	Mínimo	Recomendado	Ideal	Notas
CPU	2 cores	4 cores	8+ cores	Processamento paralelo
RAM	4 GB	8 GB	16+ GB	Depende do modelo Whisper
Disco	2 GB	5 GB	10+ GB	Para modelos + cache
GPU	Não req.	CUDA 8GB+	RTX 3060+	Acelera 5-10x (opcional)
Internet	1 Mbps	10 Mbps	50+ Mbps	Para download de vídeos

Requisitos por Modelo Whisper

Modelo	RAM Mínima	RAM Ideal	GPU VRAM	Tempo (10min áudio)
tiny	1 GB	2 GB	-	~30 segundos
base	1 GB	2 GB	-	~1 minuto
small	2 GB	4 GB	2 GB	~2 minutos
medium	5 GB	8 GB	5 GB	~5 minutos
large	10 GB	16 GB	10 GB	~10 minutos

Dependências Python

Todas as dependências estão especificadas em requirements.txt:

flask==3.0.0              # Web framework
flask-cors==4.0.0         # CORS para API
openai-whisper==20231117  # Motor de transcrição
yt-dlp==2024.3.10         # Download de vídeos
anthropic==0.18.1         # Claude AI
langdetect==1.0.9         # Deteção de idioma
torch==2.1.2              # PyTorch (ML)
torchaudio==2.1.2         # Áudio para PyTorch
ffmpeg-python==0.2.0      # Interface Python para FFmpeg

Tamanho Total do Download: ~1.5 GB (inclui PyTorch)

Verificação de Requisitos

Executar antes da instalação:

# Python
python3 --version  # Deve ser >= 3.8

# pip
pip --version  # Deve estar presente

# FFmpeg
ffmpeg -version  # Deve mostrar versão

# Espaço em disco
df -h /tmp  # Verificar espaço livre

🚀 Instalação

🎯 Método 1: Instalação Automática (Recomendado)

O script install.sh automatiza todo o processo:

# 1. Navegar para o diretório do projeto
cd video-transcription-project

# 2. Dar permissões de execução
chmod +x install.sh

# 3. Executar instalação
./install.sh

# 4. Ativar ambiente virtual
source venv/bin/activate

# 5. (Opcional) Configurar Claude AI
export ANTHROPIC_API_KEY="sua-chave-aqui"

O script faz automaticamente:

✅ Verifica Python e FFmpeg
✅ Instala FFmpeg se necessário (Linux/Mac)
✅ Cria ambiente virtual Python
✅ Instala todas as dependências
✅ Valida a instalação
✅ Cria ficheiro .env de exemplo

Tempo estimado: 5-10 minutos (depende da internet)

🔧 Método 2: Instalação Manual Detalhada

Para quem prefere controlo total ou tem requisitos específicos.

Passo 1: Instalar FFmpeg

Ubuntu / Debian

sudo apt update
sudo apt install -y ffmpeg

# Verificar
ffmpeg -version

macOS (Homebrew)

# Instalar Homebrew se necessário
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Instalar FFmpeg
brew install ffmpeg

# Verificar
ffmpeg -version

Windows

Opção A - Chocolatey (Recomendado):

# PowerShell como Administrador
choco install ffmpeg

# Verificar
ffmpeg -version

Opção B - Manual:

Download: https://ffmpeg.org/download.html#build-windows
Extrair para C:\ffmpeg
Adicionar ao PATH:
- Painel de Controlo → Sistema → Variáveis de Ambiente
- PATH → Editar → Novo → C:\ffmpeg\bin
Reiniciar terminal e verificar: ffmpeg -version

Passo 2: Configurar Python

# Verificar versão
python3 --version  # Deve ser >= 3.8

# Se não tiver Python 3.8+, instalar:

# Ubuntu/Debian
sudo apt install python3.10 python3.10-venv

# macOS
brew install python@3.10

# Windows: Download de python.org

Passo 3: Criar Ambiente Virtual

# Navegar para o projeto
cd video-transcription-project

# Criar venv
python3 -m venv venv

# Ativar venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows PowerShell
venv\Scripts\activate.bat # Windows CMD

Confirmar ativação (prompt muda para (venv)):

(venv) user@machine:~/video-transcription-project$

Passo 4: Instalar Dependências Python

# Atualizar pip
pip install --upgrade pip

# Instalar todas as dependências
pip install -r requirements.txt

# Verificar instalações críticas
python -c "import whisper; print('Whisper OK')"
python -c "import flask; print('Flask OK')"
python -c "import yt_dlp; print('yt-dlp OK')"

Se houver erros com PyTorch, instalar manualmente:

# CPU only (mais leve)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# CUDA 11.8 (para GPU NVIDIA)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

Passo 5: Configurar API (Opcional mas Recomendado)

Para usar resumos e chat com Claude AI:

# Obter API key em: https://console.anthropic.com/

# Opção A - Export temporário
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# Opção B - Ficheiro .env (permanente)
echo 'ANTHROPIC_API_KEY=sk-ant-api03-...' > .env

# Opção C - Adicionar ao .bashrc/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.bashrc
source ~/.bashrc

Passo 6: Verificar Instalação Completa

# Testar imports Python
python << EOF
import whisper
import flask
import yt_dlp
import anthropic
import torch
print("✅ Todas as dependências importadas com sucesso!")
print(f"PyTorch: {torch.__version__}")
print(f"CUDA disponível: {torch.cuda.is_available()}")
EOF

# Testar CLI
python transcribe.py --help

# Testar servidor (CTRL+C para parar)
python backend.py

🐳 Método 3: Instalação com Docker (Avançado)

Para ambientes isolados ou deployment:

Criar Dockerfile

Já incluído no projeto, mas aqui está o conteúdo:

FROM python:3.10-slim

# Instalar FFmpeg e dependências do sistema
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    ffmpeg \
    git \
    && rm -rf /var/lib/apt/lists/*

# Diretório de trabalho
WORKDIR /app

# Copiar requirements e instalar dependências
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copiar código do projeto
COPY . .

# Porta da aplicação
EXPOSE 5000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD python -c "import requests; requests.get('http://localhost:5000/api/health')"

# Comando de início
CMD ["python", "backend.py"]

Build e Run

# Build da imagem
docker build -t video-transcription:latest .

# Run com API key
docker run -d \
  --name transcription-service \
  -p 5000:5000 \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  video-transcription:latest

# Ver logs
docker logs -f transcription-service

# Parar
docker stop transcription-service

Docker Compose (Recomendado para Produção)

Criar docker-compose.yml:

version: '3.8'

services:
  transcription:
    build: .
    ports:
      - "5000:5000"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - WHISPER_MODEL=base
    volumes:
      - ./transcriptions:/app/transcriptions
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import requests; requests.get('http://localhost:5000/api/health')"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  transcriptions:

Usar:

# Iniciar
docker-compose up -d

# Ver logs
docker-compose logs -f

# Parar
docker-compose down

✅ Pós-Instalação

1. Primeiro Teste

# Ativar ambiente (se ainda não ativado)
source venv/bin/activate

# Testar transcrição CLI (ficheiro pequeno)
python transcribe.py -u "https://www.youtube.com/watch?v=jNQXAC9IVRw" -m tiny -o teste

# Verificar outputs
ls -lh teste.*
# Deve criar: teste.txt, teste.json, teste.srt

2. Iniciar Servidor Web

# Terminal 1 - Backend
python backend.py

# Terminal 2 - Frontend (opcional)
python -m http.server 8080

# Abrir browser: http://localhost:8080

3. Configurações Recomendadas

Criar ficheiro .env na raiz:

# APIs
ANTHROPIC_API_KEY=sk-ant-api03-...

# Whisper
WHISPER_MODEL=base  # ou: tiny, small, medium, large

# Flask
FLASK_PORT=5000
FLASK_DEBUG=false

# Paths
TEMP_DIR=/tmp/transcriptions
OUTPUT_DIR=./transcriptions

# Limites
MAX_FILE_SIZE=500000000  # 500MB
MAX_VIDEO_LENGTH=7200    # 2 horas

4. Otimizações Opcionais

Usar GPU (se disponível)

# Verificar CUDA
nvidia-smi

# Reinstalar PyTorch com CUDA
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Testar
python -c "import torch; print(torch.cuda.is_available())"

Pre-download de Modelos Whisper

# Fazer download antecipado dos modelos
python << EOF
import whisper
whisper.load_model("tiny")
whisper.load_model("base")
whisper.load_model("small")
print("✅ Modelos cached")
EOF

Modelos são guardados em:

Linux/Mac: ~/.cache/whisper/
Windows: C:\Users\<user>\.cache\whisper\

🎓 Próximos Passos

Instalação completa! Agora podes:

📖 Ler o Guia de Início Rápido
🌐 Explorar a interface web
💻 Experimentar a linha de comando
📚 Consultar a API Reference
🔧 Personalizar configurações avançadas

📖 Como Usar

Existem duas formas de usar o sistema: através da interface web (mais visual e intuitiva) ou via linha de comando (mais rápido para automação).

🌐 Modo Web (Interface Gráfica)

Ideal para: Uso casual, exploração visual, chat interativo

1️⃣ Iniciar o Backend

# Ativar ambiente virtual (se não estiver ativado)
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Iniciar servidor Flask
python backend.py

Saída esperada:

==================================================
Servidor de Transcrição iniciado!
==================================================
Modelo Whisper: base
Claude API: Ativada
==================================================
 * Running on http://0.0.0.0:5000
 * Running on http://127.0.0.1:5000

💡 Dica: Deixar este terminal aberto enquanto usas a interface web

2️⃣ Abrir Interface Web

Tens três opções:

Opção A - Abrir Diretamente (Mais simples):

# No diretório do projeto
open index.html           # macOS
xdg-open index.html       # Linux
start index.html          # Windows

Opção B - Servir com Python (Recomendado):

# Em outro terminal (o backend deve estar a correr)
python -m http.server 8080

# Aceder no browser:
# http://localhost:8080

Opção C - Usar browser diretamente:

file:///caminho/completo/para/index.html

3️⃣ Usar a Interface

Tab YouTube

Cole o URL completo do vídeo

https://www.youtube.com/watch?v=dQw4w9WgXcQ
ou
https://youtu.be/dQw4w9WgXcQ

Clica "Transcrever Vídeo"
- Progress bar mostra o progresso
- Status atualiza: Download → Transcrição → Resumo
Aguarda o processamento
- Vídeo de 10 min: ~2-3 minutos (modelo base)
- Vídeo de 1 hora: ~15-20 minutos

Tab Vimeo

Igual ao YouTube, mas com URLs do Vimeo:

https://vimeo.com/123456789

Tab Ficheiro Local

Clica "Escolher Ficheiro"
- Formatos suportados: MP3, MP4, WAV, M4A, WebM, AVI, MKV
- Tamanho máximo: 500MB (ajustável)
Seleciona o ficheiro e aguarda upload
Clica "Transcrever Ficheiro"

4️⃣ Explorar os Resultados

Após processamento, três tabs ficam disponíveis:

📝 Tab Transcrição

Idioma Detetado: Badge colorido no topo
Texto Completo: Toda a transcrição
Selecionável: Clique e arraste para copiar
Scroll: Para textos longos

Exemplo de visualização:

🌐 Idioma: Português (pt-PT)

Esta é a transcrição completa do vídeo.
O conteúdo inclui todos os diálogos e
narrativas presentes no áudio original...

📋 Tab Resumo

Estruturado: Título, pontos-chave, conclusão
Conciso: 3-5 parágrafos principais
Formatado: Fácil de ler

Exemplo:

📌 Resumo do Vídeo:

O vídeo aborda...

Pontos principais:
• Ponto 1...
• Ponto 2...
• Ponto 3...

Conclusão: ...

💬 Tab Chat

Mensagem inicial: IA apresenta-se
Campo de input: Escrever perguntas
Histórico mantido: Contexto preservado
Enter para enviar: Ou botão "Enviar"

Exemplos de perguntas:

"Qual é o tema principal?"
"Resume os 3 pontos mais importantes"
"Que exemplos são dados?"
"Há alguma conclusão mencionada?"
"Quantas pessoas falam no vídeo?"

Nota importante: O chat responde APENAS com base na transcrição, sem adicionar informação externa.

💻 Modo CLI (Linha de Comando)

Ideal para: Automação, scripts, batch processing, servidores

Sintaxe Básica

python transcribe.py [OPTIONS]

Opções Obrigatórias (escolher uma):
  -u, --url URL          URL do vídeo (YouTube/Vimeo/etc)
  -f, --file FILE        Caminho para ficheiro local

Opções Adicionais:
  -m, --model MODEL      Modelo Whisper (default: base)
                         Opções: tiny, base, small, medium, large
  -o, --output NAME      Nome base ficheiros saída (default: transcription)
  -h, --help            Mostrar ajuda completa

Exemplos Práticos

Exemplo 1: YouTube Básico

python transcribe.py \
  -u "https://youtube.com/watch?v=dQw4w9WgXcQ" \
  -o resultado

Cria:

resultado.txt - Transcrição texto
resultado.json - Dados completos
resultado.srt - Legendas

Exemplo 2: Ficheiro Local com Modelo Maior

python transcribe.py \
  -f ~/Videos/entrevista.mp4 \
  -m large \
  -o entrevista_transcrita

Quando usar modelo large:

Áudio de baixa qualidade
Múltiplos speakers
Termos técnicos ou específicos
Necessidade de máxima precisão

Exemplo 3: Batch Processing

Transcrever múltiplos ficheiros:

# Script bash
for video in ~/Videos/*.mp4; do
  nome=$(basename "$video" .mp4)
  python transcribe.py -f "$video" -o "output/$nome"
done

Exemplo 4: Com Timestamps no Nome

python transcribe.py \
  -u "URL_DO_VIDEO" \
  -o "reuniao_$(date +%Y%m%d_%H%M%S)"

Cria: reuniao_20241215_143022.txt etc.

Exemplo 5: Pipeline Completo

#!/bin/bash
# pipeline_transcricao.sh

URL=$1
NOME=$2

echo "📥 A fazer download..."
yt-dlp -x --audio-format mp3 "$URL" -o "temp.mp3"

echo "🎙️ A transcrever..."
python transcribe.py -f temp.mp3 -m medium -o "$NOME"

echo "🗑️ A limpar temporários..."
rm temp.mp3

echo "✅ Concluído! Ficheiros criados:"
ls -lh "${NOME}."*

Usar:

chmod +x pipeline_transcricao.sh
./pipeline_transcricao.sh "URL_YOUTUBE" "resultado"

Saídas do CLI

📄 Ficheiro TXT (resultado.txt)

Idioma: Português
==================================================

Esta é a transcrição completa do áudio.
Inclui todo o texto falado no vídeo,
processado pelo motor Whisper...

Uso:

Copiar para documentos
Análise de texto
Base para artigos

📊 Ficheiro JSON (resultado.json)

{
  "text": "Transcrição completa...",
  "language": "Português",
  "language_code": "pt",
  "segments": [
    {
      "start": 0.0,
      "end": 3.5,
      "text": "Primeiro segmento..."
    },
    {
      "start": 3.5,
      "end": 7.2,
      "text": "Segundo segmento..."
    }
  ]
}

Uso:

Programação (parse fácil)
Análise com timestamps
Integração com outros sistemas

🎬 Ficheiro SRT (resultado.srt)

1
00:00:00,000 --> 00:00:03,500
Primeiro segmento de texto

2
00:00:03,500 --> 00:00:07,200
Segundo segmento de texto

3
00:00:07,200 --> 00:00:12,800
Terceiro segmento de texto

Uso:

Editores de vídeo (Premiere, Final Cut, DaVinci)
Plataformas de vídeo
Players com suporte a legendas

Progress e Feedback CLI

Durante a transcrição, verás:

==================================================
🎥 SISTEMA DE TRANSCRIÇÃO DE VÍDEO/ÁUDIO
==================================================

🔄 A carregar modelo Whisper (base)...
✅ Modelo carregado com sucesso!

⬇️  A fazer download de: https://youtube.com/...
[youtube] Extracting URL: ...
[youtube] dQw4w9WgXcQ: Downloading webpage
[download] Destination: /tmp/temp_audio.mp3
[download] 100% of 5.20MiB in 00:02
✅ Download completo: Never Gonna Give You Up

🎙️  A transcrever: temp_audio.mp3
    (Isto pode demorar alguns minutos...)

Detecting language using up to the first 30 seconds.
Detected language: Portuguese
[████████████████████] 100%

✅ Transcrição completa!
🌐 Idioma detetado: Português (pt)

==================================================
💾 A GUARDAR RESULTADOS
==================================================

💾 Transcrição guardada: resultado.txt
💾 Dados completos guardados: resultado.json
💾 Legendas SRT guardadas: resultado.srt

==================================================
✅ TRANSCRIÇÃO COMPLETA!
==================================================

📄 Ficheiros criados:
   • resultado.txt  - Transcrição em texto
   • resultado.json - Dados completos (JSON)
   • resultado.srt  - Legendas (SRT)

🎯 Casos de Uso Detalhados

1. Transcrever Podcast para Blog Post

# 1. Transcrever
python transcribe.py -f podcast_ep01.mp3 -m small -o ep01

# 2. Usar o texto para criar artigo
cat ep01.txt | head -n 50  # Primeiras linhas

# 3. Extrair quotes específicas do JSON
python << EOF
import json
with open('ep01.json') as f:
    data = json.load(f)
    for seg in data['segments'][:10]:
        print(f"[{seg['start']:.1f}s] {seg['text']}")
EOF

2. Criar Legendas para Vídeo

# 1. Transcrever
python transcribe.py -f video_sem_legendas.mp4 -o video

# 2. Usar video.srt no editor de vídeo
# Premiere Pro: Import → Captions → video.srt
# Final Cut: File → Import → Captions → video.srt
# DaVinci: File → Import → Subtitle → video.srt

3. Documentar Reunião de Equipa

# Durante a reunião, gravar áudio
# Depois:
python transcribe.py -f reuniao.m4a -m medium -o "ata_$(date +%Y%m%d)"

# Usar interface web para fazer perguntas:
# "Quais foram as decisões tomadas?"
# "Que tarefas foram atribuídas?"
# "Há algum prazo mencionado?"

4. Estudar Aula ou Palestra

# Transcrever aula
python transcribe.py -u "URL_AULA" -o aula_materia

# Usar o resumo automático (modo web)
# Ou criar resumo manual:
cat aula_materia.txt | head -100 > resumo_aula.txt

5. Análise de Entrevistas (Pesquisa)

📡 API Reference

Base URL

http://localhost:5000/api

Endpoints

1. Transcrever YouTube

POST /api/transcribe/youtube

Transcreve um vídeo do YouTube.

Request:

{
  "url": "https://youtube.com/watch?v=dQw4w9WgXcQ"
}

Response:

{
  "transcription": "Texto completo da transcrição...",
  "language": "Português",
  "summary": "Resumo do conteúdo...",
  "segments": [
    {
      "start": 0.0,
      "end": 3.5,
      "text": "Primeiro segmento..."
    }
  ]
}

Códigos de Status:

200 - Sucesso
400 - URL inválido ou não fornecido
500 - Erro no processamento

2. Transcrever Vimeo

POST /api/transcribe/vimeo

Transcreve um vídeo do Vimeo.

Request:

{
  "url": "https://vimeo.com/123456789"
}

Response: Igual ao endpoint YouTube

3. Transcrever Ficheiro

POST /api/transcribe/file

Transcreve um ficheiro de áudio/vídeo enviado.

Request:

Content-Type: multipart/form-data

file: [ficheiro binário]

Response: Igual aos endpoints acima

Formatos Suportados:

Áudio: MP3, WAV, M4A, FLAC, OGG
Vídeo: MP4, AVI, MKV, MOV, WebM

Limite de Tamanho: 500MB (ajustável)

4. Chat sobre Transcrição

POST /api/chat

Faz perguntas sobre o conteúdo transcrito.

Request:

{
  "question": "Qual é o tema principal do vídeo?",
  "transcription": "Texto completo da transcrição...",
  "history": [
    {
      "role": "user",
      "content": "Pergunta anterior"
    },
    {
      "role": "assistant",
      "content": "Resposta anterior"
    }
  ]
}

Response:

{
  "response": "O tema principal é..."
}

5. Health Check

GET /api/health

Verifica o estado do serviço.

Response:

{
  "status": "ok",
  "whisper_model": "base",
  "claude_enabled": true
}

Exemplos de Uso

cURL

# Transcrever YouTube
curl -X POST http://localhost:5000/api/transcribe/youtube \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=..."}'

# Upload de ficheiro
curl -X POST http://localhost:5000/api/transcribe/file \
  -F "file=@audio.mp3"

# Chat
curl -X POST http://localhost:5000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Resumo?",
    "transcription": "...",
    "history": []
  }'

Python

import requests

# Transcrever YouTube
response = requests.post(
    'http://localhost:5000/api/transcribe/youtube',
    json={'url': 'https://youtube.com/watch?v=...'}
)
data = response.json()
print(data['transcription'])

# Upload ficheiro
with open('audio.mp3', 'rb') as f:
    response = requests.post(
        'http://localhost:5000/api/transcribe/file',
        files={'file': f}
    )
data = response.json()

# Chat
response = requests.post(
    'http://localhost:5000/api/chat',
    json={
        'question': 'Qual o tema?',
        'transcription': data['transcription'],
        'history': []
    }
)
print(response.json()['response'])

JavaScript

// Transcrever YouTube
const response = await fetch('http://localhost:5000/api/transcribe/youtube', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: 'https://youtube.com/watch?v=...'
  })
});
const data = await response.json();

// Upload ficheiro
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('http://localhost:5000/api/transcribe/file', {
  method: 'POST',
  body: formData
});

// Chat
const response = await fetch('http://localhost:5000/api/chat', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    question: 'Resumo?',
    transcription: transcriptionText,
    history: []
  })
});

5. Análise de Entrevistas (Pesquisa)

# Transcrever todas as entrevistas
for i in entrevista_*.m4a; do
  python transcribe.py -f "$i" -m medium -o "${i%.m4a}"
done

# Consolidar todas as transcrições
cat entrevista_*.txt > todas_entrevistas.txt

# Usar ferramentas de análise de texto
# ou importar JSONs para análise qualitativa

💡 Dicas e Melhores Práticas

Qualidade da Transcrição

Para melhores resultados:

✅ Áudio limpo

# Limpar áudio antes (reduzir ruído)
ffmpeg -i input.mp3 \
  -af "highpass=f=200,lowpass=f=3000,volume=1.5" \
  -ar 16000 \
  output_clean.mp3

✅ Modelo adequado

Voz clara, sem ruído → base ou small
Áudio com ruído → medium ou large
Múltiplos speakers → large

✅ Formato correto

# Converter para MP3 (mais compatível)
ffmpeg -i video.mov -vn -ar 16000 -ac 1 audio.mp3

❌ Evitar:

Vídeos muito longos (>2h) sem dividir
Áudio com muito ruído de fundo
Múltiplas línguas no mesmo áudio
Música alta sobre voz

Performance e Velocidade

Acelerar processamento:

Modelo menor (mais rápido):

python transcribe.py -f audio.mp3 -m tiny -o resultado

Usar GPU (se disponível):

# Verificar
import torch
print(torch.cuda.is_available())  # Deve ser True

Processar em paralelo:

# Dividir vídeo longo
ffmpeg -i long_video.mp4 -ss 00:00:00 -t 00:30:00 part1.mp3
ffmpeg -i long_video.mp4 -ss 00:30:00 -t 00:30:00 part2.mp3

# Transcrever em paralelo
python transcribe.py -f part1.mp3 -o part1 &
python transcribe.py -f part2.mp3 -o part2 &
wait

# Juntar resultados
cat part1.txt part2.txt > full.txt

Pre-processar áudio:

# Reduzir para mono 16kHz (mais rápido)
ffmpeg -i input.mp4 -ar 16000 -ac 1 -vn output.wav

Gestão de Recursos

Para sistemas com memória limitada:

# Usar modelo tiny
export WHISPER_MODEL=tiny

# Limitar tamanho de ficheiros
find . -name "*.mp4" -size -100M -exec python transcribe.py -f {} \;

# Limpar cache se necessário
rm -rf ~/.cache/whisper/*

Automação Avançada

Criar serviço systemd (Linux):

# /etc/systemd/system/transcription.service
[Unit]
Description=Video Transcription Service
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/video-transcription-project
ExecStart=/path/to/venv/bin/python backend.py
Restart=always

[Install]
WantedBy=multi-user.target

Ativar:

sudo systemctl enable transcription
sudo systemctl start transcription
sudo systemctl status transcription

Cron job para processar diretório:

# Editar crontab
crontab -e

# Adicionar (processar novos ficheiros a cada hora)
0 * * * * cd /path/to/project && find /path/to/videos -name "*.mp4" -mmin -60 -exec python transcribe.py -f {} \;

Integração com Outras Ferramentas

Enviar para Google Drive:

# Após transcrição
rclone copy resultado.txt gdrive:Transcricoes/

# Ou usar API do Google Drive

Notificação quando terminar:

# Linux (notify-send)
python transcribe.py -f video.mp4 -o resultado && \
  notify-send "Transcrição completa!" "resultado.txt criado"

# macOS (terminal-notifier)
python transcribe.py -f video.mp4 -o resultado && \
  terminal-notifier -title "Transcrição" -message "Completa!"

# Slack webhook
python transcribe.py -f video.mp4 -o resultado && \
  curl -X POST -H 'Content-type: application/json' \
  --data '{"text":"Transcrição completa!"}' \
  YOUR_SLACK_WEBHOOK_URL

Backup e Organização

Estrutura de pastas recomendada:

transcricoes/
├── 2024/
│   ├── 01_janeiro/
│   │   ├── reuniao_01/
│   │   │   ├── audio.mp3
│   │   │   ├── transcricao.txt
│   │   │   ├── transcricao.json
│   │   │   └── transcricao.srt
│   │   └── entrevista_cliente_A/
│   │       └── ...
│   └── 02_fevereiro/
│       └── ...
└── templates/
    └── script_processamento.sh

Script de organização:

#!/bin/bash
# organize_transcriptions.sh

DATA=$(date +%Y/%m_%B)
DESTINO="$HOME/transcricoes/$DATA"

mkdir -p "$DESTINO"
mv *.txt *.json *.srt "$DESTINO/" 2>/dev/null

echo "✅ Ficheiros organizados em: $DESTINO"

🎨 Personalização

Modificar Interface Web

O index.html usa CSS inline que podes personalizar:

Mudar cores:

/* Procurar e alterar estas variáveis no <style> */
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
/* Mudar para tuas cores preferidas */
background: linear-gradient(135deg, #FF6B6B 0%, #4ECDC4 100%);

Adicionar logo:

<!-- Adicionar no .header -->
<img src="logo.png" alt="Logo" style="height: 60px; margin-bottom: 10px;">
<h1>Teu Sistema de Transcrição</h1>

Customizar Backend

Adicionar webhook após transcrição:

# No backend.py, após @app.route('/api/transcribe/...')
import requests

def notify_webhook(transcription_data):
    webhook_url = os.environ.get('WEBHOOK_URL')
    if webhook_url:
        requests.post(webhook_url, json=transcription_data)

# Chamar após transcrever
notify_webhook({'status': 'complete', 'text': result['text']})

Adicionar autenticação:

from flask import request
from functools import wraps

def require_api_key(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        api_key = request.headers.get('X-API-Key')
        if api_key != os.environ.get('API_KEY'):
            return jsonify({'error': 'Invalid API key'}), 401
        return f(*args, **kwargs)
    return decorated

@app.route('/api/transcribe/youtube', methods=['POST'])
@require_api_key
def transcribe_youtube():
    # ...

Criar Temas Customizados

// Adicionar seletor de tema no index.html
const themes = {
  dark: {
    bg: '#1a1a1a',
    text: '#ffffff',
    primary: '#667eea'
  },
  light: {
    bg: '#ffffff',
    text: '#333333',
    primary: '#764ba2'
  }
};

function applyTheme(themeName) {
  const theme = themes[themeName];
  document.body.style.backgroundColor = theme.bg;
  document.body.style.color = theme.text;
  // ... aplicar outras cores
}

📊 Métricas e Monitorização

Logging Avançado

Adicionar ao backend.py:

import logging
from datetime import datetime

# Configurar logging
logging.basicConfig(
    filename='transcription.log',
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

# Usar nos endpoints
logging.info(f"Nova transcrição iniciada: {url}")
logging.info(f"Idioma detetado: {result['language']}")
logging.info(f"Duração: {duration}s")

Analytics Simples

# Criar contador de transcrições
import json
from pathlib import Path

STATS_FILE = 'stats.json'

def update_stats(language, duration, source):
    stats = {}
    if Path(STATS_FILE).exists():
        with open(STATS_FILE) as f:
            stats = json.load(f)
    
    stats.setdefault('total', 0)
    stats.setdefault('by_language', {})
    stats.setdefault('by_source', {})
    
    stats['total'] += 1
    stats['by_language'][language] = stats['by_language'].get(language, 0) + 1
    stats['by_source'][source] = stats['by_source'].get(source, 0) + 1
    
    with open(STATS_FILE, 'w') as f:
        json.dump(stats, f, indent=2)

Ver stats:

cat stats.json
# {
#   "total": 47,
#   "by_language": {"pt": 30, "en": 15, "es": 2},
#   "by_source": {"youtube": 20, "file": 27}
# }

🔐 Segurança e Privacidade

Dados Sensíveis

NUNCA transcrever:

Informação médica privada sem consentimento
Dados financeiros confidenciais
Conversas pessoais sem autorização
Material protegido por NDA

Boas Práticas

# 1. Limpar ficheiros temporários
rm /tmp/temp_audio_* 

# 2. Não partilhar transcrições sem permissão

# 3. Usar HTTPS em produção

# 4. Não logar API keys
# ❌ Errado:
logging.info(f"Using key: {api_key}")
# ✅ Correto:
logging.info("API key configured")

# 5. Limitar acesso ao servidor
# Usar firewall, autenticação, rate limiting

GDPR / Privacidade

Se operas na UE ou com dados de cidadãos EU:

✅ Informar utilizadores sobre processamento
✅ Obter consentimento para guardar transcrições
✅ Permitir eliminar dados
✅ Cifrar dados em repouso
✅ Logs de auditoria

🌍 Suporte Multi-Idioma

O Whisper suporta 99 idiomas automaticamente. Alguns exemplos:

Idioma	Código	Qualidade
Português	pt	⭐⭐⭐⭐⭐
Inglês	en	⭐⭐⭐⭐⭐
Espanhol	es	⭐⭐⭐⭐⭐
Francês	fr	⭐⭐⭐⭐⭐
Alemão	de	⭐⭐⭐⭐⭐
Italiano	it	⭐⭐⭐⭐
Russo	ru	⭐⭐⭐⭐
Japonês	ja	⭐⭐⭐⭐
Chinês	zh	⭐⭐⭐⭐
Árabe	ar	⭐⭐⭐

Forçar idioma específico:

# Em backend.py ou transcribe.py, alterar:
result = model.transcribe(
    audio_path,
    language='pt',  # Forçar português
    task="transcribe"
)

Quando forçar idioma:

Deteção automática falha
Múltiplos idiomas misturados
Sotaques fortes
Termos técnicos de outro idioma

✨ Funcionalidades Extra

Adicionar Sumário Executivo

def executive_summary(text, max_sentences=3):
    """Criar sumário ultra-curto"""
    sentences = text.split('.')
    return '. '.join(sentences[:max_sentences]) + '.'

Detetar Emoções (Básico)

def detect_emotion(text):
    """Análise básica de sentimento"""
    positive_words = ['ótimo', 'excelente', 'fantástico']
    negative_words = ['mau', 'péssimo', 'horrível']
    
    text_lower = text.lower()
    pos_count = sum(word in text_lower for word in positive_words)
    neg_count = sum(word in text_lower for word in negative_words)
    
    if pos_count > neg_count:
        return 'Positivo'
    elif neg_count > pos_count:
        return 'Negativo'
    return 'Neutro'

Extrair Keywords

from collections import Counter
import re

def extract_keywords(text, top_n=10):
    """Extrair palavras-chave mais frequentes"""
    words = re.findall(r'\b\w+\b', text.lower())
    # Remover stop words
    stop_words = set(['o', 'a', 'de', 'para', 'com', 'em'])
    words = [w for w in words if w not in stop_words and len(w) > 3]
    return Counter(words).most_common(top_n)

🎓 Recursos de Aprendizagem

Documentação Oficial

Whisper: https://github.com/openai/whisper
Claude API: https://docs.anthropic.com/
yt-dlp: https://github.com/yt-dlp/yt-dlp
Flask: https://flask.palletsprojects.com/

Tutoriais Recomendados

Whisper: "Speech Recognition with OpenAI Whisper"
Claude: "Building with Claude API"
Flask REST API: "Flask RESTful API Tutorial"

Comunidade

GitHub Issues: Para bugs e features
Stack Overflow: Tag whisper ou openai-whisper
Reddit: r/MachineLearning, r/learnpython

🎁 Extras e Bonus

No projeto estão incluídos:

✅ Script de instalação automática
✅ Guia de início rápido (QUICKSTART.md)
✅ Exemplos de uso
✅ Troubleshooting completo
✅ Interface moderna e responsiva
✅ CLI poderoso e flexível
✅ Documentação extensa

Funcionalidades ocultas:

# Ver informação detalhada
python transcribe.py -f audio.mp3 -o resultado --verbose

# Modo debug
FLASK_DEBUG=true python backend.py

# Estatísticas de performance
time python transcribe.py -f audio.mp3 -o resultado

🔍 Troubleshooting

Problemas Comuns e Soluções

❌ Erro: "FFmpeg não encontrado"

Causa: FFmpeg não está instalado ou não está no PATH

Solução:

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows (PowerShell admin)
choco install ffmpeg

# Verificar instalação
ffmpeg -version

❌ Erro: "Memória insuficiente" ou "Out of Memory"

Causa: Modelo Whisper muito grande para a RAM disponível

Soluções:

Usar modelo menor:

# Em backend.py, mudar de:
WHISPER_MODEL = "large"
# Para:
WHISPER_MODEL = "base"  # ou "tiny"

Processar ficheiros menores (dividir vídeo)
Fechar outras aplicações
Aumentar swap:

# Linux
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

❌ Erro: "Download falhou" (YouTube/Vimeo)

Causas possíveis:

Vídeo privado ou bloqueado geograficamente
URL incorreto
yt-dlp desatualizado

Soluções:

# Atualizar yt-dlp
pip install -U yt-dlp

# Verificar se o vídeo é acessível
yt-dlp --list-formats "URL_DO_VIDEO"

# Testar download manual
yt-dlp -f "bestaudio" "URL_DO_VIDEO"

❌ Chat não funciona / "Claude API não disponível"

Causa: API key não configurada ou inválida

Solução:

# Verificar se a chave está definida
echo $ANTHROPIC_API_KEY

# Se vazia, configurar:
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# Ou adicionar a .env
echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env

# Obter chave em: https://console.anthropic.com/

Alternativa sem Claude:

Resumo básico será gerado automaticamente
Chat não estará disponível

❌ Erro: "Port 5000 already in use"

Causa: Outra aplicação está a usar a porta 5000

Solução:

# Encontrar processo usando a porta
lsof -ti:5000  # Linux/Mac
netstat -ano | findstr :5000  # Windows

# Matar processo (Linux/Mac)
kill -9 $(lsof -ti:5000)

# Ou alterar porta em backend.py:
app.run(host='0.0.0.0', port=5001)  # Usar porta diferente

❌ Transcrição imprecisa ou com erros

Possíveis causas:

Áudio de má qualidade
Ruído de fundo elevado
Idioma não detetado corretamente
Modelo muito pequeno

Soluções:

Melhorar qualidade do áudio:

# Usar FFmpeg para limpar áudio
ffmpeg -i input.mp4 -af "highpass=f=200,lowpass=f=3000" -ar 16000 output.wav

Usar modelo maior:

WHISPER_MODEL = "medium"  # ou "large"

Forçar idioma (se deteção automática falhar):

result = model.transcribe(
    audio_path,
    language='pt',  # Forçar português
    task="transcribe"
)

❌ Erro: "ModuleNotFoundError"

Causa: Dependência não instalada

Solução:

# Ativar ambiente virtual
source venv/bin/activate

# Reinstalar dependências
pip install -r requirements.txt

# Se persistir, instalar manualmente
pip install flask whisper yt-dlp anthropic

❌ Lentidão no processamento

Otimizações:

Usar GPU (se disponível):

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

Usar modelo menor:

WHISPER_MODEL = "tiny"  # Mais rápido

Converter para MP3 antes:

ffmpeg -i video.mp4 -vn -ar 16000 -ac 1 audio.mp3
python transcribe.py -f audio.mp3

Fechar browser durante processamento CLI

🆘 Obter Ajuda

Se o problema persistir:

Verificar logs:

python backend.py 2>&1 | tee logs.txt

Informação do sistema:

python --version
pip list
ffmpeg -version

Criar issue com:
- Descrição do erro
- Logs completos
- Sistema operativo
- Comando executado

🗺️ Roadmap

✅ Versão Atual (v1.0)

🚧 Próxima Versão (v1.1)

Suporte para mais idiomas na interface
Editor de transcrições (correções inline)
Timestamps clicáveis (sincronização com vídeo)
Diarização (identificar múltiplos speakers)
Tradução automática entre idiomas

🔮 Futuro (v2.0+)

💡 Sugestões

Tens uma ideia? Abre um issue com:

Título: Feature Request - [Tua Ideia]
Descrição: Explicação detalhada
Caso de uso: Como ajudaria
Prioridade: Alta/Média/Baixa

🤝 Contribuir

Contribuições são bem-vindas!

Como Contribuir

Fork do repositório
Clone o teu fork:

git clone https://github.com/teu-user/video-transcription.git

Criar branch para a feature:

git checkout -b feature/minha-feature

Fazer commits:

git commit -m "Adiciona feature X"

Push para o teu fork:

git push origin feature/minha-feature

Abrir Pull Request

Guidelines

✅ Código limpo e comentado
✅ Testes para novas features
✅ Documentação atualizada
✅ Commits descritivos
✅ Seguir estilo do projeto

Áreas para Contribuir

🐛 Bug fixes
✨ Novas features
📝 Documentação
🌍 Traduções
🎨 Design/UI
⚡ Otimizações
🧪 Testes

📄 Licença

Este projeto está sob a licença MIT.

MIT License

Copyright (c) 2024

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🙏 Agradecimentos

Este projeto utiliza tecnologias incríveis de:

OpenAI Whisper - Motor de transcrição
Anthropic Claude - IA para resumos e chat
yt-dlp - Download de vídeos
Flask - Framework web
FFmpeg - Processamento multimédia

📞 Contacto & Suporte

📧 Email: [teu@email.com]
💬 Discussions: [GitHub Discussions]
🐛 Issues: [GitHub Issues]
📖 Wiki: [GitHub Wiki]

📊 Stats

Desenvolvido com ❤️ para transcrição inteligente de conteúdo multimédia

⭐ Se este projeto te ajudou, dá uma estrela no GitHub!

🏠 Home • 📖 Docs • 🚀 Quickstart • 🐛 Issues

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
__pycache__		__pycache__
.env		.env
.env.example		.env.example
LLM_PROVIDERS.md		LLM_PROVIDERS.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
backend.py		backend.py
index.html		index.html
install.sh		install.sh
llm_providers.py		llm_providers.py
requirements.txt		requirements.txt
transcribe.py		transcribe.py

DrNOFX97/YT2TXT

Folders and files

Latest commit

History

Repository files navigation

🎥 Sistema de Transcrição de Vídeo/Áudio com IA

📋 Índice

🎯 Sobre o Projeto

Por que usar este sistema?

Casos de Uso

🌟 Funcionalidades

🎬 Transcrição Multi-Fonte

🧠 IA Integrada

🔊 Transcrição com Whisper

📝 Resumo com Claude

💬 Chat Contextual

🎨 Duas Interfaces

🌐 Interface Web

💻 Linha de Comando

📦 Requisitos

Sistema Operativo

Software Base

Hardware Recomendado

Dependências Python

🚀 Instalação

Método 1: Instalação Automática (Recomendado)

Método 2: Instalação Manual

Passo 1: Instalar FFmpeg

Passo 2: Python e Dependências

Passo 3: Configurar API (Opcional)

Verificar Instalação

📖 Como Usar

🌐 Modo Web (Interface Gráfica)

1. Iniciar o Backend

2. Abrir Interface Web

3. Usar a Interface

💻 Modo CLI (Linha de Comando)

Sintaxe Básica

Exemplos Práticos

Ficheiros Gerados

🏗️ Arquitetura

Estrutura do Projeto

Fluxo de Funcionamento

Componentes Principais

1. Backend (backend.py)

2. Frontend (index.html)

3. CLI (transcribe.py)

⚙️ Configuração Avançada

Escolha do Modelo Whisper

Comparação de Modelos

Variáveis de Ambiente

CORS e Segurança

Otimização de Performance

1. Usar GPU (se disponível)

2. Cache de Modelos

3. Processamento Paralelo

Integração Docker

📦 Requisitos

Sistema Operativo

Software Base Obrigatório

Hardware Recomendado

Requisitos por Modelo Whisper

Dependências Python

Verificação de Requisitos

🚀 Instalação

🎯 Método 1: Instalação Automática (Recomendado)

🔧 Método 2: Instalação Manual Detalhada

Passo 1: Instalar FFmpeg

Ubuntu / Debian

macOS (Homebrew)

Windows

Passo 2: Configurar Python

Passo 3: Criar Ambiente Virtual

Passo 4: Instalar Dependências Python

Passo 5: Configurar API (Opcional mas Recomendado)

Passo 6: Verificar Instalação Completa

🐳 Método 3: Instalação com Docker (Avançado)

Criar Dockerfile

Build e Run

Docker Compose (Recomendado para Produção)