herel
a30d7f7f8a
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.
43 lines
2.0 KiB
Markdown
43 lines
2.0 KiB
Markdown
# 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).
|