openaudiofix 0.1.0__py3-none-any.whl

openaudiofix/__init__.py

@@ -0,0 +1,2 @@
+"""OpenAudioFix: self-hosted audio repair (glitch, declip, background noise)."""
+__version__ = "0.1.0"

openaudiofix/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

openaudiofix/algorithms/align.py

@@ -0,0 +1,39 @@
+"""Resampling and fixed-latency alignment for model outputs (copied from separation/runners/_common.py)."""
+import numpy as np
+
+MAX_LAG = 4096          # alignment search range (+-samples); the model delay is usually within a few hundred samples
+
+
+def resample(x, sr_in, sr_out):
+    if sr_in == sr_out:
+        return x
+    from scipy.signal import resample_poly
+    from math import gcd
+    g = gcd(sr_in, sr_out)
+    return resample_poly(x, sr_out // g, sr_in // g).astype(np.float32)
+
+
+def align_to(ref, y):
+    """Align the model output y to the original ref: compensate a fixed delay and trim to equal length.
+    Returns (y_aligned, lag). lag>0 means y is lag samples later than ref. Found by cross-correlating the whole
+    signal; speech-enhancement models do not change the time axis, so there should be only one fixed delay, and a
+    peak that is not prominent enough is treated as 0 (no spurious shifting)."""
+    n = min(len(ref), len(y))
+    a = ref[:n].astype(np.float64); b = y[:n].astype(np.float64)
+    L = 1 << int(np.ceil(np.log2(2 * n)))
+    A = np.fft.rfft(a, L); B = np.fft.rfft(b, L)
+    c = np.fft.irfft(np.conj(A) * B, L)
+    cand = np.r_[c[:MAX_LAG + 1], c[-MAX_LAG:]]
+    lags = np.r_[np.arange(0, MAX_LAG + 1), np.arange(-MAX_LAG, 0)]
+    k = int(np.argmax(cand))
+    lag = int(lags[k])
+    if cand[k] < 3 * np.median(np.abs(cand)):
+        lag = 0
+    if lag > 0:
+        y = np.r_[y[lag:], np.zeros(lag, np.float32)]
+    elif lag < 0:
+        y = np.r_[np.zeros(-lag, np.float32), y[:lag]]
+    if len(y) < len(ref):
+        y = np.r_[y, np.zeros(len(ref) - len(y), np.float32)]
+    return y[:len(ref)].astype(np.float32), lag
+

openaudiofix/algorithms/aspade.py

@@ -0,0 +1,114 @@
+"""A-SPADE (analysis sparse audio declipper), for a direct comparison with the whole-frame joint AR
+(declip.declip_joint).
+
+Algorithm: Kitić, Bertin, Gribonval 2015; ADMM form and parameters follow Záviška et al. 2019/2021.
+Each frame (after windowing) solves
+    min ||A x||_0   s.t.  x ∈ Γ
+A = 2x-redundant DFT (Parseval tight frame: A^H A = I), Γ = clipping-consistent set:
+    reliable samples x = y; positive clipping x ≥ y; negative clipping x ≤ y (y is the windowed observation).
+ADMM:
+    z = H_k(A x + u)            hard threshold, keep only the k largest coefficients
+    x = P_Γ(A^H (z − u))        project back onto the consistent set
+    stop if ||A x − z|| ≤ ε, otherwise u += A x − z, and every r iterations k += s
+The fundamental difference from the AR family: the prior is "time-frequency sparsity", not "linear predictability".
+For periodic speech, harmonics are already sparse in frequency, so in theory it suits dense clipping; the cost is many
+iterations.
+
+Frame synthesis: each frame is solved in the windowed domain (x_w ≈ g·x), multiplied by g again when overlap-adding,
+and finally divided by Σg², which is correct for any overlap ratio.
+Only frames containing clipping are processed; regions without clipping are unchanged sample by sample.
+"""
+import numpy as np
+
+# frame length (43 ms): speech is shorter than the music Záviška tested; start here, sweep later on the benchmark
+W = 2048
+HOP = 512         # 75% overlap
+REDUND = 2        # DFT redundancy factor
+S = 1             # sparsity relaxed at each step
+R = 1             # relax once every R iterations
+EPS = 0.1         # stopping criterion ||Ax − z|| (same as Záviška; relative to the scale of the windowed signal)
+MAX_IT = 1000
+
+
+def _A(x, n):
+    return np.fft.fft(x, n, norm="ortho")
+
+
+def _AH(z, w):
+    return np.real(np.fft.ifft(z, norm="ortho"))[:w]
+
+
+def _hard(z, k):
+    """Keep the k coefficients with the largest magnitude (conjugate pairs counted together: the threshold is decided
+    from the first half of the spectrum, which keeps the symmetry of a real signal)."""
+    a = np.abs(z)
+    if k >= len(a):
+        return z
+    thr = np.partition(a, len(a) - k)[len(a) - k]
+    return np.where(a >= thr, z, 0)
+
+
+def aspade_frame(y, rel, cp, cn, eps=EPS, s=S, r=R, max_it=MAX_IT):
+    """y: windowed frame; rel/cp/cn: reliable / positive-clip / negative-clip masks.
+    Returns the reconstructed frame (in the windowed domain)."""
+    w = len(y); n = REDUND * w
+    x = y.copy(); u = np.zeros(n, dtype=complex)
+    k = s
+    for it in range(1, max_it + 1):
+        Ax = _A(x, n)
+        z = _hard(Ax + u, k)
+        v = _AH(z - u, w)
+        x = v.copy()                      # projection onto Γ
+        x[rel] = y[rel]
+        x[cp] = np.maximum(v[cp], y[cp])
+        x[cn] = np.minimum(v[cn], y[cn])
+        Ax = _A(x, n)
+        res = np.linalg.norm(Ax - z)
+        if res <= eps:
+            break
+        u = u + Ax - z
+        if it % r == 0:
+            k += 2 * s                    # 2 = conjugate pair; makes the "true" sparsity grow by s each time
+    return x, it
+
+
+def declip_aspade(x, sr, thr_pos=None, thr_neg=None, w=W, hop=HOP, eps=EPS, max_it=MAX_IT, progress=None):
+    """Process the whole signal. If thr is not given, it is inferred with declip.estimate_threshold. Returns (y,
+    info)."""
+    x = np.asarray(x, dtype=np.float64)
+    if thr_pos is None:
+        from . import declip as _D
+        thr_pos, thr_neg, det = _D.estimate_threshold(x)
+        if not det:
+            return x.copy(), dict(detected=False)
+    cp_all = x >= thr_pos; cn_all = x <= thr_neg
+    clipped = cp_all | cn_all
+    g = np.hanning(w + 2)[1:-1]
+    num = np.zeros(len(x)); den = np.zeros(len(x))
+    its = []
+    starts = range(-w + hop, len(x), hop)
+    for st in starts:
+        a, b = st, st + w
+        a0, b0 = max(a, 0), min(b, len(x))
+        if not clipped[a0:b0].any():
+            continue
+        seg = np.zeros(w); seg[a0 - a:b0 - a] = x[a0:b0]
+        cp = np.zeros(w, bool); cn = np.zeros(w, bool)
+        cp[a0 - a:b0 - a] = cp_all[a0:b0]; cn[a0 - a:b0 - a] = cn_all[a0:b0]
+        rel = ~(cp | cn)
+        yw = seg * g
+        xr, it = aspade_frame(yw, rel, cp, cn, eps=eps, max_it=max_it)
+        its.append(it)
+        if progress is not None and len(its) % 25 == 0:
+            progress(max(st, 0), len(x))
+        num[a0:b0] += (xr * g)[a0 - a:b0 - a]
+        den[a0:b0] += (g * g)[a0 - a:b0 - a]
+    y = x.copy()
+    m = clipped & (den > 1e-9)
+    y[m] = num[m] / den[m]
+    # Consistency: reconstructed values must not fall back inside the threshold (numerical error at window edges can
+    # cause tiny violations)
+    y[cp_all] = np.maximum(y[cp_all], thr_pos)
+    y[cn_all] = np.minimum(y[cn_all], thr_neg)
+    return y, dict(detected=True, n_frames=len(its), iters_median=int(np.median(its)) if its else 0,
+                   peak=float(np.abs(y).max()))

openaudiofix/algorithms/declick.py

@@ -0,0 +1,164 @@
+"""Repair of phase jumps from dropped samples (single file): detect, then phase-aligned micro-warp / per-hole
+interpolation, then verify the residue.
+
+"Track" here corresponds to "channel" (mono=1, stereo=2).
+Uses the same logic as the whole-file pipeline for a long real recording: adjacent/overlapping
+seams are first merged into one discard zone and solved at once; after repair the detector is rerun, residues first
+fall back to the safe path and, if that still fails, are widened, and every round reapplies all patches
+from the original file. The detector is the generic single-file version (`declick_detect.py`).
+"""
+import time
+import numpy as np
+
+from . import declick_detect as D, phase_warp
+
+MAX_PASS = 4
+CLUSTER_MARGIN = 330    # seams closer than this are merged into one discard zone and solved at once
+RESID_NEAR = 200         # residual events within ± this range of an existing group count as the same spot
+MAX_GAP = 960
+
+
+def merge_groups(seams, margin=CLUSTER_MARGIN):
+    """seams: {p: {gap, za, zb, ...}} → merge nearby / overlapping windows [za-gap/2, zb+gap/2) into groups.
+    Returns a list of dict(za, zb, subs=[(a,b),...], positions=[p,...], force=False), sorted by position."""
+    items = []
+    for p, s in sorted(seams.items()):
+        half = s["gap"] // 2
+        a = min(s["za"] - half, s["za"] - 1)
+        b = max(s["zb"] + half, s["zb"] + 1)
+        if b - a < s["gap"]:
+            b = a + s["gap"]
+        items.append(dict(p=p, za=s["za"], zb=s["zb"], a=a, b=b, gap=s["gap"]))
+    groups = []
+    for it in items:
+        if groups and it["a"] <= groups[-1]["zb"] + margin:
+            g = groups[-1]
+            g["zb"] = max(g["zb"], it["zb"]); g["b"] = max(g["b"], it["b"])
+            g["subs"].append((it["a"], it["b"])); g["positions"].append(it["p"])
+        else:
+            groups.append(dict(za=it["za"], zb=it["zb"], a=it["a"], b=it["b"],
+                                subs=[(it["a"], it["b"])], positions=[it["p"]]))
+    for g in groups:
+        g["force"] = any(seams[p].get("force", False) for p in g["positions"])
+    return groups
+
+
+def run_pass(X, groups, sr, on_group=None):
+    """Call phase_warp.repair_joint on each group in turn; returns (new channel arrays, per-group repair records).
+    on_group(done, total): optional; reports progress after each batch of groups is repaired (does not affect the
+    result)."""
+    Y = [x.copy() for x in X]
+    records = []
+    prev_end = -10 ** 9
+    for gi, g in enumerate(groups):
+        if on_group and gi % 25 == 0:
+            on_group(gi, len(groups))
+        roomL = g["za"] - max(prev_end, groups[gi - 1]["zb"] if gi else -10 ** 9)
+        roomR = (groups[gi + 1]["za"] if gi + 1 < len(groups) else 10 ** 12) - g["zb"]
+        WL_av = roomL - 32
+        WR_av = roomR // 2 - 32
+        # Zero everything when there is not enough room (rather than passing a small non-zero value): a warp window
+        # shorter
+        # than the pitch period makes phase_warp's internal "extension start continuity correction" read out of bounds.
+        # The whole-file pipeline always had this safety margin (its `tight` check); the single-file pipeline initially
+        # missed
+        # this step, and an end-to-end test on a real clip with dense defects caught it (the stereo test clip triggered
+        # a
+        # broadcast error in render()), so it was added here too.
+        tight = 2 * (phase_warp.W_AVAIL_MIN + 32) + 64
+        if roomR < tight:
+            WR_av = 0
+        if roomL < tight:
+            WL_av = 0
+        if g["za"] - phase_warp.NEED - phase_warp.W_MAX < 0 or g["zb"] + phase_warp.NEED + phase_warp.W_MAX > len(Y[0]):
+            res = None
+        else:
+            res = phase_warp.repair_joint(Y, g["za"], g["zb"], g["subs"], sr, WL_av=max(WL_av, 0),
+                                           WR_av=max(WR_av, 0), roomL=max(roomL, 0), roomR=max(roomR, 0),
+                                           force_fallback=g["force"])
+        if res is None:
+            lo0, hi0 = g["a"], g["b"]
+            for t in range(len(Y)):
+                o = max(lo0 - 16384, 0)
+                ctx = Y[t][o:hi0 + 16384].copy(); ctx[lo0 - o:hi0 - o] = np.nan
+                from .v3methods import ensemble_select
+                yv = ensemble_select.fill(ctx, lo0 - o, hi0 - o, sr)
+                Y[t][lo0:hi0] = yv
+            info = dict(mode="fallback-edge", lo=lo0, hi=hi0)
+            end = hi0
+        else:
+            end = g["b"]
+            for t, (lo, y, info_t) in enumerate(res):
+                Y[t][lo:lo + len(y)] = y
+                end = max(end, lo + len(y))
+            info = res[0][2]
+        records.append(dict(group=g, info=info))
+        prev_end = end
+    return Y, records
+
+
+def repair_file(channels, sr, job_dir, progress=None, detected=None):
+    """channels: list of 1D float64 np.array (equal length). Returns (Y, seams_final, grid_info, history).
+    detected: optional (seams, grid), e.g. the result of detecting on another signal (the original, before declip
+    repair);
+    if given, detection is not rerun on channels."""
+    X0 = [x.copy() for x in channels]
+    if detected is None:
+        seams, grid = D.detect_seams(X0, sr)
+    else:
+        seams, grid = {p: dict(s) for p, s in detected[0].items()}, detected[1]
+    if progress:
+        progress(state="repairing", grid=grid, n_seams_initial=len(seams))
+    history = []
+    Y = X0
+    for it in range(1, MAX_PASS + 1):
+        groups = merge_groups(seams)
+        t0 = time.time()
+        Y, records = run_pass(X0, groups, sr, on_group=(lambda i, n, _it=it: progress(
+            state="repairing", pass_=_it, done=i, total=n)) if progress else None)
+        if progress:
+            progress(state="repairing", pass_=it, n_groups=len(groups),
+                     n_seams=len(seams), pass_seconds=round(time.time() - t0, 1))
+        evs, sts = [], []
+        for x in Y:
+            e, s = D.detect(x)
+            evs.append(e); sts.append(s)
+        tri = D.coincident_all(evs) if len(Y) > 1 else evs[0]
+        grid_tuple = (grid["L"], set(grid["residues"]), grid["coverage"], grid["confidence"])
+        resid = tri if len(Y) > 1 else np.array(
+            sorted(p for p, ntr, ongrid, strength in D.build_seam_list(evs, sts, grid_tuple) if ongrid or ntr >= 1))
+        widened = forced = added = 0
+        for t in resid.astype(int):
+            hit = [g for g in groups if g["za"] - RESID_NEAR <= t <= g["zb"] + RESID_NEAR]
+            if hit:
+                g = min(hit, key=lambda g: min(abs(g["za"] - t), abs(g["zb"] - t)))
+                if not g["force"]:
+                    # this group used phase warping in the previous round and the residue is still there -> this round
+                    # falls back to the safe path (more reliable than widening)
+                    for p in g["positions"]:
+                        seams[p]["force"] = True
+                    forced += 1
+                else:
+                    # already on the safe path and still residual -> widen the window and repair again
+                    key_p = min(g["positions"], key=lambda p: abs(p - t))
+                    s = seams[key_p]
+                    if s["gap"] < MAX_GAP:
+                        ext = min(s["gap"] // 2, (MAX_GAP - s["gap"]) // 2)
+                        s["gap"] += 2 * ext; s["za"] -= ext; s["zb"] += ext
+                        widened += 1
+            else:
+                Lg, residues, conf = grid["L"], set(grid["residues"]), grid["confidence"]
+                ongrid = (t % Lg) in residues if residues else False
+                if ongrid and conf >= D.GRID_CONFIDENCE_MIN:
+                    seams[t] = dict(gap=D.GAP0, za=t, zb=t, ntracks=1, ongrid=True, strength=0.0, force=False)
+                    added += 1
+        history.append(dict(pass_=it, residual=int(len(resid)), forced_fallback=forced, widened=widened, added=added))
+        if progress:
+            progress(state="repairing", history=history)
+        if forced == 0 and widened == 0 and added == 0:
+            break
+    mode_by_pos = {}
+    for rec in records:
+        for p in rec["group"]["positions"]:
+            mode_by_pos[p] = rec["info"].get("mode", "?")
+    return Y, seams, grid, history, mode_by_pos

openaudiofix/algorithms/declick_detect.py

@@ -0,0 +1,179 @@
+"""Phase-jump detection for dropped samples in a single uploaded file.
+
+Adapted from an earlier pipeline: the same second-difference local-scale detection, cross-channel simultaneous (±TOL)
+verification, and automatic buffer-grid inference. The difference is that "track" becomes "channel" here: a mono
+upload has only 1 track, so the cross-track rule degrades to relying on the grid prior alone (more conservative, see the
+note on `infer_grid`); a stereo upload has 2 tracks and can use the same "seen on >=2 tracks at once" rule as a
+multi-track recording, which is much more accurate.
+
+Looks for this one defect only: dropped samples caused by a driver/ASIO buffer underrun, where the signal jumps to
+another phase within one sample and normal audio follows on both sides - not clipping, not an arbitrary click, not zero
+insertion.
+"""
+import numpy as np
+from scipy.ndimage import maximum_filter1d
+
+BLOCK = 2048        # block length for the local scale (median)
+THRESH = 12.0        # d2 / local median above this value makes a candidate
+MERGE = 64           # candidates within <= MERGE samples count as the same event; keep the strongest
+TOL = 4              # tolerance (samples) for being "simultaneous" across channels
+GAP0 = 96            # default gap (samples)
+GAP_BIG = 160        # gap when the phase step is large
+BIG_STEP = 40.0      # |x[p]-x[p-1]| / local median of the first difference above this counts as a "large phase step"
+# a candidate seen on only one track/channel must exceed this strength and lie on the grid to be accepted
+SINGLE_MIN_STRENGTH = 40.0
+GRID_CANDIDATES = (32, 64, 128, 256, 512)
+# infer_grid concentration below this ratio -> distrust the grid, use only the cross-channel rule
+GRID_CONFIDENCE_MIN = 4.0
+# for mono grid inference, filter out weak candidates first (see the note in detect_seams below)
+GRID_STRENGTH_MIN = 24.0
+
+
+def detect(x):
+    """Returns (array of event positions, strength of each event). Strength = second difference / local median."""
+    d2 = np.abs(x[2:] - 2 * x[1:-1] + x[:-2])  # d2[i] corresponds to sample i+1
+    n = len(d2) // BLOCK * BLOCK
+    if n == 0:
+        return np.array([], int), np.array([])
+    med = np.median(d2[:n].reshape(-1, BLOCK), axis=1)
+    med = maximum_filter1d(np.maximum(med, 1e-9), 3)
+    sc = np.concatenate([np.repeat(med, BLOCK), np.full(len(d2) - n, med[-1] if len(med) else 1e-9)])
+    r = d2 / sc
+    cand = np.where(r > THRESH)[0] + 1
+    if not len(cand):
+        return np.array([], int), np.array([])
+    ev, st = [], []
+    peak, pv, last = cand[0], r[cand[0] - 1], cand[0]
+    for c in cand[1:]:
+        if c - last <= MERGE:
+            if r[c - 1] > pv:
+                peak, pv = c, r[c - 1]
+        else:
+            ev.append(peak); st.append(pv); peak, pv = c, r[c - 1]
+        last = c
+    ev.append(peak); st.append(pv)
+    return np.array(ev), np.array(st)
+
+
+def nearest_dist(a, b):
+    if not len(b):
+        return np.full(len(a), np.inf)
+    j = np.searchsorted(b, a)
+    j0 = np.clip(j - 1, 0, len(b) - 1)
+    j1 = np.clip(j, 0, len(b) - 1)
+    return np.minimum(np.abs(b[j0] - a), np.abs(b[j1] - a))
+
+
+def coincident_all(evs, tol=TOL):
+    """Events that appear within ±tol on all channels (positions taken from the first channel). Returned unchanged for
+    mono."""
+    if len(evs) <= 1:
+        return evs[0]
+    a = evs[0]
+    m = np.ones(len(a), bool)
+    for b in evs[1:]:
+        m &= nearest_dist(a, b) <= tol
+    return a[m]
+
+
+def infer_grid(pos, cands=GRID_CANDIDATES):
+    """Infer the buffer length: for each candidate L, compute the share of "the two adjacent bins where the residues
+    are most concentrated". Returns (L, residue set, share, ratio relative to a uniform distribution)."""
+    if len(pos) == 0:
+        return (cands[0], set(), 0.0, 0.0)
+    stats = []
+    for L in cands:
+        h = np.bincount(pos % L, minlength=L)
+        top = np.argsort(h)[::-1][:2]
+        stats.append((L, set(int(t) for t in top), h[top].sum() / max(len(pos), 1)))
+    fmax = max(f for _, _, f in stats)
+    L, res, f = max((s for s in stats if s[2] >= 0.8 * fmax), key=lambda s: s[0])
+    return (L, res, f, f / (2 / L))
+
+
+def build_seam_list(evs, sts, grid, tol=TOL):
+    """Cluster each channel's candidate events into a seam list: seen on >=2 tracks across channels at once, or on one
+    track, on the grid and strong enough. Returns [(position, n_tracks_matched, on_grid, max_strength), ...]."""
+    allp = np.sort(np.concatenate(evs)) if any(len(e) for e in evs) else np.array([], int)
+    if not len(allp):
+        return []
+    L, residues, _, _ = grid
+    clusters, cur = [], [allp[0]]
+    for p in allp[1:]:
+        if p - cur[-1] <= tol:
+            cur.append(p)
+        else:
+            clusters.append(cur); cur = [p]
+    clusters.append(cur)
+    rows = []
+    for c in clusters:
+        p = int(min(c)); ntr = 0; smax = 0.0
+        for e, s in zip(evs, sts):
+            if not len(e):
+                continue
+            d = np.abs(e - p); j = int(np.argmin(d))
+            if d[j] <= tol:
+                ntr += 1; smax = max(smax, float(s[j]))
+        ongrid = (p % L) in residues if residues else False
+        if ntr >= 2 or (ongrid and smax > SINGLE_MIN_STRENGTH):
+            rows.append((p, ntr, ongrid, smax))
+    return rows
+
+
+def step_ratio(x, p):
+    lo, hi = max(0, p - 1024), min(len(x), p + 1024)
+    d1 = np.abs(np.diff(x[lo:hi]))
+    return float(abs(x[p] - x[p - 1]) / (np.median(d1) + 1e-12)) if 0 < p < len(x) else 0.0
+
+
+def cut_of(p, grid):
+    """Convert a detected candidate position into the exact cut point "first real sample on the right" (accurate only
+    when the grid is trusted; otherwise returns p itself, and the repair side later adds a safety margin, treating it
+    as a tiny gap rather than a single-point splice)."""
+    L, residues, _, conf = grid
+    if conf >= GRID_CONFIDENCE_MIN and len(residues) >= 2:
+        lo = min(residues)
+        if p % L == lo:
+            return p + 1
+    return p
+
+
+def detect_seams(channels, sr):
+    """channels: list of 1D float64 array (one per channel, equal length).
+    Returns dict: {position: {"gap": int, "za": int, "zb": int, "ntracks": int, "ongrid": bool,
+                            "strength": float, "grid_confident": bool}}, plus the grid info (for the front end to
+                            display)."""
+    evs, sts = [], []
+    for x in channels:
+        e, s = detect(x)
+        evs.append(e); sts.append(s)
+    tri = coincident_all(evs)
+    if len(channels) > 1:
+        # simultaneous appearance across channels is strong evidence in itself, use it directly (real candidates are
+        # generally far more numerous than in the mono case, so the SNR is high enough)
+        grid = infer_grid(tri)
+    else:
+        # Mono: most of all candidates are ordinary transients (THRESH=12 is very loose), which dilute the residue
+        # distribution
+        # of the grid until it cannot be inferred. Grid inference uses only strong candidates (less noise), but once the
+        # grid is
+        # trustworthy, a weak candidate that lies on the grid can still enter build_seam_list (see the single-track
+        # branch
+        # below), so it is not blocked by this filter.
+        grid = infer_grid(evs[0][sts[0] >= GRID_STRENGTH_MIN])
+    if grid[3] < GRID_CONFIDENCE_MIN and len(channels) == 1:
+        # grid concentration still low: do not guess hard, to avoid taking ordinary transients for seams
+        grid = (grid[0], set(), 0.0, 0.0)
+    rows = build_seam_list(evs, sts, grid)
+    grid_confident = grid[3] >= GRID_CONFIDENCE_MIN
+    seams = {}
+    for p, ntr, ongrid, strength in rows:
+        gap = GAP_BIG if any(step_ratio(x, p) > BIG_STEP for x in channels) else GAP0
+        cp = cut_of(p, grid) if grid_confident else p
+        # when the grid is not trusted, leave a small gap instead of assuming a single-point splice
+        margin = 0 if grid_confident else 2
+        seams[int(p)] = dict(gap=gap, za=int(cp - margin), zb=int(cp + margin), ntracks=ntr,
+                              ongrid=bool(ongrid), strength=round(float(strength), 1), force=False)
+    return seams, dict(L=grid[0], residues=sorted(grid[1]), coverage=round(grid[2], 4),
+                        confidence=round(grid[3], 2), confident=grid_confident,
+                        n_candidates=[int(len(e)) for e in evs], n_coincident=int(len(tri)))