Mezun Tanıtım Videosu — Altyazı Aracı

İTÜ Gemi İnşaatı ve Deniz Bilimleri Fakültesi Tanıtım Komisyonu'nun mezun tanıtım videoları için geliştirilen sosyal medya (Reels/Shorts) altyazı üretim aracı. Konuşmayı otomatik yazıya döker, sessiz/mobil izlemeye uygun okunabilir karaoke altyazılara dönüştürür, sessizlik/anlamsız kısımları keser, videoya sağ üst fakülte amblemi ve giriş/çıkış kartı ekleyerek 1080×1920 dikey nihai video üretir.

Pipeline

input/<isim>.mp4
   ▼
transcribe ── faster-whisper (large-v3, int8) ──────────► work/<isim>.srt
   │   KELİME-düzeyi: her kelime ayrı cue, kesin zamanlı
   │
   │  ← Claude/elle: imla düzelt + cümle parçalarına paketle + kesim listesi
   ▼
   ├─────────────────────────────────────────► work/<isim>.packed.srt   (cümle-parçalı SRT)
   └─────────────────────────────────────────► work/<isim>.edit.json    (kesilecek aralıklar / EDL)
   ▼
cut ── EDL uygula (sessizlik/anlamsız kes) ─────────────► work/<isim>.cut.mp4
   │   altyazılar yeni zaman çizgisine remap             + .cut.packed.srt / .cut.srt
   ▼
style ── karaoke ASS (kelime-vurgulu) ──────────────────► work/<isim>.ass
   ▼
compose ── altyazı+amblem yak + giriş/çıkış kartı (xfade)► output/<isim>_final.mp4
                                                           1080×1920, yuv420p, faststart

Transkripsiyon çıktısı bilerek kelime-düzeyidir: kesin zaman etiketleri elle/AI düzeltmeyi ve akıcı cümle parçalarına dönüştürmeyi kolaylaştırır, cut aşaması da kesim sınırlarını kelimelere göre yeniden zamanlar. Otonom akış ve düzeltme/kesim kuralları için bkz. CLAUDE.md.

Klasör yapısı

├─ config.json        stil + ayar (dosya adı tutmaz)
├─ requirements.txt   faster-whisper, pysubs2
├─ src/               run · transcribe · repack · srt2ass · cut · compose · card · common
├─ input/             ham videolar + <isim>.json sidecar (ad/bölüm/yıl → kart)
├─ work/              .srt (kelime) · .packed.srt · .edit.json · .cut.mp4 · .ass · .card.png
├─ output/            nihai *_final.mp4
├─ assets/            fakülte amblemi (gidb-tr-b.png) + altın mühür (fakulte_seal_gold.png)
├─ design/            gen_card.py (kart tasarım kaynağı; PNG/_fonts git dışı)
├─ fonts/             gömülü fontlar (Montserrat/Tinos/Roboto/Source Sans Pro; fontsdir)
├─ projects/          Shotcut .mlt arşivi (yollar kırık; yalnız kayıt)
└─ docs/              tasarım/spec + çalışma durumu + mezun listesi

Ham/ara/çıktı medyası git dışıdır; yalnızca kod/config/doküman izlenir.

Ön gereksinimler

• Python 3.12 (3.9+ çalışır)
• ffmpeg — sistem PATH'inde olmalı (BtbN buildleri; bin klasörünü PATH'e ekleyin).
• Python bağımlılıkları — faster-whisper + pysubs2:

  pip install -r requirements.txt

  Kart metni için Pillow (PIL) ve şekiller için cairosvg de gerekir.
