Slideshow Studio Pro

Turn a folder of images into a polished MP4 video — in one command.

What It Does

Slideshow Studio Pro is a Python CLI tool that takes a folder of photos and renders a professional MP4 slideshow video with:

Ken Burns animations — smooth zoom & pan on every image
Transition effects — fade, slide, zoom, wipe, and more
Background music — auto-looped and faded
Custom backgrounds — your own image, sharp or blurred
Grid layouts — show 2, 4, 6, or 9 photos at once
Multiple formats — YouTube, TikTok, Instagram, Cinema, Classic
Preview mode — fast 15-second test before full render
EXIF auto-rotation — phone photos always display upright

1. Setup

Install FFmpeg

FFmpeg handles video encoding. Install it once:

# Linux / WSL
sudo apt update && sudo apt install ffmpeg -y

# macOS
brew install ffmpeg

# Windows — download from https://ffmpeg.org/download.html and add to PATH

Verify:

ffmpeg -version

Install Python packages

pip install -r slideshow_studio/requirements.txt

Go to the working directory

All commands are run from inside slideshow_studio/:

cd slideshow_studio

2. Quick Start

# Simplest possible — YouTube 1080p, random transitions & animations
python slideshow.py -i ./photos -o video.mp4

# Not sure what settings to use? Use the guided wizard
python slideshow.py --interactive

# Quick 15-second test before the full render
python slideshow.py -i ./photos -o video.mp4 --preview

3. Organize Your Images

Put all your images in one folder (no subfolders). Name them with numbers so they sort in the right order:

photos/
  001.jpg
  002.jpg
  003.png
  004.webp

Any numbering style works — photo_01.jpg, slide003.png, img_100.jpg all sort correctly.

Supported formats: JPG, JPEG, PNG, GIF, BMP, WEBP

Any resolution is fine — scaling is handled automatically. Phone photos are auto-rotated using EXIF data so they always appear upright.

4. Common Options

Preview before rendering

Full 1080p takes time. Generate a fast 15-second test first:

python slideshow.py -i ./photos -o video.mp4 --preview

Creates video_preview.mp4 at ~480p in seconds. Check your timing, transitions, and animations — then run without --preview for the real thing.

Add music

# Music loops automatically if it's shorter than the video (default)
python slideshow.py -i ./photos -o video.mp4 -a music.mp3

# Music plays once, then silence
python slideshow.py -i ./photos -o video.mp4 -a music.mp3 --audio-behavior mute

Supported formats: MP3, WAV, OGG, M4A

Audio gets automatic fade-in and fade-out — no editing needed.

Add a background image

By default each slide uses a blurred version of itself as the background. You can replace this with any photo:

# Sharp background (default) — background image fully visible
python slideshow.py -i ./photos -o video.mp4 --background ./bg.jpg

# Blurred background — softer look, slides stand out more
python slideshow.py -i ./photos -o video.mp4 --background ./bg.jpg --background-blur

Keep your background image in a separate folder from your slides folder — otherwise it will be included as a slide.

Change aspect ratio

Use -r to pick the output format:

Value	Ratio	Resolution (1080p)	Best for
`youtube`	16:9	1920×1080	YouTube, standard video (default)
`tiktok`	9:16	1080×1920	TikTok, Instagram Reels
`square`	1:1	1080×1080	Instagram posts
`cinema`	21:9	2520×1080	Cinematic widescreen
`classic`	4:3	1440×1080	Presentations, old-school TV

python slideshow.py -i ./photos -o tiktok.mp4 -r tiktok
python slideshow.py -i ./photos -o insta.mp4 -r square

Change quality

python slideshow.py -i ./photos -o video.mp4 -q 720p    # fast, small file
python slideshow.py -i ./photos -o video.mp4 -q 1080p   # default — great balance
python slideshow.py -i ./photos -o video.mp4 -q 1440p   # 2K
python slideshow.py -i ./photos -o video.mp4 -q 4k      # 4K — slow, large file

Tip: use -q 720p while testing, then switch to 1080p or higher for the final export.

Control image duration

Use -s to set how many seconds each image stays on screen (default is 3):

python slideshow.py -i ./photos -o video.mp4 -s 2.0    # faster pace
python slideshow.py -i ./photos -o video.mp4 -s 5.0    # slow, cinematic
python slideshow.py -i ./photos -o video.mp4 -s 0.5    # very fast slideshow

5. Transitions & Animations

Transitions — `-t`

The effect that plays between one image and the next:

