# 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ı)
docker-compose.yml
```

## Ön Koşullar

- Node.js 22.13+ (pnpm 11'in gereksinimi), 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 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 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).