Competenza Agente Trascrizioni YouTube

Trascrizione YouTube

Scarica trascrizioni (sottotitoli/didascalie) da video YouTube. Funziona sia con trascrizioni create manualmente che generate automaticamente. Nessuna chiave API o browser richiesto — utilizza direttamente l'API InnerTube di YouTube e ricorre automaticamente a yt-dlp quando YouTube blocca il percorso API diretto.

Recupera i metadati del video e l'immagine di copertina alla prima esecuzione, memorizza nella cache i dati grezzi per una riformattazione rapida.

Directory degli script

Script nella sottodirectory scripts/. {baseDir} = percorso della directory di questo SKILL.md. Risolvi il runtime ${BUN_X}: se bun installato → bun; se npx disponibile → npx -y bun; altrimenti suggerisci di installare bun. Sostituisci {baseDir} e ${BUN_X} con i valori effettivi.

Utilizzo

# Predefinito: markdown con timestamp (inglese)
${BUN_X} {baseDir}/scripts/main.ts <youtube-url-or-id>

# Specifica le lingue (ordine di priorità)
${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja

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

# Con segmentazione per capitoli
${BUN_X} {baseDir}/scripts/main.ts <url> --chapters

# Con identificazione dell'oratore (richiede post-elaborazione AI)
${BUN_X} {baseDir}/scripts/main.ts <url> --speakers

# File di sottotitoli SRT
${BUN_X} {baseDir}/scripts/main.ts <url> --format srt

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

# Elenca le trascrizioni disponibili
${BUN_X} {baseDir}/scripts/main.ts <url> --list

# Forza il ri-recupero (ignora la cache)
${BUN_X} {baseDir}/scripts/main.ts <url> --refresh

Opzioni

Variabili d'ambiente opzionali

Formati di input

Accetta uno qualsiasi di questi come input video:

• URL completo: https://www.youtube.com/watch?v=dQw4w9WgXcQ
• URL abbreviato: https://youtu.be/dQw4w9WgXcQ
• URL embed: https://www.youtube.com/embed/dQw4w9WgXcQ
• URL Shorts: https://www.youtube.com/shorts/dQw4w9WgXcQ
• ID video: dQw4w9WgXcQ

Formati di output

Directory di output

youtube-transcript/
├── .index.json                          # Mappatura ID video → percorso directory (per la ricerca nella cache)
└── {channel-slug}/{title-full-slug}/
    ├── meta.json                        # Metadati del video (titolo, canale, descrizione, durata, capitoli, ecc.)
    ├── transcript-raw.json              # Frammenti grezzi di trascrizione dall'API di YouTube (in cache)
    ├── transcript-sentences.json        # Trascrizione segmentata in frasi (divisa per punteggiatura, unita tra i frammenti)
    ├── imgs/
    │   └── cover.jpg                    # Miniatura del video
    ├── transcript.md                    # Trascrizione in Markdown (generata dalle frasi)
    └── transcript.srt                   # Sottotitoli SRT (generati dai frammenti grezzi, se --format srt)

• {channel-slug}: Nome del canale in kebab-case
• {title-full-slug}: Titolo completo del video in kebab-case

La modalità --list produce output solo su stdout (nessun file salvato).

Memorizzazione nella cache

Al primo recupero, lo script salva:

• meta.json — metadati del video, capitoli, percorso dell'immagine di copertina, informazioni sulla lingua
• transcript-raw.json — frammenti grezzi di trascrizione dall'API di YouTube ({ text, start, duration }[])
• transcript-sentences.json — trascrizione segmentata in frasi ({ text, start: "HH:mm:ss", end: "HH:mm:ss" }[]), divisa per punteggiatura di fine frase (.?!…。？！ ecc.), timestamp allocati proporzionalmente alla lunghezza dei caratteri, unione del testo consapevole dei caratteri CJK
• imgs/cover.jpg — miniatura del video

Le esecuzioni successive per lo stesso video utilizzano i dati memorizzati nella cache (nessuna chiamata di rete). Usa --refresh per forzare il ri-recupero. Se viene richiesta una lingua diversa, la cache viene automaticamente aggiornata.

Quando YouTube restituisce risposte anti-bot / bloccate sul percorso InnerTube diretto, lo script ritenta con identità client alternative e poi ricorre a yt-dlp se disponibile. Se è necessario il fallback ma yt-dlp non è disponibile, l'agente dovrebbe decidere come rendere disponibile yt-dlp e continuare anziché scaricare la decisione di installazione sull'utente.

L'output SRT (--format srt) è generato da transcript-raw.json. L'output testo/markdown utilizza transcript-sentences.json per limiti di frase naturali.

Flusso di lavoro

Quando l'utente fornisce un URL di YouTube e desidera la trascrizione:

1. Esegui prima con --list se l'utente non ha specificato una lingua, per mostrare le opzioni disponibili
2. Metti sempre tra virgolette singole l'URL quando esegui lo script — zsh tratta ? come un carattere jolly glob, quindi un URL di YouTube senza virgolette causa "nessuna corrispondenza trovata": usa 'https://www.youtube.com/watch?v=ID'
3. Predefinito: esegui con --chapters --speakers per l'output più ricco (capitoli + identificazione oratore)
4. Lo script salva automaticamente i dati nella cache + il file di output e stampa il percorso del file
5. Per la modalità --speakers: dopo che lo script ha salvato il file grezzo, segui il flusso di lavoro per l'identificazione dell'oratore descritto di seguito per post-elaborare con etichette degli oratori

Quando l'utente desidera solo un'immagine di copertina o i metadati, eseguire lo script con qualsiasi opzione memorizzerà comunque nella cache meta.json e imgs/cover.jpg.

Quando si riformatta lo stesso video (ad es., prima testo poi SRT), i dati nella cache vengono riutilizzati — nessun ri-recupero necessario.

Flusso di lavoro per capitoli e oratori

Capitoli (--chapters)

Lo script analizza i timestamp dei capitoli dalla descrizione del video (ad es., 0:00 Introduzione), segmenta la trascrizione in base ai confini dei capitoli, raggruppa i frammenti in paragrafi leggibili e salva come .md con un indice. Nessuna ulteriore elaborazione necessaria.

Se non esistono timestamp dei capitoli nella descrizione, la trascrizione viene emessa come paragrafi raggruppati senza intestazioni di capitolo.

Identificazione dell'oratore (--speakers)

L'identificazione dell'oratore richiede l'elaborazione AI. Lo script produce un file .md grezzo contenente:

• Frontmatter YAML con metadati del video (titolo, canale, data, copertina, descrizione, lingua)
• Descrizione del video (per l'estrazione dei nomi degli oratori)
• Elenco dei capitoli dalla descrizione (se disponibile)
• Trascrizione grezza in formato SRT (timestamp di inizio/fine precalcolati, efficiente in termini di token)

Dopo che lo script ha salvato il file grezzo, genera un sotto-agente (usa un modello più economico come Sonnet per efficienza dei costi) per elaborare l'identificazione dell'oratore:

1. Leggi il file .md salvato
2. Leggi il modello di prompt in {baseDir}/prompts/speaker-transcript.md
3. Elabora la trascrizione grezza seguendo il prompt:
   • Identifica gli oratori usando i metadati del video (titolo → ospite, canale → conduttore, descrizione → nomi)
   • Rileva i turni degli oratori dal flusso della conversazione, pattern domanda-risposta e indizi contestuali
   • Segmenta in capitoli (usa i capitoli della descrizione se disponibili, altrimenti crea dai cambi di argomento)
   • Formatta con etichette **Nome Oratore:**, raggruppamento in paragrafi (2-4 frasi) e timestamp [HH:MM:SS → HH:MM:SS]
4. Sovrascrivi il file .md con la trascrizione elaborata (mantieni il frontmatter YAML)

Quando viene usato --speakers, --chapters è implicito — l'output elaborato include sempre la segmentazione in capitoli.

Casi di errore