YouTube Transkript Ajan Becerisi

YouTube Transkript

YouTube videolarından transkriptleri (altyazıları/başlıkları) indirir. Hem manuel olarak oluşturulmuş hem de otomatik oluşturulmuş transkriptlerle çalışır. API anahtarı veya tarayıcı gerekmez — doğrudan YouTube'un InnerTube API'sini kullanır ve YouTube doğrudan API yolunu engellediğinde otomatik olarak yt-dlp'ye geri döner.

İlk çalıştırmada video meta verilerini ve kapak resmini getirir, hızlı yeniden biçimlendirme için ham verileri önbelleğe alır.

Betik Dizini

Betikler scripts/ alt dizininde bulunur. {baseDir} = bu SKILL.md'nin dizin yolu. ${BUN_X} çalışma zamanını çöz: bun yüklüyse → bun; npx mevcutsa → npx -y bun; aksi takdirde bun'u yüklemeyi öner. {baseDir} ve ${BUN_X}'i gerçek değerlerle değiştirin.

Kullanım

# Varsayılan: zaman damgalı işaretleme (İngilizce)
${BUN_X} {baseDir}/scripts/main.ts <youtube-url-veya-id>

# Dilleri belirt (öncelik sırasına göre)
${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja

# Zaman damgasız
${BUN_X} {baseDir}/scripts/main.ts <url> --no-timestamps

# Bölüm segmentasyonu ile
${BUN_X} {baseDir}/scripts/main.ts <url> --chapters

# Konuşmacı tanımlama ile (AI son işleme gerektirir)
${BUN_X} {baseDir}/scripts/main.ts <url> --speakers

# SRT altyazı dosyası
${BUN_X} {baseDir}/scripts/main.ts <url> --format srt

# Transkripti çevir
${BUN_X} {baseDir}/scripts/main.ts <url> --translate zh-Hans

# Mevcut transkriptleri listele
${BUN_X} {baseDir}/scripts/main.ts <url> --list

# Yeniden getir (önbelleği yoksay)
${BUN_X} {baseDir}/scripts/main.ts <url> --refresh

Seçenekler

İsteğe Bağlı Ortam Değişkenleri

Giriş Biçimleri

Video girişi olarak bunlardan herhangi birini kabul eder:

• Tam URL: https://www.youtube.com/watch?v=dQw4w9WgXcQ
• Kısa URL: https://youtu.be/dQw4w9WgXcQ
• Gömme URL'si: https://www.youtube.com/embed/dQw4w9WgXcQ
• Shorts URL'si: https://www.youtube.com/shorts/dQw4w9WgXcQ
• Video Kimliği: dQw4w9WgXcQ

Çıktı Biçimleri

Çıktı Dizini

youtube-transcript/
├── .index.json                          # Video kimliği → dizin yolu eşlemesi (önbellek araması için)
└── {channel-slug}/{title-full-slug}/
    ├── meta.json                        # Video meta verileri (başlık, kanal, açıklama, süre, bölümler vb.)
    ├── transcript-raw.json              # YouTube API'sinden ham transkript parçacıkları (önbelleğe alınmış)
    ├── transcript-sentences.json        # Cümle-segmentli transkript (noktalama ile bölünmüş, parçacıklar arasında birleştirilmiş)
    ├── imgs/
    │   └── cover.jpg                    # Video küçük resmi
    ├── transcript.md                    # Markdown transkript (cümlelerden oluşturulmuş)
    └── transcript.srt                   # SRT altyazı (ham parçacıklardan oluşturulmuş, eğer --format srt ise)

• {channel-slug}: Kanal adı kebab-case olarak
• {title-full-slug}: Tam video başlığı kebab-case olarak

--list modu yalnızca stdout'a çıkar (dosya kaydedilmez).

Önbellekleme

İlk getirmede betik şunları kaydeder:

• meta.json — video meta verileri, bölümler, kapak resmi yolu, dil bilgisi
• transcript-raw.json — YouTube API'sinden ham transkript parçacıkları ({ text, start, duration }[])
• transcript-sentences.json — cümle-segmentli transkript ({ text, start: "SS:dd:ss", end: "SS:dd:ss" }[]), cümle sonu noktalama ile bölünmüş (.?!…。？！ vb.), zaman damgaları karakter uzunluğuna orantılı olarak ayrılmış, CJK farkında metin birleştirme
• imgs/cover.jpg — video küçük resmi

Aynı video için sonraki çalıştırmalar önbelleğe alınmış verileri kullanır (ağ çağrısı yapılmaz). Yeniden getirmeye zorlamak için --refresh kullanın. Farklı bir dil talep edilirse, önbellek otomatik olarak yenilenir.

YouTube, doğrudan InnerTube yolunda bot karşıtı / engellenmiş yanıtlar döndürdüğünde, betik alternatif istemci kimlikleriyle yeniden dener ve ardından mevcutsa yt-dlp'ye geri döner. Geri dönüş gerekliyse ancak yt-dlp mevcut değilse, aracı kullanıcıya yükleme kararını bırakmak yerine yt-dlp'yi nasıl kullanılabilir hale getireceğine karar vermeli ve devam etmelidir.

SRT çıktısı (--format srt) transcript-raw.json'dan oluşturulur. Metin/markdown çıktısı doğal cümle sınırları için transcript-sentences.json'u kullanır.

İş Akışı

Kullanıcı bir YouTube URL'si sağladığında ve transkripti istediğinde:

1. Kullanıcı bir dil belirtmemişse, mevcut seçenekleri göstermek için önce --list ile çalıştırın
2. Betiği çalıştırırken URL'yi her zaman tek tırnak içine alın — zsh, ? işaretini bir glob joker karakteri olarak ele alır, bu nedenle tırnaksız bir YouTube URL'si "eşleşme bulunamadı" hatasına neden olur: 'https://www.youtube.com/watch?v=ID' kullanın
3. Varsayılan: En zengin çıktı için --chapters --speakers ile çalıştırın (bölümler + konuşmacı tanımlama)
4. Betik, önbelleğe alınmış verileri + çıktı dosyasını otomatik olarak kaydeder ve dosya yolunu yazdırır
5. --speakers modu için: betik ham dosyayı kaydettikten sonra, konuşmacı etiketleriyle son işlem yapmak için aşağıdaki konuşmacı tanımlama iş akışını izleyin

Kullanıcı yalnızca kapak resmi veya meta veri istediğinde, betiği herhangi bir seçenekle çalıştırmak ayrıca meta.json ve imgs/cover.jpg'yi önbelleğe alır.

Aynı videoyu yeniden biçimlendirirken (örneğin, önce metin sonra SRT), önbelleğe alınan veriler yeniden kullanılır — yeniden getirme gerekmez.

Bölüm ve Konuşmacı İş Akışı

Bölümler (--chapters)

Betik, video açıklamasındaki bölüm zaman damgalarını (ör. 0:00 Giriş) ayrıştırır, transkripti bölüm sınırlarına göre segmentlere ayırır, parçacıkları okunabilir paragraflara gruplandırır ve bir İçindekiler ile .md olarak kaydeder. Daha fazla işlem gerekmez.

Açıklamada bölüm zaman damgası yoksa, transkript bölüm başlıkları olmadan gruplandırılmış paragraflar olarak çıkar.

Konuşmacı Tanımlama (--speakers)

Konuşmacı tanımlama AI işlemi gerektirir. Betik aşağıdakileri içeren bir ham .md dosyası çıkarır:

• Video meta verileri (başlık, kanal, tarih, kapak, açıklama, dil) içeren YAML frontmatter
• Video açıklaması (konuşmacı adı çıkarma için)
• Açıklamadan bölüm listesi (varsa)
• SRT biçiminde ham transkript (önceden hesaplanmış başlangıç/bitiş zaman damgaları, token verimli)

Betik ham dosyayı kaydettikten sonra, konuşmacı tanımlamayı işlemek için bir alt aracı (maliyet verimliliği için Sonnet gibi daha ucuz bir model kullanın) başlatın:

1. Kaydedilen .md dosyasını okuyun
2. {baseDir}/prompts/speaker-transcript.md konumundaki istem şablonunu okuyun
3. Ham transkripti istem doğrultusunda işleyin:
   • Video meta verilerini kullanarak konuşmacıları tanımlayın (başlık → konuk, kanal → sunucu, açıklama → isimler)
   • Konuşma akışı, soru-cevap kalıpları ve bağlamsal ipuçlarından konuşmacı sıralarını tespit edin
   • Bölümlere ayırın (varsa açıklama bölümlerini kullanın, yoksa konu değişimlerinden oluşturun)
   • **Konuşmacı Adı:** etiketleri, paragraf gruplandırması (2-4 cümle) ve [SS:DD:SS → SS:DD:SS] zaman damgalarıyla biçimlendirin
4. .md dosyasını işlenmiş transkript ile üzerine yazın (YAML frontmatter'ı koruyun)

--speakers kullanıldığında, --chapters ima edilir — işlenmiş çıktı her zaman bölüm segmentasyonu içerir.

Hata Durumları