loopsmith 0.1.0__tar.gz

loopsmith-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Pratt
+
+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.

loopsmith-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: loopsmith
+Version: 0.1.0
+Summary: Find the longest seamlessly-loopable segment in a video via normalized cross-correlation.
+Author-email: John Pratt <john@john-pratt.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jpratt9/loopsmith
+Project-URL: Repository, https://github.com/jpratt9/loopsmith
+Project-URL: Issues, https://github.com/jpratt9/loopsmith/issues
+Keywords: video,loop,seamless-loop,gif,ncc,opencv,ffmpeg
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python>=4.8
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# loopsmith
+
+Find the longest seamlessly-loopable segment in a video.
+
+Given a clip, `loopsmith` figures out the longest stretch you can pull out and
+play on repeat without a visible jump — the point where some later frame looks
+almost exactly like an earlier one, so playback can snap back to the start with
+no seam. Handy for turning B-roll, animations, or background footage into clean
+loops (looping wallpapers, GIFs, video backdrops, and so on).
+
+## How it works
+
+The core of it is a single matrix multiply.
+
+1. Sample every Nth frame, shrink each to a 160px thumbnail, convert to
+   grayscale, and z-score normalize it (subtract the mean, divide by the
+   standard deviation).
+2. Stack the normalized frames into a matrix and multiply it by its own
+   transpose. For z-scored vectors, each dot product (divided by the pixel
+   count) *is* the normalized cross-correlation between two frames — a
+   similarity score from -1 to 1 where 1 means "visually identical." So one
+   `mat @ mat.T` produces the score for every pair of frames at once.
+3. For each pair of frames, the gap between them is a candidate loop length.
+   Among all pairs whose similarity clears a threshold, the one with the
+   largest gap wins: those two near-identical frames are the in- and out-points
+   of the longest seam-free loop.
+
+Because the expensive step is one BLAS matmul, it stays quick even though it's
+effectively comparing every frame against every other frame.
+
+## Install
+
+```bash
+pip install loopsmith
+```
+
+From source, for development (includes the test deps):
+
+```bash
+pip install -e ".[dev]"
+```
+
+Needs Python 3.9+, OpenCV, and NumPy — the last two are pulled in automatically.
+
+## Usage (CLI)
+
+```bash
+# Analyze a single video
+loopsmith clip.mp4
+
+# Batch every .mp4/.mov in a directory
+loopsmith ./footage/
+
+# Loosen or tighten the similarity threshold (default 0.85)
+loopsmith clip.mp4 --threshold 0.80
+
+# Sample every 5th frame instead of every 3rd (faster, coarser)
+loopsmith clip.mp4 --downsample 5
+
+# Detailed report: top 10 loops by similarity and by length
+loopsmith clip.mp4 --detail
+
+# Find the best loop closest to a target length, in seconds
+loopsmith clip.mp4 --detail --target-length 6
+```
+
+Batch mode prints the best loop per file as a table; `--detail` (single file)
+prints the top candidates plus a yes/no "is this clip loopable" verdict.
+
+## Usage (library)
+
+```python
+from loopsmith import extract_frames, find_best_loop
+
+rows, frame_indices, fps, total = extract_frames("clip.mp4", downsample=3)
+loop = find_best_loop(rows, frame_indices, threshold=0.85)
+if loop:
+    start_frame, end_frame, ncc = loop
+    seconds = (end_frame - start_frame) / fps
+    print(f"Loop {start_frame}->{end_frame} ({seconds:.1f}s) at {ncc:.1%} similarity")
+```
+
+Other helpers: `find_best_for_target()` (the loop closest to a target
+duration), `find_top_loops()` (ranked candidates), and `analyze_video()` (a
+one-call summary dict).
+
+## Notes & limitations
+
+- **Visual only.** It compares frames, not audio. A visually seamless loop can
+  still have an audible seam — check the sound separately if that matters.
+- **Cut resolution.** In/out points are accurate to within `--downsample`
+  frames, since that's the sampling step. Lower it for tighter cuts at the cost
+  of speed.
+- **Scales as O(N²) in sampled frames.** It builds an N×N similarity matrix, so
+  for long videos raise `--downsample` to keep time and memory in check.
+- **It reports, it doesn't cut.** Output is frame indices / timestamps and
+  similarity scores; trimming the actual clip (e.g. with ffmpeg) is up to you.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

