From 66b23834fdfc55c419317a1d7f6f2498a1404386 Mon Sep 17 00:00:00 2001 From: PhatPhuckDave Date: Tue, 16 Sep 2025 19:46:16 +0200 Subject: [PATCH] Add spec file --- croppa/spec.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 croppa/spec.md diff --git a/croppa/spec.md b/croppa/spec.md new file mode 100644 index 0000000..58d9135 --- /dev/null +++ b/croppa/spec.md @@ -0,0 +1,123 @@ +# Croppa - Feature Specification + +## Overview +Croppa is a lightweight video and image editor that provides real-time editing capabilities with persistent state management. + +## Notes: + +Note the distinction between lowercase and uppercase keys +Uppercase keys imply shift+key + +Note that every transformation (cropping, motion track points) are almost always applied to an already transformed frame +Be that by rotation, cropping, zooming or motion tracking itself +Which means that the user input must be "de-transformed" before being applied to the frame +In other words if we zoom into an area and right click to add a tracking point it must be added to that exact pixel ON THE ORIGINAL FRAME +And NOT the zoomed in / processed frame +Likwise with rotations +All coordinates (crop region, zoom center, motion tracking point) are to be in reference to the original raw unprocessed frame +To then display these points they must be transformed to the processed - display - frame +Likewise when accepting user input from the processed display frame the coordinates must be transformed back to the original raw unprocessed frame +A simple example if we are rotated by 90 degrees and click on the top left corner of the display frame +That coordinate is to be mapped to the bottom left corner of the original raw unprocessed frame + +## Core Features + +### Video Playback +- **Space**: Play/pause video +- **a/d**: Seek backward/forward 1 frame +- **A/D**: Seek backward/forward 10 frames +- **Ctrl+a/d**: Seek backward/forward 60 frames +- **W/S**: Increase/decrease playback speed (0.1x to 10.0x, increments of 0.2) +- **Q/Y**: Increase/decrease seek multiplier (multiplies the frame count for a/d/A/D/Ctrl+a/d keys by 1.0x to 100.0x, increments of 2.0) +- **q**: Quit the program +- **Timeline**: Click anywhere to jump to that position +- **Auto-repeat**: Hold seek keys for continuous seeking at 1 FPS rate + +### Visual Transformations +- **-**: Rotate 90 degrees clockwise +- **e/E**: Increase/decrease brightness (-100 to +100, increments of 5) +- **r/R**: Increase/decrease contrast (0.1 to 3.0, increments of 0.1) +- **Ctrl+Scroll**: Zoom in/out (0.1x to 10.0x, increments of 0.1) +- **Ctrl+Click**: Set zoom center point + +### Cropping +- **Shift+Click+Drag**: Select crop area with green rectangle preview +- **h/j/k/l**: Expand crop from right/down/up/left edges (15 pixels per keypress) +- **H/J/K/L**: Contract crop to left/down/up/right edges (15 pixels per keypress) +- **u**: Undo last crop +- **c**: Clear all cropping + +### Motion Tracking +- **Right-click**: Add tracking point (green circle with white border) +- **Right-click existing point**: Remove tracking point (within 50px) +- **v**: Toggle motion tracking on/off +- **V**: Clear all tracking points +- **Blue cross**: Shows computed tracking position +- **Automatic interpolation**: Tracks between keyframes +- **Crop follows**: Crop area centers on tracked object + +### Markers and Looping +- **1**: Set cut start marker at current frame +- **2**: Set cut end marker at current frame +- **t**: Toggle loop playback between markers +- **Red lines**: Markers shown on timeline with numbers +- **Continuous loop**: Playback loops between markers when enabled + +### File Management +- **Enter**: Render video (overwrites if filename contains "_edited_") +- **b**: Render video with new "_edited_001" filename (does NOT overwrite!) +- **s**: Save screenshot with auto-incrementing filename (video_frame_00001.jpg, video_frame_00002.jpg, etc. - NEVER overwrite existing screenshots) +- **N/n**: Next/previous video in directory +- **p**: Toggle project view (directory browser) + +### Project View +- **wasd**: Navigate through video thumbnails +- **e**: Open selected video +- **Q/Y**: Change thumbnail size (fewer/more per row, size automatically computed to fit row) +- **q**: Quit +- **Progress bars**: Show editing progress for each video (blue bar showing current_frame/total_frames) +- **ESC**: Return to editor + +### Display and Interface +- **f**: Toggle fullscreen +- **Status overlay**: Shows "Frame: 1500/3000 | Speed: 1.5x | Zoom: 2.0x | Seek: 5.0x | Rotation: 90° | Brightness: 10 | Contrast: 1.2 | Motion: ON (3 pts) | Playing/Paused" +- **Timeline**: Visual progress bar with current position handle +- **Feedback messages**: Temporary on-screen notifications (e.g. "Screenshot saved: video_frame_00001.jpg") +- **Progress bar**: Shows rendering progress with FPS counter (e.g. "Processing 1500/3000 frames | 25.3 FPS") + +### State Management +- **Auto-save**: Settings saved automatically on changes and on quit +- **Per-video state**: Each video remembers its own settings +- **Cross-session**: Settings persist between application restarts +- **JSON files**: State stored as .json files next to videos with the same name as the video + +### Rendering +- **Background rendering**: Continue editing while rendering (rendering happens in separate thread, you can still seek/play/edit) +- **x**: Cancel active render +- **FFmpeg output**: Invoke FFmpeg process, pipe raw video frames via stdin, output MP4 with H.264 encoding (CRF 18, preset fast) +- **Progress tracking**: Real-time progress with FPS display +- **Overwrite protection**: Only overwrites files with "_edited_" in name + +### Image Mode +- **Same controls**: All editing features work on static images +- **No playback**: Space key disabled, no timeline +- **Screenshot mode**: Treats single images like video frames + +### Error Handling +- **Format support**: MP4, AVI, MOV, MKV, WMV, FLV, WebM, M4V, JPG, PNG, BMP, TIFF, WebP +- **Backend fallback**: Tries multiple video backends automatically +- **Error messages**: Clear feedback for common issues +- **Graceful degradation**: Continues working when possible + +### Performance Features +- **Frame caching**: Smooth seeking with cached frames (cache the decoded frames, LRU eviction, max 3000 frames) +- **Transformation caching**: Fast repeated operations (cache transformed frames during auto-repeat seeking) +- **Memory management**: Automatic cache cleanup + +### Window Management +- **Resizable**: Window can be resized dynamically +- **Multi-window**: Project view opens in separate window +- **Focus handling**: Keys only affect active window +- **Context menu**: Right-click integration on Windows + +This specification describes what Croppa does from the user's perspective - the features, controls, and behaviors that make up the application.