polysync 0.1.0__py3-none-any.whl

polysync/edit/render_pip.py

@@ -0,0 +1,141 @@
+"""Render an autoedit EDL with picture-in-picture for 1, 2, or N cameras.
+
+- 1 cam: pass-through (no inset).
+- 2 cam: main = active cam; PiP = the other cam at the same time range.
+- N cam: main = active; PiP = a covered non-active cam (round-robin or first).
+
+Per-segment EDL rows may carry a `pip` field (cam index) to override the picker.
+"""
+import argparse
+import json
+import subprocess
+from pathlib import Path
+
+POSITIONS = {
+    "bottom-right": ("W-w-{m}", "H-h-{m}"),
+    "top-right":    ("W-w-{m}", "{m}"),
+    "bottom-left":  ("{m}",     "H-h-{m}"),
+    "top-left":     ("{m}",     "{m}"),
+}
+
+
+def pick_pip(row, K, coverage, mode="next"):
+    """Choose the PiP cam for a segment, among cams covered for the WHOLE
+    segment. Honours an explicit row['pip']. Returns None if no other cam fits."""
+    if row.get("pip") is not None:
+        return int(row["pip"])
+    cam = row["cam"]
+    s, e = row["start"], row["end"]
+    candidates = [k for k in range(K)
+                  if k != cam and coverage[k][0] <= s and coverage[k][1] >= e]
+    if not candidates:
+        return None
+    if mode == "next":
+        for off in range(1, K):
+            cand = (cam + off) % K
+            if cand in candidates:
+                return cand
+    return candidates[0]
+
+
+def render_pip(edl_path, out, encoder="hevc_videotoolbox", bitrate="12M",
+               width=1920, height=1080, fps=30, pip="bottom-right",
+               pip_width=480, pip_margin=24, border_px=4, pip_pick="next",
+               run=True):
+    plan = json.loads(Path(edl_path).read_text())
+    inputs = plan["inputs"]
+    deltas = plan.get("deltas", [0.0] * len(inputs))
+    edl = plan["edl"]
+    audio_src = plan["audio_source"]
+    K = len(inputs)
+    coverage = plan.get("coverage", [[0.0, plan["duration_sec"]]] * K)
+
+    W, H = width, height
+    pw = pip_width
+    ph = round(pw * 9 / 16)
+    bw = border_px
+    x_expr, y_expr = POSITIONS[pip]
+    x_expr = x_expr.format(m=pip_margin)
+    y_expr = y_expr.format(m=pip_margin)
+
+    cmd = ["ffmpeg", "-nostdin", "-y"]
+    for src, dlt in zip(inputs, deltas):
+        if abs(dlt) > 1e-9:
+            cmd.extend(["-itsoffset", "%.6f" % dlt])
+        cmd.extend(["-i", src])
+
+    filters = []
+    for i, row in enumerate(edl):
+        cam = row["cam"]
+        s, e = row["start"], row["end"]
+        main_label = "m%d" % i if K > 1 else "v%d" % i
+        filters.append(
+            "[%d:v]trim=start=%s:end=%s,setpts=PTS-STARTPTS,"
+            "scale=%d:%d:force_original_aspect_ratio=decrease,"
+            "pad=%d:%d:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=%d[%s]"
+            % (cam, s, e, W, H, W, H, fps, main_label)
+        )
+        if K == 1:
+            continue
+        pip_cam = pick_pip(row, K, coverage, mode=pip_pick)
+        if pip_cam is None:
+            filters.append("[m%d]copy[v%d]" % (i, i))
+            continue
+        chain = (
+            "[%d:v]trim=start=%s:end=%s,setpts=PTS-STARTPTS,"
+            "scale=%d:%d:force_original_aspect_ratio=decrease,"
+            "pad=%d:%d:(ow-iw)/2:(oh-ih)/2,"
+            % (pip_cam, s, e, pw, ph, pw, ph)
+        )
+        if bw > 0:
+            chain += "pad=%d:%d:%d:%d:white," % (pw + 2 * bw, ph + 2 * bw, bw, bw)
+        chain += "setsar=1,fps=%d[p%d]" % (fps, i)
+        filters.append(chain)
+        filters.append("[m%d][p%d]overlay=%s:%s:eof_action=pass[v%d]"
+                       % (i, i, x_expr, y_expr, i))
+
+    concat = "".join("[v%d]" % i for i in range(len(edl)))
+    filters.append("%sconcat=n=%d:v=1:a=0[vout]" % (concat, len(edl)))
+    audio_offset = edl[0]["start"] if edl else 0.0
+    dur = plan["duration_sec"]
+    fc = ";".join(filters)
+    fc += (";[%d:a:0]atrim=start=%s:duration=%s,asetpts=PTS-STARTPTS[aout]"
+           % (audio_src, audio_offset, dur))
+    cmd.extend([
+        "-filter_complex", fc,
+        "-map", "[vout]", "-map", "[aout]",
+        "-t", str(dur),
+        "-c:v", encoder, "-b:v", bitrate, "-tag:v", "hvc1",
+        "-c:a", "aac", "-b:a", "192k",
+        "-movflags", "+faststart", str(out),
+    ])
+    if run:
+        print("PiP %dx%d, inset %dx%d (+%dpx) at %s; %d cams; %d segments"
+              % (W, H, pw, ph, bw, pip, K, len(edl)))
+        subprocess.run(cmd, check=True)
+    return cmd
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="polysync render-pip")
+    ap.add_argument("edl", type=Path)
+    ap.add_argument("--out", type=Path, required=True)
+    ap.add_argument("--encoder", default="hevc_videotoolbox")
+    ap.add_argument("--bitrate", default="12M")
+    ap.add_argument("--width", type=int, default=1920)
+    ap.add_argument("--height", type=int, default=1080)
+    ap.add_argument("--fps", type=int, default=30)
+    ap.add_argument("--pip", choices=list(POSITIONS), default="bottom-right")
+    ap.add_argument("--pip-width", type=int, default=480)
+    ap.add_argument("--pip-margin", type=int, default=24)
+    ap.add_argument("--border-px", type=int, default=4)
+    ap.add_argument("--pip-pick", choices=["next", "second-best"], default="next")
+    args = ap.parse_args(argv)
+    render_pip(args.edl, args.out, encoder=args.encoder, bitrate=args.bitrate,
+               width=args.width, height=args.height, fps=args.fps, pip=args.pip,
+               pip_width=args.pip_width, pip_margin=args.pip_margin,
+               border_px=args.border_px, pip_pick=args.pip_pick)
+
+
+if __name__ == "__main__":
+    main()