loopsmith-0.1.0/README.md

@@ -0,0 +1,101 @@
+# loopsmith
+
+Find the longest seamlessly-loopable segment in a video.
+
+Given a clip, `loopsmith` figures out the longest stretch you can pull out and
+play on repeat without a visible jump — the point where some later frame looks
+almost exactly like an earlier one, so playback can snap back to the start with
+no seam. Handy for turning B-roll, animations, or background footage into clean
+loops (looping wallpapers, GIFs, video backdrops, and so on).
+
+## How it works
+
+The core of it is a single matrix multiply.
+
+1. Sample every Nth frame, shrink each to a 160px thumbnail, convert to
+   grayscale, and z-score normalize it (subtract the mean, divide by the
+   standard deviation).
+2. Stack the normalized frames into a matrix and multiply it by its own
+   transpose. For z-scored vectors, each dot product (divided by the pixel
+   count) *is* the normalized cross-correlation between two frames — a
+   similarity score from -1 to 1 where 1 means "visually identical." So one
+   `mat @ mat.T` produces the score for every pair of frames at once.
+3. For each pair of frames, the gap between them is a candidate loop length.
+   Among all pairs whose similarity clears a threshold, the one with the
+   largest gap wins: those two near-identical frames are the in- and out-points
+   of the longest seam-free loop.
+
+Because the expensive step is one BLAS matmul, it stays quick even though it's
+effectively comparing every frame against every other frame.
+
+## Install
+
+```bash
+pip install loopsmith
+```
+
+From source, for development (includes the test deps):
+
+```bash
+pip install -e ".[dev]"
+```
+
+Needs Python 3.9+, OpenCV, and NumPy — the last two are pulled in automatically.
+
+## Usage (CLI)
+
+```bash
+# Analyze a single video
+loopsmith clip.mp4
+
+# Batch every .mp4/.mov in a directory
+loopsmith ./footage/
+
+# Loosen or tighten the similarity threshold (default 0.85)
+loopsmith clip.mp4 --threshold 0.80
+
+# Sample every 5th frame instead of every 3rd (faster, coarser)
+loopsmith clip.mp4 --downsample 5
+
+# Detailed report: top 10 loops by similarity and by length
+loopsmith clip.mp4 --detail
+
+# Find the best loop closest to a target length, in seconds
+loopsmith clip.mp4 --detail --target-length 6
+```
+
+Batch mode prints the best loop per file as a table; `--detail` (single file)
+prints the top candidates plus a yes/no "is this clip loopable" verdict.
+
+## Usage (library)
+
+```python
+from loopsmith import extract_frames, find_best_loop
+
+rows, frame_indices, fps, total = extract_frames("clip.mp4", downsample=3)
+loop = find_best_loop(rows, frame_indices, threshold=0.85)
+if loop:
+    start_frame, end_frame, ncc = loop
+    seconds = (end_frame - start_frame) / fps
+    print(f"Loop {start_frame}->{end_frame} ({seconds:.1f}s) at {ncc:.1%} similarity")
+```
+
+Other helpers: `find_best_for_target()` (the loop closest to a target
+duration), `find_top_loops()` (ranked candidates), and `analyze_video()` (a
+one-call summary dict).
+
+## Notes & limitations
+
+- **Visual only.** It compares frames, not audio. A visually seamless loop can
+  still have an audible seam — check the sound separately if that matters.
+- **Cut resolution.** In/out points are accurate to within `--downsample`
+  frames, since that's the sampling step. Lower it for tighter cuts at the cost
+  of speed.
+- **Scales as O(N²) in sampled frames.** It builds an N×N similarity matrix, so
+  for long videos raise `--downsample` to keep time and memory in check.
+- **It reports, it doesn't cut.** Output is frame indices / timestamps and
+  similarity scores; trimming the actual clip (e.g. with ffmpeg) is up to you.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

