DEV Community: Harry Xu

Building a local video search CLI with ffmpeg and OpenCLIP

Harry Xu — Tue, 25 Aug 2026 12:45:27 +0000

I often remember the shot I want before I remember its filename.

That gap is what binquery is for. It is a local Python CLI that indexes video clips and turns a sentence into a ranked shortlist for a human to review. It deliberately stops before editing: no timeline generation, no automatic cut, and no render.

The smallest reproducible trial

You can test the complete installed command path without supplying footage:

python3 -m venv .venv
.venv/bin/pip install binquery
.venv/bin/binquery demo --out /tmp/binquery-demo

The demo generates a synthetic 30-second video locally, then exercises splitting, indexing, validation, and querying. The first run may download OpenCLIP model weights.

This is an end-to-end pipeline smoke test, not evidence of semantic search quality on real footage.

Why keep the architecture small?

The current design uses:

ffmpeg to sample three frames from each clip
OpenCLIP ViT-B-32 to build the local visual index
plain JSON and NumPy files for metadata and vectors
a JSON result containing clip paths, scores, and ranking signals

There is no database, vector service, or daemon to operate. Querying an existing index does not resample the footage or rebuild the full index.

The trade-off is straightforward: three frames keep indexing understandable and bounded, but they can miss important content in long or visually varied clips. I would rather expose that limitation than market a synthetic demo as a quality benchmark.

Ranking signals are not explanations

The output includes fields such as score, gate, and reasons. Here, reasons means ranking signals recorded by the pipeline. It should not be interpreted as a reliable semantic explanation of why a clip is correct.

That distinction matters because a plausible-looking explanation can create more confidence than the underlying retrieval quality deserves. The shortlist is meant to reduce what a person must inspect, not replace editorial judgment.

What binquery does not do

It does not build a timeline or export a finished edit.
It does not claim that the synthetic demo measures retrieval quality.
It does not turn every indexed metadata field into a user-facing search filter.
It does not hide the first-run model download.

What I want feedback on

I would especially value criticism of:

the three-frame sampling strategy,
the CLI and JSON output contracts,
packaging and first-run installation failures, and
useful ways to evaluate ranking quality without committing private footage to the repository.

The project is MIT licensed and available on GitHub. Version 0.3.0 is also on PyPI with a corresponding GitHub Release.

AI assistance disclosure: AI tools assisted parts of development, review, and preparation of this article. I personally checked the repository changes, tests, release artifacts, published package, and the factual claims above. Remaining limitations and unverified behavior are documented rather than presented as measured results.

session-close: write the handoff, fail if the card is empty

Harry Xu — Wed, 19 Aug 2026 07:50:23 +0000

A coding session ends. The next one starts from zero.

session-close is a local Python CLI. You fill a close card. It checks the fields, then writes SESSION_LOG.md (prepend one entry) and NEXT.md (open items + exactly three opening lines). Empty skeleton fails: doctor exit 2, no files written. status is read-only git. It does not commit.

It is not a model. It is not Superpowers or GSD. It is not on PyPI. Clone, then:

python3 -m venv .venv
.venv/bin/pip install -e .
./session-close doctor --in examples/ok.json
./session-close emit --in examples/ok.json --root .

Skill install is instructions only. It does not install the Python package:

npx -y skills add jennifferweslowski-design/session-close

Repo: https://github.com/jennifferweslowski-design/session-close

binquery: scene-sequence and rushes intents (local shortlist, not Premiere)

Harry Xu — Wed, 19 Aug 2026 05:15:46 +0000

Two public editor asks map onto a local shortlist CLI. That is a mapping, not a claim we ran their bins.

You have a pile of separately-cut scenes and you lose the original order when they hit a Premiere master. One r/VideoEditing thread is about pasting a lot of scenes into a master. binquery does not paste into Premiere, restore NLE markers, or read original sequence from the files. It takes one visual-intent sentence per scene and returns 8–15 clips (path, score, gate, reasons). You keep the query order as your sequence memory. People still watch.

Trailer work often starts from rushes / dailies, not a locked master. One r/editors thread asks whether trailer editors work from raw rushes. Index your own folder, then one trailer-intent sentence → the same shortlist. It is not an auto-cut trailer.

These are unmatched pictorial queries. Unknown sentences still run. You do not have to edit src/intents.py. We have not run this against a real ~500-clip bin. CI only builds 3 lavfi clips and runs index → doctor. A real demo needs your own folder.

export BINQUERY_INDEX=./my-box
./binquery index --input ./my-videos --index "$BINQUERY_INDEX"
./binquery doctor --index "$BINQUERY_INDEX"
# scene-sequence: one sentence per scene, keep this order yourself
./binquery query --index "$BINQUERY_INDEX" "scene 2 empty hallway lock-off"
# rushes / trailer intent: one sentence against your own rushes box
./binquery query --index "$BINQUERY_INDEX" "cold open wide empty night"

Skill install is instructions only. It does not install the Python package:

npx -y skills add jennifferweslowski-design/binquery

Repo: https://github.com/jennifferweslowski-design/binquery

binquery: a local CLI shortlist, now also an agent skill

Harry Xu — Wed, 19 Aug 2026 04:53:30 +0000

I cut from a local footage box. I wanted 8–15 candidates from one sentence, not a full-library skim and not an auto-edit.

binquery is a local Python CLI. You index your own folder with ffmpeg + OpenCLIP. query encodes only the sentence and prints a shortlist: path, score, gate, reasons. Limit is 8–15. People still watch.

It is not a browser. It is not on PyPI. Clone, then:

python3 -m venv .venv
.venv/bin/pip install -e .

Needs ffmpeg / ffprobe on the machine.

Agents can install the instructions as a skill (this does not install the Python package):

npx -y skills add jennifferweslowski-design/binquery

Or copy skills/binquery/ into .agents/skills/binquery or .claude/skills/binquery.

Repo: https://github.com/jennifferweslowski-design/binquery