README.md

---
title: CrownCode Backend
emoji: 👑
colorFrom: yellow
colorTo: red
sdk: docker
pinned: false
---

# CrownCode Backend

YouTube-first backend service for AI music detection workflows.

---

## Hugging Face Spaces Deployment

### Adım 0 — Model Dosyalarını HF Hub'a Yükle (tek seferlik)

Model dosyaları `.gitignore`'da — Space'e gönderilmez. Bunun yerine container
başlangıcında `startup.py` onları `Rtur2003/auris-models` hub reposundan indirir.

```bash
# Lokal makinede bir kere çalıştır:
huggingface-cli login          # HF token ister (write izni gerekli)
python upload_models_to_hub.py # ~415 MB yükler (RF 47MB + wav2vec2 360MB dahil)
```

Upload sonrası `https://huggingface.co/Rtur2003/auris-models` adresinde
tüm model dosyaları görünmeli.

### Adım 1 — Space Oluştur

- [huggingface.co/new-space](https://huggingface.co/new-space) adresine git
- Space Name: `crowncode-backend`
- SDK: **Docker** (önemli!)
- Hardware: **CPU Basic (Free)**

### Adım 2 — Kodu Push Et

```bash
cd hf-crowncode-backend
git remote add space https://huggingface.co/spaces/Rtur2003/crowncode-backend
git push space main
```

Veya Space sayfasında "Files" > "Add file" ile `Dockerfile`, `requirements.txt`,
`startup.py`, `app/` klasörünü yükle.

### Adım 3 — HF_TOKEN Secret Ekle (isteğe bağlı)

Eğer `auris-models` reposu **private** ise:

- Space > Settings > Repository secrets
- `HF_TOKEN` = HuggingFace read token

### Adım 4 — Deploy

- "Commit changes" butonuna bas
- Build ~5-8 dk sürer (PyTorch + model download)
- `startup.py` tüm model dosyalarını `/app/models/` altına indirir
- API ayağa kalkar, "Önizleme Modu" biter

### URL Format
```
https://KULLANICI_ADI-crowncode-backend.hf.space
```

### Test Endpoints
```
GET  /api/health     -> {"status": "healthy"}
GET  /docs           -> Swagger UI
POST /api/youtube/analyze
```

---

## What This Service Does

- Accepts a YouTube URL
- Downloads audio via `yt-dlp`
- Optionally forwards the audio to external services:
  - Music-AIDetector (`/predict`)
  - Ses-Analizi (`/analyze`)
- Produces a deterministic preview decision if no model is available

---

## Structure

```
hf-crowncode-backend/
  Dockerfile          <- Hugging Face Spaces icin
  requirements.txt    <- CPU-compatible dependencies
  app/
    main.py
    schemas.py
    routes/
      health.py
      analyze.py
      data_processing.py
      commend/
        router.py
        youtube_service.py
    services/
      external_clients.py
      url_parser.py
      youtube_analysis.py
      youtube_downloader.py
      audio_processor.py
      validation.py
      logging_config.py
      preview_model.py
```

---

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/health` | Health check |
| POST | `/api/analyze` | Analyze YouTube URL or uploaded file |
| POST | `/api/process/audio` | Audio augmentation |
| GET | `/api/commend/health` | Crown Commend health check |
| POST | `/api/commend/generate` | Generate AI comment for YouTube |
| POST | `/api/commend/post` | Post comment to YouTube (feature-flagged) |
| GET | `/api/commend/styles` | Get available comment styles |

### POST /api/analyze

Request (multipart form):

- `sourceType`: `youtube` | `file` | `spotify` | `apple`
- `url`: YouTube URL (when sourceType=youtube)
- `file`: Audio file upload (when sourceType=file)

Response:

```json
{
  "result": {
    "isAIGenerated": true,
    "confidence": 0.85,
    "processingTime": 2.1,
    "modelVersion": "preview-v2-enhanced",
    "decisionSource": "preview",
    "analysisMode": "preview",
    "source": { "kind": "youtube", "videoId": "..." },
    "features": { ... },
    "audioInfo": { ... }
  },
  "warnings": [],
  "errors": []
}
```

---

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `AURIS_MODELS_REPO` | `Rtur2003/auris-models` | HuggingFace model repo to download artifacts from at startup |
| `MODELS_DIR` | `/app/models` | Local directory where model files are stored |
| `HF_TOKEN` | - | HuggingFace token (required if `auris-models` repo is private) |
| `SKIP_MODEL_DOWNLOAD` | `0` | Set to `1` to skip startup download (local dev with models already present) |
| `CROWNCODE_CORS_ORIGINS` | `http://localhost:3000` | Allowed CORS origins (comma-separated). **Do not use `*` in production.** |
| `MUSIC_AI_API_URL` | - | Music-AIDetector service URL |
| `SES_ANALIZI_API_URL` | - | Ses-Analizi service URL |
| `CROWNCODE_API_TIMEOUT_SEC` | `30` | External service timeout |
| `SES_ANALIZI_THRESHOLD` | `0.5` | Authenticity score threshold |
| `LOG_LEVEL` | `INFO` | Logging level |
| `YOUTUBE_COOKIES_FROM_BROWSER` | - | Optional `yt-dlp` browser cookie source, e.g. `edge` or `chrome:Default` |
| `YOUTUBE_COOKIES_FILE` | - | Optional Netscape `cookies.txt` path for YouTube-authenticated downloads |
| `YOUTUBE_COOKIES_BASE64` | - | Optional base64-encoded `cookies.txt` content for secret managers |
| `COMMEND_GEMINI_API_KEY` | - | Gemini API key for Crown Commend (also used as YouTube API Key fallback) |
| `COMMEND_YOUTUBE_API_KEY` | - | YouTube Data API key for read operations (optional if Gemini key is set) |
| `COMMEND_TOKEN_JSON` | - | YouTube OAuth token JSON for posting comments (optional) |
| `COMMEND_API_KEY` | - | API key for commend endpoint auth (**required in production**) |
| `COMMEND_REQUIRE_AUTH` | `true` | Fail-closed auth gate. Set to `false` only for local development. |
| `COMMEND_ENABLE_POSTING` | `false` | Enable YouTube comment posting (`true`/`false`) |

---

## Frontend Configuration

Backend deploy edildikten sonra frontend `.env` dosyasini guncelle:

```env
NEXT_PUBLIC_API_URL=https://kullaniciadi-crowncode-backend.hf.space
```

---

## Local Development

```bash
# Install dependencies
pip install -r requirements.txt

# Install PyTorch CPU
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# Run server
uvicorn app.main:app --reload --port 8000
```

---

## Docker Local Build

```bash
docker build -t crowncode-backend .
docker run -p 7860:7860 crowncode-backend
```

---

## Notes

- `yt-dlp` requires network access and works best with `ffmpeg` installed
- If YouTube returns a bot-check/sign-in challenge, configure `YOUTUBE_COOKIES_FROM_BROWSER=edge` or pass a `cookies.txt` file via `YOUTUBE_COOKIES_FILE`
- When external services are not configured, returns preview decision
- Hugging Face free tier has 16GB RAM and 2 vCPU
- Build may take 5-10 minutes due to PyTorch installation