Value	What it looks like
`random`	A different effect for every pair (default)
`fade`	Smooth cross-dissolve
`fade_black`	Fades to black, then into the next image
`slide_left`	Next image slides in from the right
`slide_right`	Next image slides in from the left
`slide_up`	Next image slides in from the bottom
`slide_down`	Next image slides in from the top
`zoom_in`	Next image zooms in from the center
`zoom_out`	Current image shrinks to reveal the next
`wipe_left`	A reveal line sweeps across

python slideshow.py -i ./photos -o video.mp4 -t fade
python slideshow.py -i ./photos -o video.mp4 -t slide_left

Animations — `--animation`

The Ken Burns movement applied to each image while it's on screen:

Value	What it looks like
`random`	A different movement per image (default)
`zoom_in_center`	Slowly zooms toward the center
`zoom_out_center`	Starts zoomed in, slowly pulls back
`pan_left`	Camera drifts left
`pan_right`	Camera drifts right
`pan_up`	Camera drifts upward
`pan_down`	Camera drifts downward
`zoom_in_pan_left`	Zooms in while drifting left
`zoom_in_pan_right`	Zooms in while drifting right
`corner_tl_br`	Drifts from top-left to bottom-right
`corner_br_tl`	Drifts from bottom-right to top-left

python slideshow.py -i ./photos -o video.mp4 --animation zoom_in_center
python slideshow.py -i ./photos -o video.mp4 -t fade --animation pan_left

6. Grid Layouts

Show multiple images on screen at once — great for large photo collections.

Value	Images per frame	Description
`auto`	decided for you	Best grid based on your image count (default)
`single`	1	One image per frame
`2x1`	2	Side by side
`1x2`	2	Stacked vertically
`2x2`	4	2×2 grid
`3x2`	6	3 columns, 2 rows
`3x3`	9	3×3 grid

# One image per frame (most common)
python slideshow.py -i ./photos -o video.mp4 -g single

# 4 images per frame
python slideshow.py -i ./photos -o video.mp4 -g 2x2

# Let the tool decide
python slideshow.py -i ./photos -o video.mp4 -g auto

auto targets ~3 seconds per frame regardless of how many images you have. If you want every photo shown individually, always use -g single.

7. Presets — Save & Reuse Settings

Save your settings once and load them any time.

Save a preset

python slideshow.py -i ./photos -o video.mp4 \
  -r tiktok -s 2.5 -t fade --animation zoom_in_center \
  --save-preset my_tiktok

Load a preset

python slideshow.py -i ./new_photos -o new_video.mp4 --preset my_tiktok

Override preset values on the fly

# Same preset, different images and background
python slideshow.py -i ./other_photos -o other.mp4 --preset my_tiktok --background ./bg.jpg

List all saved presets

python slideshow.py --list-presets

Built-in presets: default, tiktok

8. Config File

Put everything in a JSON file for complex or repeatable setups:

settings.json:

{
  "images":            "./photos",
  "output":            "video.mp4",
  "aspect_ratio":      "youtube",
  "quality":           "1080p",
  "seconds_per_image": 4.0,
  "transition":        "fade",
  "animation":         "zoom_in_center",
  "audio":             "./music.mp3",
  "audio_behavior":    "loop",
  "background":        "./bg.jpg",
  "background_blur":   false,
  "grid":              "single"
}

python slideshow.py --config settings.json

Every key is optional — leave any setting out to use the default.

9. Interactive Wizard

Don't want to remember flags? Run the wizard and answer prompts step by step:

python slideshow.py --interactive

It walks you through every setting and renders the video at the end.

10. Ready-to-Run Examples

YouTube holiday slideshow with music

python slideshow.py \
  -i ./holiday_photos \
  -o holiday.mp4 \
  -r youtube -q 1080p \
  -s 4.0 -t fade \
  --animation zoom_in_center \
  -a background_music.mp3

TikTok reel with a brand background

python slideshow.py \
  -i ./product_shots \
  -o reel.mp4 \
  -r tiktok -q 1080p \
  -s 2.5 -t slide_left \
  --animation random \
  -a upbeat_track.mp3 \
  --background ./brand_bg.png

Instagram square post — fast, no music

python slideshow.py \
  -i ./photos \
  -o instagram.mp4 \
  -r square -q 1080p \
  -s 2.0 -t zoom_in \
  -g single

Cinematic widescreen with blurred background

python slideshow.py \
  -i ./landscape_photos \
  -o cinematic.mp4 \
  -r cinema -q 1440p \
  -s 5.0 -t fade_black \
  --animation zoom_out_center \
  --background ./dark_texture.jpg --background-blur \
  -a ambient.mp3

