screenclipper/prd.md

Ürün Gereksinim Dokümanı (PRD)

Proje Adı: StreamClipper AI
Sürüm: v2.0.0 (Uçtan Uca Otonom Pipeline & Dağıtım Spesifikasyonu)
Tarih: Ağustos 2026
Dağıtım Ortamı: Coolify (Multi-Container Docker Architecture)
Hedef: YouTube spor yayınlarını tarayıcısız otonom kaydeden, sinyal analizi ve yapay zeka ile viral kesitleri çıkaran, 9:16 formata dönüştüren ve YouTube Shorts / Instagram Reels / TikTok platformlarına zamanlayarak otomatik dağıtan tam kapsamlı içerik motoru.

---

1. Yönetici Özeti ve Problem Tanımı

1.1 Problem

• İş Gücü Yükü: Canlı yayınlardan manuel kesit almak saatlerce ekran başında beklemeyi, uzun videoları kurgu programlarında taramayı, dikey kadraja uydurmayı ve tek tek altyazı yazmayı gerektirir.
• Hız Kaybı: Spor gündeminde ve canlı maç tepkilerinde bir anın viralliği ilk 1-2 saat içinde zirve yapar; manuel montaj gecikmeleri etkileşim potansiyelini tüketir.
• Dağıtım Sürtünmesi: Aynı dikey videonun YouTube, Instagram ve TikTok için ayrı ayrı yüklenmesi, açıklama/etiket girilmesi operasyonel yavaşlığa yol açar.

1.2 Çözüm

Arka planda headless biçimde yayınları dinleyen, ses desibel patlamaları ve sohbet hızıyla tepe noktaları saptayan, STT + LLM ile mantıksal hikaye bütünlüğüne sahip 30-60 saniyelik klipleri seçen, dikey kadrajı konuşmacının yüzüne göre ortalayıp renkli dinamik altyazı basan ve onay sonrası tüm sosyal ağlara zamanlayarak yayınlayan otonom bir SaaS/içerik fabrikası.

---

2. Kullanıcı Tipleri ve Roller

• Sistem Yöneticisi (Admin): Takip edilecek kanalları, Docker/Coolify donanım limitlerini, API anahtarlarını ve Redis kuyruk yapılandırmasını yönetir.
• İçerik Editörü: Dashboard üzerinden üretilen klipleri izler, virallik puanlarını değerlendirir, gerekiyorsa saniyeleri kaydırır veya altyazı yazım hatalarını düzeltir, paylaşım kuyruğunu yönetir.

---

3. Sistem Mimarisi ve Veri Akışı

[ Ingestion Motoru (yt-dlp) ] ──> [ Sinyal Tespiti (Audio/Chat) ] │ ▼ [ Render Motoru (OpenCV + Altyazı) ] <── [ STT (Whisper) + LLM Skorlama ] │ ▼ [ Next.js Panel & Önizleme ] ──(Onay / Auto)──> [ Multi-Platform Dağıtım & Scheduler ] (YouTube, Instagram, TikTok)

# Ürün Gereksinim Dokümanı (PRD)

**Proje Adı:** StreamClipper AI  
**Sürüm:** v2.0.0 (Uçtan Uca Otonom Pipeline & Dağıtım Spesifikasyonu)  
**Tarih:** Ağustos 2026  
**Dağıtım Ortamı:** Coolify (Multi-Container Docker Architecture)  
**Hedef:** YouTube spor yayınlarını tarayıcısız otonom kaydeden, sinyal analizi ve yapay zeka ile viral kesitleri çıkaran, 9:16 formata dönüştüren ve YouTube Shorts / Instagram Reels / TikTok platformlarına zamanlayarak otomatik dağıtan tam kapsamlı içerik motoru.

---

## 1. Yönetici Özeti ve Problem Tanımı

