StreamClipper AI Faz 1: ingestion + sinyal analizi + STT + altyapı iskeleti

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>

README.md

@@ -0,0 +1,99 @@
+# StreamClipper AI — Faz 1
+
+`prd.md` içindeki tam kapsamlı otonom pipeline'ın ilk fazı: ingestion (yt-dlp
+headless capture + 15dk segmentleme), sinyal analizi (ses peak + chat
+velocity), Whisper STT (OpenAI API, kelime zaman damgalı), BullMQ/Redis/
+Postgres altyapısı ve durum/transkript gösteren bir Next.js panel. LLM
+virality skorlama, render/crop/altyazı ve multi-platform dağıtım bu fazda
+**yok** — bkz. `prd.md` Modül 3 (skorlama kısmı), 4 ve 5.
+
+## Klasör Yapısı
+
+```
+apps/
+  frontend/     Next.js panel (kanal durumu, segment/transkript kütüphanesi)
+  api-daemon/   Node/TS — YouTube polling, BullMQ producer, yt-dlp/ffmpeg capture
+  worker/       Python — chat-downloader, sinyal analizi, Whisper STT
+packages/
+  db/           Prisma schema + client (Node tarafı)
+infra/
+  docker-compose.yml
+```
+
+## Ön Koşullar
+
+- Node.js 20+, pnpm, Python 3.12+, `ffmpeg`, `yt-dlp` (host'ta çalıştırırken)
+- Docker + Docker Compose (container'larla çalıştırırken)
+- **OpenAI API key** — Whisper STT için
+- **Telegram bot token + chat id** — bildirimler için (`@BotFather`)
+
+Canlı yayın tespiti YouTube Data API yerine `yt-dlp`'nin kendisiyle yapılıyor
+(`/channel/<id>/live` kontrolü) — API key veya kota gerekmiyor.
+
+## Kurulum
+
+```bash
+cp .env.example .env
+# .env içindeki OPENAI_API_KEY / TELEGRAM_* değerlerini doldurun
+pnpm install
+```
+
+### Yerelde (Docker olmadan)
+
+```bash
+# Redis + Postgres'i ayağa kaldır
+docker compose -f infra/docker-compose.yml up sc_redis sc_postgres
+
+# Şemayı uygula
+pnpm db:migrate
+pnpm db:generate
+
+# Test kanalı ekle (gerçek bir YouTube channel_id ile)
+SEED_CHANNEL_ID=UCxxxxxxxx SEED_CHANNEL_NAME="Test Kanal" pnpm db:seed
+
+# Servisleri ayrı terminallerde çalıştır
+pnpm dev:daemon
+pnpm dev:frontend
+```
+
+Python worker ayrı bir sanal ortamda çalışır (pnpm workspace'in parçası değil):
+
+```bash
+cd apps/worker
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+python -m worker.main
+```
+
+### Docker Compose ile (tüm servisler)
+
+```bash
+docker compose -f infra/docker-compose.yml up --build
+```
+
+Panel: http://localhost:3000 · API daemon health: http://localhost:4001/health
+
+## Test / Doğrulama Akışı
+
+1. `FORCE_LIVE_URL=<gerçek veya kısa test yayını URL'si>` ile `apps/api-daemon`'ı
+   çalıştırırsan polling'i atlayıp doğrudan capture'ı tetikler.
+2. `shared-media/raw/<sessionId>/` altında 15dk'lık segment dosyaları ve
+   `segments.csv` oluştuğunu doğrula; DB'de `raw_segments` satırları düşer.
+3. `sc_heavy_worker` (Python) her tamamlanan segmenti `signal-detection`
+   kuyruğundan alıp ses peak + (varsa) chat velocity analiziyle
+   `candidate_segments` üretir.
+4. Her aday, `stt-scoring` kuyruğunda OpenAI Whisper API ile transkribe edilir;
+   sonuç `candidate_segments.transcript_json` alanına yazılır ve Telegram'a
+   bildirim gider.
+5. Panelde (`/` ve `/segments`) kanal durumu ve üretilen transkriptleri
+   kontrol et.
+
+## Bilinen Sınırlamalar (bu faz kapsamı dışı)
+
+- LLM virality skorlama, metadata üretimi, telif/görüntü filtresi yok.
+- 9:16 crop/altyazı render motoru yok.
+- YouTube/Instagram/TikTok'a otomatik yayınlama yok (bu API'ler ayrı onay
+  süreçleri gerektiriyor — `prd.md` tartışmasına bkz.).
+- Aday pencere çıkarımı her zaman tek bir 15dk'lık segment dosyasıyla sınırlı;
+  segment sınırına yakın bir an kırpılabilir (segment'ler arası dikiş, gelecek
+  bir iyileştirme).