Prosey

Prosey es una herramienta CLI para descargar y mostrar transcripciones de vídeo de YouTube, para que puedas obtener la información que buscas sin perder horas.

Los casos de uso principales son:

• Resumir un vídeo de YouTube y mostrarlo en la CLI con un solo comando (más rápido).
• Leer los subtítulos del vídeo, formateados y organizados en capítulos como el vídeo original (a menudo requiere más tiempo).

Ambos usos necesitan un asistente de IA en tu sistema (por defecto: opencode, usa prosey config para configurar el tuyo).

Si detectamos un resaltador de sintaxis en tu sistema, obtendrás una salida con colores agradable.

Prosey también puede generar o almacenar el formato json nativo tal cual.

Características

Inicio rápido

Pruébalo de inmediato con npx:

npx @tacone/prosey 771PQEDeRmw
npx @tacone/prosey https://youtu.be/771PQEDeRmw --lang es -o transcript.txt

Instalación

Instala globalmente con tu gestor de paquetes favorito:

npm install -g @tacone/prosey
# o
yarn global add @tacone/prosey
# o
pnpm add -g @tacone/prosey
# o
bun install -g @tacone/prosey

Luego úsalo en cualquier lugar:

prosey 771PQEDeRmw

Desde el código fuente

Usa Bun para el desarrollo — scripts, gestión de paquetes y ejecución directa del código fuente TypeScript.

git clone https://github.com/tacone/prosey.git
cd prosey
bun install
bun run start -- 771PQEDeRmw

Uso

prosey [options] <video controls-url-or-id>
prosey read [options] <video controls-url-or-id>
prosey info [options] <video controls-url-or-id>
prosey summarize [options] <video controls-url-or-id>
prosey index
prosey render
prosey config
prosey help

summarize es el comando por defecto, por lo que prosey <id> ejecuta el resumidor de IA. Usa prosey read <id> para descargar e imprimir una transcripción ricamente formateada.

El comando summarize obtiene una transcripción, antepone el prompt de la sección de configuración [summarize] y envía el resultado al comando de IA configurado.

El comando read descarga la transcripción y la imprime en stdout (texto plano, markdown o JSON). Esto es útil cuando no necesitas procesamiento con IA.

El comando info muestra los metadatos del vídeo (título, canal, duración, vistas).

El comando index reconstruye el índice de documentos y lo abre en el navegador. El índice lista cada resumen y transcripción almacenados en el directorio de datos y se reconstruye automáticamente después de cada ejecución de summarize/transcribe. Al hacer clic en el logotipo de Prosey en cualquier página de contenido se vuelve a él.

El comando render regenera cada página HTML a partir del markdown en caché (sin red ni procesamiento con IA) y reescribe el índice.

El comando config abre tu archivo de configuración en $EDITOR para editarlo. Si $EDITOR no está configurado, se imprime la ruta del archivo de configuración.

El comando help muestra el mensaje de ayuda, igual que --help.

Ejemplos

# Resumir (resumen con IA + formateo + resaltado de sintaxis)
prosey 771PQEDeRmw

# Resumir (igual que arriba)
prosey summarize 771PQEDeRmw

# Transcribir (resumen con IA + formateo + resaltado de sintaxis)
prosey read 771PQEDeRmw

# Mostrar metadatos del vídeo
prosey info 771PQEDeRmw

# Editar configuración en $EDITOR
prosey config

# Listar idiomas disponibles
prosey read https://youtu.be/771PQEDeRmw --list

# Especificar idioma
prosey read https://youtu.be/771PQEDeRmw --lang es

# Mostrar JSON (sin transcripción con IA)
prosey read 771PQEDeRmw

# Mostrar texto plano (sin transcripción con IA)
prosey read 771PQEDeRmw

# Guardar transcripción en un archivo
prosey read 771PQEDeRmw -o transcript.txt

Opciones

Formato JSON

Cuando se usa --json, la salida es un array de objetos:

[
  {
    "text": "♪ We're no strangers to love ♪",
    "offset": 18.64,
    "duration": 3.24,
    "timestamp": "00:18"
  }
]

timestamp siempre está presente en modo JSON. Los detalles del vídeo se suprimen (silenciosamente) ya que JSON son datos estructurados.

Desarrollo

Este proyecto usa Bun para el desarrollo.

bun run typecheck   # Comprobación de TypeScript
bun run start       # Ejecutar la CLI desde el código fuente
bun run test        # Ejecutar pruebas unitarias
bun run build       # Compilar el bundle de Node en bin/prosey

Antes de publicar en npm, bun run build se ejecuta automáticamente mediante el hook prepack, generando un bundle JS compatible con Node en bin/prosey.

Configuración

Prosey lee la configuración de un archivo TOML. La ubicación sigue la Especificación de directorio base XDG (~/.config/prosey/config.toml), o puedes establecer la variable de entorno PROSEY_CONFIG_PATH para usar una ruta personalizada.

El archivo de configuración se crea automáticamente en la primera ejecución con valores por defecto. Usa --reset-config para restaurar los valores por defecto en cualquier momento.

pager

Comando del paginador para la salida de transcripciones y resúmenes. El valor por defecto es "auto", que detecta el primero disponible entre: bat -lmd --style plain → glow -p → mdcat -l -p → less. Establece un comando personalizado (p. ej. "less -R") para sobrescribirlo. La variable de entorno PROSEY_PAGER tiene prioridad sobre esta configuración.

[summarize]

La sección [summarize] configura el comando summarize:

PROSEY_PAGER

Variable de entorno para establecer el comando del paginador. Tiene prioridad sobre el valor de configuración pager. Establece "auto" o déjala vacía para usar la detección automática.

Caché

Las transcripciones y resúmenes se guardan en caché en /tmp/prosey/. Las invocaciones repetidas para el mismo vídeo y opciones son instantáneas y funcionan sin conexión. Usa --no-cache para omitir las lecturas de caché y forzar una descarga nueva.

Al ejecutar prosey summarize, el comando se ejecuta dentro del directorio de caché de ese vídeo. Esto evita que el agente de IA recoja archivos específicos del proyecto como AGENTS.md o CLAUDE.md de la carpeta actual, y limita su capacidad de modificar archivos fuera de ese directorio.

Códigos de salida

Cómo funciona

prosey usa la API Innertube de YouTube mediante la biblioteca youtube-transcript-plus. No se requieren claves API ni automatización del navegador.

La herramienta funciona tanto con subtítulos creados manualmente como con transcripciones generadas automáticamente (conversión de voz a texto de YouTube). La detección automática recorre los idiomas en el orden proporcionado por la respuesta del reproductor de YouTube.