• Fontlar — fonts/ altında gömülüdür; ffmpeg fontsdir ile çözülür, kurulum gerekmez. (Kart metni ayrıca PIL ile doğrudan TTF'ten çizilir — cairosvg bu makinede sistem-dışı fontları göremediğinden.)

Donanım: Transkripsiyon config.json → whisper.device ile CPU/GPU. large-v3 GPU'da ~10 GB VRAM ister; Quadro P620 (2 GB) sığdıramaz → varsayılan CPU + compute_type: int8 (hızlı, kalite aynı). VRAM'li GPU'da device: "cuda".

İlk çalıştırma: large-v3 ilk kullanımda HuggingFace'ten ~1.5 GB iner (%USERPROFILE%\.cache\huggingface).

Kullanım

Önerilen akış (Claude/elle düzeltmeli, kartlı+karaoke)

# 1) Yazıya dök → work/<isim>.srt (KELİME-düzeyi). CPU'da dakikalar sürer.
python src/run.py transcribe "input/<isim>.mp4"

# 2) Düzelt + paketle + kesim listesi (Claude ya da elle):
#    → work/<isim>.packed.srt   imla düzeltilmiş, cümle-parçalı SRT (1–2 satır/cue)
#    → work/<isim>.edit.json     kesilecek aralıklar: {"remove":[{"start","end","reason"}]}
#    (kart bilgisi için input/<isim>.json = {"ad","bolum","yil"})

# 3) Kes (EDL uygula) → work/<isim>.cut.mp4 + altyazı remap
python src/run.py cut "<isim>"

# 4) Stil (hazır packed.srt'yi karaoke ASS'e; repack'i atla) → work/<isim>.ass
python src/run.py style "<isim>" --skip-repack --karaoke

# 5) Birleştir (altyazı+amblem yak + giriş/çıkış kartı) → output/<isim>_final.mp4
python src/run.py compose "<isim>"

edit.json zaman biçimi: ayraç , → ms (HH:MM:SS,mmm); ayraç : → frame (SS:FF, ör. 28:13 = 28 sn 13 kare; Shotcut timecode'u doğrudan yapıştırılabilir). fps config.cut.fps (30) ya da edit.json'daki "fps". Kesim yoksa remove boş olabilir.

Mekanik tek komut (Claude'suz — elle düzeltme/kart/kesim atlanır)

python src/run.py all "input/<isim>.mp4"     # transcribe → style → embed (legacy, kartsız)
python src/run.py all --batch input          # input/ içindeki her *.mp4

Legacy gömme (kartsız)

python src/run.py embed "<isim>"             # ASS'i videoya göm → output/<isim>_embedsubs.mp4

Ek seçenekler

• --skip-repack — style: mekanik repack'i atla, hazır <isim>.packed.srt'yi stiller (bayrak hedeften sonra).
• --karaoke — konuşulan kelimeyi anlık sarı vurgular. Vurgu zamanları kelime-düzeyi work/<isim>.srt'den (cut varsa .cut.srt) gerçek etiketlerle hizalanır; packed.srt'deki 2-satır kırılımı korunur.
• --device cuda — config'teki aygıtı geçici ezer.
• --extract-audio — transcribe öncesi WAV çıkarır (normalde gereksiz; faster-whisper videoyu doğrudan okur).
• --config yol/config.json — farklı config.

Modülleri tek tek çağırma

python src/transcribe.py "input/<isim>.mp4"       # → work/<isim>.srt (kelime-düzeyi)
python src/cut.py "<isim>"                          # edit.json → cut.mp4 + remap
python src/card.py --stem "<isim>" --out work/<isim>.card.png   # giriş/çıkış kartı PNG
python src/srt2ass.py "<isim>"                      # packed.srt → .ass

config.json parametreleri

Config yalnızca stil ve ayar tutar; dosya adları CLI + klasör konvansiyonundan gelir. _comment alanları işleme alınmaz.

• whisper — faster-whisper: model (large-v3), device (cpu/cuda), compute_type (int8/float16/int8_float32), language (tr), word_timestamps (repack için true), vad_filter, beam_size/best_of, temperature, eşikler (no_speech_threshold, log_prob_threshold, compression_ratio_threshold), condition_on_previous_text.
• repack_options — yalnızca mekanik (Claude'suz) yol: max_line_width (cue başına maks. karakter), merge_gap_ms. Claude yolunda satır kırılımı elle, anlam-bütünlüğü korunarak yapılır (bkz. CLAUDE.md).
• cut — EDL kesimi: silence_gap_ms (700; Claude'un taban kuralı), keep_pad_ms (nefes payı), fps (30; SS:FF frame çözümü), micro_fade_s (tıkırtı önleme), crf/preset/audio_bitrate.
• card — giriş/çıkış kartı (card.py): wave_cy/wave_amp (dalga), seal_diameter (altın mühür çapı), header_dy (mühür büyüyünce başlık bloğunu aşağı çek). Renk/font/geometri KİLİTLİ; metin PIL ile fonts/'tan çizilir. Ad/bölüm/yıl input/<isim>.json sidecar'ından.
• emblem — sağ üst amblem overlay (compose.py): source (assets/gidb-tr-b.png), width_ratio (~0.44), margin_ratio, outline+outline_ratio+outline_color (koyu OUTLINE → her zeminde okunur; gölge değil).
• transitions — kart geçişleri: card_hold_s (kart tam görünme), fade_s (xfade; giriş tarafı ilk altyazı çıkışından önce biter).
• compose — render: target_width/target_height (1080×1920; doldur+kırp), fps (30), crf/preset. Çıktı yuv420p + faststart zorlanır (evrensel oynatıcı/telefon uyumu).
• mobile_style — altyazı stili (Montserrat Bold 18, kutusuz=borderstyle 1, iki satırlı): primarycolor (beyaz), backcolor (lacivert gölge [0,0,128]), outline, shadow (1.2), alignment (2=alt-orta), marginv (60), bold.
• karaoke — --karaoke için: highlight_color ([255,214,10] sarı), scale (100=büyütme kapalı, jitter yaratmaz).
• components — legacy künye/isim kartı (ASS metin overlay). Kart artık card.py ile üretilir; bu blok yalnızca eski embed/all yolunda kullanılır.

Giriş/çıkış kartı

Kart bilgisi mezun başına input/<isim>.json sidecar'ından gelir; yoksa ad dosya adından türetilir:

{ "ad": "Ali Veli", "bolum": "Gemi ve Deniz Teknolojisi Mühendisliği", "yil": "2026" }

compose bu bilgilerle work/<isim>.card.png üretir (altın fakülte mührü, UPPERCASE ad, bölüm, "YYYY MEZUNU") ve videonun başına/sonuna xfade ile ekler.

Bilinen sınırlamalar / notlar

• Çıktı uyumu: ass filtresi 4:4:4 (yuv444p) üretir → çoğu telefon/uygulama çözemez (siyah ekran). compose/embed bu yüzden -pix_fmt yuv420p + -movflags +faststart + sabit 30fps zorlar.
• int8 kalite: float16'nın hafif altında; Türkçe large-v3 için genelde yeterli. Gerekirse compute_type: "int8_float32".
• Windows ass= yol kaçışı: ffmpeg altyazı filtresi sürücü harfi/ters bölü/Türkçe karakterde bozulabilir; run.py bunu ASS klasöründe çalışıp çıplak dosya adı vererek aşar.
• Kart fontları: cairosvg bu makinede sistem-dışı fontları göremez → kart metni PIL ile TTF'ten çizilir (font-bağımsız, garanti doğru).
• Türkçe dosya adları: klasör/kod adları ASCII; girdi adlarında da _ ve ASCII önerilir.