Youtube2Feed/README.md

# YouTube Transcript RSS Feed Generator

YouTube video transkriptlerini otomatik olarak çıkarıp, tam metin içeren RSS feed'ine dönüştüren Docker tabanlı sistem.

## Özellikler

- ✅ **RSS-Bridge benzeri URL template** - Kanal adı/linki ile direkt feed
- ✅ **Web Server Modu** - Flask ile RESTful API
- ✅ **API Key Authentication** - Tüm endpoint'ler API key gerektirir
- ✅ **Güvenlik Önlemleri** - SQL injection, XSS, rate limiting koruması
- ✅ **Transcript Cache** - 3 günlük cache ile YouTube IP blocking önleme
- ✅ RSS-Bridge entegrasyonu (100+ video desteği)
- ✅ Async rate limiting (AIOLimiter)
- ✅ SpaCy ile Sentence Boundary Detection
- ✅ SQLite veritabanı (durum yönetimi)
- ✅ Full-text RSS feed (`<content:encoded>`)
- ✅ Channel handle → Channel ID otomatik dönüştürme
- ✅ Atom ve RSS format desteği

## Hızlı Başlangıç

### Docker ile Web Server Modu (Önerilen)

```bash
# Build
docker-compose build

# Web server'ı başlat (port 5000)
docker-compose up -d

# Logları izle
docker-compose logs -f
```

### API Key Yapılandırması

**ÖNEMLİ:** Tüm endpoint'ler API key gerektirir!

API key'leri `config/security.yaml` dosyasından yönetin:

```yaml
security:
  require_api_key: true
  api_keys:
    demo_key_12345:
      name: "Demo API Key"
      rate_limit: 100
      enabled: true
```

### URL Template Kullanımı

RSS-Bridge benzeri URL template sistemi:

```bash
# Channel ID ile (API key header'da)
curl -H "X-API-Key: demo_key_12345" \
  "http://localhost:5000/?channel_id=UC9h8BDcXwkhZtnqoQJ7PggA&format=Atom"

# Channel Handle ile (API key query parametresi)
curl "http://localhost:5000/?channel=@tavakfi&format=Atom&api_key=demo_key_12345"

# Channel URL ile (max_items: her istekte işlenecek transcript sayısı, default: 10, max: 100, 20'şer batch'ler)
curl -H "X-API-Key: demo_key_12345" \
  "http://localhost:5000/?channel_url=https://www.youtube.com/@tavakfi&format=Atom&max_items=50"
```

**Detaylı API dokümantasyonu için:** [API.md](API.md)

### Batch Mode (Manuel Çalıştırma)

```bash
# Tek seferlik çalıştırma
docker-compose run --rm yttranscriptrss python main.py
```

### Yerel Geliştirme

```bash
# Virtual environment oluştur
python -m venv venv
source venv/bin/activate  # Linux/Mac
# veya
venv\Scripts\activate  # Windows

# Bağımlılıkları kur
pip install -r requirements.txt

# SpaCy modelini indir
python -m spacy download en_core_web_sm

# Çalıştır
python main.py
```

## Yapılandırma

### Ana Yapılandırma

`config/config.yaml` dosyasını düzenleyin:

```yaml
channel:
  id: "UC9h8BDcXwkhZtnqoQJ7PggA"  # veya handle: "@username"
  name: "Channel Name"
  language: "tr"

rss_bridge:
  base_url: "https://rss-bridge.org/bridge01"
  format: "Atom"
  max_items: 100  # RSS-Bridge'den çekilecek video sayısı (web server'da max_items parametresi farklı)
```

### Güvenlik Yapılandırması

`config/security.yaml` dosyasından API key'leri ve güvenlik ayarlarını yönetin:

```yaml
security:
  require_api_key: true
  api_keys:
    your_api_key_here:
      name: "Your API Key"
      rate_limit: 100
      enabled: true
  default_rate_limit: 60
```

**Detaylı güvenlik dokümantasyonu için:** [SECURITY.md](SECURITY.md)

### Transcript Cache

Sistem, işlenmiş transcript'leri **3 gün boyunca cache'de tutar**. Bu özellik:

- **YouTube IP blocking'i önler**: Aynı videoların transcript'ini tekrar çekmez
- **Performans artışı**: Cache'den hızlı yanıt
- **Rate limiting azaltır**: Gereksiz API isteklerini önler
- **Otomatik yenileme**: 3 gün sonra cache geçersiz olur, yeni transcript çekilir

Cache kontrolü otomatik yapılır ve kullanıcı müdahalesi gerektirmez.

### max_items Parametresi

Her API isteğinde kaç video transcript'inin işleneceğini kontrol eder:

- **Varsayılan**: 10 transcript
- **Maksimum**: 100 transcript
- **Kullanım**: `?max_items=50` query parametresi ile belirtilir
- **Batch İşleme**: 20'şer batch'ler halinde işlenir (YouTube IP blocking önleme için)

**Önemli Notlar:**
- `max_items` parametresi **her istekte işlenecek transcript sayısını** belirler
- RSS-Bridge'den daha fazla video çekilir (max_items × 2, minimum 50) çünkü bazı videolar transcript'siz olabilir
- **Batch İşleme**: YouTube IP blocking'i önlemek için 20'şer batch'ler halinde işlenir
- **Veritabanı Kaydı**: Her batch işlendikten sonra hemen veritabanına kaydedilir, böylece sonraki sorgularda görülebilir
- İlk isteklerde daha az transcript görebilirsiniz; sonraki isteklerde cache'den daha fazla transcript döner

**Örnek:**
```bash
# 50 transcript işle (20+20+10 batch'ler halinde)
curl -H "X-API-Key: demo_key_12345" \
  "http://localhost:5000/?channel_id=UC9h8BDcXwkhZtnqoQJ7PggA&max_items=50&format=Atom"
```

## Proje Yapısı

```
yttranscriptrss/
├── src/
│   ├── database.py          # SQLite yönetimi
│   ├── video_fetcher.py     # RSS-Bridge entegrasyonu
│   ├── transcript_extractor.py  # Transcript çıkarımı
│   ├── transcript_cleaner.py    # NLP ve temizleme
│   └── rss_generator.py     # RSS feed oluşturma
├── config/
│   └── config.yaml          # Yapılandırma
├── data/
│   └── videos.db            # SQLite veritabanı
├── output/
│   └── transcript_feed.xml  # RSS feed çıktısı
├── Dockerfile
├── docker-compose.yml
└── main.py
```

## Dokümantasyon

- **[API.md](API.md)** - Detaylı API dokümantasyonu, endpoint'ler, örnekler
- **[SECURITY.md](SECURITY.md)** - Güvenlik önlemleri, best practices
- **[development_plan.md](development_plan.md)** - Geliştirme planı ve roadmap

## Endpoints

- `GET /` - RSS/Atom feed oluştur (API key gerekli)
- `GET /health` - Health check (API key gerekmez)
- `GET /info` - API bilgileri (API key gerekli)

## Geliştirme Planı

Detaylı geliştirme planı için `development_plan.md` dosyasına bakın.

## Lisans

MIT