Whisper
Resumen
Transcribe audio con OpenAI Whisper, el modelo de reconocimiento de voz de última generación. Esta habilidad cubre Whisper local (Python), faster-whisper (CTranslate2, 4 veces más rápido), whisper.cpp (C++ optimizado para CPU) y la API de OpenAI Whisper. Incluye generación de subtítulos (SRT/VTT/JSON), transcripción en múltiples idiomas, traducción al inglés, diarización de hablantes, marcas de tiempo a nivel de palabra y patrones de pipeline de producción para podcasts, reuniones y subtítulos de video.
Instrucciones
Paso 1: Elige tu entorno de ejecución
Opción A — OpenAI Whisper (Python original):
pip install openai-whisper
# Modelos: tiny (39M), base (74M), small (244M), medium (769M), large-v3 (1.5G)
Opción B — faster-whisper (recomendado para local, 4 veces más rápido):
pip install faster-whisper
# Usa CTranslate2 — cuantificación INT8, funciona bien en CPU
Opción C — whisper.cpp (mejor para CPU, dependencias mínimas):
git clone https://github.com/ggerganov/whisper.cpp
cd whisper.cpp && make
# Descargar modelo
bash models/download-ggml-model.sh base.en
Opción D — API de OpenAI (sin necesidad de GPU local):
pip install openai
export OPENAI_API_KEY="sk-..."
Paso 2: Transcripción básica
faster-whisper (recomendado):
from faster_whisper import WhisperModel
model = WhisperModel("base", device="cpu", compute_type="int8")
# GPU: model = WhisperModel("large-v3", device="cuda", compute_type="float16")
segments, info = model.transcribe("episode.mp3", beam_size=5)
print(f"Idioma: {info.language} (prob: {info.language_probability:.2f})")
for segment in segments:
print(f"[{segment.start:.2f}s → {segment.end:.2f}s] {segment.text}")
OpenAI Whisper (original):
import whisper
model = whisper.load_model("base") # tiny, base, small, medium, large-v3
result = model.transcribe("episode.mp3")
print(result["text"])
for segment in result["segments"]:
print(f"[{segment['start']:.1f}s - {segment['end']:.1f}s] {segment['text']}")
whisper.cpp (CLI):
./main -m models/ggml-base.en.bin -f episode.wav -otxt -osrt -ovtt
# Salida: episode.txt, episode.srt, episode.vtt
API de OpenAI:
from openai import OpenAI
client = OpenAI()
with open("episode.mp3", "rb") as f:
transcript = client.audio.transcriptions.create(
model="whisper-1",
file=f,
response_format="verbose_json",
timestamp_granularities=["segment", "word"],
)
print(transcript.text)
for segment in transcript.segments:
print(f"[{segment.start:.1f}s] {segment.text}")
Paso 3: Generación de subtítulos (SRT/VTT)
Generar SRT con faster-whisper:
from faster_whisper import WhisperModel
model = WhisperModel("small", device="cpu", compute_type="int8")
segments, info = model.transcribe("episode.mp3", beam_size=5)
def format_timestamp(seconds):
h = int(seconds // 3600)
m = int((seconds % 3600) // 60)
s = int(seconds % 60)
ms = int((seconds % 1) * 1000)
return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
with open("episode.srt", "w") as f:
for i, seg in enumerate(segments, 1):
f.write(f"{i}\n")
f.write(f"{format_timestamp(seg.start)} --> {format_timestamp(seg.end)}\n")
f.write(f"{seg.text.strip()}\n\n")
print("Generado episode.srt")
Generar VTT (para video HTML5):
with open("episode.vtt", "w") as f:
f.write("WEBVTT\n\n")
for i, seg in enumerate(segments, 1):
start = format_timestamp(seg.start).replace(",", ".")
end = format_timestamp(seg.end).replace(",", ".")
f.write(f"{start} --> {end}\n")
f.write(f"{seg.text.strip()}\n\n")
Marcas de tiempo a nivel de palabra (para subtítulos estilo karaoke):
segments, info = model.transcribe("episode.mp3", word_timestamps=True)
for segment in segments:
for word in segment.words:
print(f" [{word.start:.2f}s → {word.end:.2f}s] {word.word}")
Paso 4: Detección de idioma y traducción
# Detección automática de idioma
segments, info = model.transcribe("foreign_audio.mp3")
print(f"Detectado: {info.language} ({info.language_probability:.0%})")
# Forzar un idioma específico
segments, info = model.transcribe("german.mp3", language="de")
# Traducir al inglés (cualquier idioma → inglés)
segments, info = model.transcribe("german.mp3", task="translate")
for seg in segments:
print(seg.text) # Traducción al inglés
Idiomas compatibles: 99 idiomas, incluyendo en, zh, de, es, ru, ko, fr, ja, pt, tr, pl, nl, ar, sv, it, hi, y muchos más.
Paso 5: Diarización de hablantes
Combina Whisper con pyannote-audio para identificar "quién dijo qué":
from faster_whisper import WhisperModel
from pyannote.audio import Pipeline
import torch
# Transcribir
model = WhisperModel("small", device="cpu", compute_type="int8")
segments, info = model.transcribe("meeting.wav", beam_size=5)
whisper_segments = list(segments)
# Diarizar (requiere token de HuggingFace con acceso a pyannote)
diarization = Pipeline.from_pretrained(
"pyannote/speaker-diarization-3.1",
use_auth_token="hf_YOUR_TOKEN"
)
diarization_result = diarization("meeting.wav")
# Fusionar: asignar hablante a cada segmento de whisper
def get_speaker(start, end, diarization_result):
"""Encuentra el hablante dominante durante un rango de tiempo."""
speakers = {}
for turn, _, speaker in diarization_result.itertracks(yield_label=True):
overlap_start = max(start, turn.start)
overlap_end = min(end, turn.end)
if overlap_start < overlap_end:
duration = overlap_end - overlap_start
speakers[speaker] = speakers.get(speaker, 0) + duration
return max(speakers, key=speakers.get) if speakers else "Desconocido"
for seg in whisper_segments:
speaker = get_speaker(seg.start, seg.end, diarization_result)
print(f"[{speaker}] [{seg.start:.1f}s → {seg.end:.1f}s] {seg.text}")
Paso 6: Procesamiento por lotes y pipelines
Transcribir todos los episodios en un directorio:
import os
from pathlib import Path
from faster_whisper import WhisperModel
model = WhisperModel("small", device="cpu", compute_type="int8")
episodes_dir = Path("episodes")
output_dir = Path("transcripts")
output_dir.mkdir(exist_ok=True)
for audio_file in sorted(episodes_dir.glob("*.mp3")):
print(f"Transcribiendo: {audio_file.name}")
segments, info = model.transcribe(str(audio_file), beam_size=5)
# Texto plano
txt_path = output_dir / f"{audio_file.stem}.txt"
with open(txt_path, "w") as f:
for seg in segments:
f.write(seg.text.strip() + "\n")
# SRT
srt_path = output_dir / f"{audio_file.stem}.srt"
segments2, _ = model.transcribe(str(audio_file), beam_size=5) # Re-iterar
with open(srt_path, "w") as f:
for i, seg in enumerate(segments2, 1):
h, m = divmod(int(seg.start), 3600)
m, s = divmod(m, 60)
ms = int((seg.start % 1) * 1000)
start_ts = f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
h2, m2 = divmod(int(seg.end), 3600)
m2, s2 = divmod(m2, 60)
ms2 = int((seg.end % 1) * 1000)
end_ts = f"{h2:02d}:{m2:02d}:{s2:02d},{ms2:03d}"
f.write(f"{i}\n{start_ts} --> {end_ts}\n{seg.text.strip()}\n\n")
print(f" → {txt_path}, {srt_path}")
Paso 7: Guía de selección de modelos
| Modelo | Tamaño | VRAM | Velocidad (CPU) | Precisión | Mejor para |
|---|---|---|---|---|---|
| tiny | 39M | ~1GB | Muy rápida | Baja | Borradores rápidos, tiempo real |
| base | 74M | ~1GB | Rápida | Media | Buen equilibrio para CPU |
| small | 244M | ~2GB | Moderada | Buena | Podcasts, audio claro |
| medium | 769M | ~5GB | Lenta | Muy buena | Audio ruidoso, acentos |
| large-v3 | 1.5G | ~10GB | Muy lenta | Mejor | Calidad de producción |
Recomendaciones:
- Solo CPU, la velocidad importa:
tinyobasecon faster-whisper - Solo CPU, la precisión importa:
smallcon faster-whisper - GPU disponible:
large-v3con faster-whisper (float16) - Sin cómputo local: API de OpenAI (
whisper-1)
Ejemplos
Ejemplo 1: Transcribir una temporada de podcast y generar subtítulos SRT
Solicitud del usuario: "Transcribe los 20 episodios MP3 en ./episodes/ y genera transcripciones de texto plano y archivos de subtítulos SRT. Tengo una GPU con 10 GB de VRAM."
El agente:
- Instalará faster-whisper mediante
pip install faster-whisper. - Cargará el modelo
large-v3condevice="cuda"ycompute_type="float16"para aprovechar la GPU. - Creará un directorio de salida
./transcripts/. - Recorrerá todos los archivos
.mp3en./episodes/, transcribiendo cada uno conbeam_size=5. - Escribirá un archivo
.txt(texto plano) y un archivo.srt(con marcas de tiempo formateadas correctamente) para cada episodio. - Reportará el idioma detectado y el tiempo total de procesamiento por episodio.
Ejemplo 2: Traducir una entrevista en alemán al inglés con etiquetas de hablante
Solicitud del usuario: "Tengo una grabación de una entrevista en alemán de 45 minutos en meeting.wav con dos hablantes. Transcríbela al inglés y etiqueta quién dijo qué."
El agente:
- Instalará faster-whisper y pyannote-audio (
pip install faster-whisper pyannote.audio). - Transcribirá
meeting.wavcontask="translate"para obtener texto en inglés a partir del audio en alemán. - Ejecutará la diarización de hablantes de pyannote para identificar segmentos de hablantes (requiere un token de HuggingFace con acceso al modelo pyannote).
- Fusionará los segmentos de Whisper con los resultados de la diarización emparejando rangos de tiempo para asignar etiquetas de hablante.
- Generará una transcripción formateada con etiquetas
[Speaker 1]y[Speaker 2]antes de cada segmento.
Pautas
- Usa faster-whisper en lugar del Whisper original de OpenAI para transcripción local; es 4 veces más rápido y usa menos memoria gracias a la cuantificación INT8 mediante CTranslate2.
- Selecciona el tamaño del modelo según tu hardware:
tiny/basepara velocidad en CPU,smallpara precisión en CPU,large-v3para calidad de producción en GPU. - Siempre convierte el audio a WAV o asegúrate de tener ffmpeg instalado al trabajar con entradas MP3/M4A; Whisper depende de ffmpeg para decodificar formatos que no sean WAV.
- Para la diarización de hablantes, el pipeline de pyannote requiere un token de acceso de HuggingFace con los términos del modelo aceptados; configura esto antes de intentar transcripciones con múltiples hablantes.
- Al generar archivos SRT, usa
beam_size=5para límites de segmento más precisos; la decodificación greedy predeterminada puede producir cortes de subtítulos mal temporizados.