Image Slideshow CLI
> A lightweight Node.js command-line tool to generate a
beautiful Tailwind CSS dark-themed HTML slideshow from a folder of images — now with
WebM and MP4 video export!
---
Overview
Image Slideshow CLI scans a folder of images (
.png,
.jpg,
.jpeg,
.webp,
.gif) and optionally generates:
- A stunning interactive HTML slideshow with thumbnails, autoplay, and keyboard controls
- A high-quality WebM video slideshow (VP9) using ffmpeg
- A dedicated show-video.html page that embeds the video full-screen with native controls
Perfect for quick portfolios, presentations, social media sharing, or archival backups.
---
Screenshot
- !
Slideshow- !
Video ViewerInstallation
$3
``
bash
npm install -g image-slideshow-cli
`
Then run anywhere:
`
bash
image-slideshow -f ./photos
`
> Requires Node.js ≥ 14
> For video export: ffmpeg must be installed and in your PATH
---
Usage
`
bash
image-slideshow -f [options]
`
$3
`
bash
Just the HTML slideshow
image-slideshow -f ./vacationHTML slideshow + WebM video + video viewer page
image-slideshow -f ./vacation -vCustom title, autoplay, and longer image duration in video
image-slideshow -f ./vacation -v -t "Summer 2025" -a 4 --duration 5 --quality high
`
---
Options
| Option | Alias | Description | Default |
|-------------------------|-------|--------------------------------------------------|--------------------|
|
--folder
| -f | Folder containing images | (Required) |
| --output | -o | Output HTML slideshow filename | slideshow.html |
| --title <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | </code>-t<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Title shown in both slideshow and video page | </code>Image Slideshow<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> |<br />| </code>--autoplay <seconds><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | </code>-a<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Autoplay interval in HTML slideshow (0 = off) | </code>5<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> |<br />| </code>--pattern <exts><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | | Comma-separated extensions (no dots) | </code>png,jpg,jpeg,webp,gif<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> |<br />| </code>--video<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | </code>-v<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Generate <strong>both WebM + MP4</strong> + </code>show-video.html<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | </code>false<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> |<br />| </code>--video-output <file><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | | Output video filename | </code>slideshow.webm<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> |<br />| </code>--duration <seconds><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | | Seconds each image is shown in video | </code>3<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> |<br />| </code>--fps <number><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | | Frames per second for video | </code>30<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> |<br />| </code>--quality <level><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | | Video quality: </code>low<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> │ </code>medium<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> │ </code>high<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | </code>medium<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> |<br />| --background-music <path>|-b| path to background music file (mp3, wav, ogg, etc.)|None|</p><p class="my-3">---<br /><h2 class="text-xl font-semibold mt-5 mb-3">New: WebM Video Features (-v)</h2></p><p class="my-3">When you add the </code>-v<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> flag, the tool generates <strong>three</strong> files:</p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />/your-folder/<br />├── photo1.jpg<br />├── photo2.webp<br />├── slideshow.html ← Interactive image slideshow<br />├── slideshow.webm ← High-quality VP9 WebM video<br />└── show-video.html ← Beautiful full-screen video player (auto-opens)<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3><br />- Full-screen responsive video<br />- Autoplay + loop + muted (mobile-friendly)<br />- Native browser controls<br />- Dark theme with header/footer<br />- Link back to the image slideshow</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3><br />| Level | CRF | Bitrate | Best For |<br />|---------|-----|---------|------------------------------|<br />| </code>low<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | 35 | ~500kbps| Fast encoding, small file |<br />| </code>medium<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">| 23 | ~1Mbps | Great balance (default) |<br />| </code>high<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | 15 | ~2Mbps | Maximum quality |</p><p class="my-3">---<br /><h2 class="text-xl font-semibold mt-5 mb-3">Features</h2></p><p class="my-3">- <strong>Dark Tailwind Theme</strong> – Modern, elegant UI<br />- <strong>Fully Responsive</strong> – Looks great on phones, tablets, desktops<br />- <strong>Keyboard Navigation</strong> – </code>←<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> </code>→<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> </code>Space<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />- <strong>Thumbnail Grid</strong> – Jump instantly to any image<br />- <strong>Zero Dependencies</strong> (except optional </code>ffmpeg<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">)<br />- <strong>Video Export</strong> – Share as a single file<br />- <strong>Auto-open Results</strong> – Both HTML pages open automatically</p><p class="my-3">---<br /><h2 class="text-xl font-semibold mt-5 mb-3">Example Commands</h2></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">bash<br /><h1 class="text-2xl font-bold mt-6 mb-4">Quick slideshow only</h1><br />image-slideshow -f ./gallery</p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">Full package: slideshow + high-quality video</h1><br />image-slideshow -f ./gallery -v -t "My Portfolio 2025" --quality high --duration 6</p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">Fast video for social media</h1><br />image-slideshow -f ./memories -v --quality low --duration 2 --fps 24</p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">Only PNG/WEBP images, custom output name</h1><br />image-slideshow -f ./art -v --pattern png,webp -o gallery.html<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3">---<br /><h2 class="text-xl font-semibold mt-5 mb-3">Output Structure (with </code>-v<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">)</h2></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />./your-folder/<br />├── image1.jpg<br />├── image2.png<br />├── ...<br />├── slideshow.html ← Interactive viewer<br />├── slideshow.webm ← Video file<br />└── show-video.html ← Full-screen video player (opens automatically)<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3">---<br /><h2 class="text-xl font-semibold mt-5 mb-3">Requirements for Video Export</h2></p><p class="my-3">Make sure </code>ffmpeg<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> is installed:</p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">bash<br /><h1 class="text-2xl font-bold mt-6 mb-4">macOS</h1><br />brew install ffmpeg</p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">Ubuntu/Debian</h1><br />sudo apt update && sudo apt install ffmpeg</p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">Windows</h1><br /><h1 class="text-2xl font-bold mt-6 mb-4">Download from: https://ffmpeg.org/download.html</h1><br /><h1 class="text-2xl font-bold mt-6 mb-4">or use: choco install ffmpeg</h1><br /></code>``</p><p class="my-3">---<br /><h2 class="text-xl font-semibold mt-5 mb-3">License</h2></p><p class="my-3">MIT License © 2025 <br />Mohan Chinnappan<br /></p></div><div class="flex justify-center absolute inset-x-0 bottom-0 bg-gradient-to-t from-background via-background to-transparent pb-4 pt-16"><button data-slot="button" class="inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down mr-1 h-4 w-4"><path d="m6 9 6 6 6-6"></path></svg>Show more</button></div></div></div><template id="P:3"></template><template id="P:4"></template></div></div></div><div hidden id="S:3"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-dependencies" hidden="" id="radix-_R_aav5ubrb_-content-dependencies" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS=function(a,b){a=document.getElementById(a);b=document.getElementById(b);for(a.parentNode.removeChild(a);a.firstChild;)b.parentNode.insertBefore(a.firstChild,b);b.parentNode.removeChild(b)};$RS("S:3","P:3")</script><div hidden id="S:4"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-versions" hidden="" id="radix-_R_aav5ubrb_-content-versions" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS("S:4","P:4")</script><script>$RC("B:1","S:1")</script></body></html>