pixcull 2.43.4__tar.gz

pixcull-2.43.4/.gitignore

@@ -0,0 +1,98 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# PixCull artifacts
+models/*.onnx
+models/*.pt
+models/*.bin
+models/*.safetensors
+output/
+v0_output/
+*.xmp.bak
+*.sqlite
+*.sqlite3
+thumbs/
+
+# v2.5 — the committed hermetic visual-smoke fixture run lives under an
+# output/ dir (serve_demo._reload_run_from_disk requires that layout), so
+# un-ignore just it (the broad output/ rule above would otherwise hide it).
+!tests/fixtures/smoke_run/output/
+!tests/fixtures/smoke_run/output/**
+
+# Internal / not for public repo
+MARKET_ANALYSIS_*.md
+.claude/
+*.local
+*.notes.md
+
+# Per-developer or runtime config — these should stay private even on a
+# fork. The taxonomy and config defaults live in code; anything written
+# at runtime (DeepSeek key, license token, sync paths) belongs in the
+# user's app-data dir, not the repo.
+.envrc
+.env
+.env.local
+*.token
+
+# Lr plugin packaged bundles
+lr_plugin/*.zip
+lr_plugin/*.lrtemplate
+
+# Large generated artifacts
+*.h5
+*.npz
+face_library*.npz
+*.bak
+
+# P-PRO-4.2 — wedding-moment eval output (contains real photographer
+# filenames; goldenset CSV is a local artifact, not a public dataset)
+out_wedding_eval/
+predictions*.csv
+
+# Swift Package Manager build cache (generated by `swift build` /
+# Xcode); large + machine-specific.  Don't commit.
+mobile/PixCullCompanion/.build/
+out_wedding_eval/realdemo01_smoke/
+goldenset/v0.11/_eval_output/
+goldenset/v0.11/training.csv
+
+# modelscope upload cache (transient)
+docs/screenshots/.ms_upload_cache
+
+# v2.14 — local labeling sheets (may contain real photo filenames; keep private)
+label_sheet*.csv
+
+# v2.19 — local wheel build output
+dist_wheel/
+
+# v2.32 — cross-run library index: records REAL absolute photo paths,
+# private to the machine. Never commit; it lives in ~/.pixcull/library/
+# but guard against a stray local copy too.
+library/
+vectors.npy
+manifest.jsonl

pixcull-2.43.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chris Chen (ChrisChen667788)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pixcull-2.43.4/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: pixcull
+Version: 2.43.4
+Summary: Local-first AI photo culling for professional photographers — 6-axis rubric, XMP/IPTC export, Lightroom & Capture One ready.
+Project-URL: Homepage, https://github.com/ChrisChen667788/pixcull
+Project-URL: Repository, https://github.com/ChrisChen667788/pixcull
+Project-URL: Issues, https://github.com/ChrisChen667788/pixcull/issues
+Project-URL: Documentation, https://github.com/ChrisChen667788/pixcull#readme
+Project-URL: ModelScope, https://www.modelscope.cn/profile/haozi667788
+Author-email: Chris Chen <hello@pixcull.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,capture-one,computer-vision,image-classification,image-quality-assessment,iptc,lightroom,local-first,on-device-ai,photo-culling,photography,raw-photography,rubric-scoring,wedding-photography,xmp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: <3.13,>=3.11
+Requires-Dist: imagededup>=0.3.2
+Requires-Dist: insightface>=0.7
+Requires-Dist: jinja2>=3.1
+Requires-Dist: numpy<2,>=1.26
+Requires-Dist: onnxruntime>=1.17
+Requires-Dist: opencv-python>=4.9
+Requires-Dist: pandas>=2.2
+Requires-Dist: pillow>=10.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyiqa>=0.1.11
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rawpy>=0.19
+Requires-Dist: rembg>=2.0.57
+Requires-Dist: rich>=13.7
+Requires-Dist: safetensors>=0.4
+Requires-Dist: sqlmodel>=0.0.16
+Requires-Dist: structlog>=24.1
+Requires-Dist: torch<3,>=2.2
+Requires-Dist: torchvision<1,>=0.17
+Requires-Dist: tqdm>=4.66
+Requires-Dist: transformers<6,>=4.40
+Requires-Dist: typer>=0.12
+Provides-Extra: asr
+Requires-Dist: funasr>=1.1; extra == 'asr'
+Requires-Dist: torchaudio>=2.0; extra == 'asr'
+Provides-Extra: asr-mlx
+Requires-Dist: mlx-whisper>=0.4; extra == 'asr-mlx'
+Provides-Extra: asr-whisper
+Requires-Dist: faster-whisper>=1.0; extra == 'asr-whisper'
+Provides-Extra: bird
+Requires-Dist: segment-anything>=1.0; extra == 'bird'
+Requires-Dist: ultralytics>=8.2; extra == 'bird'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hatchling>=1.20; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pillow; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: face
+Requires-Dist: mediapipe>=0.10.14; extra == 'face'
+Provides-Extra: shots
+Requires-Dist: scenedetect>=0.6; extra == 'shots'
+Provides-Extra: sync
+Requires-Dist: zeroconf>=0.131; extra == 'sync'
+Description-Content-Type: text/markdown
+
+# PixCull
+
+**Local-first AI photo culling for working photographers.**
+Six calibrated scoring axes · burst folding · style-aware personalization ·
+Lightroom / Capture One round-trip. **No photo ever leaves your disk.**
+
+本地优先的 AI 摄影分拣:6 轴评分 · 连拍折叠 · 个性化学习 · Lr/C1 双向 round-trip,
+原图永远不离开你的硬盘。
+
+![PixCull results grid](https://raw.githubusercontent.com/ChrisChen667788/pixcull/main/docs/screenshots/01-results-grid.png)
+
+## Install
+
+```bash
+pip install pixcull
+```
+
+Python 3.11–3.12. First run downloads the optional scoring models to
+`~/.pixcull/models/` (everything runs on-device; Apple-silicon accelerated).
+
+## Quickstart
+
+```bash
+# score a folder of photos (JPG / RAW) — keep/maybe/cull + per-axis rubric
+pixcull run /path/to/photos -o ./out
+
+# write the decisions back as XMP sidecars for Lightroom / Capture One
+pixcull export ./out --xmp
+
+# score a video → temporal windows + reel candidates
+pixcull video clip.mp4 -o ./out
+
+# fold near-duplicates, build a contact sheet, learn your taste, …
+pixcull --help
+```
+
+```bash
+# open the review workspace in your browser (v2.31 — now packaged)
+pixcull serve
+```
+
+The pip package ships the full scoring engine, the CLI **and** the
+interactive review workspace: keyboard-first grid, ⌘K palette, per-axis
+"why" explanations, n-way compare, maybe-resolution queue, XMP export.
+`pixcull serve` stores runs under `~/.pixcull/runs` by default
+(`--root` to change, `--host 0.0.0.0` to share on a trusted LAN).
+
+![PixCull lightbox](https://raw.githubusercontent.com/ChrisChen667788/pixcull/main/docs/screenshots/03-lightbox.png)
+
+## Highlights
+
+- **Glass-box scoring** — every keep/cull carries a per-axis breakdown
+  (technical / subject / composition / light / moment / aesthetic) and a
+  plain-language "why", not just a number.
+- **Learns your taste** — corrections feed a personal profile that tilts
+  the axis weights toward what *you* demonstrably value.
+- **Burst & near-dup folding** — stacks collapse to the peak frame with a
+  one-key compare.
+- **Video too** — temporal scoring, audio events (laughter / applause /
+  music), reel-candidate detection with the same glass-box treatment.
+- **13 UI languages**, dark/light studio-neutral themes, WCAG-conscious.
+- **Local-first, always** — no uploads, no cloud, no telemetry.
+
+## Links
+
+- [GitHub + full README](https://github.com/ChrisChen667788/pixcull)
+- [Releases](https://github.com/ChrisChen667788/pixcull/releases)
+- [ModelScope mirror](https://www.modelscope.cn/models/haozi667788/pixcull)
+
+MIT © Chris Chen

pixcull-2.43.4/README-PYPI.md

@@ -0,0 +1,70 @@
+# PixCull
+
+**Local-first AI photo culling for working photographers.**
+Six calibrated scoring axes · burst folding · style-aware personalization ·
+Lightroom / Capture One round-trip. **No photo ever leaves your disk.**
+
+本地优先的 AI 摄影分拣:6 轴评分 · 连拍折叠 · 个性化学习 · Lr/C1 双向 round-trip,
+原图永远不离开你的硬盘。
+
+![PixCull results grid](https://raw.githubusercontent.com/ChrisChen667788/pixcull/main/docs/screenshots/01-results-grid.png)
+
+## Install
+
+```bash
+pip install pixcull
+```
+
+Python 3.11–3.12. First run downloads the optional scoring models to
+`~/.pixcull/models/` (everything runs on-device; Apple-silicon accelerated).
+
+## Quickstart
+
+```bash
+# score a folder of photos (JPG / RAW) — keep/maybe/cull + per-axis rubric
+pixcull run /path/to/photos -o ./out
+
+# write the decisions back as XMP sidecars for Lightroom / Capture One
+pixcull export ./out --xmp
+
+# score a video → temporal windows + reel candidates
+pixcull video clip.mp4 -o ./out
+
+# fold near-duplicates, build a contact sheet, learn your taste, …
+pixcull --help
+```
+
+```bash
+# open the review workspace in your browser (v2.31 — now packaged)
+pixcull serve
+```
+
+The pip package ships the full scoring engine, the CLI **and** the
+interactive review workspace: keyboard-first grid, ⌘K palette, per-axis
+"why" explanations, n-way compare, maybe-resolution queue, XMP export.
+`pixcull serve` stores runs under `~/.pixcull/runs` by default
+(`--root` to change, `--host 0.0.0.0` to share on a trusted LAN).
+
+![PixCull lightbox](https://raw.githubusercontent.com/ChrisChen667788/pixcull/main/docs/screenshots/03-lightbox.png)
+
+## Highlights
+
+- **Glass-box scoring** — every keep/cull carries a per-axis breakdown
+  (technical / subject / composition / light / moment / aesthetic) and a
+  plain-language "why", not just a number.
+- **Learns your taste** — corrections feed a personal profile that tilts
+  the axis weights toward what *you* demonstrably value.
+- **Burst & near-dup folding** — stacks collapse to the peak frame with a
+  one-key compare.
+- **Video too** — temporal scoring, audio events (laughter / applause /
+  music), reel-candidate detection with the same glass-box treatment.
+- **13 UI languages**, dark/light studio-neutral themes, WCAG-conscious.
+- **Local-first, always** — no uploads, no cloud, no telemetry.
+
+## Links
+
+- [GitHub + full README](https://github.com/ChrisChen667788/pixcull)
+- [Releases](https://github.com/ChrisChen667788/pixcull/releases)
+- [ModelScope mirror](https://www.modelscope.cn/models/haozi667788/pixcull)
+
+MIT © Chris Chen

pixcull-2.43.4/pixcull/__init__.py

@@ -0,0 +1,55 @@
+"""PixCull — AI photo culling & scoring."""
+
+import sys
+
+# v2.19 — single-source the version from package metadata (pyproject);
+# the literal is only the fallback for running from a raw source tree.
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("pixcull")
+except Exception:
+    __version__ = "2.43.4"
+
+
+def _check_numpy_compatibility() -> None:
+    """ROADMAP INFRA-5 — runtime guard against the numpy 2.x regression.
+
+    We've been bitten twice (V18.1 and V22.0.1) when a transitive
+    ``pip install`` upgraded numpy to 2.x. The symptoms are subtle:
+    mediapipe imports cleanly but its face detector silently returns
+    empty results, and pre-V18.3 rescorer joblibs fail to unpickle
+    because the ``numpy.random._pcg64.PCG64`` paths differ between
+    1.x and 2.x. Neither failure is loud — face_count just stays 0
+    on all images, the rescorer silently falls back to rule-only.
+
+    Pin in pyproject.toml is ``numpy>=1.26,<2``, but a third-party
+    install command (``pip install some-other-package``) can still
+    blow past the pin. We don't fail hard here — that would break
+    perfectly fine pipelines that don't touch faces — but we DO
+    print a loud warning on every import so the regression is
+    visible at the top of the log.
+    """
+    try:
+        import numpy
+    except ImportError:
+        return  # numpy missing is a different problem; let downstream report
+    ver = getattr(numpy, "__version__", "")
+    try:
+        major = int(ver.split(".")[0])
+    except (ValueError, IndexError):
+        return
+    if major >= 2:
+        print(
+            "\n"
+            "⚠ PixCull: numpy " + ver + " detected.\n"
+            "  mediapipe (face detector) and the V18.3 rescorer joblibs\n"
+            "  need numpy 1.x. Run:\n"
+            "      pip install 'numpy<2'\n"
+            "  to fix. Without this, faces won't be detected (face_count\n"
+            "  will be 0 on every photo) and the rescorer falls back to\n"
+            "  rule-only mode.\n",
+            file=sys.stderr,
+        )
+
+
+_check_numpy_compatibility()

pixcull-2.43.4/pixcull/__main__.py

@@ -0,0 +1,4 @@
+from pixcull.cli import app
+
+if __name__ == "__main__":
+    app()

pixcull-2.43.4/pixcull/audio_sync.py

@@ -0,0 +1,269 @@
+"""v0.10-P1-4 — audio-photo sync for the wedding tether flow.
+
+Experimental.  Wedding-day shooters often want photos that
+correspond to specific ceremony moments (vows / ring exchange /
+first kiss / cake cutting) auto-flagged with the right
+``wedding_moment`` so the post-shoot delivery groups them
+cleanly.  The hard part is *detecting* the moment in real time —
+we offload that to a client (iOS PixCullCompanion with
+WhisperKit, or an external CLI hooked to the venue's PA system)
+which sends us transcripts.
+
+Wire model
+==========
+Client posts transcript chunks via:
+
+    POST /api/v1/runs/<run_id>/audio_sync
+    body: {
+      "transcripts": [
+        {"ts_ms": 1700000000000, "text": "I now pronounce you...",
+         "confidence": 0.92},
+        ...
+      ]
+    }
+
+We:
+
+1. Run keyword matching against a built-in vocabulary
+   (CEREMONY_KEYWORDS below).  Returns the matched moments
+   each transcript hit.
+2. Correlate transcript ts_ms ± window_s with photo capture
+   times (read from scores.csv's mtime column).
+3. Boost the wedding_moment field on matched rows.
+
+The keyword vocabulary is intentionally conservative — we want
+high precision (false moment tags would mislead the delivery)
+at the cost of recall.  A photographer who wants more moments
+matched can extend CEREMONY_KEYWORDS in their own deployment.
+
+Opt-in only.  PIXCULL_AUDIO_SYNC=1 env var required to enable
+the route; otherwise the POST returns 403.  Privacy guarantee:
+audio bytes are NEVER sent to the server — only the transcript
+text + timestamps.  WhisperKit on iOS does all the STT locally.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Iterable
+
+
+# Keyword → wedding_moment vocabulary.  Lowercased ASCII keys
+# only — clients normalise transcripts to ASCII before sending.
+# Format: phrase → moment_id.  ``moment_id`` matches the
+# canonical wedding_moment vocabulary used by
+# pixcull.scoring.wedding_moment.WEDDING_MOMENTS.
+#
+# Conservative — only phrases that are extremely unlikely to
+# appear outside the corresponding moment.  "ring" alone is
+# excluded (it shows up in too many other contexts).  "the
+# rings" / "exchange rings" are included because those phrasings
+# are strongly ceremony-bound.
+CEREMONY_KEYWORDS: dict[str, str] = {
+    # Vows
+    "i, take you to be my":      "vows",
+    "to have and to hold":       "vows",
+    "from this day forward":     "vows",
+    "for better or for worse":   "vows",
+    "till death do us part":     "vows",
+    "vows":                       "vows",
+    "我愿意":                     "vows",       # Chinese ceremony
+
+    # Ring exchange
+    "exchange rings":             "ring_exchange",
+    "with this ring":             "ring_exchange",
+    "place this ring":            "ring_exchange",
+    "the rings":                  "ring_exchange",
+    "交换戒指":                   "ring_exchange",
+
+    # First kiss
+    "you may now kiss":           "kiss",
+    "you may kiss the bride":     "kiss",
+    "kiss the bride":             "kiss",
+    "kiss the partner":           "kiss",
+    "first kiss as":              "kiss",
+
+    # Pronouncement
+    "i now pronounce you":        "pronouncement",
+    "by the power vested in me":  "pronouncement",
+    "husband and wife":           "pronouncement",
+    "wife and wife":              "pronouncement",
+    "husband and husband":        "pronouncement",
+
+    # First dance
+    "first dance":                "first_dance",
+    "their first dance":          "first_dance",
+    "请新郎新娘跳第一支舞":         "first_dance",
+
+    # Cake cutting
+    "cake cutting":               "cake_cutting",
+    "cut the cake":               "cake_cutting",
+    "cutting the cake":           "cake_cutting",
+    "切蛋糕":                     "cake_cutting",
+
+    # Toasts
+    "to the bride and groom":     "toast",
+    "raise a glass":              "toast",
+    "raise our glasses":          "toast",
+    "举杯":                       "toast",
+
+    # Chinese-tradition moments
+    "敬茶":                       "tea_ceremony",
+    "tea ceremony":               "tea_ceremony",
+    "三鞠躬":                     "bow",
+    "跪拜":                       "bow",
+}
+
+
+# Default time window: when a transcript matches at ts, photos
+# whose mtime falls within ±window_s get the wedding_moment
+# boost.  90 s is a Goldilocks default — large enough to cover
+# "celebrant says 'I now pronounce you...' then 60s of kiss +
+# applause" but small enough that consecutive ceremony moments
+# (vows then ring then pronouncement) don't all get the same
+# tag.  Override via the POST body's `window_s` field.
+DEFAULT_WINDOW_S = 90.0
+
+
+def is_enabled() -> bool:
+    """v0.10-P1-4 is opt-in to keep privacy posture conservative.
+
+    Photographers who want it set PIXCULL_AUDIO_SYNC=1 in their
+    shell env; the server route returns 403 otherwise so a
+    runaway client doesn't accidentally boost wedding moments
+    on a run that should have stayed scene-only.
+    """
+    return os.environ.get("PIXCULL_AUDIO_SYNC", "").strip() in ("1", "true", "yes")
+
+
+def match_transcript(text: str) -> str | None:
+    """Return the wedding_moment matched by this transcript, or None.
+
+    Lowercases the input before matching so the vocab keys can
+    stay lowercase.  Uses substring match (not regex) for both
+    speed and to keep the vocab obvious to a human auditor.
+    Matches the FIRST keyword found scanning the vocab in
+    insertion order — most-specific phrases first by convention.
+    """
+    if not text:
+        return None
+    t = text.lower()
+    for kw, moment in CEREMONY_KEYWORDS.items():
+        if kw in t:
+            return moment
+    return None
+
+
+def match_transcripts(
+    transcripts: Iterable[dict],
+    *,
+    min_confidence: float = 0.6,
+) -> list[dict]:
+    """Apply match_transcript to a batch, with confidence gate.
+
+    Returns the SUBSET of transcripts that matched, each enriched
+    with the inferred ``moment``.  Drops anything below
+    min_confidence (defensive against noisy STT environments;
+    weddings are loud).  Order is preserved from the input.
+    """
+    out = []
+    for t in transcripts:
+        if not isinstance(t, dict):
+            continue
+        try:
+            ts_ms = int(t.get("ts_ms") or 0)
+        except (TypeError, ValueError):
+            continue
+        try:
+            conf = float(t.get("confidence") or 0)
+        except (TypeError, ValueError):
+            conf = 0.0
+        text = str(t.get("text") or "")
+        if conf < min_confidence:
+            continue
+        moment = match_transcript(text)
+        if moment is None:
+            continue
+        out.append({
+            "ts_ms":     ts_ms,
+            "text":      text,
+            "moment":    moment,
+            "confidence": conf,
+        })
+    return out
+
+
+def correlate_with_rows(
+    matches: list[dict],
+    rows: list[dict],
+    *,
+    window_s: float = DEFAULT_WINDOW_S,
+) -> dict[str, str]:
+    """Assign wedding_moment to photo rows whose mtime falls
+    within ±window_s of any transcript match.
+
+    Returns a {filename: moment} dict — caller persists.  Rows
+    that fall inside multiple moments' windows take the LATEST
+    match (the transcript chronologically closest "before" the
+    photo wins, because the photographer typically captures
+    AFTER the celebrant says the words).
+
+    Defensive against rows missing mtime: those are skipped
+    silently.
+    """
+    if not matches or not rows:
+        return {}
+    window_ms = window_s * 1000.0
+    sorted_matches = sorted(matches, key=lambda m: m["ts_ms"])
+    out: dict[str, str] = {}
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        fn = row.get("filename")
+        if not isinstance(fn, str) or not fn:
+            continue
+        try:
+            # rows store seconds-since-epoch; transcripts ms.
+            mtime_ms = float(row.get("mtime") or 0) * 1000.0
+        except (TypeError, ValueError):
+            continue
+        if mtime_ms <= 0:
+            continue
+        # Walk matches from latest-before to earliest-before so
+        # the first valid window wins.
+        best: str | None = None
+        for m in reversed(sorted_matches):
+            if m["ts_ms"] - window_ms <= mtime_ms <= m["ts_ms"] + window_ms:
+                best = m["moment"]
+                break
+        if best is not None:
+            out[fn] = best
+    return out
+
+
+def apply_audio_sync(
+    transcripts: Iterable[dict],
+    rows: list[dict],
+    *,
+    window_s: float = DEFAULT_WINDOW_S,
+    min_confidence: float = 0.6,
+) -> dict:
+    """Top-level — what the HTTP handler calls.
+
+    Returns the summary the client renders + the suggested
+    wedding_moment overrides.  The actual write-back to
+    scores.csv / annotations.jsonl is the caller's job (the
+    server-side handler decides whether to persist or just
+    preview).
+    """
+    matches = match_transcripts(transcripts, min_confidence=min_confidence)
+    suggestions = correlate_with_rows(matches, rows, window_s=window_s)
+    return {
+        "n_transcripts":  len(list(transcripts) if not isinstance(transcripts, list) else transcripts),
+        "n_matched":      len(matches),
+        "matches":        matches,
+        "n_suggestions":  len(suggestions),
+        "suggestions":    suggestions,
+        "window_s":       window_s,
+    }