# 🌀 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
1. **Launch Application**: Open `hypno-gallery.html` in the electron app
2. **Create Slideshow**: Click "🎬 New" to create your first slideshow
3. **Add Directories**: Use "📁 Add Directory" to select image folders
4. **Configure Settings**: Customize timing, transitions, and visual effects
5. **Start Experience**: Click "🌀 Start Hypno Gallery" to begin

### Slideshow Management
```javascript
// 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:

```javascript
// 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
1. **Directory Scanning**: Recursively find all image files
2. **Metadata Extraction**: File size, path, format detection
3. **Preprocessing**: Path normalization, title generation
4. **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
```javascript
// 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
```javascript
// 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
1. **Images not loading**: Check directory permissions and file formats
2. **Slideshow won't start**: Ensure at least one directory is added with images
3. **Transitions choppy**: Reduce image size or transition duration
4. **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