fix: harden selection and processing pipelines

Author: shrimbly

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [master, develop]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install FFmpeg (Ubuntu)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install --yes ffmpeg
+
+      - name: Install FFmpeg (macOS)
+        if: runner.os == 'macOS'
+        run: brew install ffmpeg
+
+      - name: Install FFmpeg (Windows)
+        if: runner.os == 'Windows'
+        run: choco install ffmpeg --yes --no-progress
+
+      - name: Install package and test dependencies
+        run: python -m pip install --upgrade pip && python -m pip install -r requirements.txt
+
+      - name: Run tests
+        run: python -m pytest -q
+
+      - name: Build wheel
+        run: python -m pip wheel . --no-deps --wheel-dir dist

README.md

@@ -14,11 +14,13 @@ Or with pipx for isolated installation:
 pipx install sharp-frames
 ```
 
-**IMPORTANT: Video Processing Requirement**: Install FFmpeg separately for video input support.
+**IMPORTANT: Video Processing Requirement**: Install an FFmpeg distribution that includes both `ffmpeg` and `ffprobe`. Both executables must be on `PATH`; image-directory processing does not require them.
 - **Windows**: Download from [FFmpeg website](https://ffmpeg.org/download.html) and add to PATH
 - **macOS**: `brew install ffmpeg`
 - **Linux**: `sudo apt install ffmpeg`
 
+HDR-to-SDR extraction additionally requires an FFmpeg build with the `zscale` filter (`libzimg`). You can verify support with `ffmpeg -filters | grep zscale`. Non-HDR video processing does not require `zscale`.
+
 ## Quick Start
 
 ### Modern Interface (Default)
@@ -45,9 +47,9 @@ sharp-frames <input> <output> [options]
 ```
 
 **Input Types:**
-- Video files: `.mp4`, `.avi`, `.mov`, `.mkv`, `.wmv`, `.flv`, `.webm`, `.m4v`, etc.
+- Video files: `.mp4`, `.avi`, `.mov`, `.mkv`, `.wmv`, `.flv`, `.webm`, `.m4v`, `.3gp`, `.3g2`, `.ogv`, `.ts`, `.mts`, `.m2ts`, `.mpg`, `.mpeg`, `.vob`
 - Video directories: Processes all videos in a folder
-- Image directories: `.jpg`, `.jpeg`, `.png`, `.bmp`, `.tiff`, `.webp`, etc.
+- Image directories: `.jpg`, `.jpeg`, `.png`, `.bmp`, `.tif`, `.tiff`, `.webp`, `.ppm`, `.pgm`, `.pbm`
 
 ## Selection Methods
 
@@ -79,7 +81,7 @@ Removes unusually blurry frames by comparing each frame to its neighbors.
 
 ### Selection Method Parameters
 - `--num-frames <int>`: Number of frames to select (best-n, default: 300)
-- `--min-buffer <int>`: Minimum gap between selected frames (best-n, default: 3)
+- `--min-buffer <int>`: Minimum number of intervening frames between selected frames (best-n, default: 3)
 - `--batch-size <int>`: Frames per batch (batched, default: 5)
 - `--batch-buffer <int>`: Frames to skip between batches (batched, default: 2)
 - `--outlier-window-size <int>`: Neighbor comparison window (outlier-removal, default: 15)
@@ -125,9 +127,10 @@ sharp-frames photos selected --selection-method outlier-removal --outlier-sensit
 
 ## Requirements
 
-- Python 3.7 or higher
+- Python 3.10 or higher
 - Dependencies installed automatically: `opencv-python`, `numpy`, `tqdm`, `textual`
-- FFmpeg (for video processing only)
+- FFmpeg and FFprobe (for video processing only)
+- FFmpeg `zscale`/`libzimg` support (for HDR-to-SDR processing only)
 
 ## How It Works
 
@@ -141,7 +144,7 @@ sharp-frames photos selected --selection-method outlier-removal --outlier-sensit
 
 - Selected frames/images with descriptive filenames
 - `selected_metadata.json` with processing details, parameters, and sharpness scores