polysync/sidecar.py

@@ -0,0 +1,88 @@
+"""`.sync.json` sidecar — the reversible alignment record polysync emits.
+
+One sidecar per original input, written next to it as `<input>.sync.json`.
+Originals are never modified. Downstream aligns the source to the reference
+timeline with `ffmpeg -itsoffset delta_seconds` (optionally
+`atempo=1+drift_slope` for long-form lip-sync).
+"""
+import json
+from pathlib import Path
+
+SCHEMA_VERSION = 1
+
+
+def sidecar_path(media_path):
+    """Sidecar lives next to the original, named `<original>.sync.json`."""
+    media_path = Path(media_path)
+    return media_path.with_suffix(media_path.suffix + ".sync.json")
+
+
+def write_sidecar(media_path, *, source, reference, delta_seconds, drift_slope,
+                  overlap_in_reference, overlap_in_source, verification=None):
+    """Write the canonical sidecar next to `media_path` and return its Path."""
+    sc = {
+        "_about": (
+            "Sync metadata for %s (aligned to %s). Generated by polysync. "
+            "Originals are not modified; downstream uses "
+            "ffmpeg -itsoffset delta_seconds to align." % (source, reference)
+        ),
+        "_help": {
+            "delta_seconds": (
+                "Source's t=0 expressed in reference's timeline. "
+                "Positive => source starts after reference. "
+                "Apply via `ffmpeg -itsoffset <delta_seconds> -i <source>`."
+            ),
+            "drift_slope": (
+                "Residual clock drift between source and reference clocks "
+                "(dimensionless, ~1e-5 typical). For camera-cut editing, "
+                "ignore. For sync-sound / long-form lip-sync apply "
+                "atempo=1+drift_slope to the source."
+            ),
+            "overlap_in_reference": (
+                "[start, end] window in reference's timeline where BOTH source "
+                "and reference have valid content. Use to constrain trims/EDLs."
+            ),
+            "overlap_in_source": (
+                "Same window in the source's local timeline "
+                "(= overlap_in_reference shifted by -delta_seconds)."
+            ),
+            "verification": (
+                "Filled in by `polysync verify`: median_residual_ms, "
+                "residual_spread_ms, probe_count. None until verify runs."
+            ),
+        },
+        "schema_version": SCHEMA_VERSION,
+        "source": source,
+        "reference": reference,
+        "delta_seconds": float(delta_seconds),
+        "drift_slope": float(drift_slope),
+        "overlap_in_reference": [float(overlap_in_reference[0]),
+                                 float(overlap_in_reference[1])],
+        "overlap_in_source": [float(overlap_in_source[0]),
+                              float(overlap_in_source[1])],
+        "verification": verification,
+    }
+    p = sidecar_path(media_path)
+    p.write_text(json.dumps(sc, indent=2, ensure_ascii=False))
+    return p
+
+
+def read_sidecar(input_path):
+    """Read `<input>.sync.json`. Returns (delta_seconds, overlap_in_reference,
+    has_sidecar). Falls back to (0.0, None, False) if absent or unparseable —
+    callers treat that as 'this input is at reference t=0, full coverage'."""
+    sc = sidecar_path(input_path)
+    if not sc.exists():
+        return (0.0, None, False)
+    try:
+        d = json.loads(sc.read_text())
+        if d.get("schema_version") != SCHEMA_VERSION:
+            print("WARN: %s schema_version != %d; reading anyway"
+                  % (sc.name, SCHEMA_VERSION))
+        delta = float(d["delta_seconds"])
+        ovl = d.get("overlap_in_reference")
+        ovl = (float(ovl[0]), float(ovl[1])) if ovl else None
+        return (delta, ovl, True)
+    except Exception as e:  # noqa: BLE001 — best-effort, never crash the edit
+        print("WARN: failed to parse %s: %s; using delta=0" % (sc.name, e))
+        return (0.0, None, False)

