# Baoyu Youtube Transcript

> Descarga transcripciones/subtítulos e imágenes de portada de vídeos de YouTube por URL o ID, con soporte de idiomas, traducción, capítulos e identificación de hablantes.

Fuente: https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-youtube-transcript
Markdown: https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-youtube-transcript.md

Repositorio: https://github.com/JimLiu/baoyu-skills
Autor: JimLiu
Licencia: MIT
Actualizado: hace 4 meses
Coste de contexto: 117 tok instalada, 2.4k tok al activarse, 17.5k tok con todos los archivos del bundle
Bundle: 9 archivos, 68 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add JimLiu/baoyu-skills --skill baoyu-youtube-transcript --agent claude-code
# Cursor
npx -y skills add JimLiu/baoyu-skills --skill baoyu-youtube-transcript --agent cursor
# Codex
npx -y skills add JimLiu/baoyu-skills --skill baoyu-youtube-transcript --agent codex
# Gemini CLI
npx -y skills add JimLiu/baoyu-skills --skill baoyu-youtube-transcript --agent gemini
# Windsurf
npx -y skills add JimLiu/baoyu-skills --skill baoyu-youtube-transcript --agent windsurf
# Cline
npx -y skills add JimLiu/baoyu-skills --skill baoyu-youtube-transcript --agent cline
```

## Qué hace

- Descarga transcripciones/subtítulos de vídeos de YouTube por URL o ID, con timestamps, capítulos y traducción
- Descarga la imagen de portada (thumbnail) del vídeo
- Identifica hablantes en la transcripción usando un sub-agente de IA con etiquetas de tipo Speaker Name
- Cachea metadatos y transcripción cruda para reformatear rápido sin volver a llamar a la red
- Exporta en formato Markdown o SRT

## Cuándo usarla

- El usuario pide obtener/descargar una transcripción, subtítulos o captions de YouTube
- El usuario pide la imagen de portada o thumbnail de un vídeo de YouTube
- El usuario da una URL de YouTube y quiere el texto o el título/capítulos extraídos

## Qué la activa

- "Descárgame la transcripción de este vídeo de YouTube"
- "Consígueme los subtítulos en español de este video"
- "Quiero la miniatura/portada de este vídeo de YouTube"
- "Genera un SRT con los capítulos y hablantes identificados de este video"

## Antes de instalar

- Requiere `bun` o `npx` instalado; si YouTube bloquea el acceso directo, hace fallback a `yt-dlp` (opcionalmente con cookies de navegador vía YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER).
- Variables de entorno: BUN_X, INNERTUBE_URL, WATCH_URL, YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER
- makes network requests
- reads environment config

## Archivos

- SKILL.md — 9 KB
- prompts/speaker-transcript.md — 5 KB
- scripts/main.test.ts — 6 KB
- scripts/main.ts — 8 KB
- scripts/shared.ts — 3 KB
- scripts/storage.ts — 2 KB
- scripts/transcript.ts — 13 KB
- scripts/types.ts — 2 KB
- scripts/youtube.ts — 20 KB

## SKILL.md

Reproducido tal cual desde JimLiu/baoyu-skills bajo MIT. Esta sección es el documento original y está en inglés.

# YouTube Transcript

Downloads transcripts (subtitles/captions) from YouTube videos. Works with both manually created and auto-generated transcripts. No API key or browser required — uses YouTube's InnerTube API directly and automatically falls back to `yt-dlp` when YouTube blocks the direct API path.

Fetches video metadata and cover image on first run, caches raw data for fast re-formatting.

## Script Directory

Scripts in `scripts/` subdirectory. `{baseDir}` = this SKILL.md's directory path. Resolve `${BUN_X}` runtime: if `bun` installed → `bun`; if `npx` available → `npx -y bun`; else suggest installing bun. Replace `{baseDir}` and `${BUN_X}` with actual values.

| Script | Purpose |
|--------|---------|
| `scripts/main.ts` | Transcript download CLI |

## Usage

```bash
# Default: markdown with timestamps (English)
${BUN_X} {baseDir}/scripts/main.ts <youtube-url-or-id>

