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.jpg becomes “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:

https://github.com/unaffiliatedstudios/photo_shuffle

I’d love to hear your thoughts or any features you’d like to see added!