Add trackcrop: crop a video to a square around a tracked objectHEADmaster

Single-file Python script. The user boxes an object on the first frame,
a CSRT tracker follows it, the path is smoothed over ~0.5 s and the
square crop is encoded with h264_vaapi, audio copied.

--ak820 FPS limits the output to the AJAZZ AK820 Pro screen's 255
frames at FPS, prompting for which window to keep (start, end or a
start second) when the clip is longer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 58 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f2d86e2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,58 @@
+# trackcrop
+
+Crop a video to a 1:1 square while keeping a chosen object centered. You pick
+the object on the first frame, OpenCV's CSRT tracker follows it, the path is
+smoothed to remove jitter, and the cropped frames are encoded with ffmpeg.
+
+## Requirements
+
+- Python 3 with numpy and `opencv-contrib-python` (a GUI build, not `-headless`)
+- ffmpeg with the `h264_vaapi` encoder and a VA-API device at `/dev/dri/renderD128`
+
+## Usage
+
+```sh
+./trackcrop.py [--no-audio] [--ak820 FPS] in.mp4 out.mp4
+```
+
+1. A window opens on the first frame. Drag a box around the object and press
+   Enter or Space (`c` cancels the selection).
+2. The script tracks the object and encodes the result. It is done when the
+   prompt returns.
+
+Audio is copied unchanged unless `--no-audio` is given.
+
+### AJAZZ AK820 Pro screen
+
+The AK820 Pro keyboard screen holds at most 255 frames, so at a given upload
+frame rate it can only show `255 / FPS` seconds (8.5 s at 30 fps). With
+`--ak820 FPS`, a clip longer than that asks which part to keep before the
+object selection:
+
+- `s` or Enter: the start
+- `e`: the end
+- a number: start at that many seconds
+
+The object box is then drawn on the first frame of the kept part, and the
+audio is trimmed to match. Upload the result with
+`ak820-upload out.mp4 FPS`, using the same `FPS`.
+
+## Notes
+
+- The object must be visible in the first frame. Trim the start otherwise:
+  `ffmpeg -ss 3 -i in.mp4 -c copy trimmed.mp4`.
+- The square never leaves the frame, so the object sits off center near the
+  edges.
+- Works on landscape videos too, the square is cut horizontally.
+
+## License
+
+GPLv2 only. See [LICENSE](LICENSE).
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.