# Specify languages (priority order)
${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja

# Without timestamps
${BUN_X} {baseDir}/scripts/main.ts <url> --no-timestamps

# With chapter segmentation
${BUN_X} {baseDir}/scripts/main.ts <url> --chapters

# With speaker identification (requires AI post-processing)
${BUN_X} {baseDir}/scripts/main.ts <url> --speakers

# SRT subtitle file
${BUN_X} {baseDir}/scripts/main.ts <url> --format srt

# Translate transcript
${BUN_X} {baseDir}/scripts/main.ts <url> --translate zh-Hans

# List available transcripts
${BUN_X} {baseDir}/scripts/main.ts <url> --list

# Force re-fetch (ignore cache)
${BUN_X} {baseDir}/scripts/main.ts <url> --refresh
```

## Options

| Option | Description | Default |
|--------|-------------|---------|
| `<url-or-id>` | YouTube URL or video ID (multiple allowed) | Required |
| `--languages <codes>` | Language codes, comma-separated, in priority order | `en` |
| `--format <fmt>` | Output format: `text`, `srt` | `text` |
| `--translate <code>` | Translate to specified language code | |
| `--list` | List available transcripts instead of fetching | |
| `--timestamps` | Include `[HH:MM:SS → HH:MM:SS]` timestamps per paragraph | on |
| `--no-timestamps` | Disable timestamps | |
| `--chapters` | Chapter segmentation from video description | |
| `--speakers` | Raw transcript with metadata for speaker identification | |
| `--exclude-generated` | Skip auto-generated transcripts | |
| `--exclude-manually-created` | Skip manually created transcripts | |
| `--refresh` | Force re-fetch, ignore cached data | |
| `-o, --output <path>` | Save to specific file path | auto-generated |
| `--output-dir <dir>` | Base output directory | `youtube-transcript` |

## Optional Environment Variables

| Variable | Description |
|----------|-------------|
| `YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER` | Passed to `yt-dlp --cookies-from-browser` during fallback, e.g. `chrome`, `safari`, `firefox`, or `chrome:Profile 1` |

## Input Formats

Accepts any of these as video input:
- Full URL: `https://www.youtube.com/watch?v=dQw4w9WgXcQ`
- Short URL: `https://youtu.be/dQw4w9WgXcQ`
- Embed URL: `https://www.youtube.com/embed/dQw4w9WgXcQ`
- Shorts URL: `https://www.youtube.com/shorts/dQw4w9WgXcQ`
- Video ID: `dQw4w9WgXcQ`

## Output Formats

| Format | Extension | Description |
|--------|-----------|-------------|
| `text` | `.md` | Markdown with frontmatter (incl. `description`), title heading, summary, optional TOC/cover/timestamps/chapters/speakers |
| `srt` | `.srt` | SubRip subtitle format for video players |

## Output Directory

```
youtube-transcript/
├── .index.json                          # Video ID → directory path mapping (for cache lookup)
└── {channel-slug}/{title-full-slug}/
    ├── meta.json                        # Video metadata (title, channel, description, duration, chapters, etc.)
    ├── transcript-raw.json              # Raw transcript snippets from YouTube API (cached)
    ├── transcript-sentences.json        # Sentence-segmented transcript (split by punctuation, merged across snippets)
    ├── imgs/
    │   └── cover.jpg                    # Video thumbnail
    ├── transcript.md                    # Markdown transcript (generated from sentences)
    └── transcript.srt                   # SRT subtitle (generated from raw snippets, if --format srt)
```

- `{channel-slug}`: Channel name in kebab-case
- `{title-full-slug}`: Full video title in kebab-case

The `--list` mode outputs to stdout only (no file saved).

## Caching

On first fetch, the script saves:
- `meta.json` — video metadata, chapters, cover image path, language info
- `transcript-raw.json` — raw transcript snippets from YouTube API (`{ text, start, duration }[]`)
- `transcript-sentences.json` — sentence-segmented transcript (`{ text, start: "HH:mm:ss", end: "HH:mm:ss" }[]`), split by sentence-ending punctuation (`.?!…。？！` etc.), timestamps proportionally allocated by character length, CJK-aware text merging
- `imgs/cover.jpg` — video thumbnail

Subsequent runs for the same video use cached data (no network calls). Use `--refresh` to force re-fetch. If a different language is requested, the cache is automatically refreshed.

When YouTube returns anti-bot / blocked responses on the direct InnerTube path, the script retries with alternate client identities and then falls back to `yt-dlp` if available. If fallback is needed but `yt-dlp` is unavailable, the agent should decide how to make `yt-dlp` available and continue rather than pushing the installation decision to the user.

SRT output (`--format srt`) is generated from `transcript-raw.json`. Text/markdown output uses `transcript-sentences.json` for natural sentence boundaries.

## Workflow

When user provides a YouTube URL and wants the transcript:

1. Run with `--list` first if the user hasn't specified a language, to show available options
2. **Always single-quote the URL** when running the script — zsh treats `?` as a glob wildcard, so an unquoted YouTube URL causes "no matches found": use `'https://www.youtube.com/watch?v=ID'`
3. Default: run with `--chapters --speakers` for the richest output (chapters + speaker identification)
3. The script auto-saves cached data + output file and prints the file path
4. For `--speakers` mode: after the script saves the raw file, follow the speaker identification workflow below to post-process with speaker labels

When user only wants a cover image or metadata, running the script with any option will also cache `meta.json` and `imgs/cover.jpg`.

When re-formatting the same video (e.g., first text then SRT), the cached data is reused — no re-fetch needed.

## Chapter & Speaker Workflow

### Chapters (`--chapters`)

The script parses chapter timestamps from the video description (e.g., `0:00 Introduction`), segments the transcript by chapter boundaries, groups snippets into readable paragraphs, and saves as `.md` with a Table of Contents. No further processing needed.

If no chapter timestamps exist in the description, the transcript is output as grouped paragraphs without chapter headings.

### Speaker Identification (`--speakers`)

Speaker identification requires AI processing. The script outputs a raw `.md` file containing:
- YAML frontmatter with video metadata (title, channel, date, cover, description, language)
- Video description (for speaker name extraction)
- Chapter list from description (if available)
- Raw transcript in SRT format (pre-computed start/end timestamps, token-efficient)

After the script saves the raw file, spawn a sub-agent (use a cheaper model like Sonnet for cost efficiency) to process speaker identification:

1. Read the saved `.md` file
2. Read the prompt template at `{baseDir}/prompts/speaker-transcript.md`
3. Process the raw transcript following the prompt:
   - Identify speakers using video metadata (title → guest, channel → host, description → names)
   - Detect speaker turns from conversation flow, question-answer patterns, and contextual cues
   - Segment into chapters (use description chapters if available, else create from topic shifts)
   - Format with `**Speaker Name:**` labels, paragraph grouping (2-4 sentences), and `[HH:MM:SS → HH:MM:SS]` timestamps
4. Overwrite the `.md` file with the processed transcript (keep the YAML frontmatter)

When `--speakers` is used, `--chapters` is implied — the processed output always includes chapter segmentation.

## Error Cases

| Error | Meaning |
|-------|---------|
| Transcripts disabled | Video has no captions at all |
| No transcript found | Requested language not available |
| Video unavailable | Video deleted, private, or region-locked |
| IP blocked | Too many requests, try again later |
| Age restricted | Video requires login for age verification |
| bot detected | The script retries alternate clients and then `yt-dlp`; if fallback tooling is missing, the agent should resolve that itself, otherwise if it still fails try `YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER=safari` (or your browser) |

## Dónde encaja

- Categoría: [Productividad](https://skillsagentes.com/categorias/productividad.md) — Planificación, toma de notas y automatización de flujos personales.
- Creador: [JimLiu](https://skillsagentes.com/creators/jimliu.md) — 0 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Baoyu Image Gen](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-image-gen.md): Generación de imágenes con IA usando OpenAI GPT Image 2, Azure OpenAI, Google, OpenRouter, DashScope, Z.AI GLM-Image, MiniMax, Jimeng, Seedream, Replicate y Agnes; soporta texto a imagen, referencias, aspectos y lotes.
- [Baoyu Post To Wechat](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-post-to-wechat.md): Publica contenido en WeChat Official Account (微信公众号) vía API o Chrome CDP, con posts de artículo (文章) o de imagen-texto (贴图/图文).
- [Baoyu Wechat Summary](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-wechat-summary.md): Convierte los chats de un grupo de WeChat en un resumen estructurado usando el binario local wx-cli, con historial, perfiles de usuario y memoria de hechos por grupo entre ejecuciones.
- [Baoyu Post To X](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-post-to-x.md): Publica contenido y artículos en X (Twitter): posts normales con imágenes/vídeos y X Articles en Markdown, vía plugin Chrome de Codex, Computer Use o scripts CDP.
- [Baoyu Cover Image](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-cover-image.md): Genera portadas de artículos con 5 dimensiones (tipo, paleta, renderizado, texto, mood), combinando 11 paletas y 7 estilos de renderizado, en formatos cinematic, widescreen o square.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)