amverge 0.1.0__tar.gz

amverge-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.spec
+*.npy
+*.jpg
+*.jpeg
+*.mp4
+*.mkv
+*.mov
+.env

amverge-0.1.0/AGENTS.md

@@ -0,0 +1,232 @@
+# AGENTS.md - AMVerge CLI
+
+AMVerge features as a CLI tool and Python library. Ports the AMVerge desktop app backend (by Crptk) into a standalone `pip install amverge` package.
+
+## AI Agent Instructions
+
+- **Update this file** when adding/removing files, changing architecture, adding new commands, or introducing conventions.
+- **Commit style:** prefix tag in parentheses: `(add)` new features, `(fix)` bug fixes, `(update)` refactors/formatting/chores. Example: `(fix) wizard: handle KeyboardInterrupt during path input`.
+- **Commit author:** always commit under the user's account. Do NOT add a `Co-Authored-By: Claude` trailer or any self-attribution.
+- **Commit per task:** separate commit after each task/logical change. Do not batch unrelated changes.
+- **No code comments:** do NOT add comments when writing or modifying code. Put any needed explanation in the commit message or this file.
+- **No em dashes:** never use `—` in any prose, docs, README, or commit messages. Use a comma, colon, parentheses, or plain hyphen `-` instead.
+- **Rich style= params:** theme names (`accent`, `muted`, etc.) only resolve inside markup strings `[accent]text[/]`. They do NOT work in `style=`, `header_style=`, or `title_style=` kwargs - use literal hex `#22c55e bold` there instead.
+
+## Build & Run
+
+```bash
+pip install -e .           # base install (keyframe detection only)
+pip install -e ".[edge]"   # + OpenCV for edge detection method
+pip install -e ".[ml]"     # + TransNetV2 ML detection (torch, GPU optional)
+```
+
+No build step. Pure Python package, `hatchling` backend.
+
+```bash
+amverge                    # interactive wizard (no-args mode)
+amverge detect video.mp4   # direct command
+amverge --help             # Typer help
+```
+
+To publish to PyPI (not done yet - verify `pypi.org/project/amverge` name is free first):
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+## Tech Stack
+
+| Layer | Tech |
+|---|---|
+| CLI | Typer |
+| UI | Rich (custom green theme) |
+| Video decode | PyAV (packet demux + keyframe timestamps) |
+| Video decode (ML) | Nelux (Windows native, optional) or FFmpeg pipe |
+| Video process | FFmpeg / FFprobe (subprocess) |
+| Scene detection | TransNetV2 via `transnetv2_pytorch` (optional, `[ml]` extra) |
+| Scene cutting | Smart cut: lossless copy + re-encode tail, or full re-encode (HEVC/fallback) |
+| Image | Pillow |
+| Numerics | NumPy |
+| GPU | PyTorch (CUDA auto-detected, CPU fallback) |
+| Edge detection | OpenCV (optional, `[edge]` extra) |
+| Package | hatchling, PyPI name `amverge` |
+| Discord RPC | pypresence (optional, `[discord]` extra) |
+
+## Directory Map
+
+```
+AMVerge-CLI/
+├── amverge/
+│   ├── __init__.py          public exports: detect_scenes, DetectResult, Scene, DetectionMethod
+│   ├── __version__.py       version string
+│   ├── cli.py               Typer app, registers all commands, no-args -> wizard
+│   ├── pipeline.py          high-level detect_scenes() public API
+│   ├── wizard.py            interactive session (no-args mode)
+│   ├── ui.py                shared Rich theme, console, banner, progress, table helpers
+│   │
+│   ├── commands/
+│   │   ├── backend.py       amverge backend <video> <output_dir>  (hidden - Rust sidecar replacement)
+│   │   ├── rpc_server.py    amverge rpc-server  (hidden - Discord RPC sidecar, reads JSON from stdin)
+│   │   ├── detect.py        amverge detect
+│   │   ├── export.py        amverge export  (CODEC_PROFILES/AUDIO_FFMPEG dicts - wizard imports these)
+│   │   ├── merge.py         amverge merge
+│   │   ├── info.py          amverge info  (stream metadata via PyAV)
+│   │   ├── probe.py         amverge probe  (V2 diagnostics: codec/HEVC/keyframes/scene cache)
+│   │   ├── gpu.py           amverge gpu  (PyTorch version, CUDA, GPU name/VRAM, all optional deps)
+│   │   ├── doctor.py        amverge doctor  (full health check: ffmpeg, deps, write access, pass/fail)
+│   │   ├── version.py       amverge version  (CLI + Python + all dep versions, --json for bug reports)
+│   │   ├── bench.py         amverge bench  (keyframe scan + TransNetV2 decode/inference timing)
+│   │   ├── cache.py         amverge cache  (list/clear TransNetV2 .npy scene caches)
+│   │   ├── keyframes.py     amverge keyframes  (dump keyframe timestamps, --json, --count)
+│   │   ├── scenes.py        amverge scenes  (show scene list from .npy cache, --json, --min-duration)
+│   │   ├── usage.py         amverge usage  (CLI reference page)
+│   │   ├── about.py         amverge about
+│   │   ├── credits.py       amverge credits  (exports _credits_table() for wizard reuse)
+│   │   └── changelog.py     amverge changelog
+│   │
+│   └── core/                pure logic - no Rich/Typer deps, safe as library
+│       ├── binaries.py              get_binary(), get_ffmpeg(), get_ffprobe() - PyInstaller-aware PATH search
+│       ├── ipc.py                   emit_progress(), emit_event(), log(), check_if_path_exists(), build_video_cache_prefix()
+│       ├── probe_utils.py           probe_video_fps/duration/dimensions/total_frames via ffprobe
+│       ├── scene_utils.py           scenes_to_objects(), scenes_frames_to_seconds()
+│       ├── diagnostics.py            get_gpu_info(), get_versions() - clean wrappers
+│       ├── codec_utils.py           check_if_hevc(), CODEC_PROFILES, AUDIO_FFMPEG, CODEC_ALIASES, PRORES_CODECS, resolve_gpu()
+│       ├── keyframe_align.py        get_keyframe_timestamps_pyav(), classify_scenes_by_keyframe_alignment()
+│       ├── smart_cut.py             cut_scene(), cut_all_scenes() - lossless copy / smartcut / reencode
+│       ├── nelux_runtime.py         _get_nelux_video_reader() - Windows DLL config for Nelux
+│       ├── scene_detection.py       decode_video_frames_nelux(), decode_and_detect_scenes(), run_model_one_pass()
+│       ├── transnet_constants.py    FRAME_WIDTH/HEIGHT/CHANNELS/BYTES, WINDOW_SIZE, STRIDE
+│       ├── keyframes.py             generate_keyframes() - PyAV packet demux (V1 detect command)
+│       ├── video.py                 get_video_duration(), get_video_info(), merge_short_scenes()
+│       ├── segmenter.py             run_ffmpeg_segment() - 1500-cut Windows chunking (V1)
+│       ├── thumbnails.py            make_thumbnail(), generate_thumbnails() - ThreadPoolExecutor
+│       ├── similarity.py            find_similar_pairs() - cosine similarity on pixel arrays
+│       ├── hevc.py                  is_hevc() - ffprobe codec check (V1)
+│       ├── image.py                 crop_image() + CropData - supports animated GIF
+│       ├── thumbnails_streaming.py  streaming thumbnail gen with IPC events (V1 backend mode)
+│       ├── discord_rpc.py           DiscordRPC class - pypresence wrapper, CLIENT_ID from AMVerge
+│       └── detection/
+│           ├── keyframe.py  detect_cuts_by_keyframe() (V1)
+│           └── edge.py      detect_cuts_by_edge() - guarded cv2 import (V1)
+│
+├── docs/
+│   ├── installation.md
+│   ├── cli-reference.md
+│   ├── library.md
+│   ├── detection-methods.md
+│   └── contributing.md
+│
+├── assets/
+│   └── amverge_title_gif.gif
+│
+├── pyproject.toml
+├── README.md
+└── AGENTS.md
+```
+
+## Key Architecture
+
+### No-args wizard routing
+
+`cli.py` uses `@app.callback(invoke_without_command=True)`. When `ctx.invoked_subcommand is None`, calls `run_wizard()` from `wizard.py`. All wizard output goes to `stderr` so stdout stays clean for piping.
+
+### V2 backend pipeline (TransNetV2)
+
+```
+decode_video_frames_nelux() or decode_and_detect_scenes()
+        ↓ (frames ndarray)
+run_model_one_pass() (TransNetV2, GPU/CPU)
+        ↓ (scenes_secs, scenes_frames ndarray - cached as .npy)
+scenes_to_objects()
+        ↓ emit INITIAL_CLIPS_READY|[json]
+get_keyframe_timestamps_pyav() + check_if_hevc()
+        ↓
+classify_scenes_by_keyframe_alignment()
+        ↓
+Phase 1: cut_all_scenes() lossless copy (max_workers=8)  -> emit CLIP_READY per scene
+        ↓ emit PHASE1_COMPLETE
+Phase 2: cut_all_scenes() re-encode (max_workers=2)      -> emit REENCODE_PROGRESS + CLIP_READY
+```
+
+### V1 detection pipeline (keyframe, no ML)
+
+```
+generate_keyframes() (PyAV packet demux)
+        ↓
+merge_short_scenes() (drop cuts < min_duration)
+        ↓
+run_ffmpeg_segment() (ffmpeg -segment_times, stream copy)
+        ↓
+generate_thumbnails() (PyAV decode, ThreadPoolExecutor)
+        ↓
+find_similar_pairs() (cosine similarity on pixel arrays)
+```
+
+### Library API
+
+```python
+from amverge import detect_scenes
+
+result = detect_scenes("episode.mp4")
+for scene in result.scenes:
+    print(scene.index, scene.start, scene.end, scene.path)
+```
+
+`core/` has no CLI dependencies. Import anything from it without pulling in Rich or Typer.
+
+## Code Conventions
+
+- **Python:** snake_case vars/fns, PascalCase dataclasses, type hints on all public APIs
+- **CLI commands:** one file per command in `commands/`, registered in `cli.py`, added to wizard in `wizard.py`
+- **Library modules:** all in `core/`, no Rich/Typer imports allowed
+- **UI:** all Rich output through `ui.py` helpers (`console`, `err`, `banner()`, `make_table()`)
+- **Subprocess:** all ffmpeg/ffprobe calls include `creationflags=0x08000000` on win32 (suppress console popups)
+
+## Critical Paths
+
+| File | Role |
+|---|---|
+| `core/segmenter.py` | Windows 32,767-char command line limit. If video has >1500 cut points, chunks into multiple ffmpeg passes. Do not remove this chunking. |
+| `core/keyframes.py` | Fast path reads packet metadata only (no frame decode). Falls back to full decode for pathological encodes. Deduplicates I-frames within short windows. |
+| `core/detection/edge.py` | `import cv2` is inside the function body, not at module level. Raises clear `ImportError` pointing to `pip install amverge[edge]` if OpenCV missing. Keep it this way - edge is an optional dep. |
+| `wizard.py` | `_credits_table()` is imported from `commands/credits.py` to avoid duplication. `_wizard_export()` imports `CODEC_PROFILES`, `AUDIO_FFMPEG`, `CODEC_ALIASES`, `PRORES_CODECS`, `resolve_gpu` from `core/codec_utils.py` - single source of truth for codec mappings. |
+| `ui.py` | `err` console (stderr) used for all interactive/wizard output. `console` (stdout) for command results. Do not mix them. `ok()`/`warn()`/`fail()` use ASCII-safe marker `>` - Python `●`/`→` crash on CP1252 Windows terminals. |
+| `core/similarity.py` | `find_similar_pairs()` accepts both `scene_index` and `index` keys for V1 (collect_scenes) / V2 (Scene.to_dict()) compat. |
+| `commands/export.py` | `CODEC_PROFILES`/`AUDIO_FFMPEG`/`CODEC_ALIASES`/`PRORES_CODECS`/`_resolve_gpu` imported from `core/codec_utils.py`. |
+| `pipeline.py` | `DetectionMethod` is `Literal["keyframe", "edge", "transnetv2"]`. TransNetV2 path uses `decode_and_detect_scenes()` + `cut_all_scenes()` (V2 pipeline). Monkey-patches `emit_progress` on `scene_detection`/`smart_cut` module-local refs (not `ipc` module) to route IPC progress to Rich callback. |
+| `core/ipc.py` | IPC protocol for Tauri app. V2 events: `PROGRESS\|pct\|msg`, `INITIAL_CLIPS_READY\|json`, `CLIP_READY\|idx\|path\|mode`, `PHASE1_COMPLETE`, `REENCODE_PROGRESS\|done\|total`. stdout reserved for final JSON. Never mix IPC output with Rich output. |
+| `core/scene_detection.py` | TransNetV2 inference. Requires `[ml]` extra. `TRANSNET_AVAILABLE` flag guards import at module level - raises clear `ImportError` if missing. Do not import torch at module level in other files. |
+| `core/smart_cut.py` | Four cut modes: `copy` (start on keyframe), `snapped_copy` (HEVC CPU - snaps to nearest keyframe within 5s), `smartcut` (H.264 - encode tiny head + lossless tail), `reencode` (full fallback). Never remove the HEVC CPU path - HEVC re-encode without CUDA takes 10+ minutes. |
+| `core/codec_utils.py` | `check_if_hevc()` via ffprobe. Also contains `CODEC_PROFILES` (14 codec -> ffmpeg encoder mappings), `AUDIO_FFMPEG` (10 audio choices), `CODEC_ALIASES`, `PRORES_CODECS`, `resolve_gpu()`. Single source of truth - `commands/export.py` and `wizard.py` import from here. Do not duplicate these dicts. |
+| `core/nelux_runtime.py` | Windows DLL setup for Nelux video reader. Set `AMVERGE_FFMPEG_BIN` env var to FFmpeg shared DLL directory. Idempotent - safe to call multiple times. |
+| `core/keyframe_align.py` | `get_keyframe_timestamps_pyav` uses PyAV demux with `type(stream.discard).nonkey` enum (PyAV 17.x; was `"NONKEY"` string in older PyAV). `classify_scenes_by_keyframe_alignment` partitions scenes for Phase 1 vs Phase 2 cutting. |
+| `core/thumbnails_streaming.py` | V1 backend mode only. Emits events as each thumbnail completes. Not used in V2 backend. |
+| `core/discord_rpc.py` | Uses same CLIENT_ID as AMVerge app (`1497922104065134823`). Silently no-ops if pypresence not installed. `--no-rpc` flag on detect/export/merge to disable. Methods: idle/detecting/selecting/navigating/exporting/merging/complete/error. |
+| `commands/rpc_server.py` | Hidden sidecar: `amverge rpc-server`. Long-lived process; Rust spawns it once and sends JSON commands via stdin (`{"type":"update","details":"...","state":"..."}`, `{"type":"clear"}`, `{"type":"shutdown"}`). Throttles Discord updates to max 1 per 15s. Exits when stdin closes or parent dies. |
+| `commands/backend.py` | V2 backend. Positional interface: `amverge backend <video_path> <output_dir> [import_method]`. Rust replaces `python app.py <video> <dir>` with `amverge backend <video> <dir>` - no Rust changes needed. Emits V2 IPC events. Outputs JSON schema v1.0 with `schema_version`, `run_id`, `video` metadata block. |
+
+## Theme
+
+```python
+THEME = Theme({
+    "accent":        "#22c55e",
+    "accent.bright": "#00f07a",
+    "muted":         "bright_black",
+    "success":       "#22c55e bold",
+    "warn":          "#facc15",
+    "error":         "#ef4444",
+    "label":         "white",
+    "bar.back":      "bright_black",
+    "bar.complete":  "#22c55e",
+    "bar.finished":  "#00f07a",
+}, inherit=False)
+```
+
+Banner markup: `[accent]AMV[/][white bold]erge[/]` - AMV is green, erge is white. Match this everywhere.
+
+## Origin
+
+All core logic ported from `AMVergeNew/backend/` (Crptk's original AMVerge desktop app).
+Color palette from `AMVergeNew/frontend/src/styles/variables.css`.

amverge-0.1.0/LICENSE

@@ -0,0 +1,35 @@
+AMVerge CLI
+Copyright (C) 2026 Moongetsu
+
+Based on AMVerge by Crptk <https://github.com/crptk/AMVerge>
+Original AMVerge Copyright (C) 2026 Crptk
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  For the precise terms and conditions for copying, distribution and
+modification, see <https://www.gnu.org/licenses/gpl-3.0.txt>.

amverge-0.1.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: amverge
+Version: 0.1.0
+Summary: AMVerge Features as a CLI Tool and Python Library
+Project-URL: repository, https://github.com/moongetsu/AMVerge-CLI
+Author-email: Moongetsu <moongetsu@proton.me>
+License: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: amverge,anime,clip-management,ffmpeg,keyframe,scene-detection,transnetv2,video,video-editing
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: av>=12
+Requires-Dist: numpy>=1.26
+Requires-Dist: pillow>=10
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pyinstaller>=6; extra == 'dev'
+Provides-Extra: discord
+Requires-Dist: pypresence>=4.3; extra == 'discord'
+Provides-Extra: edge
+Requires-Dist: opencv-python-headless>=4.9; extra == 'edge'
+Provides-Extra: ml
+Requires-Dist: torch>=2.0; extra == 'ml'
+Requires-Dist: tqdm>=4.0; extra == 'ml'
+Requires-Dist: transnetv2-pytorch; extra == 'ml'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/amverge_title_gif.gif" alt="AMVerge CLI" width="1440"/>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.11+-blue?style=flat-square" alt="Python"/>
+  <img src="https://img.shields.io/badge/pypi-amverge-22c55e?style=flat-square" alt="PyPI"/>
+  <img src="https://img.shields.io/badge/license-GPL--3.0-22c55e?style=flat-square" alt="License"/>
+</p>
+
+# AMVerge CLI
+
+**AMVerge Features as a CLI Tool and Python Library.**
+Port of the AMVerge desktop app backend by [Crptk](https://github.com/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
+
+```bash
+pip install amverge
+```
+
+See [docs/installation.md](docs/installation.md) for FFmpeg setup, optional dependencies, and dev install.
+
+---
+
+## Quick Start
+
+```bash
+# 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
+```
+
+```python
+from amverge import detect_scenes
+
+result = detect_scenes("episode.mp4")
+for scene in result.scenes:
+    print(scene.index, scene.start, scene.end, scene.path)
+```
+
+---
+
+<details open>
+<summary><b>How It Works</b></summary>
+
+```txt
+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.
+
+</details>
+
+---
+
+<details>
+<summary><b>Repository Structure</b></summary>
+
+```txt
+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
+```
+
+</details>
+
+---
+
+<details>
+<summary><b>Examples</b></summary>
+
+Runnable Python scripts for every feature. Each with its own README:
+
+| Directory | Description |
+|---|---|
+| [detect/](examples/detect/) | keyframe, edge, TransNetV2 detection |
+| [export/](examples/export/) | copy, re-encode with profiles, merge |
+| [info-probe/](examples/info-probe/) | stream metadata, probe diagnostics, HEVC check |
+| [keyframes/](examples/keyframes/) | extract timestamps, classify for cutting |
+| [cutting/](examples/cutting/) | smart cut, ffmpeg segment, single scene |
+| [thumbnails/](examples/thumbnails/) | JPEG thumbnail generation |
+| [similarity/](examples/similarity/) | adjacent scene similarity detection |
+| [diagnostics/](examples/diagnostics/) | GPU, CUDA, dependency versions |
+| [discord-rpc/](examples/discord-rpc/) | Discord Rich Presence |
+| [custom-pipeline/](examples/custom-pipeline/) | full end-to-end custom pipeline |
+
+```bash
+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](examples/README.md) for the full directory map.
+
+</details>
+
+---
+
+<details>
+<summary><b>Documentation</b></summary>
+
+| | |
+|---|---|
+| [Installation](docs/installation.md) | Requirements, FFmpeg setup, optional deps, dev install |
+| [CLI Reference](docs/cli-reference.md) | All commands, flags, and usage examples |
+| [Python Library](docs/library.md) | API reference, return types, low-level modules |
+| [Detection Methods](docs/detection-methods.md) | Keyframe vs edge vs TransNetV2, cut modes, tuning |
+| [Examples](examples/) | 20 runnable Python scripts in 10 categories |
+| [Contributing](docs/contributing.md) | Project structure, guidelines, links |
+| [AI Setup](docs/ai-setup.md) | How to train AI tools to work like you, not generically |
+
+</details>
+
+---
+
+<details>
+<summary><b>AI Agents</b></summary>
+
+An [AGENTS.md](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](docs/ai-setup.md) for a practical guide on how to do this.
+
+</details>
+
+---
+
+<details>
+<summary><b>Credits</b></summary>
+
+Built by [Moongetsu](https://github.com/Moongetsu) as a standalone port of the [AMVerge](https://github.com/crptk/AMVerge) backend.
+
+AMVerge was created by [Crptk](https://github.com/crptk). All core scene detection and clip management logic originates from the original AMVerge project.
+
+</details>
+
+---
+
+<details>
+<summary><b>License</b></summary>
+
+AMVerge CLI is licensed under the GNU GPL v3.0.
+
+Any derivative work must also be open-source under the same license.
+
+</details>