subwatcher/README.md

subwatcher

Docker tabanli altyazi otomasyon sistemi.

• core: watcher + ffprobe + BullMQ + Mongo job/log API + review akisi
• api: gercek provider subtitle engine + archive extraction + security + scoring
• ui: React/Vite panel (dashboard, jobs, detail live logs, review, settings, watched paths)

Mimari

• Mongo koleksiyonlari: watched_paths, settings, media_files, jobs, job_logs
• Redis/BullMQ kuyruklari:
  • fileEvents
  • mediaAnalysis
  • subtitleFetch
  • finalizeWrite
• Core -> API servis cagrisi (docker network): http://api:3002
• UI -> Core API: http://localhost:3001/api (CORS acik)
• Temp alan: /temp/{jobToken}

TurkceAltyazi Gercek Modu (v2)

Gercek entegrasyon feature flag ile acilabilir:

ENABLE_TURKCEALTYAZI_REAL=true
TURKCEALTYAZI_BASE_URL=https://turkcealtyazi.org
TURKCEALTYAZI_TIMEOUT_MS=12000
TURKCEALTYAZI_MIN_DELAY_MS=300

• ENABLE_TURKCEALTYAZI_REAL=true: TurkceAltyaziProvider gercek HTTP+HTML parse dener.

Gelistirme (Dev)

1. Ortam dosyasi:

cp .env.example .env

2. Servisleri kaldir:

docker compose -f compose.dev.yml up --build

3. Portlar:

• UI: http://localhost:5173
• Core: http://localhost:3001
• API: http://localhost:3002
• Mongo: localhost:27017
• Redis: localhost:6379

4. Media dosyasi yerlestirme:

• TV: ./_media/tv
• Movie: ./_media/movie

Gercek .mkv dosyasi ekleyince watcher pipeline'i tetikler.

5. Debug enqueue (dev-only):

curl -X POST http://localhost:3001/api/debug/enqueue \
  -H 'content-type: application/json' \
  -d '{"path":"/media/movie/example.mkv","kind":"movie"}'

Production

docker compose -f compose.yml up --build -d

Portlar:

• UI: http://localhost:3000
• Core: http://localhost:3001
• API: http://localhost:3002

UI Ozellikleri

• Dashboard: son 24h ozet + son isler
• Jobs: filtreleme + job detayi
• Job Detail: metadata, mediaInfo, sonuc dosyalari, canli SSE log paneli
• Review List: NEEDS_REVIEW isler
• Manual override: metadata ile ara + candidate sec + finalize write
• Settings: language/overwrite/stability/security ayarlari
• Watched Paths: ekle/sil/enable/disable

API Endpointleri

Core

• GET /api/health
• GET /api/settings
• POST /api/settings
• GET /api/watched-paths
• POST /api/watched-paths
• GET /api/jobs
• GET /api/jobs/:id
• GET /api/jobs/:id/logs
• GET /api/jobs/:id/stream (SSE)
• GET /api/review
• POST /api/review/:jobId/search
• POST /api/review/:jobId/choose
• POST /api/debug/enqueue (dev)

Subtitle API

• GET /v1/health
• POST /v1/subtitles/search
• POST /v1/subtitles/choose
• POST /v1/subtitles/cleanup

Guvenlik ve Dogrulama

• Archive extraction: 7z
• Zip slip kontrolu: realpath root disina cikis reddi
• Limit kontrolleri:
  • max file count
  • max total size
  • max single file size
• SRT/ASS extension'a gore degil, icerige gore validate edilir
• Gecersiz altyazilar aninda silinir (INVALID_SUBTITLE_DELETED)

Encoding

Core finalize adiminda:

• BOM kontrol
• UTF-8 / windows-1254 / latin1 fallback
• LF newline normalizasyonu
• hedef adlandirma: {base}.{lang}.{ext}
• overwrite false ise .2, .3...

Testler

Core:

cd services/core && npm test

API:

cd services/api && npm test

Kapsam:

• filename parser
• SRT/ASS validator
• scoring + ambiguous karari
• zip slip helper

Gelecek (v2)

• Gercek OpenSubtitles API entegrasyonu
• ClamAV tarama (feature flag hazir)