amverge 0.1.0

AMVerge Features as a CLI Tool and Python Library

AMVerge CLI

AMVerge Features as a CLI Tool and Python Library. Port of the AMVerge desktop app backend by Crptk. Split videos into scenes, export clips, merge fragments, and build your own tools on top of it.

---

Features

• TransNetV2 ML detection - deep learning scene boundary detection (GPU/CPU)
• Keyframe detection - fast I-frame based splitting, no re-encode
• Edge detection - Canny edges + cosine similarity for difficult encodes
• Smart cut - automatic lossless copy / smartcut / re-encode per scene
• 15 codec profiles - H.264, HEVC, AV1, ProRes with hardware (NVENC) support
• 10 audio codecs - AAC, FLAC, Opus, PCM, MP3, pass-through
• 3 container formats - MP4, MKV, MOV (ProRes auto-enforces MOV)
• Auto-generated scene thumbnails (progressive JPEG)
• Duplicate / similar scene detection (cosine similarity)
• Scene export with full codec + audio + hardware selection
• Clip merging via FFmpeg concat
• Video metadata inspection and diagnostics
• TransNetV2 scene cache (.npy) - skip re-detection on re-open
• Discord Rich Presence (same app ID as AMVerge desktop)
• Interactive wizard mode (amverge with no args)
• Fully usable as a Python library - 52 names from import amverge

---

Install

pip install amverge

See docs/installation.md for FFmpeg setup, optional dependencies, and dev install.

---

Quick Start

# Interactive wizard
amverge

# Direct commands
amverge detect episode.mp4
amverge export episode.mp4 --scenes episode_scenes/scenes.json --select 0,2,5-8
amverge merge clip1.mp4 clip2.mp4 --output out.mp4
amverge info episode.mp4

from amverge import detect_scenes

result = detect_scenes("episode.mp4")
for scene in result.scenes:
    print(scene.index, scene.start, scene.end, scene.path)

---

How It Works

amverge CLI  /  Python library
          ↓
   amverge package
          ↓
    PyAV  +  FFmpeg  +  PyTorch (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.

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

---

Repository Structure

AMVerge-CLI/
│
├── amverge/
│   ├── cli.py                  entry point
│   ├── pipeline.py             high-level detect_scenes() API
│   ├── wizard.py               interactive session
│   ├── ui.py                   shared Rich theme + components
│   ├── commands/               one file per CLI subcommand
│   └── core/                   pure logic, no CLI dependencies
│
├── examples/
│   ├── detect/          scene detection scripts
│   ├── export/          export + re-encode scripts
│   ├── info-probe/      metadata + diagnostics
│   ├── keyframes/       extraction + alignment
│   ├── cutting/         smart cut + segment
│   ├── thumbnails/      JPEG generation
│   ├── similarity/      pair detection
│   ├── diagnostics/     GPU + versions
│   ├── discord-rpc/     Rich Presence
│   └── custom-pipeline/ full end-to-end
│
├── docs/
├── assets/
├── pyproject.toml
└── README.md

---

Examples

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

Directory	Description
detect/	keyframe, edge, TransNetV2 detection
export/	copy, re-encode with profiles, merge
info-probe/	stream metadata, probe diagnostics, HEVC check
keyframes/	extract timestamps, classify for cutting
cutting/	smart cut, ffmpeg segment, single scene
thumbnails/	JPEG thumbnail generation
similarity/	adjacent scene similarity detection
diagnostics/	GPU, CUDA, dependency versions
discord-rpc/	Discord Rich Presence
custom-pipeline/	full end-to-end custom pipeline

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.

---

Documentation

Installation	Requirements, FFmpeg setup, optional deps, dev install
CLI Reference	All commands, flags, and usage examples
Python Library	API reference, return types, low-level modules
Detection Methods	Keyframe vs edge vs TransNetV2, cut modes, tuning
Examples	20 runnable Python scripts in 10 categories
Contributing	Project structure, guidelines, links
AI Setup	How to train AI tools to work like you, not generically

---

AI Agents

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.

---

Credits

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.

---

License

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

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