query-video 0.1.1

Agent-native YouTube/video tool — index, search, inspect frames for coding tutorials (import qv, CLI qv)

qv

Quick video / query video — a minimal agent tool for coding tutorials. Three MCP tools (index, search, inspect_frame), one CLI (qv), one Python package.

Agents navigate screencasts by searching speech, then pulling precise frames for vision — without transcript dumps or 40-tool menus.

PyPI: install as query-video (qv is blocked as a PyPI project name). The Python import and CLI remain qv.

Install

uv tool install 'query-video[stt]'
# or
pip install 'query-video[stt]'

Provides the qv command. Optional extras: [mcp], [stt], [all].

System deps: ffmpeg on PATH. yt-dlp is bundled via pip. Indexing requires the [stt] extra (faster-whisper).

Development setup

Prerequisites: Python 3.12+, uv, ffmpeg and ffprobe on PATH.

git clone https://github.com/jkvc/qv.git
cd qv
uv sync --group dev
uv sync --extra stt
git config core.hooksPath .githooks   # optional; runs lint/format/unit tests on push

Run from the repo (editable install via uv sync):

uv run qv --help
uv run pytest
uv run pytest -m integration
uv run ruff check . && uv run ruff format --check .

GPU Whisper (optional): default device=auto uses CUDA when a GPU is visible. ctranslate2 4.x needs CUDA 12 user-space libs (e.g. on Ubuntu/Pop: sudo apt install libcublas12 libcudart12). If GPU libs are missing, indexing fails — set QV_DEVICE=cpu or device="cpu" in code. See notes/20260614-v0-config-and-tooling.md.

Lib usage:

from qv.lib.api import index_video, search_video, inspect_frame

CLI

qv index URL --json
qv search VIDEO_ID "useState setup" --json
qv inspect-frame VIDEO_ID --at 754 --json
qv mcp   # stdio MCP server (requires [mcp] extra)

CLI commands are stubs; use qv.lib.api directly until wired.

MCP (Cursor, Claude Code, etc.)

{
  "mcpServers": {
    "qv": {
      "command": "uvx",
      "args": ["--from", "query-video[mcp]", "qv", "mcp"],
      "env": {
        "QV_CACHE": "~/.cache/qv",
        "QV_DEVICE": "cpu"
      }
    }
  }
}

Layout

PyPI package	query-video
Python import	qv (src/qv/)
CLI	qv only
Lib API	from qv.lib.api import index_video, search_video, inspect_frame
GitHub repo	jkvc/qv

Cache default: ~/.cache/qv (override with QV_CACHE).

Configuration

Precedence: call-site args → env → ~/.config/qv/config.toml → defaults.

Setting	Default	Env	Config key
STT model	whisper_base	QV_MODEL_NAME (legacy: QV_WHISPER_MODEL = bare size)	model_name
Device	auto	QV_DEVICE	device
Frame quality	p720	QV_FRAME_QUALITY	frame_quality
Frame window (s)	15	QV_FRAME_WINDOW	frame_window_s
Cache dir	~/.cache/qv	QV_CACHE	cache_dir

model_name is backend-qualified: whisper_base, whisper_small, soniox, etc. device (auto / cpu / cuda) applies to whisper only.

Example ~/.config/qv/config.toml:

model_name = "whisper_base"
device = "auto"

Override config file path with QV_CONFIG. Interactive qv configure is planned.

Publishing (PyPI)

Single PyPI project query-video ships the qv Python package and qv CLI entrypoint. The name qv is prohibited on PyPI.

Version bump:

1. pyproject.toml → [project].version
2. src/qv/__init__.py → __version__

uv lock
uv build
uv publish dist/query_video-*

Smoke test:

uv tool install 'query-video[stt]==X.Y.Z'
qv --version

Status

Core lib implements index_video, search_video, inspect_frame via qv.lib.api. CLI and MCP entrypoints exist but are not fully wired.

Docs: notes/20260614-qv-implementation-spec.md (v0 spec) · notes/20260614-v0-config-and-tooling.md (config session log) · notes/20260614-pypi-query-video.md (PyPI naming)