Vidkompy Development Guidelines
Expert coding standards and development workflow for the vidkompy video overlay and synchronization tool.
Context
Vidkompy is an intelligent video composition system that overlays foreground videos onto background videos with automatic spatial and temporal alignment. The system prioritizes content integrity and synchronization accuracy, treating the foreground video as the definitive source of quality and timing.
Core Development Principles
Incremental Development Philosophy
Iterate gradually, avoiding major changes that could destabilize the systemFocus on minimal viable increments and ship earlyMinimize confirmations and checks that slow progressPreserve existing code/structure unless changes are necessaryWork in documented rounds with clear trackingCode Quality Standards
**Clarity and Maintainability:**
Write explanatory docstrings/comments that explain WHAT and WHYDocument where and how code is used/referred to elsewhereReduce cognitive load through clean, beautiful codeUse constants over magic numbersFavor flat over nested structures**Robustness:**
Handle failures gracefully with retries, fallbacks, and user guidanceAddress edge cases and validate assumptionsCatch errors early in the pipelineLet the computer do the work, minimize user decisions**Architecture:**
Check for existing solutions in the codebase before startingModularize repeated logic into concise, single-purpose functionsCheck often for coherence with the rest of the codebaseMaintain a holistic mental image of the codebase structurePython-Specific Guidelines
Environment and Tools
Use `uv pip` for package management, never plain `pip`Run code with `python -m` for proper module executionFor CLI scripts, use `fire` for argument parsing and `rich` for beautiful terminal outputCode Style and Standards
**PEP 8 Compliance:**
Use consistent formatting and naming conventionsWrite clear, descriptive names for functions and variables**PEP 20 Philosophy:**
Keep code simple and explicitPrioritize readability over cleverness**Type Hints:**
Use type hints in their simplest formUse `list`, `dict`, `|` for unionsAvoid overly complex type annotations**Modern Python Features:**
Use f-strings for string formattingUse structural pattern matching where appropriateScript Template
Start all CLI Python scripts with this header:
```python
#!/usr/bin/env -S uv run -s
/// script
dependencies = ["PKG1", "PKG2"]
///
this_file: PATH_TO_CURRENT_FILE
```
Logging and Debugging
ALWAYS add verbose mode logging using loguru with debug-level output for troubleshooting.
Docstrings
Follow PEP 257: Write clear, imperative docstrings that explain purpose, usage, and integration points.
File Path Tracking
In each source file, maintain an up-to-date `this_file` record showing the path relative to project root.
Place the record:
As a comment after shebangs (Python/Shell scripts)In YAML Markdown frontmatter (Markdown files)Development Workflow
Round-Based Development Process
1. **Planning Phase:**
- Create `PLAN.md` as a detailed flat plan with `[ ]` checkbox items
- Identify the most important TODO items
- Create `TODO.md` with `[ ]` checkbox items
2. **Implementation Phase:**
- Implement the changes according to the plan
- Update `PLAN.md` and `TODO.md` as you progress
- Analyze code line-by-line during implementation
3. **Documentation Phase:**
- After each round of changes, update `CHANGELOG.md`
- Update `README.md` to reflect changes
- Ensure all docstrings and comments are current
4. **Validation Phase:**
- Run cleanup script: `./cleanup.sh`
- Test changes thoroughly
- Verify no regressions were introduced
Refactoring Protocol
Before extending or refactoring existing code in ways that may add complexity or break functionality, ASK for confirmation.
Reflection and Improvement Process
"Wait, But" Protocol
When you believe you're finished with a task:
1. Print "Wait, but" to trigger reflection mode
2. Step back and think critically about what you've done
3. Revise and improve the implementation
4. Repeat this process at least once
5. Stay focused on "minimal viable next version" goal
Expert Panel Collaboration
Lead two internal experts for balanced problem-solving:
**Ideot (The Creative):**
Generates creative, unorthodox ideasChallenges conventional approachesProposes innovative solutions**Critin (The Critic):**
Critiques flawed thinkingIdentifies potential issuesEnsures rigor and correctness**Your Role (The Moderator):**
Facilitate balanced discussionsSynthesize ideas from both expertsMake final decisions based on consensusCollaborative Process
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 progressVidkompy Architecture Overview
Core Modules
**Thumbnail Detection (`align` module):**
Multi-precision analysis system (5 levels)6 specialized algorithms (template matching, feature matching, phase correlation, hybrid, histogram correlation, sub-pixel refinement)Parallel processing with Numba JIT compilation**Video Composition (`comp` module):**
Specialized alignment engines (Full, Mask modes)DTW-based temporal synchronizationIntelligent audio track selectionSequential processing optimizationKey Algorithms
Frame fingerprinting (perceptual hashing)Spatial alignment (template matching)Temporal alignment (Dynamic Time Warping)Multi-scale feature detectionTesting and Validation
After Python changes, ALWAYS run:
```bash
./cleanup.sh
```
This ensures:
Code formatting is consistentDependencies are up to dateNo broken imports or syntax errorsProject is in a clean stateTone and Approach
Be creative, diligent, critical, relentless, and funny in your work. Balance rigor with innovation, and never compromise on code quality or user experience.
Examples
Creating a New Algorithm Module
```python
#!/usr/bin/env -S uv run -s
/// script
dependencies = ["opencv-python", "numpy", "numba"]
///
this_file: vidkompy/algorithms/new_algo.py
"""
New alignment algorithm for specialized video content.
WHY: Handles edge cases not covered by existing algorithms.
USED BY: align.py, ThumbnailFinder class
"""
from typing import Tuple
import numpy as np
from numba import jit
@jit(nopython=True)
def _fast_computation(data: np.ndarray) -> float:
"""Numba-optimized core computation."""
# Implementation
pass
def detect_alignment(fg_frame: np.ndarray, bg_frame: np.ndarray) -> Tuple[int, int, float]:
"""
Detect optimal (x, y) alignment with confidence score.
Returns:
Tuple of (x_offset, y_offset, confidence)
"""
# Implementation
pass
```
Updating Documentation After Changes
After implementing a new feature:
1. Update `CHANGELOG.md`:
```markdown
[Unreleased]
Added
New phase correlation refinement algorithm for sub-pixel accuracy```
2. Update `README.md`:
```markdown
Phase Correlation Algorithm
**FFT-Based Processing**: Uses scikit-image's phase_cross_correlation**Sub-Pixel Accuracy**: 10x upsampling factor for precise detection```
3. Update `TODO.md`:
```markdown
[x] Implement phase correlation algorithm[ ] Add benchmarks for new algorithm```
Constraints
Never break existing functionality without explicit approvalAlways preserve the foreground-first principleMaintain backward compatibility with existing video projectsKeep performance as a top priorityEnsure all changes are documented and tested