Skip to main content

Amon Hen

"From the Seat of Seeing, no moment remains hidden."

A fast, lightweight CLI and Python library for natural language video moment retrieval on local CPU. Runs entirely on CPU without discrete GPUs, background daemons, or cloud dependencies.

PyPI Python 3.11+ License: MIT


Key Highlights

  • 100% CPU Execution: Powered by Apple's MobileCLIP2 architecture, Whisper-Tiny ONNX, and ONNX Runtime.
  • Hybrid Visual & Speech Retrieval: Simultaneously retrieves moments based on visual semantics and spoken dialogue.
  • Low Footprint: Hybrid FP32-vision + INT8-quantized text pipeline (approx. 105 MB RAM).
  • Zero Infrastructure: Embedded vector database and full-text index via SQLite, sqlite-vec, and FTS5 (single .db file).
  • High Throughput: 3-gate adaptive motion sampler achieving 4.8x to 18.5x realtime indexing speed.
  • Temporal Grouping: Merges consecutive matching frames into start-end timestamp intervals.

Installation

# Recommended via uv
uv tool install amon-hen

# Or via pipx
pipx install amon-hen

# Or standard pip
pip install amon-hen

Quickstart

1. Interactive Terminal UI

Run amon-hen without arguments to launch the interactive prompt:

amon-hen

Supports instant search queries, history navigation (↑/↓), /open <n> to play matches in your default player, and /cut <n> [output] to export clips.

2. Index Videos

# Index a video or entire folder with adaptive motion sampling
amon-hen index /path/to/videos/ --sampler adaptive

3. Search Moments

# Search visual actions or spoken dialogue (Battle of Amon Hen)
amon-hen search "swords fight warriors in forest"

# Search real-world surveillance events (CCTV footage)
amon-hen search "a person holding an umbrella"

4. Extract Video Clip

# Extract matching segment into a standalone video clip
amon-hen cut battle-of-amon-hen.webm --start 00:03:56 --end 00:04:52 -o battle_climax.mp4

Python API

from amonhen.encode import TextEncoder
from amonhen.model_registry import get_model
from amonhen.pipeline import search
from amonhen.store import Store

# 1. Connect to index
store = Store("index.db", embed_dim=512)

# 2. Load CPU-optimized text encoder
spec = get_model("mobileclip2-s0")
text_encoder = TextEncoder(spec)

# 3. Retrieve matching video segments
results = search("red sports car turning", store=store, text_encoder=text_encoder)
for seg in results:
    print(
        f"{seg.video_path}: {seg.start_ms / 1000.0:.1f}s - {seg.end_ms / 1000.0:.1f}s (score: {seg.score:.3f})"
    )

store.close()

Capabilities & Known Limitations

  • Visual Semantic Search (MobileCLIP2): Strong zero-shot recognition for objects, actions, settings, spatial arrangements, and characters. Adding descriptive context (e.g. "Aragorn with sword" vs "Aragorn") maximizes cosine similarity and avoids domain noise.
  • Speech-to-Text (Whisper-Tiny ONNX): Indexes clean spoken dialogue across speeches, podcasts, lectures, and vlogs. It is not an acoustic sound-effects classifier. Low-confidence dialogue on heavy orchestral soundtracks is automatically filtered to prevent hallucinations.
  • Lossless Stream Cut: Sub-second extraction aligns to nearest container keyframes; use --reencode for exact frame-level cuts.

Metadata

Release files for amon-hen 0.1.21

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for amon-hen 0.1.21
File Size Uploaded Provenance Actions
amon_hen-0.1.21.tar.gz 27.2 MB With provenance Details for amon_hen-0.1.21.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amon-hen 0.1.21
File Interpreter ABI Platform Actions
amon_hen-0.1.21-py3-none-any.whl Python 3 none any Details for amon_hen-0.1.21-py3-none-any.whl

Total release size: 27.3 MB

Release files / amon_hen-0.1.21.tar.gz

Download URL amon_hen-0.1.21.tar.gz
Size 27.2 MB
Tags Source
SHA-256 checksum
How to use checksums
a135eef8b9c6b4ab919b8859c8268e12565b7a038185ec4db086fbb7be9e17d9
BLAKE2b-256 checksum
How to use checksums
25033ebbbb27506e010ab027723f850e5ef8d2283da6cf542bf517a5c86ede7a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 2, 2026.

Transparency log

Release files / amon_hen-0.1.21-py3-none-any.whl

Download URL amon_hen-0.1.21-py3-none-any.whl
Size 41.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a6458974be37d277a0923427a2143386573a4ad2bd9d1f9544cdae150d6dc3a8
BLAKE2b-256 checksum
How to use checksums
3a26879119266174dc83ffc20fb3e89a919a9566d3a9c29f481de952f1482777
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 2, 2026.

Transparency log

Security for amon-hen 0.1.21

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for amon_hen-0.1.21.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page