Machine-readable timing cues for video analysis.
BeatCue is being designed as both a Python library and an agent-friendly CLI for extracting editorial timing cues from video files. The planned package identifies cuts, transitions, audio beats, ease-in and ease-out ramps, rising and falling audiovisual intensity, object entries and exits, and selected image-to-text annotations.
Video analysis tools often mix timing, captions, and presentation into one opaque result. BeatCue keeps those concerns separate:
- Cue sheets first: Emit WebVTT metadata cues, BeatCue JSON, and OpenTimelineIO markers for downstream tooling.
- Explainable timing: Base cues on colour, motion, audio, scene, and object signals before semantic annotations are attached.
- Library and CLI parity: Keep the Python API and command-line behaviour on the same domain model.
- Agent-native operation: Design the CLI for
--json, bounded output, non-interactive execution, profiles, jobs, and explicit delivery targets.
This repository currently provides the package skeleton and design documents. Install the development environment from the repository root:
uv sync --group devThe current package exposes a small smoke-check function while the roadmap builds the video-analysis API and CLI:
from beatcue import hello
print(hello())Run it from the repository root:
uv run python -c "from beatcue import hello; print(hello())"Expected output:
hello from Python
Planned capabilities are defined in the technical design and roadmap:
- Hexagonal Python architecture with dependency injection.
- Cyclopts-based CLI specification and tiered configuration.
- Rich human output with clean ASCII machine and LLM-facing payloads.
- Cuprum-backed subprocess calls for
ffprobe,ffmpeg, and helper tools. - CmdMox-backed tests for external command adapters.
- Deterministic cue extraction from colourgrams, optical flow, scene changes, and audio features.
- Optional semantic annotation and object tracking behind domain-owned ports.
- WebVTT, BeatCue JSON, and OpenTimelineIO output writers.
- Users' Guide — user-facing documentation as the package grows
- Technical design — architecture, contracts, and implementation decisions
- Roadmap — planned features and delivery sequence
- Contributor guidance — repository workflow and engineering standards
ISC — see LICENSE for details.
Contributions are welcome. Please read AGENTS.md before changing the repository; it defines the local workflow, quality gates, and documentation standards.
Run make spelling to refresh the shared en-GB-oxendict dictionary when newer,
regenerate typos.toml, and check maintained Markdown with a pinned typos
release. A valid committed config remains usable without network access.