YouTube Transcript Fetcher

Obtén transcripciones de cualquier video de YouTube usando la transcripción de Whisper AI. Busca en YouTube y obtén transcripciones de los mejores resultados. No se requiere clave API de YouTube.

Características

Impulsado por Whisper — Transcripción de IA de última generación, más del 99% de precisión
Búsqueda en YouTube — Busca en YouTube y obtén transcripciones de los mejores resultados
No se necesita clave API — Funciona sin credenciales de la API de datos de YouTube
Múltiples formatos — Salida en texto, JSON, SRT, VTT
Almacenamiento en caché — La caché respaldada por SQLite evita volver a transcribir
Sin límites de tasa — Whisper se ejecuta localmente, sin límites de API externos
CLI y biblioteca — Úsalo como herramienta de línea de comandos o módulo de Python
Servidor MCP — Intégralo con herramientas de IA a través del Protocolo de Contexto de Modelo (MCP)

Instalación

# Clone the repository
git clone https://github.com/andrewctf/ytt.git
cd ytt

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Optional: GPU support
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

Nota: Para una configuración detallada de GPU/CUDA, consulta QUICKSTART.md.

Configuración adicional para Whisper

Whisper requiere ffmpeg para la extracción de audio:

Windows (con winget):

winget install ffmpeg

macOS:

brew install ffmpeg

Linux:

sudo apt install ffmpeg

Inicio rápido

Para obtener instrucciones detalladas de instalación y configuración, consulta QUICKSTART.md.

CLI

# Get transcript (Whisper is used by default)
python cli.py transcript VIDEO_ID

# Or with a full YouTube URL
python cli.py transcript "https://www.youtube.com/watch?v=a1JTPFfshI0"

# Different output formats
python cli.py transcript VIDEO_ID --format json
python cli.py transcript VIDEO_ID --format srt
python cli.py transcript VIDEO_ID --format vtt

# Save to file
python cli.py transcript VIDEO_ID --output transcript.txt

# Batch processing
python cli.py transcript VIDEO_ID1 VIDEO_ID2 VIDEO_ID3

# Search YouTube for videos and get transcripts
python cli.py search "Python tutorial" --limit 5 --with-transcripts

# Search only (no transcripts)
python cli.py search "Python tutorial" --limit 10

# JSON output for search
python cli.py search "Python tutorial" --format json

# Cache management
python cli.py cache-stats
python cli.py cache-stats --clean  # Remove expired entries

Biblioteca de Python

from src.service import get_transcript
from src.search_service import search, search_and_get_transcripts

# Basic usage
result = await get_transcript("VIDEO_ID")
print(result.content)

# With options
result = await get_transcript(
    "VIDEO_ID",
    language="en",
    output_format="json",
    use_cache=True,
)

# Access metadata
print(f"Source: {result.source}")      # 'whisper' or 'innertube'
print(f"Language: {result.language}")   # Detected language
print(f"Video ID: {result.video_id}")

# Search YouTube for videos
results = await search("Python tutorial", max_results=5)
for video in results:
    print(f"{video.title} ({video.video_id}) - {video.channel_name}")

# Search and get transcripts for results
results = await search_and_get_transcripts("Python tutorial", max_results=3, language="en")
for video, transcript in results:
    if transcript:
        print(f"{video.title}: {transcript.content[:100]}...")

Para uso síncrono:

import asyncio
from src.service import get_transcript
from src.search_service import search

def fetch_transcript(video_id):
    return asyncio.run(get_transcript(video_id))

def search_videos(query, max_results=5):
    return asyncio.run(search(query, max_results=max_results))

result = fetch_transcript("VIDEO_ID")
print(result.content)

videos = search_videos("Python tutorial")

Servidor MCP

Nota: Consulta QUICKSTART.md para obtener una configuración detallada con Claude Desktop, Cursor y VS Code.

Inicia el servidor MCP:

python -m mcp_server.server

El servidor expone tres herramientas:

get_transcript - Obtener transcripción para un solo video
get_transcripts_batch - Obtener transcripciones para múltiples videos simultáneamente
search_videos - Buscar videos en YouTube que coincidan con una consulta

O intégralo con Claude Desktop añadiéndolo a tu configuración de MCP:

{
  "mcpServers": {
    "yt-transcript": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/absolute/path/to/ytt"
    }
  }
}

Cómo funciona

Video ID → Cache Check
              ↓ found?
         Return Cached
              ↓ not found
         Whisper (primary)
         - Download audio via yt-dlp
         - Transcribe with faster-whisper
         - Returns word-level timestamps
              ↓ fails?
         Innertube API (fallback)
         - Extract API key from video page
         - Fetch caption tracks
         - Parse JSON3 timed text
              ↓
         Cache Result
              ↓
         Format & Return