polysync/sync.py

@@ -0,0 +1,206 @@
+"""Compute the time offset between two recordings of the same event.
+
+Algorithm (envelope cross-correlation + multi-probe drift fit):
+  1. Log-energy envelope of each signal (audio.log_envelope), high-passed.
+  2. FFT cross-correlate envelopes end-to-end -> coarse offset (~10 ms).
+  3. Refine at sample level with 60 s probes near the coarse position,
+     parabolic peak interpolation.
+  4. Linear-fit delta(t) across probes -> clock drift; report the
+     midpoint-canonical offset so residual error is symmetric around zero.
+
+Two failure philosophies, selected by `partial`:
+  - partial=False (full-overlap multicam): demand >=3 good probes or raise
+    SyncError. Too few good matches almost always means the wrong files.
+  - partial=True (a source covering only part of the reference): degrade
+    gracefully — median delta on few probes, coarse delta if none.
+
+`compute_sync` works on numpy PCM arrays (unit-testable, no ffmpeg). `sync_files`
+is the file/CLI layer that extracts audio and writes sidecars.
+"""
+import sys
+import tempfile
+from pathlib import Path
+
+import numpy as np
+from scipy import signal
+
+from . import audio
+from .sidecar import write_sidecar
+
+SR = 8000  # sync works fine at 8 kHz; the envelope is what matters, not HF
+GOOD_NCOEF = 0.05  # a probe counts as "good" above this normalized correlation
+
+
+class SyncError(Exception):
+    """Raised when full-overlap sync cannot find enough evidence to trust."""
+
+
+class SyncResult(object):
+    """Outcome of compute_sync. `delta_seconds` is the source's t=0 expressed
+    in the reference timeline; positive => source starts after reference."""
+
+    def __init__(self, delta_seconds, drift_slope, coarse_corr,
+                 n_probes, n_good, fallback):
+        self.delta_seconds = float(delta_seconds)
+        self.drift_slope = float(drift_slope)
+        self.coarse_corr = float(coarse_corr)
+        self.n_probes = int(n_probes)
+        self.n_good = int(n_good)
+        self.fallback = fallback  # None | "median" | "coarse"
+
+    def __repr__(self):
+        return ("SyncResult(delta=%.6f, drift=%.3e, coarse_corr=%.3f, "
+                "probes=%d, good=%d, fallback=%r)"
+                % (self.delta_seconds, self.drift_slope, self.coarse_corr,
+                   self.n_probes, self.n_good, self.fallback))
+
+
+def coarse_offset(env_a, env_b, env_sr):
+    """Return (delta, normalized_corr) with delta = tA - tB so A_t = B_t + delta."""
+    a_n = audio.normalize(env_a)
+    b_n = audio.normalize(env_b)
+    xc = signal.correlate(a_n, b_n, mode="full", method="fft")
+    lags = np.arange(len(xc)) - (len(b_n) - 1)
+    pk = int(np.argmax(xc))
+    return float(lags[pk] / env_sr), float(xc[pk] / len(env_b))
+
+
+def _refine(a, b, b_start_s, expected_delta, sr, probe_len_s=60.0, pad_s=1.5):
+    pl = int(probe_len_s * sr)
+    bs = int(b_start_s * sr)
+    if bs + pl > len(b):
+        return None
+    probe = b[bs:bs + pl].astype(np.float32)
+    a_center = b_start_s + expected_delta
+    lo = max(0, int((a_center - pad_s) * sr))
+    hi = min(len(a), int((a_center + pad_s + probe_len_s) * sr))
+    if hi - lo < pl:
+        return None
+    seg = a[lo:hi].astype(np.float32)
+    xc = signal.correlate(audio.normalize(seg), audio.normalize(probe),
+                          mode="valid", method="fft")
+    pk = int(np.argmax(np.abs(xc)))
+    val = xc[pk] / len(probe)
+    if 0 < pk < len(xc) - 1:
+        y0, y1, y2 = xc[pk - 1], xc[pk], xc[pk + 1]
+        denom = (y0 - 2 * y1 + y2)
+        sub = 0.5 * (y0 - y2) / denom if abs(denom) > 1e-9 else 0.0
+    else:
+        sub = 0.0
+    a_pos = (lo + pk + sub) / sr
+    return float(a_pos - b_start_s), float(val)
+
+
+def _multi_probe(a, b, expected_delta, b_dur, a_dur, sr, step_s=180.0):
+    rs = []
+    for bs in np.arange(60.0, b_dur - 60.0, step_s):
+        a_center = bs + expected_delta
+        if a_center < 1.5 or a_center + 60.0 + 1.5 > a_dur:
+            continue
+        r = _refine(a, b, bs, expected_delta, sr)
+        if r:
+            rs.append((bs, r[0], r[1]))
+    return rs
+
+
+def compute_sync(a, b, a_dur, b_dur, sr=SR, partial=False, verbose=False):
+    """Align PCM array `b` (source) to `a` (reference). Returns SyncResult.
+
+    `a`, `b` are mono float arrays at `sr` Hz. `a_dur`/`b_dur` are their
+    durations in seconds (usually len/sr, passed explicitly so callers can use
+    container duration). Raises SyncError in full-overlap mode when evidence is
+    too weak.
+    """
+    env_a, esr = audio.log_envelope(a, sr)
+    env_b, _ = audio.log_envelope(b, sr)
+    coarse_d, coarse_v = coarse_offset(env_a, env_b, esr)
+    if verbose:
+        print("  coarse delta = %+.4fs (xc/N=%.3f)" % (coarse_d, coarse_v))
+
+    probes = _multi_probe(a, b, coarse_d, b_dur, a_dur, sr)
+    good = np.array([abs(p[2]) > GOOD_NCOEF for p in probes], dtype=bool)
+    if verbose:
+        print("  good probes: %d / %d" % (int(good.sum()), len(probes)))
+
+    if good.sum() >= 3:
+        bs_arr = np.array([p[0] for p in probes])
+        d_arr = np.array([p[1] for p in probes])
+        slope, intercept = np.polyfit(bs_arr[good], d_arr[good], 1)
+        delta = float(slope * (b_dur / 2) + intercept)
+        return SyncResult(delta, float(slope), coarse_v,
+                          len(probes), int(good.sum()), None)
+    if not partial:
+        raise SyncError(
+            "too few good probes (%d < 3); sync unreliable. If this is a "
+            "short partial-coverage clip, use partial=True / --partial."
+            % int(good.sum()))
+    if probes:
+        delta = float(np.median([p[1] for p in probes]))
+        return SyncResult(delta, 0.0, coarse_v, len(probes),
+                          int(good.sum()), "median")
+    return SyncResult(float(coarse_d), 0.0, coarse_v, 0, 0, "coarse")
+
+
+def _overlap(delta, a_dur, b_dur):
+    ref_start = max(0.0, delta)
+    ref_end = min(a_dur, delta + b_dur)
+    return (ref_start, ref_end), (ref_start - delta, ref_end - delta)
+
+
+def sync_files(reference, source, partial=False, verbose=True):
+    """Extract audio from both files, compute the offset, write sidecar(s).
+
+    In full-overlap mode writes a sidecar for BOTH inputs (reference gets
+    delta=0). In partial mode writes only the source sidecar. Returns the
+    source's sidecar Path.
+    """
+    reference, source = Path(reference), Path(source)
+    a_dur = audio.media_duration(reference)
+    b_dur = audio.media_duration(source)
+    if verbose:
+        print("Mode: %s" % ("partial-coverage" if partial else "full-overlap"))
+        print("A (reference): %s  duration=%.3fs" % (reference.name, a_dur))
+        print("B (source):    %s  duration=%.3fs" % (source.name, b_dur))
+
+    with tempfile.TemporaryDirectory() as td:
+        td = Path(td)
+        a_pcm, b_pcm = td / "a.pcm", td / "b.pcm"
+        if verbose:
+            print("Extracting mono PCM @ %d Hz..." % SR)
+        audio.extract_pcm(reference, a_pcm, SR)
+        audio.extract_pcm(source, b_pcm, SR)
+        a = audio.read_pcm(a_pcm)
+        b = audio.read_pcm(b_pcm)
+        res = compute_sync(a, b, a_dur, b_dur, sr=SR, partial=partial,
+                           verbose=verbose)
+
+    if res.coarse_corr < 0.3 and verbose:
+        print("  WARNING: low coarse correlation; sync may be unreliable.",
+              file=sys.stderr)
+    if verbose:
+        msg = "  delta=%+.6fs  drift=%+.3e" % (res.delta_seconds, res.drift_slope)
+        if res.fallback:
+            msg += "  (fallback: %s)" % res.fallback
+        print(msg)
+
+    (ref_ovl, src_ovl) = _overlap(res.delta_seconds, a_dur, b_dur)
+    if ref_ovl[1] - ref_ovl[0] < 1.0:
+        raise SyncError("overlap window <1s; the two recordings barely share "
+                        "content (delta=%.3fs)" % res.delta_seconds)
+
+    src_sc = write_sidecar(
+        source, source=source.name, reference=reference.name,
+        delta_seconds=res.delta_seconds, drift_slope=res.drift_slope,
+        overlap_in_reference=ref_ovl, overlap_in_source=src_ovl,
+    )
+    if verbose:
+        print("Wrote %s" % src_sc)
+    if not partial:
+        ref_sc = write_sidecar(
+            reference, source=reference.name, reference=reference.name,
+            delta_seconds=0.0, drift_slope=0.0,
+            overlap_in_reference=ref_ovl, overlap_in_source=ref_ovl,
+        )
+        if verbose:
+            print("Wrote %s" % ref_sc)
+    return src_sc

