home_video/AGENTS.md

Repository Guidelines

Project Structure & Modules

This is a small, flat Python video workflow. home_video_phase1.py scans source videos and creates daily JSON manifests and LosslessCut .llc projects. review_videos.py provides the Tkinter manifest reviewer and title editor. build_project.py generates OpenShot project files from a folder of clips. make_video.py assembles selected clips with FFmpeg; its input paths and encoder are configured in the script. README.md documents the workflows. vids/ contains sample media links and a generated title SVG; out/ contains generated manifests and editing projects. Keep generated videos, projects, and local environments (such as .venv/) out of source changes unless they are intentional examples.

Build, Run & Development

There is no package build step. Use Python 3.9+ and install FFmpeg so ffprobe and ffmpeg are available on PATH.

• py home_video_phase1.py "D:\Home Videos" "D:\Video Days" --timezone America/New_York scans recursively and writes per-day outputs. Keep the output outside the input folder.
• py -m pip install -r requirements-review.txt installs the optional VLC binding; py review_videos.py "D:\Video Days\2024-07-11.json" opens a manifest for review.
• py build_project.py "D:\Video Days" "Family Memories" creates OpenShot projects from supported videos directly in the given folder.
• py make_video.py runs the configured render pipeline; update INPUT_FILES, OUTPUT_FILE, and ENCODER in the script for the intended job first.
• py -m compileall home_video_phase1.py review_videos.py build_project.py make_video.py checks Python syntax.

Style & Testing

Use four spaces for indentation, standard-library imports, snake_case for functions and variables, and uppercase names for configuration constants. Keep CLI options explicit and preserve existing media-handling behavior. No formatter, linter, or automated test suite is configured. For changes, run the relevant command on a small disposable sample set and inspect the generated manifest/project; never use irreplaceable source footage as a test fixture.

Commits & Pull Requests

This checkout has no Git history to establish a commit convention. Use a short imperative subject (for example, Preserve timezone offsets in manifests). Pull requests should explain the user-visible change, list the script or sample workflow used to validate it, and include a small before/after example when output structure changes. Link a related issue when one exists.

Media & Configuration

Treat source video paths as user data. Confirm generated outputs go to the requested destination, avoid committing personal footage or rendered files, and document external requirements such as FFmpeg, LosslessCut, and OpenShot when changing a workflow.