### 1.1 Problem
* **İş Gücü Yükü:** Canlı yayınlardan manuel kesit almak saatlerce ekran başında beklemeyi, uzun videoları kurgu programlarında taramayı, dikey kadraja uydurmayı ve tek tek altyazı yazmayı gerektirir.
* **Hız Kaybı:** Spor gündeminde ve canlı maç tepkilerinde bir anın viralliği ilk 1-2 saat içinde zirve yapar; manuel montaj gecikmeleri etkileşim potansiyelini tüketir.
* **Dağıtım Sürtünmesi:** Aynı dikey videonun YouTube, Instagram ve TikTok için ayrı ayrı yüklenmesi, açıklama/etiket girilmesi operasyonel yavaşlığa yol açar.

### 1.2 Çözüm
Arka planda headless biçimde yayınları dinleyen, ses desibel patlamaları ve sohbet hızıyla tepe noktaları saptayan, STT + LLM ile mantıksal hikaye bütünlüğüne sahip 30-60 saniyelik klipleri seçen, dikey kadrajı konuşmacının yüzüne göre ortalayıp renkli dinamik altyazı basan ve onay sonrası tüm sosyal ağlara zamanlayarak yayınlayan otonom bir SaaS/içerik fabrikası.

---

## 2. Kullanıcı Tipleri ve Roller

* **Sistem Yöneticisi (Admin):** Takip edilecek kanalları, Docker/Coolify donanım limitlerini, API anahtarlarını ve Redis kuyruk yapılandırmasını yönetir.
* **İçerik Editörü:** Dashboard üzerinden üretilen klipleri izler, virallik puanlarını değerlendirir, gerekiyorsa saniyeleri kaydırır veya altyazı yazım hatalarını düzeltir, paylaşım kuyruğunu yönetir.

---

## 3. Sistem Mimarisi ve Veri Akışı

[ Ingestion Motoru (yt-dlp) ] ──> [ Sinyal Tespiti (Audio/Chat) ] │ ▼ [ Render Motoru (OpenCV + Altyazı) ] <── [ STT (Whisper) + LLM Skorlama ] │ ▼ [ Next.js Panel & Önizleme ] ──(Onay / Auto)──> [ Multi-Platform Dağıtım & Scheduler ] (YouTube, Instagram, TikTok)

---

## 4. Fonksiyonel Modüller

### Modül 1: Ingestion & Canlı Yayın Dinleyici (Ingestion Daemon)
* **Otomatik Polling:** Tanımlı kanal listesini her 60 saniyede bir kontrol eder. Yayın başladığı anda yakalar.
* **Headless Stream Capture:** Tarayıcı çalıştırmadan doğrudan `yt-dlp` üzerinden raw HLS/DASH akışını diske yazar (CPU/GPU yükü oluşturmaz).
* **Segmentli Kayıt:** FFmpeg pipe yardımıyla saatler süren tek dosya yerine 15'er dakikalık bağımsız `.mp4` parçaları üretir.
* **Canlı Sohbet Kaydedici:** Yayındaki canlı sohbet akışını zaman damgalarıyla eşzamanlı toplar.

### Modül 2: Aday Segment & Sinyal Analiz Motoru
* **Ses Desibel Analizi (Audio Peak):** FFmpeg ses analiz filtreleriyle ortalamanın üzerindeki ani desibel sıçramalarını (bağırma, gol sevinci, tartışma) tespit eder.
* **Sohbet Yoğunluğu (Chat Velocity):** Dakika başına atılan mesaj sayısının ortalamanın 3 katına çıktığı anları işaretler.
* **Aday Pencere Çıkarımı:** Ses ve sohbet tepe noktalarının ortaklaştığı anların $\pm 45$ saniyesini aday aralık olarak kesip kuyruğa iletir.

### Modül 3: Yapay Zeka (STT, LLM & Güvenlik Analizi)
* **Kelime Seviyesi Transkripsiyon (STT):** Aday video bloğunun sesini kelime bazlı zaman damgalarıyla (`word_timestamps`) metne dönüştürür.
* **Virallik Puanlama ve Sınır Belirleme:**
  * LLM metni analiz eder; 0-100 arası virallik puanı verir. Eşik değerin (varsayılan: 75) altındaki adayları eler.
  * Giriş-gelişme-sonuç dengesi olan, 30-60 saniye aralığında kesin başlangıç ve bitiş saniyelerini belirler.
