amverge CLI  /  Python library
          ↓
    amverge package
           ↓
    PyAV  +  FFmpeg  +  PyTorch (optional)  +  ONNX (optional)

Detection: Keyframe mode extracts I-frame timestamps via PyAV packet demux. Edge mode decodes frames and compares Canny edge maps. TransNetV2 runs a deep CNN on 48x27 RGB frames (GPU auto-detected, CPU fallback).

Cutting: Scenes aligned to keyframes get lossless stream copy. Non-aligned scenes get smartcut (encode head + copy tail) or full re-encode. HEVC on CPU uses snapped-copy (nearest keyframe within 5s) to avoid slow re-encode.

Upscaling: Three methods. ML mode runs ShuffleCUGAN U-Net via PyTorch/spandrel. Anime4K applies GLSL shaders via FFmpeg libplacebo (no ML deps). ArtCNN infers ONNX models via onnxruntime. All cache weights to %APPDATA%/amverge/.

Thumbnails: Decoded via PyAV, resized to 960px, saved as progressive JPEG in parallel. Similarity: Adjacent thumbnails compared via cosine similarity on 8x8 pooled pixels.

Interpolation: RIFE PyTorch inference (CUDA/CPU) with mod-32 padded frames, encoded feature caching, and FFmpeg rawvideo pipe. Flowframes 1.42.0 external process integration with session log tailing and output discovery. Support for free Flowframes 1.36.0 is planned (delivery TBD - differs from 1.42.0 Patreon version).

Depth Maps: Depth-Anything-V2 per-frame monocular depth estimation. Small (24.8M), Base (97.5M), or Large (335.3M) model. Color or grayscale output, side-by-side or depth-only. Models auto-downloaded from AniSmooth-Models GitHub Releases. H.264 output via FFmpeg pipe with source audio mux.

Deadframe Removal: Detects and removes frames where the main subject does not move (static/dead frames). Uses Farneback dense optical flow, ORB feature matching with RANSAC homography to distinguish subject motion from camera motion, and motion-area analysis to reject transient foreground passers. Output is CFR-compacted: kept frames packed back-to-back, duration shortens. Safe to feed into frame interpolation. Auto-calibration mode, keep-talking/keep-camera/safe flags, and cadence smoothing for native animation holds.

Pipeline: Chains deadframe removal, AI upscaling, and frame interpolation into a single run. Interactive arrow-key prompts or full-screen Textual TUI. Save configurations as named presets for reuse. Detects installed extras and only shows available operations. After each step, choose whether to chain the output into the next operation or revert to the original input.

AMVerge-CLI/
├── amverge/
│   ├── __init__.py              public exports: detect_scenes, DetectResult, Scene, DetectionMethod
│   ├── __version__.py           version string
│   ├── cli.py                   Typer app, registers commands, no-args -> wizard
│   ├── pipeline.py              high-level detect_scenes() API
│   ├── wizard.py                interactive session (no-args mode)
│   ├── ui.py                    shared Rich theme, console, banner, progress, table helpers
│   │
│   ├── commands/
│   │   ├── about/               about, credits, changelog, usage
│   │   ├── detection/           detect, bench, cache, scenes, keyframes
│   │   ├── export/              export, merge
│   │   ├── upscaling/           upscale, models
│   │   ├── interpolation/       interpolate, flowframes, flowframes-path
│   │   ├── depth/                depth-map
│   │   ├── deadframes/           deadframes
│   │   ├── pipeline/              pipeline
│   │   ├── info/                info, probe
│   │   ├── sidecar/             backend, rpc_server (hidden)
│   │   └── system/              doctor, gpu, version
│   │
│   └── core/                    pure logic, no CLI/Rich deps
│       ├── codec/               codec profiles, HEVC detection (codec_utils)
│       ├── cutting/             segmenter (V1), smart_cut (V2)
│       ├── detection/           keyframe, edge (V1), scene_detection, nelux_runtime (V2)
│       ├── discord/             Discord RPC integration
│       ├── image/               image cropping
│       ├── infra/               binaries, IPC, diagnostics
│       ├── keyframes/           keyframe extraction + alignment
│       ├── similarity/          cosine similarity pair detection
│       ├── thumbnails/          thumbnail generation + streaming
│       ├── transnet/            TransNetV2 constants
│       ├── upscaling/           ml, anime4k, artcnn, registry
│       ├── interpolation/       RIFE PyTorch inference, Flowframes 1.42.0 integration
│       ├── depth/                Depth-Anything-V2 monocular depth estimation
│       ├── deadframes/           deadframe removal via optical flow + ORB homography
│       ├── pipeline/              operation-chaining presets (JSON save/load)
│       ├── video/               probe_utils, scene_utils, video metadata
│       └── wrappers/            public class wrappers (AmvergeVideo, SceneDetector, etc.)
│
├── examples/                runnable Python scripts
│   ├── custom-pipeline/     full end-to-end pipeline
│   ├── cutting/             smart cut, ffmpeg segment
│   ├── depth/                  depth map examples
│   ├── detect/              keyframe, edge, TransNetV2 detection
│   ├── diagnostics/         GPU, CUDA, dependency versions
│   ├── discord-rpc/         Discord Rich Presence
│   ├── export/              copy, re-encode with profiles, merge
│   ├── info-probe/          stream metadata, diagnostics, HEVC check
│   ├── keyframes/           extraction + classification for cutting
│   ├── similarity/          adjacent scene similarity detection
│   └── thumbnails/          JPEG thumbnail generation
│
├── docs/                    markdown documentation
├── assets/                  GIF and image assets
├── pyproject.toml
├── README.md
└── AGENTS.md

Runnable Python scripts for every feature. Each with its own README:

pip install amverge[ml,edge,discord]
python examples/detect/01_basic_detect.py episode.mp4
python examples/custom-pipeline/full_pipeline.py episode.mp4

See the examples README for the full directory map.

An AGENTS.md file is included for AI coding assistants (OpenCode, Claude Code, Cursor, etc.).

Using AI without understanding the codebase is not recommended. Read the code, understand the architecture, then use the agents file if it saves you time.

The best approach is not to use a generic AI assistant - it is to train it to work like you. Teach it your conventions, your decisions, your style. Done right, the output looks like yours, not like a generic answer. See docs/ai-setup.md for a practical guide on how to do this.

Built by Moongetsu as a standalone port of the AMVerge backend.

AMVerge was created by Crptk. All core scene detection and clip management logic originates from the original AMVerge project.

AMVerge CLI is licensed under the GNU GPL v3.0.

Any derivative work must also be open-source under the same license.