ayrisdevandClaude Sonnet 5
eccc74166a
yt-dlp headless capture (15dk segmentleme), ses peak + chat velocity sinyal tespiti, OpenAI Whisper STT (kelime zaman damgalı), BullMQ/Redis/Postgres altyapısı ve kanal durumu + transkript kütüphanesi gösteren Next.js panel. LLM virality skorlama, render/crop/altyazı ve multi-platform dağıtım bu fazın kapsamı dışında. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
188 lines
12 KiB
Markdown
188 lines
12 KiB
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)
|
||
|
||
```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.
|
||
|
||
``` |