docs: Expand README with usage and behavior details

Replace the one-line README with a full project description in
English: requirements, supported image formats, CLI options table,
pipeline overview and error handling, and license section.

README.md

@@ -1,3 +1,42 @@
 # stop-motion
 
-shell script to create stop-motion videos from images
+A small shell script to turn a folder of images into a stop-motion video, using ffmpeg.
+
+Give it a directory of photos (e.g. shot with an iPhone in burst mode), and it builds a single H.264 MP4: each image becomes one frame, played at a fixed frame rate.
+
+## Requirements
+
+- [ffmpeg](https://ffmpeg.org/) available in your `PATH` (on macOS: `brew install ffmpeg`)
+- Bash
+
+Supported image formats: `jpg`, `jpeg`, `png`, `heic` (case-insensitive). Only files in the top level of the input directory are used; they are ordered by filename, so make sure the names reflect the intended play order (e.g. `IMG_0001`, `IMG_0002`, ...).
+
+## Usage
+
+```sh
+./stopmotion.sh                          # ./images -> ./stop_motion.mp4, 12 fps, 1080 px
+./stopmotion.sh -i photos -o film.mp4 -f 15 -s 720 -y
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-i DIR` | `./images` | Directory containing the images |
+| `-o FILE` | `./stop_motion.mp4` | Output video file |
+| `-f FPS` | `12` | Frame rate (frames per second, > 0) |
+| `-s SIZE` | `1080` | Maximum size of the longest side in pixels (aspect ratio preserved) |
+| `-y` | off | Overwrite the output file without asking |
+| `-h` | — | Show help |
+
+## How it works
+
+1. Validates options and checks that `ffmpeg` is installed.
+2. Lists the images in the input directory (top level only, sorted by name) and fails with a clear error if none are found.
+3. Generates a temporary [ffconcat](https://ffmpeg.org/ffmpeg-formats.html#concat) playlist giving each image a duration of `1/fps`.
+4. Encodes with ffmpeg: `libx264`, `yuv420p`, `+faststart` (web-friendly MP4), frames scaled down to fit `SIZE` while keeping the aspect ratio and even dimensions.
+5. Prints a summary: image count, fps, video duration and output file size.
+
+If the output file already exists, the script asks for confirmation unless `-y` is given. Any error exits with a non-zero status and a failed encode leaves no partial file behind.
+
+## License
+
+GPL-3.0 — see [LICENSE](LICENSE).