# Ü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) ```markdown # Ü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. ```