loopsmith-0.1.0/loopsmith.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: loopsmith
+Version: 0.1.0
+Summary: Find the longest seamlessly-loopable segment in a video via normalized cross-correlation.
+Author-email: John Pratt <john@john-pratt.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jpratt9/loopsmith
+Project-URL: Repository, https://github.com/jpratt9/loopsmith
+Project-URL: Issues, https://github.com/jpratt9/loopsmith/issues
+Keywords: video,loop,seamless-loop,gif,ncc,opencv,ffmpeg
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python>=4.8
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# loopsmith
+
+Find the longest seamlessly-loopable segment in a video.
+
+Given a clip, `loopsmith` figures out the longest stretch you can pull out and
+play on repeat without a visible jump — the point where some later frame looks
+almost exactly like an earlier one, so playback can snap back to the start with
+no seam. Handy for turning B-roll, animations, or background footage into clean
+loops (looping wallpapers, GIFs, video backdrops, and so on).
+
+## How it works
+
+The core of it is a single matrix multiply.
+
+1. Sample every Nth frame, shrink each to a 160px thumbnail, convert to
+   grayscale, and z-score normalize it (subtract the mean, divide by the
+   standard deviation).
+2. Stack the normalized frames into a matrix and multiply it by its own
+   transpose. For z-scored vectors, each dot product (divided by the pixel
+   count) *is* the normalized cross-correlation between two frames — a
+   similarity score from -1 to 1 where 1 means "visually identical." So one
+   `mat @ mat.T` produces the score for every pair of frames at once.
+3. For each pair of frames, the gap between them is a candidate loop length.
+   Among all pairs whose similarity clears a threshold, the one with the
+   largest gap wins: those two near-identical frames are the in- and out-points
+   of the longest seam-free loop.
+
+Because the expensive step is one BLAS matmul, it stays quick even though it's
+effectively comparing every frame against every other frame.
+
+## Install
+
+```bash
+pip install loopsmith
+```
+
+From source, for development (includes the test deps):
+
+```bash
+pip install -e ".[dev]"
+```
+
+Needs Python 3.9+, OpenCV, and NumPy — the last two are pulled in automatically.
+
+## Usage (CLI)
+
+```bash
+# Analyze a single video
+loopsmith clip.mp4
+
+# Batch every .mp4/.mov in a directory
+loopsmith ./footage/
+
+# Loosen or tighten the similarity threshold (default 0.85)
+loopsmith clip.mp4 --threshold 0.80
+
+# Sample every 5th frame instead of every 3rd (faster, coarser)
+loopsmith clip.mp4 --downsample 5
+
+# Detailed report: top 10 loops by similarity and by length
+loopsmith clip.mp4 --detail
+
+# Find the best loop closest to a target length, in seconds
+loopsmith clip.mp4 --detail --target-length 6
+```
+
+Batch mode prints the best loop per file as a table; `--detail` (single file)
+prints the top candidates plus a yes/no "is this clip loopable" verdict.
+
+## Usage (library)
+
+```python
+from loopsmith import extract_frames, find_best_loop
+
+rows, frame_indices, fps, total = extract_frames("clip.mp4", downsample=3)
+loop = find_best_loop(rows, frame_indices, threshold=0.85)
+if loop:
+    start_frame, end_frame, ncc = loop
+    seconds = (end_frame - start_frame) / fps
+    print(f"Loop {start_frame}->{end_frame} ({seconds:.1f}s) at {ncc:.1%} similarity")
+```
+
+Other helpers: `find_best_for_target()` (the loop closest to a target
+duration), `find_top_loops()` (ranked candidates), and `analyze_video()` (a
+one-call summary dict).
+
+## Notes & limitations
+
+- **Visual only.** It compares frames, not audio. A visually seamless loop can
+  still have an audible seam — check the sound separately if that matters.
+- **Cut resolution.** In/out points are accurate to within `--downsample`
+  frames, since that's the sampling step. Lower it for tighter cuts at the cost
+  of speed.
+- **Scales as O(N²) in sampled frames.** It builds an N×N similarity matrix, so
+  for long videos raise `--downsample` to keep time and memory in check.
+- **It reports, it doesn't cut.** Output is frame indices / timestamps and
+  similarity scores; trimming the actual clip (e.g. with ffmpeg) is up to you.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

loopsmith-0.1.0/loopsmith.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+loopsmith.py
+pyproject.toml
+loopsmith.egg-info/PKG-INFO
+loopsmith.egg-info/SOURCES.txt
+loopsmith.egg-info/dependency_links.txt
+loopsmith.egg-info/entry_points.txt
+loopsmith.egg-info/requires.txt
+loopsmith.egg-info/top_level.txt
+tests/test_loopsmith.py