Whisper (Principal)

Descarga audio usando yt-dlp
Transcribe usando faster-whisper (optimizado para CPU)
Devuelve marcas de tiempo a nivel de palabra y texto de segmento
Funciona en cualquier video con audio
Velocidad de procesamiento de ~1-3x en tiempo real

API de Innertube (Respaldo)

Extrae datos de la API interna de YouTube
No se requiere clave API
Rápido (~0.5-2s por video)
~85% de cobertura (algunos videos carecen de subtítulos)
Límite de tasa (~5 solicitudes/10s por IP)

Formatos de salida

Texto (predeterminado)

Good morning, here we are, a live suturing course like nobody else has ever
done and what are we covering, we're covering every suturing technique...

JSON

{
  "video_id": "a1JTPFfshI0",
  "language": "en",
  "source": "whisper",
  "segments": [
    {"start": 0.0, "end": 4.5, "text": "Good morning, here we are..."},
    {"start": 4.5, "end": 9.2, "text": "a live suturing course..."}
  ]
}

SRT (SubRip)

1
00:00:00,000 --> 00:00:04,500
Good morning, here we are, a live suturing course...

2
00:00:04,500 --> 00:00:09,200
a live suturing course like nobody else...

VTT (WebVTT)

WEBVTT

00:00:00.000 --> 00:00:04.500
Good morning, here we are, a live suturing course...

00:00:04.500 --> 00:00:09.200
a live suturing course like nobody else...

Configuración

Edita config.py para personalizar el comportamiento:

class Config:
    # Whisper settings
    WHISPER_MODEL = "base"      # tiny/base/small/medium/large
    WHISPER_FALLBACK_ENABLED = True

    # Cache settings
    CACHE_TTL_DAYS = 7
    CACHE_DB_PATH = ".transcript_cache.db"

    # Rate limiting (for Innertube fallback)
    RATE_LIMIT_RATE = 0.5       # tokens per second
    RATE_LIMIT_BURST = 5       # max bucket size

    # Batch processing
    MAX_BATCH_SIZE = 50

Modelos de Whisper

Modelo	Velocidad	Precisión	Memoria
tiny	10x	~75%	~1GB
base	7x	~85%	~1GB
small	4x	~90%	~2GB
medium	2x	~95%	~5GB
large	1x	~97%	~6GB

Se recomienda el modelo base para la mayoría de los casos de uso: rápido y lo suficientemente preciso.

Estructura de archivos

ytt/
├── src/
│   ├── __init__.py
│   ├── fetcher.py          # Innertube API client
│   ├── whisper_runner.py    # Whisper transcription
│   ├── parser.py            # Caption parsing utilities
│   ├── formatters.py        # Output formatters
│   ├── cache.py             # SQLite cache
│   ├── rate_limiter.py      # Token bucket
│   ├── service.py           # Orchestrator
│   ├── searcher.py          # YouTube search
│   ├── search_cache.py      # Search result cache
│   ├── search_service.py    # Search orchestrator
│   ├── cuda_dll_manager.py  # Auto-download CUDA libraries
│   └── exceptions.py        # Custom exceptions
├── mcp_server/
│   ├── __init__.py
│   └── server.py           # FastMCP server
├── cli.py                   # CLI entrypoint
├── main.py                  # Library entrypoint
├── config.py                # Configuration
├── requirements.txt         # Core dependencies
├── requirements-mcp.txt     # MCP dependencies
├── README.md
└── QUICKSTART.md

Solución de problemas

"No module named 'rich'"

Instala las dependencias:

pip install -r requirements.txt

Whisper falla con "ffmpeg not found"

Instala ffmpeg (consulta la sección de Instalación arriba).

Velocidad de transcripción lenta

Usa un modelo de Whisper más pequeño (base en lugar de large)
Usa aceleración por GPU cambiando device="cpu" a device="cuda" en whisper_runner.py
Habilita la caché para evitar volver a transcribir

Límite de tasa de Innertube

El respaldo de Innertube tiene un límite de tasa por parte de YouTube (~5 solicitudes/10s). Usa Whisper como principal (predeterminado) para evitar esto. La caché también evita solicitudes redundantes.

La caché no funciona

Verifica las estadísticas de la caché:

python cli.py cache-stats

Limpia las entradas caducadas:

python cli.py cache-stats --clean

Desarrollo

Ejecutar pruebas

pytest

Formatear código

black src/
ruff check src/

Licencia

Licencia MIT

YouTube Transcript Fetcher (YTT)