fillercut 1.2.4__py3-none-any.whl

fillercut/__init__.py

@@ -0,0 +1,22 @@
+"""Filler-Cut — konuşma analiziyle filler ve sessizlik kesen CLI aracı.
+
+**Versiyonun tek doğruluk kaynağı `pyproject.toml`'dır.** Burada sabit bir
+sürüm dizesi TUTULMAZ: v0.3.1'de `--version`'ın bayat `0.1.0` basmasının kök
+sebebi versiyonun iki ayrı yerde yazılmasıydı. Runtime'da kurulu dağıtımın
+metadata'sı okunur; böylece bump tek yerde (`pyproject.toml`) yapılır.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+#: pyproject.toml'daki `[project] name` — dağıtım adı (paket adıyla aynı).
+#: `tests/test_cli.py` bu eşitliği pyproject'ten okuyarak kilitler.
+DIST_NAME = "fillercut"
+
+try:
+    __version__ = version(DIST_NAME)
+except PackageNotFoundError:  # pragma: no cover - kurulu değilken (çıplak import)
+    # Repo kökünden `sys.path` hilesiyle import edilmiş olabilir; sürüm bilgisi
+    # yoktur ama import patlamamalıdır.
+    __version__ = "0.0.0+notinstalled"
+
+__all__ = ["DIST_NAME", "__version__"]

fillercut/assets/__init__.py

@@ -0,0 +1,196 @@
+"""İndirme manifesti — sihirbazın ne indireceğinin tek doğruluk kaynağı.
+
+`manifest.json` **veridir**: her varlığın adı, URL'si, boyutu ve SHA-256'sı
+orada durur; bu modül onu okur, doğrular ve tipli hale getirir. İndirme
+motoru (`kurulum/indir.py`) hash ve boyutu buradan alır — yani "ne indirdik"
+sorusunun cevabı koda gömülü değildir.
+
+**Manifest'teki her hash gerçek indirmeden hesaplanmıştır** ve HF'in kendi
+API'siyle (`siblings[].lfs.sha256`) çapraz doğrulanmıştır; ölçüm ve kaynak
+seçimi kararı `experiments/download_spike/README.md`'de. Bir değeri
+"güncellerken" indirmeden değiştirmek sessizce bozar — `tests/test_assets.py`
+ölçülen değerleri ayrıca kilitler.
+
+**Tuzak:** HF'in `ETag` başlığı 64 hex karakterdir ama SHA-256 DEĞİLDİR (xet
+içerik hash'i). "ETag'i hash diye yaz" kestirmesi ölçüldü ve yanlış çıktı.
+
+Kaynak seçimi (spike kararı): modeller resmi upstream'den (Hugging Face
+`ggerganov/whisper.cpp`), wcpp binary'si **kendi** GitHub Release
+asset'imizden — upstream whisper.cpp Windows release'leri Vulkan binary'si
+yayınlamıyor (bkz. AGENTS.md, Vulkan dağıtım hattı).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+#: Paket içi manifest yolu. PyInstaller fazı bu dosyayı bundle'lamalı
+#: (`--add-data`); wheel'e `[tool.hatch.build]` üzerinden zaten giriyor.
+MANIFEST_YOLU = Path(__file__).parent / "manifest.json"
+
+#: Şema sürümü. Alan EKLEMEK bump gerektirmez (bilinmeyen alan hata verir,
+#: yani eski kod yeni manifest'i okumaz — bump o zaman gerekir).
+MANIFEST_VERSION = 1
+
+#: Zorunlu alanlar — eksikse `ManifestHatasi`.
+_ZORUNLU = ("ad", "url", "sha256", "boyut", "tur", "varsayilan_mi")
+
+#: İzinli alanların tamamı (zorunlular + opsiyoneller). Bilinmeyen anahtar
+#: SESSİZCE YUTULMAZ: config.py'nin "bilinmeyen anahtar → uyarı" davranışının
+#: aksine burada hata veririz, çünkü manifest kullanıcı dosyası değil bizim
+#: veri dosyamızdır — yazım hatası bug'dır.
+_IZINLI = frozenset(_ZORUNLU) | {"aciklama", "arsiv", "calistirilabilir"}
+
+
+class ManifestHatasi(Exception):
+    """Manifest okunamadı/geçersiz — Türkçe, eyleme dökülebilir mesaj."""
+
+
+@dataclass(frozen=True)
+class Varlik:
+    """Manifest'teki tek indirilebilir varlık.
+
+    Args:
+        ad: Tekil kimlik; CLI (`fillercut setup --model AD`) ve UI bunu kullanır.
+        tur: ``"binary"`` ya da ``"model"``.
+        url: Doğrudan indirme adresi (yalnız https).
+        sha256: İndirilen baytların SHA-256'sı (64 hex).
+        boyut: Bayt cinsinden tam boyut — disk alanı kontrolü ve ilerleme
+            yüzdesi bundan hesaplanır.
+        varsayilan_mi: Sihirbazda önceden seçili gelir.
+        aciklama: UI'da kullanıcıya gösterilen tek satır.
+        arsiv: ``"zip"`` ise indirme sonrası açılır; ``None`` ise dosya
+            doğrudan hedefe konur.
+        calistirilabilir: Arşiv içindeki çalıştırılabilir dosyanın adı
+            (arşiv DÜZ yapıdadır — DLL'ler exe'nin YANINDA olmak zorunda,
+            o yüzden arşivin tamamı tek dizine açılır).
+    """
+
+    ad: str
+    tur: str
+    url: str
+    sha256: str
+    boyut: int
+    varsayilan_mi: bool
+    aciklama: str = ""
+    arsiv: str | None = None
+    calistirilabilir: str | None = None
+
+    @property
+    def dosya_adi(self) -> str:
+        """URL'nin son parçası — diske bu adla yazılır."""
+        return self.url.rsplit("/", 1)[-1]
+
+
+def _varlik_kur(ham: dict[str, Any]) -> Varlik:
+    eksik = [a for a in _ZORUNLU if a not in ham]
+    if eksik:
+        raise ManifestHatasi(
+            f"manifest girdisinde eksik alan: {', '.join(eksik)} "
+            f"(girdi: {ham.get('ad', '?')})"
+        )
+    fazla = set(ham) - _IZINLI
+    if fazla:
+        raise ManifestHatasi(
+            f"manifest girdisinde bilinmeyen alan: {', '.join(sorted(fazla))} "
+            f"(girdi: {ham.get('ad', '?')})"
+        )
+    if ham["tur"] not in ("binary", "model"):
+        raise ManifestHatasi(f"bilinmeyen tur: {ham['tur']!r} (binary|model)")
+    return Varlik(
+        ad=str(ham["ad"]),
+        tur=str(ham["tur"]),
+        url=str(ham["url"]),
+        sha256=str(ham["sha256"]),
+        boyut=int(ham["boyut"]),
+        varsayilan_mi=bool(ham["varsayilan_mi"]),
+        aciklama=str(ham.get("aciklama", "")),
+        arsiv=ham.get("arsiv"),
+        calistirilabilir=ham.get("calistirilabilir"),
+    )
+
+
+def manifest_yukle(yol: Path | None = None) -> tuple[Varlik, ...]:
+    """Manifest'i okur ve doğrular; her çağrıda diskten (cache YOK).
+
+    Cache bilinçli olarak yok: dosya paket içindedir ve okuma maliyeti
+    ihmal edilebilir; cache'lemek testlerde ve PyInstaller'da bayat durum
+    riski yaratırdı.
+    """
+    hedef = yol if yol is not None else MANIFEST_YOLU
+    try:
+        ham = json.loads(hedef.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise ManifestHatasi(f"manifest bulunamadı: {hedef}") from exc
+    except (OSError, ValueError) as exc:
+        raise ManifestHatasi(f"manifest okunamadı ({hedef}): {exc}") from exc
+
+    if not isinstance(ham, dict) or "varliklar" not in ham:
+        raise ManifestHatasi(f"manifest biçimi geçersiz: {hedef}")
+    surum = ham.get("manifest_version")
+    if surum != MANIFEST_VERSION:
+        raise ManifestHatasi(
+            f"desteklenmeyen manifest_version: {surum} "
+            f"(bu sürüm {MANIFEST_VERSION} bekliyor)"
+        )
+    return tuple(_varlik_kur(g) for g in ham["varliklar"])
+
+
+def varliklar() -> tuple[Varlik, ...]:
+    """Paket içi manifest'teki tüm varlıklar."""
+    return manifest_yukle()
+
+
+def modeller() -> tuple[Varlik, ...]:
+    """Yalnız modeller — sihirbazın model seçicisi bunu listeler."""
+    return tuple(v for v in varliklar() if v.tur == "model")
+
+
+def binary_varligi() -> Varlik:
+    """Tek wcpp binary'si (Vulkan win-x64).
+
+    GPU tespiti / CUDA-vs-Vulkan seçimi YOKTUR (kapsam dışı): tek Vulkan
+    ikilisi üç donanım ailesini de sürüyor, CUDA yolu ileri kullanıcı için
+    manuel kalır.
+    """
+    for v in varliklar():
+        if v.tur == "binary":
+            return v
+    raise ManifestHatasi("manifest'te binary varlığı yok")
+
+
+def varsayilan_model() -> Varlik:
+    """Sihirbazda önceden seçili gelen model."""
+    for m in modeller():
+        if m.varsayilan_mi:
+            return m
+    raise ManifestHatasi("manifest'te varsayılan model işaretlenmemiş")
+
+
+def varlik_bul(ad: str) -> Varlik:
+    """Ada göre varlık; yoksa geçerli adları sayan Türkçe hata."""
+    tumu = varliklar()
+    for v in tumu:
+        if v.ad == ad:
+            return v
+    raise ManifestHatasi(
+        f"bilinmeyen varlık adı: {ad!r} — geçerli adlar: "
+        + ", ".join(v.ad for v in tumu)
+    )
+
+
+__all__ = [
+    "MANIFEST_VERSION",
+    "MANIFEST_YOLU",
+    "ManifestHatasi",
+    "Varlik",
+    "binary_varligi",
+    "manifest_yukle",
+    "modeller",
+    "varlik_bul",
+    "varliklar",
+    "varsayilan_model",
+]

fillercut/assets/manifest.json

@@ -0,0 +1,43 @@
+{
+  "manifest_version": 1,
+  "varliklar": [
+    {
+      "ad": "whisper-cli-vulkan-win-x64",
+      "tur": "binary",
+      "url": "https://github.com/inanx12/Filler-Cut/releases/download/v1.1.0/fillercut-whisper-cli-vulkan-win-x64.zip",
+      "sha256": "01707efa01523d042cd1b5980dabc43c70a68509360b16ee77d23317b90ccdf9",
+      "boyut": 23672623,
+      "varsayilan_mi": true,
+      "arsiv": "zip",
+      "calistirilabilir": "whisper-cli.exe",
+      "aciklama": "whisper.cpp / Vulkan (AMD, Intel, NVIDIA - ayni ikili)"
+    },
+    {
+      "ad": "ggml-large-v3-turbo-q5_0",
+      "tur": "model",
+      "url": "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin",
+      "sha256": "394221709cd5ad1f40c46e6031ca61bce88931e6e088c188294c6d5a55ffa7e2",
+      "boyut": 574041195,
+      "varsayilan_mi": true,
+      "aciklama": "Onerilen: hiz ve dogruluk dengesi (Turkce icin repo referansi)"
+    },
+    {
+      "ad": "ggml-small-q5_1",
+      "tur": "model",
+      "url": "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small-q5_1.bin",
+      "sha256": "ae85e4a935d7a567bd102fe55afc16bb595bdb618e11b2fc7591bc08120411bb",
+      "boyut": 190085487,
+      "varsayilan_mi": false,
+      "aciklama": "Hafif: yavas baglanti veya dar disk icin; dogruluk daha dusuk"
+    },
+    {
+      "ad": "ggml-large-v3-q5_0",
+      "tur": "model",
+      "url": "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-q5_0.bin",
+      "sha256": "d75795ecff3f83b5faa89d1900604ad8c780abd5739fae406de19f23ecd98ad1",
+      "boyut": 1081140203,
+      "varsayilan_mi": false,
+      "aciklama": "Kalite agirlikli: turbo olmayan large-v3, en yavas secenek"
+    }
+  ]
+}

fillercut/audio/__init__.py

@@ -0,0 +1 @@
+"""Katman 1 — EXTRACT: ses çıkarımı ve dalga formu analizi."""

fillercut/audio/extractor.py

@@ -0,0 +1,119 @@
+"""Katman 1 — EXTRACT: ffmpeg ile videodan 16 kHz mono WAV çıkarımı.
+
+ASR ve sessizlik tespiti için tek kanallı, 16 kHz WAV yeterlidir; orijinal
+ses kanalı/kazancı korunmaz çünkü bu dosya sadece analiz içindir (DESIGN.md §2).
+
+Bu modül bilerek sadece standart kütüphaneyi kullanır: birim testleri
+`subprocess.run`'ı mock'layarak ffmpeg olmadan da çalışır.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from fillercut import surec
+
+#: ASR backend'lerinin beklediği örnekleme hızı (Hz).
+SAMPLE_RATE = 16_000
+#: Analiz için mono yeterli.
+CHANNELS = 1
+
+#: Hata mesajında gösterilecek maksimum stderr uzunluğu.
+_STDERR_TAIL = 400
+
+
+class ExtractionError(RuntimeError):
+    """ffmpeg çıkarımı başarısız olduğunda fırlatılır."""
+
+
+def build_command(input_path: Path, output_path: Path) -> list[str]:
+    """ffmpeg komut satırını üretir.
+
+    Saf fonksiyondur — yan etkisi yoktur, testler doğrudan bunu doğrular.
+    """
+    return [
+        "ffmpeg",
+        "-y",  # çıktı varsa soru sormadan üzerine yaz
+        "-i",
+        str(input_path),
+        "-vn",  # video akışını at
+        "-ac",
+        str(CHANNELS),
+        "-ar",
+        str(SAMPLE_RATE),
+        "-f",
+        "wav",
+        str(output_path),
+    ]
+
+
+def default_output_path(input_path: Path) -> Path:
+    """Girdiyle aynı klasörde, aynı isimli `.wav` yolu."""
+    return input_path.with_suffix(".wav")
+
+
+def extract_audio(
+    input_path: str | Path,
+    output_path: str | Path | None = None,
+    *,
+    timeout: float = 600.0,
+) -> Path:
+    """Videodan 16 kHz mono WAV çıkarır.
+
+    Args:
+        input_path: Kaynak video (veya ses) dosyası.
+        output_path: Hedef WAV; verilmezse girdinin yanına `<isim>.wav` yazılır.
+        timeout: ffmpeg işlemi için saniye cinsinden üst sınır.
+
+    Returns:
+        Üretilen WAV dosyasının yolu.
+
+    Raises:
+        FileNotFoundError: Girdi dosyası yoksa.
+        ExtractionError: ffmpeg bulunamazsa, sıfırdan farklı kodla çıkarsa,
+            süre aşımına uğrarsa veya çıktıyı üretemezse.
+    """
+    src = Path(input_path)
+    if not src.is_file():
+        raise FileNotFoundError(f"girdi dosyası bulunamadı: {src}")
+
+    if shutil.which("ffmpeg") is None:
+        raise ExtractionError(
+            "ffmpeg bulunamadı — PATH'e kurulu olmalı (bkz. README: sistem bağımlılığı)"
+        )
+
+    dst = Path(output_path) if output_path is not None else default_output_path(src)
+    cmd = build_command(src, dst)
+
+    try:
+        proc = surec.kos(
+            cmd,
+            capture_output=True,
+            text=True,
+            # `errors` olmadan decode STRICT'tir ve hata subprocess.run
+            # ÇAĞRISININ KENDİSİNDE UnicodeDecodeError olarak patlar; aşağıdaki
+            # ExtractionError sarması hiç devreye giremez. ffmpeg banner'ı locale
+            # encoding'inde (Windows-TR: cp1254) çözülemeyen byte içerebilir —
+            # Türkçe dosya adları, kaynak metadata'sı. Locale encoding'i korunur:
+            # okunan şey yalnızca kullanıcıya gösterilen hata kuyruğudur.
+            errors="replace",
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise ExtractionError(
+            f"ffmpeg {timeout:.0f} sn içinde bitmedi: {src}"
+        ) from exc
+
+    if proc.returncode != 0:
+        tail = (proc.stderr or "").strip()[-_STDERR_TAIL:]
+        raise ExtractionError(
+            f"ffmpeg hata kodu {proc.returncode} ile çıktı: {src}\n{tail}"
+        )
+
+    if not dst.is_file() or dst.stat().st_size == 0:
+        raise ExtractionError(f"ffmpeg çıktı üretmedi: {dst}")
+
+    return dst

fillercut/audio/probe.py

@@ -0,0 +1,98 @@
+"""ffprobe ile medya süresi — ms-int (zaman birimi kuralı, models.py docstring'i).
+
+`total_ms` iki yerde zorunludur: `audio/silence.py`'nin kapanmamış sessizliği
+uzatması ve `report/json_report.py`'nin plan/gerçeklik uyuşma kontrolü. Tek
+ffprobe çağrısıyla alınır (pipeline [1] EXTRACT öncesi okur).
+
+Saf/yan-etki ayrımı (extractor deseni): `parse_duration` saf fonksiyondur
+(str → int ms); subprocess çağrısı `probe_duration_ms` wrapper'ındadır.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from fillercut import surec
+
+#: Hata mesajında gösterilecek maksimum stderr uzunluğu.
+_STDERR_TAIL = 400
+
+
+class ProbeError(RuntimeError):
+    """ffprobe çalıştırılamadığında/başarısız olduğunda fırlatılır."""
+
+
+def build_command(path: Path) -> list[str]:
+    """ffprobe komut satırı — saf fonksiyon (extractor deseni).
+
+    `format=duration` container süresidir (saniye-float, örn. `14.814331`).
+    """
+    return [
+        "ffprobe",
+        "-v",
+        "error",
+        "-show_entries",
+        "format=duration",
+        "-of",
+        "default=noprint_wrappers=1:nokey=1",
+        str(path),
+    ]
+
+
+def parse_duration(stdout: str) -> int:
+    """ffprobe `format=duration` çıktısını (saniye-float) ms-int'e çevirir.
+
+    Saf fonksiyondur. `int()` yerine `round()`: kırpma değil en yakın ms —
+    audio/silence.py ile aynı kural.
+
+    Raises:
+        ProbeError: Çıktı sayı değilse veya süre pozitif değilse.
+    """
+    try:
+        ms = int(round(float(stdout.strip()) * 1000))
+    except ValueError as exc:
+        raise ProbeError(f"ffprobe süre çıktısı parse edilemedi: {stdout.strip()!r}") from exc
+    if ms <= 0:
+        raise ProbeError(f"ffprobe pozitif olmayan süre döndü: {ms}ms")
+    return ms
+
+
+def probe_duration_ms(path: str | Path, *, timeout: float = 60.0) -> int:
+    """Medya dosyasının süresini ffprobe ile ms-int olarak döner.
+
+    Raises:
+        FileNotFoundError: Girdi dosyası yoksa.
+        ProbeError: ffprobe bulunamazsa, hata koduyla çıkarsa, süre aşımına
+            uğrarsa veya çıktısı parse edilemezse.
+    """
+    src = Path(path)
+    if not src.is_file():
+        raise FileNotFoundError(f"girdi dosyası bulunamadı: {src}")
+    if shutil.which("ffprobe") is None:
+        raise ProbeError("ffprobe bulunamadı — ffmpeg ile birlikte PATH'e kurulu olmalı")
+
+    try:
+        proc = surec.kos(
+            build_command(src),
+            capture_output=True,
+            text=True,
+            # ffprobe çıktısı spec gereği UTF-8'dir (Türkçe `title` metadata'sı
+            # dahil); locale encoding'i (Windows-TR: cp1254) onu mojibake'e
+            # çevirir. `errors` olmadan decode strict'tir ve hata subprocess.run
+            # ÇAĞRISININ KENDİSİNDE UnicodeDecodeError olarak patlar — aşağıdaki
+            # ProbeError sarması hiç devreye giremez.
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise ProbeError(f"ffprobe {timeout:.0f} sn içinde bitmedi: {src}") from exc
+
+    if proc.returncode != 0:
+        tail = (proc.stderr or "").strip()[-_STDERR_TAIL:]
+        raise ProbeError(f"ffprobe hata kodu {proc.returncode} ile çıktı: {src}\n{tail}")
+
+    return parse_duration(proc.stdout)

fillercut/audio/silence.py

@@ -0,0 +1,161 @@
+"""Katman 3 — DETECT (dalga formu tarafı): ffmpeg `silencedetect` parse'ı.
+
+**KRİTİK:** `silencedetect` sonuçları **stderr**'e yazar, stdout'a DEĞİL.
+Komut::
+
+    ffmpeg -i in.wav -af silencedetect=noise=-35dB:d=0.4 -f null -
+
+stderr'deki satırlar şöyledir::
+
+    [silencedetect @ 0000021f8a3b4c00] silence_start: 1.0234
+    [silencedetect @ 0000021f8a3b4c00] silence_end: 2.4576 | silence_duration: 1.4342
+
+`parse_silence` saf fonksiyondur (str → list[Segment]); subprocess çağrısı
+`detect_silence` wrapper'ındadır — extractor.py ile aynı desen.
+
+Süre sınırlaması (`silence_min_ms`) burada UYGULANMAZ; o filtre
+`detect/silence.py`'nin işi. Bu modül ffmpeg'in raporladığını aynen döner.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from fillercut import surec
+from fillercut.models import Segment
+
+#: Eşik sabitleri — config'e v0.2'de taşınacak (DESIGN.md §6).
+NOISE_DB = -35
+MIN_SILENCE_SEC = 0.4
+
+_START_RE = re.compile(r"silence_start:\s*(-?\d+(?:\.\d+)?)")
+_END_RE = re.compile(r"silence_end:\s*(-?\d+(?:\.\d+)?)\s*\|\s*silence_duration:")
+
+
+class SilenceDetectionError(RuntimeError):
+    """ffmpeg silencedetect çalıştırılamadığında/başarısız olduğunda fırlatılır."""
+
+
+def _sn_to_ms(sn: float) -> int:
+    """Saniye (float) → milisaniye (int).
+
+    `int()` yerine `round()`: 1.4342 sn → 1434 ms (kırpma değil, en yakın ms).
+    Kesim noktalarındaki birikimli kaymayı önler (ms-int disiplini).
+    """
+    return int(round(sn * 1000))
+
+
+def parse_silence(stderr: str, total_duration_ms: int | None = None) -> list[Segment]:
+    """silencedetect stderr çıktısını ``kind="silence"`` segmentlere çevirir.
+
+    Saf fonksiyondur — yan etki yok, ffmpeg olmadan test edilebilir.
+
+    Args:
+        stderr: ffmpeg'in stderr çıktısı (banner/satır gürültüsü tolere edilir).
+        total_duration_ms: Dosya sessizlikle biterse ffmpeg `silence_end` BASMAZ;
+            açık kalan sessizlik bu değere uzatılır. Böyle bir durumda zorunludur.
+
+    Raises:
+        ValueError: Kapanmamış `silence_start` varken `total_duration_ms`
+            verilmediyse.
+    """
+    segments: list[Segment] = []
+    pending_start_ms: int | None = None
+
+    def _kapat(end_ms: int) -> None:
+        nonlocal pending_start_ms
+        if pending_start_ms is not None and end_ms > pending_start_ms:
+            segments.append(
+                Segment(
+                    start_ms=pending_start_ms,
+                    end_ms=end_ms,
+                    kind="silence",
+                    reason=(
+                        f"sessizlik {end_ms - pending_start_ms}ms "
+                        f"(noise={NOISE_DB}dB, min={MIN_SILENCE_SEC}s)"
+                    ),
+                )
+            )
+        pending_start_ms = None
+
+    for line in stderr.splitlines():
+        if m := _START_RE.search(line):
+            pending_start_ms = _sn_to_ms(float(m.group(1)))
+        elif m := _END_RE.search(line):
+            _kapat(_sn_to_ms(float(m.group(1))))
+
+    if pending_start_ms is not None:
+        if total_duration_ms is None:
+            raise ValueError(
+                "kapanmamış silence_start var (dosya sessizlikle bitiyor); "
+                "uzatma için total_duration_ms gerekli"
+            )
+        _kapat(total_duration_ms)
+
+    return segments
+
+
+def build_command(wav_path: Path) -> list[str]:
+    """silencedetect komut satırı — saf fonksiyon (extractor deseni)."""
+    return [
+        "ffmpeg",
+        "-i",
+        str(wav_path),
+        "-af",
+        f"silencedetect=noise={NOISE_DB}dB:d={MIN_SILENCE_SEC}",
+        "-f",
+        "null",
+        "-",
+    ]
+
+
+def detect_silence(
+    wav_path: str | Path,
+    *,
+    total_duration_ms: int | None = None,
+    timeout: float = 600.0,
+) -> list[Segment]:
+    """WAV üzerinde silencedetect çalıştırır ve stderr'i parse eder.
+
+    Raises:
+        FileNotFoundError: Girdi dosyası yoksa.
+        SilenceDetectionError: ffmpeg yoksa veya hata koduyla çıkarsa.
+    """
+    src = Path(wav_path)
+    if not src.is_file():
+        raise FileNotFoundError(f"girdi dosyası bulunamadı: {src}")
+    if shutil.which("ffmpeg") is None:
+        raise SilenceDetectionError("ffmpeg bulunamadı — PATH'e kurulu olmalı")
+
+    try:
+        proc = surec.kos(
+            build_command(src),
+            capture_output=True,
+            text=True,
+            # `errors` olmadan decode STRICT'tir ve hata subprocess.run
+            # ÇAĞRISININ KENDİSİNDE UnicodeDecodeError olarak patlar; aşağıdaki
+            # SilenceDetectionError sarması hiç devreye giremez. Parse ettiğimiz
+            # `silence_start:`/`silence_end:` satırları saf ASCII'dir — Türkçe
+            # dosya adı yalnızca ATLANAN header satırlarında geçer, dolayısıyla
+            # U+FFFD'ye dönen byte'lar sonuçları etkilemez. Locale encoding'i
+            # korunur: ffmpeg log'u UTF-8 değil, locale encoding'indedir.
+            errors="replace",
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise SilenceDetectionError(
+            f"ffmpeg {timeout:.0f} sn içinde bitmedi: {src}"
+        ) from exc
+
+    if proc.returncode != 0:
+        tail = (proc.stderr or "").strip()[-400:]
+        raise SilenceDetectionError(
+            f"ffmpeg hata kodu {proc.returncode} ile çıktı: {src}\n{tail}"
+        )
+
+    # DİKKAT: sonuçlar stderr'de — stdout bilerek kullanılmıyor.
+    return parse_silence(proc.stderr, total_duration_ms=total_duration_ms)