loopsmith-0.1.0/loopsmith.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

loopsmith-0.1.0/loopsmith.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+loopsmith = loopsmith:main

loopsmith-0.1.0/loopsmith.egg-info/requires.txt

@@ -0,0 +1,5 @@
+opencv-python>=4.8
+numpy>=1.24
+
+[dev]
+pytest>=8.0

loopsmith-0.1.0/loopsmith.egg-info/top_level.txt

@@ -0,0 +1 @@
+loopsmith

loopsmith-0.1.0/loopsmith.py

@@ -0,0 +1,290 @@
+"""Find the longest seamlessly-loopable segment in a video using NCC.
+
+Uses vectorized N^2 pairwise Normalized Cross-Correlation (a single matrix
+multiply) to find the largest frame gap whose endpoints match above a
+similarity threshold -- i.e. the longest sub-clip you can loop without a
+visible seam.
+
+CLI:
+    loopsmith video.mp4
+    loopsmith path/to/videos/                 # batch every .mp4/.mov in a dir
+    loopsmith video.mp4 --threshold 0.80
+    loopsmith video.mp4 --downsample 5
+    loopsmith video.mp4 --detail              # top-10 by similarity and length
+    loopsmith video.mp4 --detail --target-length 6
+"""
+
+import argparse
+import glob
+import os
+import time
+
+import cv2
+import numpy as np
+
+THUMB = 160  # scale longest edge to this for comparison
+DEFAULT_THRESHOLD = 0.85
+DEFAULT_DOWNSAMPLE = 3  # every Nth frame
+
+
+def extract_frames(video_path, downsample):
+    """Extract downsampled, normalized grayscale frames from a video.
+
+    Returns:
+        Tuple of (list of flattened normalized frames, list of original frame indices, fps).
+    """
+    cap = cv2.VideoCapture(video_path)
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+    rows = []
+    frame_indices = []
+    for i in range(0, total, downsample):
+        cap.set(cv2.CAP_PROP_POS_FRAMES, i)
+        ret, frame = cap.read()
+        if not ret:
+            break
+        h, w = frame.shape[:2]
+        scale = THUMB / max(h, w)
+        nw, nh = int(w * scale), int(h * scale)
+        g = cv2.cvtColor(cv2.resize(frame, (nw, nh)), cv2.COLOR_BGR2GRAY).astype(np.float32)
+        std = g.std()
+        if std < 1.0:
+            continue
+        normed = ((g - g.mean()) / std).flatten()
+        rows.append(normed)
+        frame_indices.append(i)
+    cap.release()
+
+    return rows, frame_indices, fps, total
+
+
+def compute_ncc_matrix(rows, frame_indices):
+    """Compute all pairwise NCCs via matrix multiplication.
+
+    Returns:
+        Tuple of (ncc_matrix, gaps_matrix, frame_indices array).
+    """
+    mat = np.stack(rows)  # (N, pixels)
+    ncc_matrix = mat @ mat.T / mat.shape[1]  # (N, N)
+    idx_arr = np.array(frame_indices)
+    gaps = idx_arr[None, :] - idx_arr[:, None]  # (N, N)
+    return ncc_matrix, gaps
+
+
+def find_best_loop(rows, frame_indices, threshold):
+    """Find the largest frame gap with NCC above threshold.
+
+    Returns:
+        Tuple of (best_start_frame, best_end_frame, best_ncc) or None if no loop found.
+    """
+    n = len(rows)
+    if n < 2:
+        return None
+
+    ncc_matrix, gaps = compute_ncc_matrix(rows, frame_indices)
+    mask = (ncc_matrix >= threshold) & (gaps > 0)
+
+    if not mask.any():
+        return None
+
+    qualified_gaps = np.where(mask, gaps, 0)
+    flat_idx = np.argmax(qualified_gaps)
+    a, b = divmod(flat_idx, n)
+
+    return frame_indices[a], frame_indices[b], float(ncc_matrix[a, b])
+
+
+def find_best_for_target(rows, frame_indices, fps, target_seconds, min_ncc=0.90):
+    """Find the best loop closest to target_seconds among high-NCC pairs.
+
+    Filters to pairs with NCC >= min_ncc and duration >= 1s, then picks
+    the one closest to the target duration.
+
+    Returns:
+        Tuple of (start_frame, end_frame, gap_seconds, ncc) or None.
+    """
+    n = len(rows)
+    if n < 2:
+        return None
+
+    ncc_matrix, gaps = compute_ncc_matrix(rows, frame_indices)
+
+    mask = gaps > 0
+    ai, bi = np.where(mask)
+    nccs = ncc_matrix[ai, bi]
+    durations = gaps[ai, bi].astype(float) / fps
+
+    # Filter: NCC >= min_ncc AND duration >= 1s
+    valid = (nccs >= min_ncc) & (durations >= 1.0)
+    if not valid.any():
+        return None
+
+    ai, bi, nccs, durations = ai[valid], bi[valid], nccs[valid], durations[valid]
+
+    # Pick closest to target duration
+    best_k = np.argmin(np.abs(durations - target_seconds))
+    return (
+        frame_indices[ai[best_k]],
+        frame_indices[bi[best_k]],
+        float(durations[best_k]),
+        float(nccs[best_k]),
+    )
+
+
+def find_top_loops(rows, frame_indices, fps, top_n=10):
+    """Find top loops ranked by NCC and by gap length.
+
+    Returns:
+        Tuple of (by_ncc, by_gap) where each is a list of
+        (start_frame, end_frame, gap_seconds, ncc) tuples.
+    """
+    n = len(rows)
+    if n < 2:
+        return [], []
+
+    ncc_matrix, gaps = compute_ncc_matrix(rows, frame_indices)
+
+    # Upper triangle only (j > i)
+    mask = gaps > 0
+    ai, bi = np.where(mask)
+    nccs = ncc_matrix[ai, bi]
+    gap_vals = gaps[ai, bi]
+
+    # Top by NCC
+    ncc_order = np.argsort(nccs)[::-1][:top_n]
+    by_ncc = [
+        (frame_indices[ai[k]], frame_indices[bi[k]], float(gap_vals[k]) / fps, float(nccs[k]))
+        for k in ncc_order
+    ]
+
+    # Top by gap (longest first), with minimum NCC > 0.5 to filter garbage
+    valid = nccs > 0.5
+    if valid.any():
+        valid_idx = np.where(valid)[0]
+        gap_order = np.argsort(gap_vals[valid_idx])[::-1][:top_n]
+        by_gap = [
+            (frame_indices[ai[valid_idx[k]]], frame_indices[bi[valid_idx[k]]],
+             float(gap_vals[valid_idx[k]]) / fps, float(nccs[valid_idx[k]]))
+            for k in gap_order
+        ]
+    else:
+        by_gap = []
+
+    return by_ncc, by_gap
+
+
+def analyze_video(video_path, threshold, downsample):
+    """Analyze a single video for loop segments.
+
+    Returns:
+        Dict with video info and loop detection results.
+    """
+    rows, frame_indices, fps, total = extract_frames(video_path, downsample)
+    dur = total / fps if fps > 0 else 0
+
+    result = {
+        "file": os.path.basename(video_path),
+        "total_frames": total,
+        "fps": fps,
+        "duration": dur,
+        "loop": None,
+    }
+
+    loop = find_best_loop(rows, frame_indices, threshold)
+    if loop:
+        start, end, ncc = loop
+        result["loop"] = {
+            "start_frame": start,
+            "end_frame": end,
+            "duration": (end - start) / fps,
+            "ncc": ncc,
+        }
+
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Detect loop segments in video files")
+    parser.add_argument("path", help="Video file or directory of videos")
+    parser.add_argument("--threshold", type=float, default=DEFAULT_THRESHOLD,
+                        help=f"NCC threshold (default: {DEFAULT_THRESHOLD})")
+    parser.add_argument("--downsample", type=int, default=DEFAULT_DOWNSAMPLE,
+                        help=f"Extract every Nth frame (default: {DEFAULT_DOWNSAMPLE})")
+    parser.add_argument("--detail", action="store_true",
+                        help="Show top 10 loops by NCC and by duration (single file only)")
+    parser.add_argument("--target-length", type=float, default=None,
+                        help="Find best NCC loop closest to this duration in seconds")
+    args = parser.parse_args()
+
+    if os.path.isdir(args.path):
+        videos = sorted(
+            glob.glob(os.path.join(args.path, "*.mp4"))
+            + glob.glob(os.path.join(args.path, "*.mov"))
+        )
+    else:
+        videos = [args.path]
+
+    if args.detail and len(videos) == 1:
+        path = videos[0]
+        print(f"Analyzing: {os.path.basename(path)}")
+        t0 = time.time()
+        rows, frame_indices, fps, total = extract_frames(path, args.downsample)
+        dur = total / fps if fps > 0 else 0
+        print(f"Frames: {total}, FPS: {fps:.0f}, Duration: {dur:.1f}s, Sampled: {len(rows)}")
+
+        by_ncc, by_gap = find_top_loops(rows, frame_indices, fps)
+
+        print(f"\nTop 10 by NCC (highest similarity):")
+        print(f"  {'Start':>6} {'End':>6} {'Duration':>9} {'NCC':>7}")
+        for start, end, gap_s, ncc in by_ncc:
+            print(f"  f{start:>5} f{end:>5} {gap_s:>8.1f}s {ncc:>6.1%}")
+
+        print(f"\nTop 10 by duration (longest loops with NCC > 50%):")
+        print(f"  {'Start':>6} {'End':>6} {'Duration':>9} {'NCC':>7}")
+        for start, end, gap_s, ncc in by_gap:
+            print(f"  f{start:>5} f{end:>5} {gap_s:>8.1f}s {ncc:>6.1%}")
+
+        if args.target_length:
+            result = find_best_for_target(rows, frame_indices, fps, args.target_length)
+            if result:
+                print(f"\nBest loop near {args.target_length:.0f}s: f{result[0]}->f{result[1]} ({result[2]:.1f}s) NCC={result[3]:.1%}")
+            else:
+                print(f"\nNo loop found near {args.target_length:.0f}s")
+
+        # Check if highest NCC pair (>= 1s) is loopable
+        best = find_best_for_target(rows, frame_indices, fps, target_seconds=dur)
+        if best and best[3] >= 0.97:
+            raw_loopable = abs(best[2] - dur) <= 0.5
+            print(f"\nLoopable: YES (best NCC={best[3]:.1%}, {best[2]:.1f}s)")
+            if raw_loopable:
+                print(f"Original clip is loopable as-is (within 0.5s of {dur:.1f}s)")
+        else:
+            ncc_str = f"{best[3]:.1%}" if best else "N/A"
+            print(f"\nLoopable: NO (best NCC={ncc_str})")
+
+        print(f"\nDone in {time.time() - t0:.1f}s")
+        return
+
+    print(f"{'File':<55} {'Dur':>5} {'Best Loop':>22} {'NCC':>7} {'Loop?'}")
+    print("-" * 100)
+
+    t0 = time.time()
+    for path in videos:
+        result = analyze_video(path, args.threshold, args.downsample)
+        name = result["file"]
+        dur = result["duration"]
+
+        if result["loop"]:
+            lp = result["loop"]
+            loop_str = f"f{lp['start_frame']}->{lp['end_frame']} ({lp['duration']:.1f}s)"
+            tag = "YES" if lp["ncc"] >= 0.90 else "~"
+            print(f"{name:<55} {dur:>4.1f}s {loop_str:>22} {lp['ncc']:>6.1%}  {tag}")
+        else:
+            print(f"{name:<55} {dur:>4.1f}s {'none found':>22}         no")
+
+    print(f"\nDone in {time.time() - t0:.1f}s")
+
+
+if __name__ == "__main__":
+    main()

