Add spec file
This commit is contained in:
123
croppa/spec.md
Normal file
123
croppa/spec.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user