-- Preserves original formats for image directory input
+- Transcodes selected images to the configured output format (`jpg` by default)
 - Automatic output directory creation with permission validation
 
 ## Help & Support

docs/APPLICATION_AUDIT.md

@@ -0,0 +1,278 @@
+# Sharp Frames Application Audit
+
+Date: 2026-07-14
+Baseline: `develop` at `e712afa`
+Remediation branch: `codex/deep-application-review`
+
+## Scope
+
+This audit covered the direct CLI, Textual UI, extraction and saving pipelines,
+all three selection methods, multi-video and image-directory inputs, sharpness
+analysis, packaging, dependency health, cancellation, and platform support.
+
+The audit combined source inspection with focused behavior probes, synthetic
+FFmpeg runs, package builds, static analysis, and the full test suite.
+
+## Remediation Outcome
+
+All Critical and High findings in this audit are resolved on
+`codex/deep-application-review`.
+
+| Finding | Resolution |
+| --- | --- |
+| C1 | All non-interactive save paths now fail closed on unapproved output conflicts. |
+| C2 | Modern and direct-CLI directory saves transcode to the requested format and deterministically disambiguate colliding stems. |
+| H1–H5 | CLI, TUI, previews, and compatibility entry points share canonical, source-aware selection implementations with exact previews. |
+| H6 | FFmpeg output is continuously drained; completion requires a clean exit; failure, timeout, and cancellation reject partial output. |
+| H7 | Cancellation reaches active extraction and analysis, and temporary directories are cleaned on every tested exit path. |
+| H8 | The declared and tested support floor is Python 3.10. |
+| H9 | Image-only processing skips video-tool checks; video checks require FFmpeg and FFprobe; HDR and platform requirements are documented. |
+| H10 | CLI, TUI, validation, extraction, and documentation use one shared media-format contract. |
+| H11 | FFprobe failures preserve actionable stderr and can no longer be masked by a local import error. |
+| H12 | The maintained suite is green, dependencies no longer install a stale app revision, and CI covers four Python versions on three operating systems. |
+
+Final local verification used clean environments with current dependency
+resolution on Python 3.10, 3.11, 3.12, and 3.13. Each environment passed all
+307 tests. The runtime regressions include real synthetic FFmpeg extraction,
+nonzero partial output, overall timeout, cancellation, temporary-directory
+cleanup, image-only dependency checks, format discovery, and OS-specific
+guidance. The sdist and wheel build cleanly and advertise Python 3.10+ with the
+expected runtime dependencies and license metadata. A final dependency audit
+reported no known vulnerabilities in the resolved environment.
+
+## Baseline Verification
+
+- Wheel build succeeded.
+- A synthetic video completed end-to-end extraction with the expected frame
+  count.
+- Color-space tests passed, including real FFmpeg Display P3, BT.2020 SDR, and
+  HDR filter execution.
+- The full suite reported 220 passing and 71 failing tests.
+- No GitHub Actions workflow was configured.
+- Two Dependabot findings were open: a medium-severity pytest temporary
+  directory issue and a low-severity Pygments ReDoS issue.
+
+## Critical Findings
+
+### C1. Non-interactive saving bypasses overwrite protection
+
+When the Textual path uses `FrameSaver(show_progress=False)`, an existing
+output directory only produces a warning when `force_overwrite` is false. The
+save then proceeds and overwrites matching output names. This contradicts the
+UI choice and creates a direct data-loss risk.
+
+Required outcome: existing output files must remain untouched unless overwrite
+was explicitly authorized. Non-interactive conflicts must fail safely and
+report the conflicting paths.
+
+### C2. Image-directory output can have false extensions and collisions
+
+For directory inputs without resizing, the saver constructs a filename using
+the configured output format but copies the source bytes unchanged. A PNG can
+therefore be written as `image.jpg` while retaining PNG content. Files with the
+same stem but different extensions can map to the same destination and
+overwrite one another.
+
+Required outcome: byte copies preserve their real format, requested format
+changes perform an actual transcode, and every selected input gets a unique,
+deterministic destination.
+
+## High Findings
+
+### H1. Best-N is behaviorally different between CLI and TUI
+
+The Textual `FrameSelector` ranks by sharpness only; its advertised
+distribution weighting is absent. The direct CLI uses a separate segmented
+implementation. Users can receive materially different selections from the
+same frames and parameters depending on entry point.
+
+Required outcome: one canonical algorithm and identical results across CLI,
+TUI, preview, and tests. Sharpness and temporal distribution must be normalized
+to comparable scales before weighting.
+
+### H2. Best-N buffer semantics disagree with the preview
+
+The preview treats `min_buffer` as the number of intervening frames, while
+selection accepts an index distance equal to `min_buffer`. This creates count
+and guarantee mismatches.
+
+Required outcome: define `min_buffer` as intervening frames, require an index
+distance of at least `min_buffer + 1`, and calculate preview counts using the
+same implementation as execution.
+
+### H3. Outlier-removal endpoints contradict each other
+
+At sensitivity 100, the Textual implementation removes every frame, the CLI
+keeps every frame, and the preview estimates that roughly 60 percent remain.
+At sensitivity 0, execution keeps every frame while preview still removes a
+small percentage.
+
+Required outcome: consistent monotonic semantics, with 0 disabling removal and
+100 representing maximum useful aggressiveness without a hard-coded all/none
+special case.
+
+### H4. Outlier preview is not an actual preview
+
+The Textual preview uses a fixed sensitivity-to-removal-rate lookup and ignores
+the scores and window size. It can disagree with execution and show an
+incorrect save count and completion message.
+
+Required outcome: exact preview counts from the canonical selection algorithm.
+
+### H5. Video-directory selection crosses source boundaries
+
+All extracted frames are concatenated. Best-N spacing, batched groups, and
+outlier neighborhoods can cross from one source video to another. Global
+sharpness ranking can also starve videos with lower-resolution or lower-contrast
+content.
+
+Required outcome: group-aware selection. Batches, neighborhoods, and spacing
+reset at source boundaries; Best-N allocates a deterministic and fair quota
+across sources.
+
+### H6. FFmpeg extraction can silently accept incomplete output
+
+The modern extractor pipes stderr without continuously draining it, terminates
+after ten seconds without a newly observed file, may terminate when its frame
+estimate is reached, and accepts any extraction that produced at least ten
+files even if FFmpeg failed or was killed.
+
+Required outcome: continuously consume process output, support explicit
+cancellation and a real overall timeout, wait for a successful FFmpeg exit,
+and never infer success from an arbitrary minimum file count.
+
+### H7. Cancellation does not stop extraction and can leak temporary files
+
+`TUIProcessor.cancel_processing()` only signals sharpness analysis. Active
+FFmpeg extraction continues in a worker thread. Cleanup attempts before
+`current_result` is assigned do not know the temporary directory and therefore
+leak it on cancellation or intermediate errors.
+
+Required outcome: cancellation propagates to the extractor and process, every
+temporary directory has explicit ownership, and cleanup runs on all exit paths.
+
+### H8. Declared Python support is inaccurate
+
+Packaging advertises Python 3.7 and 3.8, while runtime code uses built-in
+generic annotations and executor APIs requiring Python 3.9 behavior.
+
+Required outcome: either restore compatibility or declare and test the real
+minimum. The implemented correction is Python 3.10+ with matching classifiers
+and CI. Python 3.9 is end-of-life, and the security-fixed pytest 9 line also
+requires Python 3.10+.
+
+### H9. Platform dependency checks and documentation disagree with reality
+
+The Textual validation path requires FFmpeg even for image-only input. Modern
+video processing requires FFprobe although metadata describes it as optional.
+HDR conversion requires an FFmpeg build with `zscale`/libzimg but this is not
+documented.
+
+Required outcome: dependency checks are input-type-specific, FFprobe and
+zscale requirements are accurately communicated, and errors include
+platform-appropriate remediation.
+
+### H10. Supported formats differ between entry points
+
+The README, validators, single-file processing, image extractor, and video
+directory scanner use different extension sets. Validated WebP or M4V inputs
+can later be ignored.
+
+Required outcome: shared format constants used by detection, validation,
+extraction, help, and documentation.
+
+### H11. FFprobe errors are masked
+
+`FrameExtractor._get_video_info()` imports `json` inside its try block and
+references it in an exception clause. Failures before that import can surface
+as `UnboundLocalError` instead of the real FFprobe error.
+
+Required outcome: preserve the original failure type and actionable stderr.
+
+### H12. Test and dependency baselines are not release-grade
+
+The suite had 71 failures, many encoding obsolete or contradictory selection
+semantics. `requirements.txt` mixes runtime, documentation, and test packages
+and includes an editable install pinned to an old application commit.
+`tests/requirements.txt` omits Pillow even though tests import it. With no CI,
+these failures cannot prevent regressions.
+
+Required outcome: one truthful green suite, separated dependency manifests,
+and CI across supported Python and operating-system versions.
+
+## Deferred Selection-Quality Roadmap
+
+The following quality improvements are important but are deferred until the
+Critical and High correctness and safety defects above are closed.
+
+### Q1. Normalize analysis resolution
+
+Laplacian variance is strongly resolution-dependent. The same synthetic edge
+scored approximately 2032 at 128 pixels and 508 at 512 pixels under the current
+half-size analysis. Normalize every analysis image to a defined scale before
+comparing focus scores, especially across image directories and source videos.
+
+### Q2. Reduce sensitivity to noise and compression
+
+Noise can score as high-frequency detail. In a focused probe, a blurred image
+scored about 66, while adding noise raised it to about 820. Add light denoising
+and evaluate a combined focus metric such as normalized Laplacian variance plus
+Tenengrad. Validate against a labeled sharp/blurred corpus.
+
+### Q3. Use natural and metadata-aware ordering
+
+Lexicographic ordering places `frame10` before `frame2` and is case-sensitive
+across platforms. Use natural sorting for numbered sequences and consider EXIF
+capture time where appropriate. Temporal methods must operate on the intended
+chronology.
+
+### Q4. Make outlier statistics robust
+
+The global min/max range is distorted by a single extreme noisy or corrupt
+frame. Prefer robust scale estimates such as median/MAD or percentile ranges,
+and consider scene boundaries so legitimate softer scenes are not compared to
+unrelated high-detail scenes.
+
+### Q5. Treat unreadable images explicitly
+
+The modern analyzer converts failed reads into score zero while keeping the
+frame eligible for later saving. Exclude failed inputs from selection, report
+them separately, and expose partial-success information in metadata and UI.
+
+### Q6. Define selection quality metrics
+
+Build a repeatable evaluation corpus covering motion blur, defocus, noise,
+compression, exposure changes, animation, scene cuts, mixed resolution, HDR,
+and multi-camera directories. Track precision/recall for rejected blurry
+frames, coverage uniformity, duplicate rate, and per-source representation.
+
+### Q7. Improve visualization and explainability
+
+The Textual chart only shows the first portion of long inputs. Downsample the
+whole timeline, show source boundaries, and explain why a frame was selected or
+rejected. This makes parameter tuning and regression review substantially more
+trustworthy.
+
+## Lower-Priority Engineering Improvements
+
+- Remove dead and duplicated legacy UI/preview implementations after migration.
+- Replace broad `except`/silent-pass blocks with typed errors and structured
+  logging.
+- Avoid import-time FFmpeg subprocess checks, especially for image-only use.
+- Use `opencv-python-headless` as an optional server/CLI installation extra.
+- Add deterministic metadata schemas and atomic metadata writes.
+- Add performance benchmarks for large frame sets and long videos.
+- Add linting, type checking, security scanning, and package smoke tests to CI.
+
+## Exit Criteria for This Remediation
+
+All Critical and High findings are closed only when:
+
+1. Each issue has a regression test that failed before the fix.
+2. CLI and TUI selection results agree for equivalent input and parameters.
+3. All save paths preserve data and honor conflict policy.
+4. Synthetic FFmpeg success, failure, timeout, and cancellation paths pass.
+5. Image-only processing succeeds without FFmpeg.
+6. Supported format and Python-version declarations match tested behavior.
+7. The complete maintained test suite is green.
+8. A final review finds no remaining Critical or High regression.