* **Metadata Üretimi:** Platforma özel başlık, açıklama metni ve algoritma uyumlu 3-5 adet hashtag üretir.
* **Telif / Maç Görüntüsü Filtresi:** Ekrandaki resmi maç özetlerini veya yayıncı arkasındaki telifli müzikleri algılar; video alanını otomatik bulanıklaştırır (blur) veya ses miksini dengeler.

### Modül 4: Akıllı Görüntü & Render Motoru
* **Dinamik 9:16 Kadrajlama (Auto-Reframe):** OpenCV/MediaPipe ile konuşmacının yüzünü takip eder; 16:9 yatay videodan yüzü merkezleyen dikey kadraj üretir.
* **Çoklu Şablon Desteği (Template Switcher):**
  * *Tekil Yayıncı:* Ortalanmış dikey kadraj.
  * *İkili / Konuklu Yayın:* İki yüz algılandığında dikeyde alt alta yerleştiren Split-Screen şablonu.
  * *Yayıncı + Ekran:* Yayıncının yüzünü dairesel maskede tutarken alt alanı ekrana ayıran hazır düzen.
* **Dinamik Altyazı:** Kelime zamanlamalarına göre ekranda senkronize parlayan (karaoke/TikTok stili) renkli altyazı basar.
* **Arayüz Güvenli Bölgesi (Safe Zone):** Shorts ve Reels butonlarının (beğeni, yorum, profil) denk geldiği alt ve sağ kenarları boş bırakır.

### Modül 5: Multi-Platform Dağıtım & Post Scheduler
* **YouTube Data API v3:** Videoyu doğrudan kanala `private`, `unlisted` veya `scheduled` (zamanlanmış) olarak yükler.
* **Instagram Graph API:** Reels formatında kapak görseli, açıklama ve hashtag'lerle doğrudan veya ileri tarihli paylaşım yapar.
* **TikTok Content Posting API:** Hesaba doğrudan taslak (draft) veya zamanlanmış video gönderir.
* **Akıllı Yayın Kuyruğu (Queue Slots):** Aynı yayından çıkan birden fazla klibi algoritmayı boğmayacak şekilde kullanıcının belirlediği aralıklarla (örn. 3 saatte bir) otomatik paylaşıma dağıtır.
* **YouTube "Draft-Test" Güvenlik Aşaması:** Videoyu önce gizli yükleyip otomatik Content ID kontrolünü sorgular; telif uyarısı varsa durumu panele bildirir.

### Modül 6: Next.js Yönetim Paneli & Bildirimler
* **Canlı Durum Ekranı:** Hangi kanalların kayıtta olduğunu, aktif indirme durumunu ve kuyruk yoğunluğunu anlık gösterir.
* **Klip Kütüphanesi:** Üretilen kliplerin önizleme oynatıcısı, virallik skoru ve platform açıklamalarıyla listelenmesi.
* **Hızlı Kurgu / Düzeltme Editörü:** Başlangıç-bitiş saniyelerini ileri-geri kaydırma ve altyazı metnini manuel düzeltme imkanı.
* **Zamanlama Takvimi (Calendar View):** Hangi klibin ne zaman hangi platformda paylaşılacağını gösteren sürükle-bırak takvim.
* **Telegram / Discord Bot Bildirimi:** Yeni klip hazır olduğunda önizleme videosu ve `[Hemen Paylaş]`, `[Zamanla]`, `[Reddet]` aksiyon butonlarıyla bildirim iletir.

---

## 5. BullMQ Kuyruk Mimarisi

İş parçacıkları Redis tabanlı BullMQ üzerinde birbirinden izole çalışır:

| Kuyruk Adı | Tetikleyici | Görev | Yeniden Deneme (Retry) |
|---|---|---|---|
| `stream-ingest` | Polling servisi canlı algıladığında | 15 dk'lık blok kaydı diske yazma | 3 deneme, yayın biterse kapat |
| `signal-detection` | 15 dk'lık segment tamamlandığında | Desibel tepe noktaları ve chat hızı analizi | 2 deneme |
| `stt-scoring` | Aday pencere bulunduğunda | Whisper transkripti, LLM virallik ve süre analizi | 3 deneme, üstel geri çekilme |
| `video-render` | LLM onay verdiğinde | Yüz takibi, 9:16 crop, altyazı ve final render | 1 deneme, hata logla |
| `post-publish` | Zamanlanan saat geldiğinde | YouTube / Instagram / TikTok API çağrısı | 5 deneme, token hatasında bildirim |

---

## 6. Coolify Altyapı ve Konteyner Yapılandırması

Sistem Coolify üzerinde tek bir Docker Compose projesi olarak barındırılır:

* **Paylaşımlı Depolama (Shared Volume):**  
  `/shared-media` adlı kalıcı disk birimi tüm container'lara bağlanır:
  * `/raw`: 15 dakikalık ham yayın kayıtları.
  * `/candidates`: Kesilen ham aday parçalar.
  * `/shorts`: Dağıtıma hazır final MP4 çıktıları.
* **Container Rolleri:**
  * `sc_frontend`: Next.js (Dashboard & App Router)
  * `sc_api_daemon`: Node.js API, YouTube Polling & Queue Dispatcher
  * `sc_heavy_worker`: Python (Whisper, MediaPipe, FFmpeg Render Motoru)
  * `sc_redis`: BullMQ kuyruk durum yönetimi
  * `sc_postgres`: Kalıcı veri tabanı (Prisma ORM)
* **Kendi Kendini Temizleme (Auto-Purge Lifecycle):**
  * İşlenmiş ham kayıtlar (`/raw`) 24 saat sonra cron ile otomatik temizlenir.
  * Final Shorts videoları dağıtımı tamamlandıktan 7 gün sonra arşivlenir veya silinir.
* **Donanım Sınırlandırması:**
  * `sc_heavy_worker` için kesin CPU/RAM limiti belirlenir; render esnasında panelin kilitlenmesi engellenir. Donanımda GPU varsa NVIDIA Docker Runtime ile FFmpeg NVENC hızlandırması açılır.

---

## 7. Veritabanı Şeması (Temel Varlıklar)

* **Channel:** `id`, `name`, `youtube_handle`, `channel_id`, `is_active`, `last_checked_at`
* **StreamSession:** `id`, `channel_id`, `started_at`, `ended_at`, `total_segments`
* **RawSegment:** `id`, `session_id`, `file_path`, `duration`, `status` (PENDING, PROCESSED, DISCARDED)
* **ShortVideo:** `id`, `segment_id`, `file_path`, `virality_score`, `start_sec`, `end_sec`, `title`, `description`, `tags`, `transcript_json`, `status` (DRAFT, APPROVED, REJECTED)
* **ScheduledPost:** `id`, `short_video_id`, `platform` (YOUTUBE, INSTAGRAM, TIKTOK), `scheduled_time`, `status` (QUEUED, PUBLISHED, FAILED), `external_post_id`, `error_message`

---

## 8. Başarı Kriterleri (KPI'lar)

* **Uçtan Uca Teslimat Hızı:** Canlı yayındaki olayın gerçekleştiği andan klibin paneline düşmesine kadar geçen sürenin 5 dakikayı aşmaması.
* **Manuel Müdahale Oranı:** Üretilen kliplerin en az %75'inin zamanlama kuyruğuna hiçbir kırpma gerektirmeden doğrudan eklenebilmesi.
* **Eşzamanlı Kapasite:** Sunucunun performans kaybı yaşamadan en az 3 farklı canlı yayını aynı anda kaydedip işleyebilmesi.
* **Dağıtım Başarısı:** Zamanlanan sosyal medya paylaşımlarının %99 oranında hatasız platformlara iletilmesi.