polysync/verify.py

@@ -0,0 +1,118 @@
+"""Independent residual check for a (reference, source, sidecar) triple.
+
+Re-extracts audio from BOTH originals NATIVELY (loudest stream, no ffmpeg
+offset) and runs multi-probe cross-correlation inside the overlap window,
+applying the sidecar's `delta_seconds` (and, with `apply_drift`, the slope) as
+index arithmetic in numpy.
+
+Why index arithmetic and not `ffmpeg -itsoffset`: `-itsoffset` shifts input
+timestamps, but a headerless raw stream (`-f s16le`) has no timestamps to carry
+the offset — ffmpeg silently drops it and inserts NO leading silence. Relying
+on it lines the source's t=0 up with the reference's t=0 regardless of delta,
+so every probe correlates the wrong region, peaks land in noise (ncoef ~0), and
+verification falsely FAILs. Shifting indices ourselves matches exactly how the
+offset was computed.
+
+PASS = |median_residual_ms| < 15 AND residual_spread_ms < 1 frame at target fps.
+A spread-only fail with a near-zero median is usually far-field-mic noise on a
+wide/B-roll camera, not real desync — for camera-cut editing, trust the median.
+"""
+import json
+import sys
+import tempfile
+from pathlib import Path
+
+import numpy as np
+from scipy import signal
+
+from . import audio
+
+SR = 8000
+
+
+def verify_files(reference, source, sidecar, probe_len=60.0, step=600.0,
+                 max_frame_ms=33.33, apply_drift=False, verbose=True):
+    """Run verification and write results into the sidecar's `verification`
+    field. Returns (passed: bool, stats: dict)."""
+    reference, source, sidecar = Path(reference), Path(source), Path(sidecar)
+    sc = json.loads(sidecar.read_text())
+    delta = float(sc["delta_seconds"])
+    drift_slope = float(sc.get("drift_slope", 0.0))
+    overlap_ref = sc["overlap_in_reference"]
+
+    if verbose:
+        print("Reference: %s" % reference.name)
+        print("Source:    %s" % source.name)
+        print("delta_seconds = %+.6f  drift_slope = %+.3e (%s)"
+              % (delta, drift_slope,
+                 "applied" if apply_drift else "not applied"))
+
+    with tempfile.TemporaryDirectory() as td:
+        td = Path(td)
+        ref_pcm, src_pcm = td / "ref.pcm", td / "src.pcm"
+        audio.extract_pcm(reference, ref_pcm, SR)
+        audio.extract_pcm(source, src_pcm, SR)
+        ref = audio.read_pcm(ref_pcm)
+        src = audio.read_pcm(src_pcm)
+
+    pl = int(probe_len * SR)
+    pad = int(0.5 * SR)
+    ovl_start = max(60.0, float(overlap_ref[0]) + 1.0)
+    ovl_end = float(overlap_ref[1]) - probe_len - 1.0
+    if ovl_end <= ovl_start:
+        raise ValueError("overlap window too short to verify")
+
+    rs = []
+    for bs in np.arange(ovl_start, ovl_end, step):
+        # Source-local time corresponding to this reference time.
+        src_t = bs - delta
+        if apply_drift:
+            src_t = src_t / (1.0 + drift_slope)
+        si = int(src_t * SR)
+        bsi = int(bs * SR)
+        if si < 0 or si + pl > len(src):
+            continue
+        probe = src[si:si + pl]
+        if np.abs(probe).mean() < 1.0:
+            continue  # silence — nothing to correlate
+        lo = max(0, bsi - pad)
+        hi = min(len(ref), bsi + pl + pad)
+        if hi - lo < pl:
+            continue
+        seg = ref[lo:hi].astype(np.float32)
+        xc = signal.correlate(audio.normalize(seg),
+                              audio.normalize(probe.astype(np.float32)),
+                              mode="valid", method="fft")
+        pk = int(np.argmax(np.abs(xc)))
+        ncoef = float(xc[pk] / len(probe))
+        residual_ms = ((lo + pk) / SR - bs) * 1000
+        rs.append((bs, residual_ms, ncoef))
+        if verbose:
+            print("t=%7.1fs  residual=%+7.2f ms  ncoef=%+.3f"
+                  % (bs, residual_ms, ncoef))
+
+    if not rs:
+        raise ValueError("no usable probes (all silence or out of overlap)")
+
+    arr = np.array([r[1] for r in rs])
+    median_residual_ms = float(np.median(arr))
+    residual_spread_ms = float(np.max(np.abs(arr - median_residual_ms)) * 2)
+    passed = (abs(median_residual_ms) <= 15.0
+              and residual_spread_ms <= max_frame_ms)
+
+    stats = {
+        "median_residual_ms": round(median_residual_ms, 3),
+        "residual_spread_ms": round(residual_spread_ms, 3),
+        "probe_count": len(rs),
+        "drift_applied": bool(apply_drift),
+    }
+    sc["verification"] = stats
+    sidecar.write_text(json.dumps(sc, indent=2, ensure_ascii=False))
+    if verbose:
+        print("\nResidual: median=%+.2f ms  spread=+-%.2f ms  -> %s"
+              % (median_residual_ms, residual_spread_ms / 2,
+                 "PASS" if passed else "FAIL"))
+        if not passed and abs(median_residual_ms) <= 15.0:
+            print("  (spread-only fail with near-zero median is usually "
+                  "far-field-mic noise, not real desync)", file=sys.stderr)
+    return passed, stats

