README.md

metadata

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.

# 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 adresine git
• Space Name: crowncode-backend
• SDK: Docker (önemli!)
• Hardware: CPU Basic (Free)

Adım 2 — Kodu Push Et

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:

{
  "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:

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

---

Local Development

# 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

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