@azerogluemin/ai-bootstrap 0.2.1

package/templates/skills/youtube-thumbnail-designer/knowledge/youtube-analysis.md

@@ -0,0 +1,289 @@
+# YouTube Analysis — Link parse + script analysis procedure
+
+> Skill iki input mode-u qəbul edir: YouTube link və ya ssenari fayl yolu. Bu fayl analiz prosedurunu və çıxarılacaq field-ləri saxlayır.
+
+## Contents
+
+1. Input mode tanıma
+2. YouTube link parse — WebFetch addımları
+3. Transkript fallback (WebFetch kifayət etmədikdə)
+4. Ssenari fayl analizi
+5. Çıxarılan field-lər (uniform schema)
+
+---
+
+## 1. Input mode tanıma
+
+İstifadəçinin verdiyi input-a baxıb mode-u təyin et:
+
+| Input pattern | Mode |
+|---|---|
+| `https://youtube.com/watch?v=...` və ya `youtu.be/...` | YouTube link mode |
+| `https://www.youtube.com/shorts/...` | Shorts mode — bu skill landscape üçündür, Shorts üçün xəbərdar et |
+| Fayl yolu (.md, .txt, .docx, .pdf) | Ssenari fayl mode |
+| Çıplaq mətn (paste edilmiş ssenari) | Inline script mode |
+| YouTube link + ssenari yol — hər ikisi | Combined mode (link → context, script → detail) |
+
+İstifadəçi heç birini verməyibsə, soruş:
+> "Hansı input verirsən? YouTube link, ssenari fayl yolu, ya hər ikisi?"
+
+---
+
+## 2. YouTube link parse — 3-tier prosedur
+
+`WebFetch` YouTube üzərində praktiki olaraq işləmir — YouTube SPA-dır (JS-rendered), static HTML boşdur. Bunun əvəzinə **3 səviyyəli avtomatik prosedur**:
+
+### Addım 2.1 — URL normallaşdır
+```
+https://youtu.be/ABC123 → https://www.youtube.com/watch?v=ABC123
+https://www.youtube.com/watch?v=ABC123&t=42s → https://www.youtube.com/watch?v=ABC123
+https://www.youtube.com/shorts/ABC123 → Shorts mode (§ 7 edge case)
+```
+
+### Tier 1 — oEmbed (instant, ZERO setup, always works)
+
+YouTube-un rəsmi public oEmbed endpoint-i. Heç bir API key, heç bir install lazım deyil.
+
+```bash
+curl -sL "https://www.youtube.com/oembed?url=https://www.youtube.com/watch?v=<VIDEO_ID>&format=json"
+```
+
+Çıxan JSON-da bu sahələr var (məcburi):
+- `title` — video başlığı (AZ glyphs daxil)
+- `author_name` — channel name
+- `author_url` — channel URL (handle-i çıxar)
+- `thumbnail_url` — mövcud thumbnail URL
+- `provider_name`, `html` — minor
+
+Bu, hər video üçün dərhal işləyir. Çatışmayan: description, transcript, tags.
+
+### Tier 2 — yt-dlp (preferred, one-time install)
+
+`yt-dlp` lokal mövcuddursa, **tam metadata + auto-subtitles** çıxır.
+
+#### Yoxla:
+```bash
+which yt-dlp && yt-dlp --version
+```
+
+#### Mövcud deyilsə → istifadəçiyə install təklifi (məcburi disclosure):
+```
+"yt-dlp mövcud deyil. Bu alət YouTube-dan tam məlumat çıxarmaq üçündür
+(title, description, tags, transkript). 10 saniyəlik bir-dəfəlik install:
+
+  brew install yt-dlp
+
+Mən sənin üçün indi quraşdırım? (bəli/xeyr)
+- Bəli: install edirəm, sonra tam avtomatik analiz davam edir
+- Xeyr: yalnız Tier 1 (oEmbed) + transkript paste lazım gələcək"
+```
+
+İstifadəçi razıdırsa → `brew install yt-dlp` icra et.
+
+#### yt-dlp ilə tam metadata çıxar:
+```bash
+yt-dlp --skip-download \
+  --print "%(title)s|%(channel)s|%(upload_date)s|%(view_count)s|%(duration)s|%(categories)s|%(tags)s" \
+  "<URL>"
+```
+
+Çıxan format: pipe-separated values. Field-lər:
+- Title
+- Channel name
+- Upload date (YYYYMMDD)
+- View count
+- Duration (seconds)
+- Categories (Entertainment, Education, Music, və s.)
+- Tags (siyahı kvadrat mötərizədə)
+
+#### Description ayrıca:
+```bash
+yt-dlp --skip-download --print "%(description)s" "<URL>"
+```
+
+#### AZ auto-subtitle çəkmə (real transkript):
+```bash
+yt-dlp --skip-download \
+  --write-auto-sub --sub-lang az --sub-format vtt \
+  "<URL>" \
+  -o "/tmp/yt-transcript.%(ext)s"
+```
+
+VTT formatda fayl `/tmp/yt-transcript.az.vtt` olaraq yazılır.
+
+#### Transkripti təmizlə (timestamp və duplikatları sil):
+```bash
+grep -v "^[0-9]" /tmp/yt-transcript.az.vtt | \
+  grep -v "WEBVTT" | grep -v "^$" | \
+  grep -v "Kind:" | grep -v "Language:" | grep -v "^align" | \
+  sed 's/<[^>]*>//g' | awk '!seen[$0]++'
+```
+
+#### Mövcud dilləri yoxla (əgər AZ yoxdursa):
+```bash
+yt-dlp --list-subs "<URL>" | grep -E "(Language|Available)"
+```
+
+AZ yoxdursa, mövcud bir dili seç (en, ru, tr) və xəbərdar et:
+> "Bu videoda AZ auto-subtitle yoxdur. <En/Ru/Tr> versiya çəkim, yoxsa transkripti manual paste edəcəksən?"
+
+### Tier 3 — Manual paste (fallback)
+
+Tier 1 və Tier 2 hər ikisi uğursuz olarsa (məs. video private, internet kəsilir, yt-dlp install rədd edilir):
+
+> "Avtomatik məlumat çəkilmədi. Sən manual yardım et:
+> 1. YouTube videoya gir → '...' menyusu → 'Show transcript' → bütün mətni kopya et → buraya yapışdır
+> 2. Yoxsa sadəcə 4-5 cümlə ilə kontekst de (kanal, mövzu, niche, audience)"
+
+### Addım 2.5 — Yetərlilik testi (3 tier birləşdirildikdən sonra)
+
+Aşağıdakı sahələr doldurulubsa → davam et:
+- [ ] Title var (oEmbed-dən gəlir, həmişə)
+- [ ] Channel name var (oEmbed-dən gəlir, həmişə)
+- [ ] Topic / niche hint var (description + tags + transcript-dən)
+- [ ] Tone hint var (transcript-dən və ya istifadəçinin verdiyi kontekstdən)
+
+**Hər dörd ✅** → Addım 4-ə keç (script analysis lazım deyil — meta-data + transcript-dən çıxan field-lər kifayət edir).
+
+**Hər hansı ❌** → istifadəçidən kontekst soruş.
+
+---
+
+## 4. Ssenari fayl analizi
+
+### Addım 4.1 — Fayl Read
+İstifadəçinin verdiyi fayl yolunu Read et. Fayl tipləri:
+- `.md`, `.txt` — birbaşa
+- `.docx` — Bash + python-docx və ya pandoc
+- `.pdf` — Read tool PDF dəstəyi var (pages: "1-N" parametri)
+
+### Addım 4.2 — Struktur çıxar
+Ssenari oxunduqdan sonra çıxar:
+- **Scene heading-lər** (`İNT.`, `EKS.`)
+- **Action satırları** (vizual təsvirlər)
+- **Dialoqlar** (kim danışır + nə)
+- **Transitions** (`> KƏSİK:`, `> SOLUR:`)
+- **VO / off-screen text** (varsa)
+
+### Addım 4.3 — 5 key field çıxar
+
+Bu skill üçün ən vacib məlumatlar:
+
+```yaml
+topic: <1 cümlə mövzu — "AI mənim işimi əvəz edirmi?">
+hook_moment: <vizual qənaət ediləcək an — şok, sürpriz, sual>
+emotional_payoff: <baxan nə hiss etməlidir — qorxu, maraq, ümid, sürpriz>
+audience: <yaş aralığı + dil + niche>
+subject: <kim/nə kadrda — host adı, abstract konsept, multi-subject>
+```
+
+### Addım 4.4 — Hook moment-i identifikasiya et
+
+Hook moment = video-nun **vizual zirvəsi** — thumbnail bu anı vizuallaşdırır.
+
+Ssenaridə tap:
+- **Climax beat** (genəlliklə 60-80% bölgədə)
+- **En çətin sual** (rhetorical question, "Hmm" moment)
+- **Visual surprise** (transformation, reveal, unexpected obj)
+- **Emotional break** (laughter, tears, gasp)
+
+Bunlardan **bir** hook moment seç → thumbnail bu anı təsvir edir.
+
+### Addım 4.5 — Subject identifikasiya et
+
+Hook moment-də kim/nə kadrda olacaq?
+
+- **Host kadrda?** → host face required (refs/host-face.png lazım)
+- **Multi-character?** → hər karakter üçün ref
+- **Abstract** (yalnız obyekt, mətn) → host face lazım deyil
+- **Mixed** (subject + obyekt) → həm host həm obyekt ref
+
+---
+
+## 5. Çıxarılan field-lər (uniform schema)
+
+Hansı mode (YouTube link / transkript / ssenari fayl / inline script) istifadə olunsa da, çıxarılan field-lər **eyni schema**-dadır:
+
+```yaml
+# Standart input analysis output
+input_source: <youtube_link | youtube_link+transcript | script_file | inline_script | combined>
+source_url_or_path: <URL və ya fayl yolu>
+
+# Content
+title: <video başlığı və ya 1-cümlə özet>
+topic: <1 cümlə mövzu>
+hook_moment: <vizual hook an — 1-2 cümlə>
+emotional_payoff: <1 cümlə>
+subject: <kim/nə kadrda — açıq sıralanmış>
+
+# Audience hints
+niche_hint: <edu / vlog / podcast / how-to / drama / music / news / commentary>
+audience_hint: <yaş + dil + xüsusiyyət>
+tone_hint: <serious / playful / dramatic / authoritative / friendly>
+
+# Channel context (yalnız YouTube link mode)
+channel_name: <if available>
+channel_handle: <if available>
+existing_thumbnail_style: <əgər mövcud thumbnail-lara baxa bilərikdirsə>
+```
+
+Bu schema → Mərhələ A Addım A3 sual klasterinin **default cavabları** ola bilər (istifadəçi təsdiqləyir və ya dəyişdirir).
+
+---
+
+## 6. Misal — workflow icra
+
+### Senario A: YouTube link
+İstifadəçi: "https://www.youtube.com/watch?v=ABC123 üçün thumbnail layihəsi qurmaq istəyirəm"
+
+1. URL normallaşdır
+2. WebFetch çağır
+3. Title: "Will AI Replace Programmers in 2026?"
+4. Description: "I explore the latest AI tools and..."
+5. Niche hint: edu / tech
+6. Audience hint: developers, tech-curious, EN dominant
+7. Tone hint: question-based → curious + slightly alarming
+8. Transkript test: title + desc kifayətdir → davam et
+9. → A3 sual klasterini başlat, bu hint-ləri default cavab kimi istifadə et
+
+### Senario B: AZ ssenari fayl
+İstifadəçi: "`01-script/v1-stride-30s.md` üçün thumbnail layihəsi"
+
+1. Fayl oxu
+2. Scene-headings, action, dialoglarını parse et
+3. Hook moment: Beat 3 (emotional climax — "Sənə uyğunlaşır" voiceover)
+4. Subject: Aytac (host), park yolu
+5. Emotional payoff: empowerment, breakthrough
+6. Audience: AZ-speaking, fitness/lifestyle niche
+7. Niche hint: vlog / lifestyle / sport
+8. → A3 sual klasteri, defaults preset
+
+### Senario C: Mixed (link + ssenari)
+İstifadəçi həm link, həm ssenari versə → ikisini birləşdir:
+- Link → channel context, tone
+- Ssenari → hook moment, subject, emotional arc
+- Daha zəngin input → daha dəqiq stylistic plan
+
+---
+
+## 7. Edge cases
+
+### YouTube Shorts URL
+Skill xəbərdar et:
+> "Bu YouTube Shorts URL-dir (9:16 aspect). Bu skill landscape 16:9 thumbnail üçündür. Shorts üçün ayrı pipeline lazımdır — istəyirsən regular 16:9 thumbnail kimi davam edək, yoxsa Shorts pattern üçün gözləyək?"
+
+### Private / unlisted video
+WebFetch nəticəsi 403 və ya boş olsa:
+> "Bu video private/unlisted görünür — WebFetch açıq məlumat çıxara bilmədi. Title və mövzu mənə paste edə bilərsən, yoxsa ssenari faylı versən?"
+
+### Multi-language description
+Description AZ+EN qarışıqdırsa, dominant dili çıxar (söz sayı), həm də qeyd et: "Channel multi-lingual — thumbnail dilini istifadəçi seçəcək (Sahə 2)."
+
+### Heç bir input
+İstifadəçi heç bir input vermədən "thumbnail yaradaq" desə:
+> "Yeni layihə yaratmaq üçün input lazımdır:
+> 1. YouTube link (mövcud video)
+> 2. Ssenari faylı (planlaşdırılan video)
+> 3. Hər ikisi (ideal)
+>
+> Hansını verirsən?"