polysync-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: polysync
+Version: 0.1.0
+Summary: Multicam audio sync and director-style auto-edit — align N angles of one event by audio cross-correlation, then cut/PiP them into one MP4. Reversible sidecars, never re-encodes the originals.
+Author: 王建硕 (Jian Shuo Wang)
+License: MIT
+Project-URL: Homepage, https://github.com/jianshuo/polysync
+Project-URL: Issues, https://github.com/jianshuo/polysync/issues
+Keywords: multicam,audio-sync,video-editing,cross-correlation,ffmpeg,picture-in-picture,podcast,interview
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scipy>=1.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# polysync
+
+**Multicam audio sync + director-style auto-edit.** Align N recordings of the
+same event by audio cross-correlation, then cut or picture-in-picture them into
+a single MP4 — driven entirely by who's talking.
+
+What makes it different from "yet another sync tool":
+
+- **Reversible sidecars, never re-encodes the originals.** Sync writes a tiny
+  `<input>.sync.json` next to each file holding a single offset. A 75-min 4K
+  3-camera shoot is 250+ GB; baking offsets into re-encoded copies would double
+  that and lose quality. Downstream applies the offset with `ffmpeg -itsoffset`
+  at consume time. Originals are touched read-only, always.
+- **Envelope cross-correlation, not raw waveform.** Matches the log-energy
+  envelope, which both mics hear regardless of their frequency response — robust
+  even when a second camera's on-board mic sounds nothing like the main one.
+- **Clock-drift aware.** Cheap recorders drift 5–50 ppm; polysync fits the drift
+  across the recording and reports it separately, so long-form lip-sync can
+  correct it while camera-cut editing can ignore it.
+- **Handles the messy real cases.** Auto-picks the loudest audio track (pro
+  cameras often leave track 1 dead), partial-coverage clips that only span part
+  of the session, and independent verification of the result.
+
+## Install
+
+```bash
+pip install polysync          # once published
+# or, from a checkout:
+pip install -e ".[dev]"
+```
+
+Requires **Python ≥ 3.9** and **ffmpeg / ffprobe** on your `PATH`
+(`brew install ffmpeg`, `apt install ffmpeg`, …). Python deps: `numpy`, `scipy`.
+
+## Quickstart
+
+```bash
+# 1. Sync each angle to a reference camera (writes <file>.sync.json sidecars)
+polysync sync  CAM_A.mp4 CAM_B.mxf
+polysync sync  CAM_A.mp4 CAM_C.mxf
+
+# 2. (optional) Verify the alignment — re-checks residual independently
+polysync verify CAM_A.mp4 CAM_B.mxf CAM_B.mxf.sync.json
+
+# 3. Build an auto-edit decision list (who's on screen each second)
+polysync edit  CAM_A.mp4 CAM_B.mxf CAM_C.mxf --out edl.json
+
+# 4. Render — hard cuts, or with a picture-in-picture inset
+polysync render-cuts edl.json --out final.mp4
+polysync render-pip  edl.json --out final.mp4 --pip bottom-right
+```
+
+A clip that only covers **part** of the session (a Riverside / phone / lavalier
+recording that started mid-way):
+
+```bash
+polysync sync REFERENCE.mp4 PARTIAL.m4a --partial
+```
+
+## How it consumes the sidecar
+
+`delta_seconds` is the source's `t=0` in the reference's timeline (positive =
+source starts later). To align by hand:
+
+```bash
+ffmpeg -itsoffset $(jq -r .delta_seconds CAM_B.mxf.sync.json) -i CAM_B.mxf \
+       -i CAM_A.mp4 -filter_complex "[0:v][1:v]hstack" out.mp4
+```
+
+The `edit` / `render-*` commands read every sidecar automatically.
+
+## Python API
+
+```python
+from polysync import compute_sync           # pure-numpy core, unit-testable
+from polysync.sync import sync_files         # file → sidecar
+from polysync.verify import verify_files
+from polysync.edit import build_edl
+```
+
+## Status
+
+Beta (0.1). Sync + verify are battle-tested on real Sony FX3/FX6 multicam
+interview footage; the auto-edit is audio-energy-driven (no face detection).
+Issues and PRs welcome.
+
+## License
+
+MIT © 王建硕 (Jian Shuo Wang)

