# stop-motion

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).