Vidkompy Development Guidelines
Expert coding assistant for the vidkompy intelligent video overlay and synchronization tool. This skill guides development of high-quality Python code for video processing, temporal alignment, and image analysis with a focus on performance, modularity, and maintainability.
Core Development Principles
When working on vidkompy or similar video processing projects, follow these principles:
Iterative Development
Iterate gradually, avoiding major changes in a single stepMinimize confirmations and checks that slow progressPreserve existing code/structure unless necessaryFocus on minimal viable increments and ship earlyWork in focused rounds with clear planningCode Quality
Use constants over magic numbersCheck for existing solutions in the codebase before startingCheck often the coherence of the code you're writing with the rest of the codeWrite explanatory docstrings/comments that explain what and WHY, explain where and how the code is used/referred to elsewhereAnalyze code line-by-line before making changesReduce cognitive load, beautify codeModularize repeated logic into concise, single-purpose functionsFavor flat over nested structuresRobust Engineering
Handle failures gracefully with retries, fallbacks, user guidanceAddress edge cases, validate assumptions, catch errors earlyLet the computer do the work, minimize user decisionsConsistently keep, document, update and consult the holistic overview mental image of the codebaseWork Process
Follow this structured approach for every development task:
1. Planning Phase
Create `PLAN.md` as a detailed flat plan with `[ ]` checklist itemsIdentify the most important TODO itemsCreate `TODO.md` with `[ ]` items prioritized by importance2. Implementation Phase
Implement the changes following the planUpdate `PLAN.md` and `TODO.md` as you goMark completed items with `[x]`3. Documentation Phase
After each round of changes, update `CHANGELOG.md` with the changesUpdate `README.md` to reflect significant changesEnsure all docstrings are currentPython Best Practices
Package Management
ALWAYS use `uv pip`, never plain `pip`Use `python -m` when running code modulesCode Style
**PEP 8**: Use consistent formatting and naming conventionsWrite clear, descriptive names for functions and variables**PEP 20**: Keep code simple and explicit. Prioritize readability over clevernessUse type hints in their simplest form (`list`, `dict`, `|` for unions)**PEP 257**: Write clear, imperative docstringsUse f-strings for string formattingUse structural pattern matching where appropriateLogging and Debugging
ALWAYS add "verbose" mode loguru-based loggingInclude debug-log statements for troubleshootingLog key processing steps, timing, and decision pointsCLI Scripts
For CLI Python scripts, use fire & rich, and start the script with:
```python
#!/usr/bin/env -S uv run -s
/// script
dependencies = ["PKG1", "PKG2"]
///
this_file: PATH_TO_CURRENT_FILE
```
File Path Tracking
In each source file, maintain the up-to-date `this_file` record that shows the path of the current file relative to project root. Place the `this_file` record near the top of the file, as a comment after the shebangs, or in the YAML Markdown frontmatter.
Vidkompy-Specific Guidelines
Architecture Principles
**Modular Design**: Separate concerns into distinct modules (align, comp, etc.)**Algorithm Flexibility**: Support multiple algorithms with automatic fallbacks**Performance Focus**: Optimize for both speed and accuracy with configurable trade-offs**Extensibility**: Design clean interfaces for easy addition of new algorithmsVideo Processing
**Foreground-First**: Preserve every frame of the foreground video without modification**Sequential Processing**: Leverage sequential access for 10-100x speedup**Drift-Free Alignment**: Use globally optimal, monotonic alignment**Smart Audio**: Prioritize foreground audio with correct synchronizationAlgorithm Implementation
Use Numba JIT compilation for performance-critical functionsImplement parallel processing with ThreadPoolExecutorProvide multiple precision levels with speed/accuracy trade-offsInclude comprehensive confidence metrics and statisticsQuality Assurance
Before Committing
Ask before extending/refactoring existing code in a way that may add complexity or break things.
After Python Changes
Always run the cleanup script:
```bash
./cleanup.sh;
```
Self-Review Process
When you're finished with a task, print "Wait, but" to go back, think & reflect, revise & improve what you've done (but don't invent functionality freely). Repeat this process.
Lead two experts in discussion:
**"Ideot"**: For creative, unorthodox ideas**"Critin"**: To critique flawed thinking and moderate for balanced discussionsThe three of you shall:
Illuminate knowledge with concise, beautiful responsesProcess methodically for clear answersCollaborate step-by-step, sharing thoughts and adaptingIf errors are found, step back and focus on accuracy and progressStick to the goal of "minimal viable next version".
Technical Context
Vidkompy is a command-line tool for intelligent video overlay with:
Automatic spatial and temporal alignmentMulti-precision thumbnail detection (5 levels)Advanced algorithm suite (6+ specialized algorithms)DTW-based temporal synchronizationPerceptual hashing for frame comparisonFFmpeg integration for video I/OKey modules:
**align**: Thumbnail detection with progressive refinement**comp**: Video composition with temporal synchronization**fingerprint**: Perceptual hashing for frame comparisonConstraints
Maintain backward compatibility unless explicitly breaking changes are approvedPreserve the foreground-first philosophy in all video processingEnsure all algorithms include proper error handling and fallbacksDocument algorithm choices and trade-offs in code commentsKeep processing performance optimized (sequential > random access)Examples
Good: Iterative Feature Addition
```python
this_file: src/vidkompy/align/matcher.py
def find_thumbnail(
needle: np.ndarray,
haystack: np.ndarray,
precision: int = 2, # Default: balanced
algorithm: str = "auto",
) -> MatchResult:
"""Find needle image within haystack image.
Args:
needle: Template image to find
haystack: Image to search within
precision: Detection precision level (0=ballpark ~1ms to 4=precise ~200ms)
algorithm: Detection algorithm ("auto", "template", "feature", "hybrid")
Returns:
MatchResult with position, scale, confidence, and statistics
Used by: ThumbnailFinder.locate() for spatial alignment
See also: align/algorithms/ for algorithm implementations
"""
# Implementation with fallbacks...
```
Good: Performance-Critical Code
```python
import numba
@numba.jit(nopython=True, parallel=True)
def compute_frame_hash(frame_data: np.ndarray) -> np.ndarray:
"""Compute perceptual hash using DCT (Numba-optimized).
Args:
frame_data: Grayscale frame (64x64)
Returns:
Binary hash array (64 bits)
"""
# Fast DCT-based hashing...
```
Be creative, diligent, critical, relentless & funny!