slideshow

# Slideshow > *"The camera is the pickaxe. The slideshow is the museum."* > > *"Every image tells a story. The slideshow tells THE story."* The **Slideshow** skill presents generated images as linear visual narratives. While the [Visualizer](../visualizer/) creates images, the Slideshow **presents** them — synthesizing metadata from prompts and mining sidecars into scrollable stories. --- ## Philosophy Images live in directories. Directories accumulate chaos. A SLIDESHOW.md transforms that chaos into narrative: - **Time-ordered** entries create journeys - **Metadata synthesis** extracts meaning - **Death-scrollable** layout works everywhere - **Encapsulation** keeps related files together Think of it as the **museum** for your visual **mining operation**. --- ## Stereo Slideshows: YML + MD > *"The left eye sees truth. The right eye sees story. Together: depth perception."* A **stereo slideshow** maintains two complementary files: | File | Role | Purpose | |------|------|---------| | `SLIDESHOW.yml` | **Left Eye** | Machine-readable source of truth | | `SLIDESHOW.md` | **Right Eye** | Human-readable narrative for GitHub | ### Why Two Files? **SLIDESHOW.yml** (Source of Truth): - Structured data the compiler can read - Photo metadata, locations, room references - No prose, just semantic facts - Stable structure for tooling **SLIDESHOW.md** (Narrative View): - Rich markdown for GitHub display - Images inline, captions, stories - Death-scrollable presentation - Generated FROM the YML ### The SYNC Protocol ``` ┌─────────────────────────────────────────────────────────────────┐ │ STEREO SLIDESHOW SYNC │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ SLIDESHOW.yml (left eye) SLIDESHOW.md (right eye) │ │ ┌─────────────────────┐ ┌─────────────────────────┐ │ │ │ id: slideshow/pub │ │ # 📸 Pub Photo Gallery │ │ │ │ name: Pub Gallery │ ───▶ │ > *"Opening quote..."* │ │ │ │ location: room/pub │ SYNC │ │ │ │ │ contents: │ │ ## Shot 1: The Bar │ │ │ │ - dir: bar-shot │ │  │ │ │ │ subject: ... │ │ **Location:** The Bar │ │ │ └─────────────────────┘ └─────────────────────────┘ │ │ │ │ EDIT the YML → SYNC generates MD │ │ The YML is the single source of truth │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### SLIDESHOW.yml Format ```yaml # SLIDESHOW.yml — Machine-readable slideshow definition id: slideshow/pub/photos name: "Pub Photo Gallery" type: slideshow location: room/pub # Links to compiled room tagline: "Memories from the Gezelligheid Grotto" # Photo metadata contents: - dir: bar-shot-2026-01-19 subject: "Marieke at the bar" mood: warm role: ESTABLISHING image: bar-marieke.png - dir: palm-cats-2026-01-19 subject: "Palm with the cats" mood: cozy role: DETAIL image: palm-cats.png # Optional: narrative hints for MD generation narrative: opening_quote: "The best nights are the ones you almost remember..." style_notes: "First-person phone camera, golden hour lighting" # Compiler uses this to link slideshow to room compiled: room_ref: room/pub photo_count: 2 ``` ### Photo Directory Structure (Stereo) Each photo can also be stereo: ``` photo-directory/ PHOTO.yml # Left eye: metadata, generation settings PHOTO.md # Right eye: narrative description main-image.png # The actual image MINING-*.yml # Mining layer files ``` **PHOTO.yml** (metadata): ```yaml subject: primary: "Marieke serving drinks" secondary: ["Palm", "cats"] mood: warm camera: type: "iPhone 15 Pro" settings: { aperture: 1.8, iso: 800 } generation: provider: dalle3 prompt: "..." ``` **PHOTO.md** (narrative): ```markdown # Marieke at the Bar The warm glow of Edison bulbs catches the brass fixtures as Marieke pours a perfect pint... ``` ### Commands ``` SYNC SLIDESHOW [directory] ``` Regenerates `SLIDESHOW.md` from `SLIDESHOW.yml`. ``` CREATE STEREO SLIDESHOW FOR [directory] ``` Creates both YML (from scanning directory) and MD (from YML). ``` UPDATE SLIDESHOW YML [directory] ``` Scans for new photos and updates the YML source of truth. --- ## The CREATE Method Generate a SLIDESHOW.md for a directory of images: ``` CREATE SLIDESHOW for pub/dons-photos-2026-01-19/ ``` **What happens:** 1. **Discover** images in directory (`.png`, `.jpg`, `.webp`) 2. **Find sidecars** for each image (`.yml` prompt, `-mined.yml` resources) 3. **Order** by timestamp in filename or file creation time 4. **Synthesize** narrative descriptions from metadata 5. **Write** SLIDESHOW.md with gallery structure --- ## The LANDING Method Create a README.md landing page for GitHub display: ``` LANDING for pub/dons-pub-photos-2026-01-19/ ``` **Why README.md?** GitHub renders `README.md` automatically when you browse a directory, but not `SLIDESHOW.md`. The landing page is the **front door** — motivating visitors to read the story. ``` ┌─────────────────────────────────────────────────────────────────┐ │ README.md (Landing Page) SLIDESHOW.md (Story) │ ├─────────────────────────────────────────────────────────────────┤ │ ✓ Shown on GitHub automatically ✗ Must click to view │ │ ✓ Metadata table Pure narrative flow │ │ ✓ Character links No links — just story │ │ ✓ Location links No context jumps │ │ ✓ Story summary (fresh!) Full detailed story │ │ → "View the slideshow" The actual experience │ └─────────────────────────────────────────────────────────────────┘ ``` **What goes in README.md:** | Section | Content | |---------|---------| | Title + Tagline | Hook the reader | | Gallery Info | Slide count, date, style, location | | Featuring | Characters with links to their directories | | Locations | Rooms with links to their directories | | Story Summary | Fresh synthesis — "why should I look at these?" | | Preview | Optional image grid | | Technical | Mining layers, generator | **Key insight:** The story summary is **freshly synthesized**, not copy-pasted from SLIDESHOW.md. It answers: *"What will I experience if I click through?"* **Workflow:** ``` 1. CREATE SLIDESHOW # Generate the story 2. ORGANIZE INTO dirname # Encapsulate files 3. LANDING # Create GitHub front door ``` --- ## The ORGANIZE Method Encapsulate a SLIDESHOW.md and its images into a named subdirectory: ``` ORGANIZE pub/SLIDESHOW.md INTO dons-pub-photos-2026-01-19 ``` **Before:** ``` pub/ SLIDESHOW.md dons-photos-2026-01-19-16-30-00-bar-marieke-palm-cats.png dons-photos-2026-01-19-16-30-00-bar-marieke-palm-cats.yml dons-photos-2026-01-19-16-30-00-bar-marieke-palm-cats-mined.yml ...20 more files... ``` **After:** ``` pub/ dons-pub-photos-2026-01-19/ SLIDESHOW.md # Inherits from slideshow skill bar-marieke-palm-cats.png bar-marieke-palm-cats.yml bar-marieke-palm-cats-mined.yml ...all files moved and renamed... ``` **Naming convention:** `lowercase-dashes`, descriptive, date-suffixed if temporal. --- ## SLIDESHOW.md Format Every SLIDESHOW.md should declare inheritance: ```yaml --- inherits: slideshow title: "Don's Pub Photos — January 19, 2026" created: 2026-01-19 images: 8 style: first-person-phone-camera --- ``` ### Structure ```markdown # 📸 Title > *"Opening quote capturing the vibe"* Brief description of what this gallery contains. --- ## 📍 Shot 1: Location (Time) ### *"Caption quote"*  **Location:** Where this was taken **Who's Here:** - 👩🌷 Character 1 doing something - 🐒🌴 Character 2 doing something else 📎 **Files:** [Prompt](image-file.yml) | [Resources](image-file-mined.yml) --- ## 📍 Shot 2: Next Location (Time) ... --- ## 📊 Stats Table | Time | Location | Highlights | |------|----------|------------| | 4:30 PM | Bar | Marieke, Palm, cats | | ... | ... | ... | --- ## 🎨 Style Notes Notes on artistic direction, visual consistency, mood. --- *"Closing quote"* ``` --- ## Metadata Synthesis The SUMMARIZE method transforms raw sidecar data into narrative: **From prompt.yml:** - Scene description → Location - Characters present → Who's Here - Time of day → Shot timing - Artistic style → Style notes **From prompt-mined.yml:** - Dominant colors → Visual palette - Mood/atmosphere → Emotional tone - Implied sounds/smells → Sensory details - Symbolism → Deeper meaning **Output:** Human-readable narrative that tells the story. --- ## Integration with Visualizer The Visualizer creates. The Slideshow presents. ``` ┌─────────────────────────────────────────────────────────────────┐ │ VISUAL PIPELINE │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Context YAML → Visualizer → Image + Sidecars │ │ (rooms, chars) (generate) (.png, .yml) │ │ │ │ Image + Sidecars → Image Miner → Resources │ │ (extract) (-mined.yml) │ │ │ │ All Files → Slideshow → SLIDESHOW.md │ │ (present) (narrative) │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` **Visualizer advertises to Slideshow:** ```yaml # In visualizer/CARD.yml advertisements: SLIDESHOW: delegates_to: slideshow score: 85 condition: "After generating images, create/update gallery" ``` --- ## Gallery Discovery Slideshows can be discovered and linked: ```bash # Find all slideshows in adventure-4 find examples/adventure-4 -name "SLIDESHOW.md" ``` Cross-slideshow navigation: ```markdown **Related Galleries:** - [Palm's Study](../stage/palm-nook/study/palm-study-images/SLIDESHOW.md) - [Attic Adventures](../attic/dusty-attic-images/SLIDESHOW.md) ``` --- ## Why Encapsulate? **Without encapsulation:** ``` pub/ ROOM.yml SLIDESHOW.md guestbook.yml fireplace.yml 20 image files... 20 prompt files... 20 mining files... # Chaos. What belongs together? ``` **With encapsulation:** ``` pub/ ROOM.yml guestbook.yml fireplace.yml dons-pub-photos-2026-01-19/ SLIDESHOW.md all-related-files... rooftop-telescope-images/ SLIDESHOW.md all-related-files... ``` **Benefits:** - Files that belong together STAY together - Directory name is descriptive - Easy to move, share, archive - No pollution of parent directory - SLIDESHOW.md becomes the index --- ## Example Workflow ``` # 1. Generate images with visualizer visualize.py character.yml room.yml -p openai # 2. Mine resources from images mine.py *.png --depth full # 3. Create slideshow gallery CREATE SLIDESHOW for current directory # 4. Organize into encapsulated directory ORGANIZE SLIDESHOW.md INTO palm-portrait-session-2026-01-19 # 5. Result: clean, self-contained gallery ``` --- ## Death-Scrollable Design SLIDESHOW.md targets GitHub rendering: - **Mobile-first:** Images scale, text wraps - **Death-scrollable:** Just keep scrolling - **Inline images:** No external links needed - **Collapsible sections:** For detailed metadata - **Emoji headers:** Visual navigation - **Tables:** Stats and comparisons --- ## James Burke Connections Every good slideshow tells a story through connections: > **How do these images connect?** > - Shot 1 introduces the setting > - Shot 3 shows the characters in that setting > - Shot 5 captures the climax > - Shot 8 is the aftermath, full circle The metadata enables this synthesis — prompts describe intent, mining reveals what emerged. --- ## Commands Reference | Method | Purpose | |--------|---------| | CREATE | Generate SLIDESHOW.md for directory | | UPDATE | Add new images to existing gallery | | SUMMARIZE | Synthesize metadata into narrative | | ORGANIZE | Encapsulate into subdirectory | | COMPARE | Cross-image comparison section | --- ## 🔧 UPGRADE: Legacy Slideshow Migration > *Future feature — not yet implemented* UPGRADE is super flexible. Start with ANYTHING: - Single file with list of prompts (YML or MD) - Dir full of loose images (reverse-engineer prompts via mining) - Just prompts (generate images later!) - Mixed chaos - Even empty dirs with just ideas **Input option A — Single prompt list file:** ``` my-ideas.yml (or my-ideas.md) ``` → Breaks into individual prompts, removes original, creates full structure **Input option B — Dir of images:** ``` messy-folder/ ├── 2026-01-19-dusk-scene-v3.png ├── morning-light-final.png └── random-sketch.jpg ``` → Mines images for prompts (mine prompt mode), structures everything **Input option C — Mixed chaos (images + prompts + whatever):** ``` messy-folder/