Preview first, then render final

# Step 1 — quick test (creates video_preview.mp4)
python slideshow.py -i ./photos -o video.mp4 -r tiktok -s 2.5 -t fade --preview

# Step 2 — happy with it? Run the full render
python slideshow.py -i ./photos -o video.mp4 -r tiktok -s 2.5 -t fade

Batch render multiple folders

for folder in ./event1 ./event2 ./event3; do
    name=$(basename "$folder")
    python slideshow.py -i "$folder" -o "output/${name}.mp4" --quiet
    echo "Done: output/${name}.mp4"
done

11. All Options Reference

Flag	Long form	Default	What it does
`-i PATH`	`--images PATH`	required	Folder containing your images
`-o PATH`	`--output PATH`	required	Output `.mp4` file path
`-a PATH`	`--audio PATH`	none	Background music file
	`--audio-behavior`	`loop`	`loop` or `mute` when audio ends before video
	`--background PATH`	none	Image used as background behind all slides
	`--background-blur`	off	Blur and darken the background image
`-r RATIO`	`--aspect-ratio`	`youtube`	`youtube` `tiktok` `square` `cinema` `classic`
`-q QUAL`	`--quality`	`1080p`	`720p` `1080p` `1440p` `4k`
`-s SECS`	`--seconds-per-image`	`3.0`	How long each image stays on screen
`-t TYPE`	`--transition`	`random`	Transition effect between images
	`--animation`	`random`	Ken Burns movement per image
`-g GRID`	`--grid`	`auto`	`auto` `single` `2x1` `1x2` `2x2` `3x2` `3x3`
`-c FILE`	`--config FILE`	none	Load all settings from a JSON file
`-p NAME`	`--preset NAME`	none	Load a saved preset by name
	`--save-preset NAME`	none	Save current settings as a named preset
	`--list-presets`	—	List all saved presets and exit
	`--preview`	—	Fast 15-second test render at ~480p
	`--interactive`	—	Step-by-step guided wizard
	`--quiet`	—	No output except the final file path (great for scripts)
`-v`	`--verbose`	—	Print per-image and per-transition debug info

12. Troubleshooting

"FFmpeg not found"

sudo apt install ffmpeg -y

"No images found"

Check that the path after -i is correct
Images must be directly in the folder — no subfolders
Supported: JPG, JPEG, PNG, GIF, BMP, WEBP

"Background image not found"

Check the path after --background is correct and the file exists
Make sure the background file is not inside your images folder — it would be treated as a slide

Video has fewer slides than expected

The -g auto setting groups multiple images per frame. To give every image its own frame:

python slideshow.py -i ./photos -o video.mp4 -g single

Render is slow

Use -q 720p during testing — much faster
Use --preview for a quick 15-second check
Downscale very large images (20MP+ camera exports) before processing

Out of memory

Switch to -q 720p
Use --preview
Process a smaller batch of images

Exit codes

Code	Meaning
`0`	Success
`1`	Invalid argument or setting
`2`	No images found
`4`	Output path not writable
`5`	FFmpeg not installed
`6`	Video encoding failed
`7`	Out of memory
`130`	Cancelled with Ctrl+C

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.claude		.claude
how-we-host-it-on-vercel		how-we-host-it-on-vercel
slideshow_studio		slideshow_studio
video-roadmap		video-roadmap
.gitignore		.gitignore
How_to_Use.md		How_to_Use.md
README.md		README.md
prd.md		prd.md
slideshow_studio.zip		slideshow_studio.zip

Folders and files

Latest commit

History

Repository files navigation

Slideshow Studio Pro

What It Does

Table of Contents

1. Setup

Install FFmpeg

Install Python packages

Go to the working directory

2. Quick Start

3. Organize Your Images

4. Common Options

Preview before rendering

Add music

Add a background image

Change aspect ratio

Change quality

Control image duration

5. Transitions & Animations

Transitions — -t

Animations — --animation

6. Grid Layouts

7. Presets — Save & Reuse Settings

Save a preset

Load a preset

Override preset values on the fly

List all saved presets

8. Config File

9. Interactive Wizard

10. Ready-to-Run Examples

YouTube holiday slideshow with music

TikTok reel with a brand background

Instagram square post — fast, no music

Cinematic widescreen with blurred background

Preview first, then render final

Batch render multiple folders

11. All Options Reference

12. Troubleshooting

"FFmpeg not found"

"No images found"

"Background image not found"

Video has fewer slides than expected

Render is slow

Out of memory

Exit codes

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Transitions — `-t`

Animations — `--animation`

Packages