polysync-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+polysync/__init__.py,sha256=RgITjxkGmBXYPCZf1HB8k51BhzuAlJZ18_fdArxOQs4,738
+polysync/audio.py,sha256=ynWo_o_EyOt5oeOV3DlWbmYGKSs18ccd4Kqnffe9qqY,4838
+polysync/cli.py,sha256=BlkblUjiS47Fv75JK09yRJpsjqBRLeX2jMmH7LaK40Q,2725
+polysync/sidecar.py,sha256=q8S0-NndFC3cTHJu-jWEUeIStwfpnTtBejMMSmuZYbg,3833
+polysync/sync.py,sha256=rftcvHKNjWCvW9ajxGDiwaQ9rb-Our0wErkI6Iz5BqE,8301
+polysync/verify.py,sha256=RMCzLsX37idtOj3M0kHrc4Vuy5fkQrUKCz7YmNIuGhU,4798
+polysync/edit/__init__.py,sha256=DbaXJlHTigztesgHv1Drq5qnOVInbVqaJk-pqvXntBQ,328
+polysync/edit/autoedit.py,sha256=CpwaQNNgw8OeZs71DJ-se5SF4e412UPbCi0Go-dSgIc,12230
+polysync/edit/render_cuts.py,sha256=a_r4YrF0sd16Q1nfPJe5d6V-T7dby2WnHwZl9cvFPJ4,2617
+polysync/edit/render_pip.py,sha256=1HSDq-aNCPC1l98iBh8DOZCS-G02TtJukzunvsmXCmA,5372
+polysync-0.1.0.dist-info/licenses/LICENSE,sha256=hcmoQh1_1s1uNIhPR-r0iRSaW5podyrLeiRSN6aQETY,1083
+polysync-0.1.0.dist-info/METADATA,sha256=cpCI34EHIzrUlFWd_uMOdv_KuDZ_lR8YQl9S6WM1ddU,4363
+polysync-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+polysync-0.1.0.dist-info/entry_points.txt,sha256=NmYIEaQREjCdPPfVab4LZfuC8AlMMS1JqaTokiyXpGo,47
+polysync-0.1.0.dist-info/top_level.txt,sha256=GQB7IrzkxyfeEJZAvijNYqf43U6cksUB8_qhV7OfvFE,9
+polysync-0.1.0.dist-info/RECORD,,