Hello, I’m excited to introduce PhotoShuffle, a lightweight Elixir library designed for managing image collections with intelligent metadata generation. It’s built specifically for portfolio sites, galleries, and applications that need to turn a directory of files into a structured, randomized display.
Features
PhotoShuffle handles the “boring” parts of building a gallery by automating metadata:
-
Intelligent Shuffling: Easily shuffle and select a specific number of images from your collections. -
Smart Titles: Automatically generates human-readable titles from filenames (e.g., IMG_5366.jpgbecomes “Professional Installation Project”). -
Deterministic Locations: Uses path hashing to assign consistent locations to images from a configurable list, ensuring a photo doesn’t “move” cities every time you refresh the page. -
Pluggable File Systems: Built with a behavior-based design, making it easy to mock file system interactions in your tests using tools like Mox. -
Zero Runtime Dependencies: Keeps your project lean with no external runtime requirements.
Quick Start
You can process a directory and shuffle the results in just a few lines:
Elixir
# Process images from a directory with a specific category context
{:ok, images} = PhotoShuffle.process_images("/path/to/images", "Portfolio")
# Shuffle and select 6 random images
selected = PhotoShuffle.shuffle_images(images, 6)
Usage in Phoenix LiveView
It integrates cleanly into a LiveView mount or handle_event:
Elixir
def mount(_params, _session, socket) do
path = Application.app_dir(:my_app, "priv/static/images/gallery")
{:ok, all_images} = PhotoShuffle.process_images(path, "Gallery")
displayed_images = PhotoShuffle.shuffle_images(all_images, 8)
{:ok, assign(socket, images: displayed_images, all_images: all_images)}
end
The Story Behind PhotoShuffle
The idea for PhotoShuffle emerged while building portfolio sites and photo galleries, specifically for contractors in the construction space. I found myself repeatedly writing the same logic to parse filenames, generate “fake-but-consistent” metadata like locations, and handle randomized layouts.
I wanted a way to point a library at a folder of images and get back a structured list of maps ready for a Phoenix template, without manually tagging every single file. By using deterministic hashing for locations and smart string parsing for titles, PhotoShuffle makes static image folders feel like a dynamic, managed database.
Hex: https://hex.pm/packages/photo_shuffle
GitHub:
I’d love to hear your thoughts or any features you’d like to see added!