loopsmith-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "loopsmith"
+version = "0.1.0"
+description = "Find the longest seamlessly-loopable segment in a video via normalized cross-correlation."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "John Pratt", email = "john@john-pratt.com" }]
+keywords = ["video", "loop", "seamless-loop", "gif", "ncc", "opencv", "ffmpeg"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "opencv-python>=4.8",
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://github.com/jpratt9/loopsmith"
+Repository = "https://github.com/jpratt9/loopsmith"
+Issues = "https://github.com/jpratt9/loopsmith/issues"
+
+[project.scripts]
+loopsmith = "loopsmith:main"
+
+[tool.setuptools]
+py-modules = ["loopsmith"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

loopsmith-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

loopsmith-0.1.0/tests/test_loopsmith.py

@@ -0,0 +1,197 @@
+"""Tests for the loopsmith module."""
+
+from unittest.mock import patch
+
+import numpy as np
+import pytest
+
+from loopsmith import (
+    compute_ncc_matrix,
+    find_best_for_target,
+    find_best_loop,
+    find_top_loops,
+    analyze_video,
+)
+
+
+def _make_frame(value, size=100):
+    """Create a normalized flat frame with a known pattern."""
+    frame = np.random.RandomState(value).randn(size).astype(np.float32)
+    frame = (frame - frame.mean()) / frame.std()
+    return frame
+
+
+class TestComputeNccMatrix:
+    def test_self_similarity_is_one(self):
+        rows = [_make_frame(1), _make_frame(2)]
+        ncc_matrix, gaps = compute_ncc_matrix(rows, [0, 10])
+        assert ncc_matrix[0, 0] == pytest.approx(1.0, abs=0.01)
+        assert ncc_matrix[1, 1] == pytest.approx(1.0, abs=0.01)
+
+    def test_gaps_computed_correctly(self):
+        rows = [_make_frame(1), _make_frame(2), _make_frame(3)]
+        ncc_matrix, gaps = compute_ncc_matrix(rows, [0, 30, 90])
+        assert gaps[0, 1] == 30
+        assert gaps[0, 2] == 90
+        assert gaps[1, 2] == 60
+        assert gaps[1, 0] == -30
+
+    def test_identical_frames_have_high_ncc(self):
+        frame = _make_frame(42)
+        rows = [frame.copy(), frame.copy()]
+        ncc_matrix, _ = compute_ncc_matrix(rows, [0, 100])
+        assert ncc_matrix[0, 1] == pytest.approx(1.0, abs=0.01)
+
+    def test_different_frames_have_low_ncc(self):
+        rows = [_make_frame(1), _make_frame(999)]
+        ncc_matrix, _ = compute_ncc_matrix(rows, [0, 100])
+        assert ncc_matrix[0, 1] < 0.5
+
+
+class TestFindBestLoop:
+    def test_finds_loop_above_threshold(self):
+        frame = _make_frame(42)
+        rows = [frame.copy(), _make_frame(2), frame.copy()]
+        indices = [0, 30, 90]
+        result = find_best_loop(rows, indices, threshold=0.90)
+        assert result is not None
+        start, end, ncc = result
+        assert start == 0
+        assert end == 90
+        assert ncc > 0.90
+
+    def test_returns_none_below_threshold(self):
+        rows = [_make_frame(1), _make_frame(2), _make_frame(3)]
+        indices = [0, 30, 60]
+        result = find_best_loop(rows, indices, threshold=0.99)
+        assert result is None
+
+    def test_returns_none_with_fewer_than_two_frames(self):
+        result = find_best_loop([_make_frame(1)], [0], threshold=0.5)
+        assert result is None
+
+    def test_picks_largest_gap(self):
+        frame = _make_frame(42)
+        rows = [frame.copy(), frame.copy(), _make_frame(99), frame.copy()]
+        indices = [0, 10, 50, 100]
+        result = find_best_loop(rows, indices, threshold=0.90)
+        assert result is not None
+        start, end, ncc = result
+        # Should pick f0->f100 (gap=100) over f0->f10 (gap=10)
+        assert end - start == 100
+
+
+class TestFindBestForTarget:
+    def test_finds_closest_to_target(self):
+        frame = _make_frame(42)
+        # 3 identical frames at 0, 150, 300 -> gaps of 5s and 10s at 30fps
+        rows = [frame.copy(), frame.copy(), frame.copy()]
+        indices = [0, 150, 300]
+        result = find_best_for_target(rows, indices, fps=30.0, target_seconds=9.0)
+        assert result is not None
+        start, end, dur, ncc = result
+        # Should pick the 10s pair (closest to 9s target)
+        assert dur == pytest.approx(10.0, abs=0.1)
+        assert ncc > 0.99
+
+    def test_picks_closest_duration_among_top_ncc(self):
+        frame = _make_frame(42)
+        # 4 identical frames at different gaps: 2s, 5s, 8s, 10s at 30fps
+        rows = [frame.copy(), frame.copy(), frame.copy(), frame.copy()]
+        indices = [0, 60, 150, 300]
+        # Target 7s -> should pick 8s (f0->f240 isn't available, but f60->f300 = 8s)
+        result = find_best_for_target(rows, indices, fps=30.0, target_seconds=7.0)
+        assert result is not None
+        # All pairs have ~100% NCC, so it picks purely by closest duration
+        assert result[3] > 0.9
+
+    def test_skips_short_gaps(self):
+        frame = _make_frame(42)
+        # Two identical frames only 10 frames apart at 30fps = 0.33s (< 1s threshold)
+        rows = [frame.copy(), frame.copy()]
+        indices = [0, 10]
+        result = find_best_for_target(rows, indices, fps=30.0, target_seconds=5.0)
+        assert result is None
+
+    def test_returns_none_with_fewer_than_two_frames(self):
+        result = find_best_for_target([_make_frame(1)], [0], fps=30.0, target_seconds=5.0)
+        assert result is None
+
+    def test_returns_none_when_no_high_ncc_pairs(self):
+        # Two different frames -- NCC will be low, below min_ncc threshold
+        rows = [_make_frame(1), _make_frame(2)]
+        indices = [0, 300]
+        result = find_best_for_target(rows, indices, fps=30.0, target_seconds=10.0)
+        assert result is None
+
+
+class TestFindTopLoops:
+    def test_returns_top_by_ncc(self):
+        frame_a = _make_frame(1)
+        frame_b = _make_frame(2)
+        rows = [frame_a.copy(), frame_b.copy(), frame_a.copy()]
+        indices = [0, 30, 60]
+        by_ncc, by_gap = find_top_loops(rows, indices, fps=30.0, top_n=5)
+        assert len(by_ncc) > 0
+        # First entry should have highest NCC
+        assert by_ncc[0][3] >= by_ncc[-1][3]
+
+    def test_returns_top_by_gap(self):
+        frame = _make_frame(42)
+        rows = [frame.copy(), _make_frame(2), frame.copy()]
+        indices = [0, 30, 90]
+        by_ncc, by_gap = find_top_loops(rows, indices, fps=30.0, top_n=5)
+        assert len(by_gap) > 0
+        # First entry should have largest gap
+        assert by_gap[0][2] >= by_gap[-1][2]
+
+    def test_empty_with_fewer_than_two_frames(self):
+        by_ncc, by_gap = find_top_loops([_make_frame(1)], [0], fps=30.0)
+        assert by_ncc == []
+        assert by_gap == []
+
+    def test_gap_duration_is_in_seconds(self):
+        frame = _make_frame(42)
+        rows = [frame.copy(), frame.copy()]
+        indices = [0, 90]
+        by_ncc, _ = find_top_loops(rows, indices, fps=30.0)
+        # 90 frames at 30fps = 3.0 seconds
+        assert by_ncc[0][2] == pytest.approx(3.0, abs=0.01)
+
+
+class TestAnalyzeVideo:
+    @patch("loopsmith.extract_frames")
+    def test_returns_loop_info(self, mock_extract):
+        frame = _make_frame(42)
+        mock_extract.return_value = (
+            [frame.copy(), _make_frame(2), frame.copy()],
+            [0, 30, 90],
+            30.0,
+            100,
+        )
+        result = analyze_video("/fake/video.mp4", threshold=0.85, downsample=3)
+        assert result["file"] == "video.mp4"
+        assert result["total_frames"] == 100
+        assert result["fps"] == 30.0
+        assert result["loop"] is not None
+        assert result["loop"]["start_frame"] == 0
+        assert result["loop"]["end_frame"] == 90
+        assert result["loop"]["ncc"] > 0.90
+
+    @patch("loopsmith.extract_frames")
+    def test_returns_none_when_no_loop(self, mock_extract):
+        mock_extract.return_value = (
+            [_make_frame(1), _make_frame(2), _make_frame(3)],
+            [0, 30, 60],
+            30.0,
+            100,
+        )
+        result = analyze_video("/fake/video.mp4", threshold=0.99, downsample=3)
+        assert result["loop"] is None
+
+    @patch("loopsmith.extract_frames")
+    def test_handles_zero_fps(self, mock_extract):
+        mock_extract.return_value = ([], [], 0.0, 0)
+        result = analyze_video("/fake/video.mp4", threshold=0.85, downsample=3)
+        assert result["duration"] == 0
+        assert result["loop"] is None