11 KiB

Raw Permalink Blame History

🌀 Hypno Gallery - Immersive Slideshow System

Overview

The Hypno Gallery is an advanced, feature-rich slideshow application designed for creating immersive visual experiences. It supports recursive directory scanning, multiple slideshow management, customizable timing patterns, and sophisticated visual effects.

Current Features

📋 Slideshow Management

Multiple Slideshow Support: Create, save, load, and manage multiple slideshow configurations
Slideshow Playlists: Each slideshow can have its own directories, settings, and configurations
Persistent Storage: Slideshows are automatically saved to localStorage and persist between sessions
Duplicate & Share: Clone existing slideshows for quick customization
Import/Export: Load existing slideshows or create new ones

📁 Directory Management

Recursive Directory Scanning: Automatically finds all images in directories and subdirectories
Multiple Directory Support: Add multiple image directories to a single slideshow
Space-Friendly Path Handling: Properly handles directory names with spaces
Real-time Directory Updates: Add/remove directories from active slideshows
Cross-Platform Path Support: Works with Windows, macOS, and Linux file paths

⏱️ Advanced Timing System

Constant Duration: Fixed timing between image transitions
Random Range: Variable timing within a specified min/max range
Wave Pattern: Sinusoidal timing that creates rhythmic acceleration/deceleration
Customizable Parameters: Fine-tune wave amplitude, frequency, and base timing

🖼️ Image Handling

Multiple Format Support: JPG, PNG, GIF, BMP, WebP, SVG, TIFF, ICO
Smart Image Ordering: Random shuffle, sequential, or reverse order
Flexible Display Modes:
- Contain: Fit entire image within screen bounds
- Cover: Fill screen, cropping if necessary
- Stretch: Fill screen, distorting aspect ratio if needed
Memory Efficient: Loads images on-demand with preloading optimization

✨ Transition Effects

Fade Transitions: Smooth cross-fade between images
Customizable Duration: Adjust transition timing (100ms - 2s)
Instant Switching: Option for no transitions for rapid changes
GPU Accelerated: Hardware-accelerated CSS transitions for smooth performance

🎨 Background Customization

Solid Colors: Customizable solid background colors
Gradient Backgrounds: Linear gradients with multiple direction options
Blurred Image Backgrounds: Dynamic blurred version of current image
Opacity Control: Adjustable background opacity and blur intensity
Real-time Preview: Live preview of background changes

🎮 Interactive Controls

Fullscreen Experience: Immersive fullscreen slideshow mode
Mouse Controls: Auto-hiding UI elements, show on mouse movement
Keyboard Shortcuts: Space to pause/resume, arrow keys for navigation, Escape to exit
Progress Indicator: Optional progress bar showing slideshow advancement
Real-time Information: Current image counter, timing info, slideshow status

📷 Captured Photo Integration

Webcam Integration: Include photos captured from webcam sessions
Mixed Media: Combine directory images with captured photos
Flexible Inclusion: Toggle captured photos on/off per slideshow

💾 Data Persistence

Auto-Save Settings: All settings automatically saved to localStorage
Session Recovery: Resume slideshow configurations after restart
Export/Import Ready: Prepared for future backup/restore functionality

File Structure

hypno-gallery.html          # Main application file
src/
├── core/
│   ├── main.js            # Electron main process (includes recursive image scanner)
│   └── preload.js         # IPC bridge (exposes readImageDirectoryRecursive)
├── styles/
│   ├── styles.css         # Base application styles
│   └── styles-dark-edgy.css # Dark theme styles
└── utils/
    └── desktop-file-manager.js # File system utilities

Usage Guide

Getting Started

Launch Application: Open hypno-gallery.html in the electron app
Create Slideshow: Click "🎬 New" to create your first slideshow
Add Directories: Use "📁 Add Directory" to select image folders
Configure Settings: Customize timing, transitions, and visual effects
Start Experience: Click "🌀 Start Hypno Gallery" to begin

Slideshow Management

// Creating a new slideshow
1. Click "🎬 New" button
2. Enter slideshow name
3. Click "✅ Create"

// Loading existing slideshow
1. Click "📁 Load" button
2. Select from dropdown
3. Click "✅ Load"

// Adding directories to slideshow
1. Load or create a slideshow
2. Click "📁 Add Directory" 
3. Select folder containing images
4. Directory is recursively scanned and added

Advanced Configuration

Timing Patterns

Constant: duration = 3000ms (3 seconds per image)
Random: min = 1500ms, max = 5000ms (random between 1.5-5 seconds)
Wave: waveMin = 1000ms, waveMax = 5000ms, rate = 100 (sinusoidal pattern)

Transition Types

Fade: Smooth cross-fade transition with customizable duration
None: Instant image switching for rapid-fire effects

Background Modes

Solid: Single color background
Gradient: Linear gradient from color A to color B
Blurred: Dynamically blurred version of current image

Technical Implementation

Recursive Directory Scanning

The application uses a main process function for reliable directory traversal:

// Main process implementation (main.js)
ipcMain.handle('read-image-directory-recursive', async (event, dirPath) => {
    // Recursive scanning with fs.readdir and fs.stat
    // Handles subdirectories and file filtering
    // Returns array of image file objects with metadata
});

// Renderer usage (hypno-gallery.html)
const images = await window.electronAPI.readImageDirectoryRecursive(directoryPath);

Image Loading Pipeline

Directory Scanning: Recursively find all image files
Metadata Extraction: File size, path, format detection
Preprocessing: Path normalization, title generation
Memory Management: On-demand loading with preloading optimization

Performance Optimizations

GPU Acceleration: CSS transitions and transforms
Memory Efficiency: Image preloading with memory limits
File System Caching: Reduced redundant directory scans
Event Throttling: Optimized mouse movement and resize handlers

Future Implementations

🎯 Planned Features (Near-term)

📱 Grid Functionality

Multi-Slideshow Grid System:
- Display multiple slideshows simultaneously
- 2x2, 3x3, or custom grid layouts
- Independent timing and settings per grid cell
- Synchronized or independent playback modes
- Grid-specific transition effects (wave patterns across cells)

📝 Text Overlay System

Dynamic Text Integration:
- Customizable text overlays on images
- Multiple font options and styles
- Position presets (center, corners, custom)
- Text animation effects (fade in/out, scroll, pulse)
- Per-slideshow text configuration
- Image-specific text metadata support

🎵 Audio Integration

Synchronized Audio Experience:
- Background music support
- Audio track per slideshow
- Beat-synchronized image timing
- Audio visualization elements
- Volume and fade controls

🎨 Advanced Visual Effects

Enhanced Visual Processing:
- Image filters (sepia, blur, contrast, saturation)
- Color correction and enhancement
- Edge detection and artistic effects
- Real-time image transformation
- GPU-accelerated filter pipeline

🚀 Advanced Features (Long-term)

🌐 Network Capabilities

Cloud and Network Features:
- Cloud storage integration
- Network directory mounting
- Remote slideshow control
- Multi-device synchronization
- Collaborative slideshow creation

🤖 AI-Enhanced Features

Intelligent Automation:
- AI-powered image categorization
- Smart slideshow generation based on content
- Mood-based timing adjustment
- Automatic image enhancement
- Content-aware transitions

📊 Analytics and Insights

Usage Analytics:
- Slideshow viewing statistics
- Image popularity tracking
- Timing pattern analysis
- User interaction heatmaps
- Performance metrics dashboard

🎮 Interactive Elements

Enhanced Interactivity:
- Touch gesture support
- Voice control integration
- Eye-tracking compatibility
- Biometric feedback integration
- Interactive hotspots on images

Configuration Examples

Basic Slideshow Setup

// Example slideshow configuration
const slideshowConfig = {
    name: "Nature Photography",
    directories: [
        "E:/Photos/Nature",
        "E:/Photos/Landscapes"
    ],
    settings: {
        timingMode: "random",
        minDuration: 2000,
        maxDuration: 6000,
        transitionType: "fade",
        transitionDuration: 800,
        backgroundType: "blurred",
        fitMode: "cover"
    },
    includeCapturedPhotos: false
};

Advanced Wave Timing

// Wave timing for hypnotic effects
const hypnoConfig = {
    timingMode: "wave",
    waveMin: 500,      // Fastest: 0.5 seconds
    waveMax: 4000,     // Slowest: 4 seconds
    waveRate: 50,      // Wave frequency
    transitionType: "fade",
    transitionDuration: 1200
};

API Reference

Core Functions

loadImagesFromDirectory(path): Recursively scan directory for images
startSlideshow(): Initialize and begin slideshow playback
pauseSlideshow(): Pause/resume slideshow
stopSlideshow(): Stop and exit slideshow mode
createSlideshow(name): Create new slideshow configuration
loadSlideshow(name): Load existing slideshow
saveSlideshow(): Persist current slideshow settings

Event Handlers

onImageLoad: Triggered when new image is loaded
onTimingChange: Fired when timing pattern changes
onTransitionComplete: Called after transition finishes
onSlideshowEnd: Triggered when slideshow completes loop

Browser Compatibility

Electron: Full feature support (recommended)
Chrome/Edge: Core features supported
Firefox: Core features supported
Safari: Limited support (no file system access)

Performance Notes

Recommended: 500+ images per slideshow
Memory Usage: ~50MB for 1000 images
File Formats: All modern image formats supported
Directory Depth: No practical limit on subdirectory scanning

Troubleshooting

Common Issues

Images not loading: Check directory permissions and file formats
Slideshow won't start: Ensure at least one directory is added with images
Transitions choppy: Reduce image size or transition duration
Directory not found: Verify path exists and contains supported image files

Debug Mode

Enable debug logging by opening browser console - all operations are logged with detailed information.

Version: 2.0.0
Last Updated: November 2025
Platform: Electron Desktop Application
License: Proprietary

11 KiB Raw Permalink Blame History