WebCloudCam Photobooth

A client-side web-based photobooth application that allows users to take 3 selfies with effects and frames, create collages, and automatically save everything to a user-selected folder. Built with vanilla HTML, CSS, and JavaScript - no frameworks required!

🎯 Project Overview

This is a standalone photobooth application that runs entirely in the browser. It's designed for events, parties, or personal use where you want to capture fun photos with effects and automatically save them to a local folder.

✨ Key Features

📸 Photo Capture

• 3 Photos per Session: Always captures exactly 3 photos
• 3-Second Countdown: Full countdown (3-2-1) before each photo
• Live Camera Preview: Real-time camera feed with effects and frames
• Automatic Collage: Creates a 600x1800 pixel collage strip automatically

🎨 Effects & Frames

• 6 Built-in Effects: Normal, B&W, Sepia, Vintage, Cartoon, Pixelated
• Frame Overlays: Support for PNG frames with alpha channels
• Real-time Preview: Effects and frames apply to live camera feed
• Baked-in Effects: Captured photos retain effects and frames permanently

⌨️ Hotkeys

• E: Cycle effects forward
• Q: Cycle effects backward
• F: Cycle frames forward
• R: Cycle frames backward
• Space: Take photos
• Configurable: All hotkeys can be customized in settings

🖥️ Display Modes

• Fullscreen Camera: Immersive camera view for taking photos
• Fullscreen Preview: Large view of captured photos and collage
• Responsive Design: Works on desktop and mobile devices

💾 File Management

• Permission-based Saving: Uses File System Access API when available
• Automatic Organization: Saves individual photos and collage with timestamps
• Fallback Download: Downloads files if folder access is denied
• No Server Required: Everything runs client-side

🖨️ Printing

• Direct Printing: Bypasses print dialog, sends directly to default printer
• Optimized Layout: 600x1800 pixel format perfect for photo strips
• Automatic Cleanup: Closes print windows automatically

🏗️ Architecture

Technology Stack

• Frontend: Vanilla HTML5, CSS3, JavaScript (ES6+)
• APIs: MediaDevices API, File System Access API, Canvas API
• Storage: LocalStorage for settings, File System for photos
• Printing: Window.print() with iframe optimization

Core Components

• Photobooth Class: Main application logic (1500+ lines)
• Settings Management: Camera, printer, hotkey configuration
• Permission System: Camera and file system access
• Effect Engine: Real-time image processing
• Frame System: PNG overlay management
• Print Engine: Direct printing without dialogs

File Structure

webcloudcam/
├── index.html          # Main HTML structure with settings and photobooth screens
├── styles.css          # Complete styling with responsive design and animations
├── photobooth.js       # Main application logic (Photobooth class)
├── README.md           # Project documentation and memory bank
├── .cursorrules        # Cursor IDE configuration
└── output/             # Generated photos and collages (user-created)

🚀 Getting Started

Prerequisites

• Modern web browser (Chrome 86+, Firefox 78+, Safari 14+, Edge 86+)
• Camera/webcam access
• File system access (for saving photos)

Installation

1. Clone or download the project files
2. Open index.html in a modern web browser
3. Grant camera and file system permissions when prompted
4. Configure settings and start taking photos!

First Time Setup

1. Camera Permission: Click "Camera Access" in permissions section
2. Save Permission: Click "Save Photos" to select output folder
3. Optional: Load frames folder for overlay effects
4. Optional: Configure hotkeys to your preference
5. Click "Start Photobooth" to begin

⚙️ Configuration

Settings Screen

• Camera Selection: Choose from available cameras/webcams
• Printer Selection: Select default printer (if available)
• Frames Folder: Load PNG frames for overlay effects
• Collage Background: Set custom background for photo strips
• Paper Size: Fixed at 600x1800 pixels (photobooth standard)
• Hotkeys: Customize all keyboard shortcuts

Permissions

• Camera Access: Required for photo capture
• Save Photos: Required for automatic file saving
• Frames Directory: Optional, for loading custom frames
• Microphone: Not required (photo-only application)

🎮 Usage Guide

Taking Photos

1. Start Session: Click "📸 Take Photos" or press Space
2. Countdown: Wait for 3-2-1 countdown before each photo
3. Capture: 3 photos are taken automatically with flash indicator
4. Save: Photos and collage are saved automatically to selected folder

Using Effects

• Live Preview: Effects apply immediately to camera feed
• Hotkeys: Press E/Q to cycle through effects
• Permanent: Effects are baked into captured photos
• Individual: Each photo retains its effect even if changed later

Using Frames

• File Input: Select frames folder in settings
• Hotkeys: Press F/R to cycle through frames
• Alpha Support: PNG frames with transparency work perfectly
• Overlay: Frames appear on live preview and captured photos

Printing

• Automatic: Click "🖨️ Print" to send directly to printer
• No Dialog: Bypasses browser print confirmation
• Optimized: Perfect sizing for photo strip printers
• Clean: No browser UI in printed output

🔧 Development

Code Organization

• Photobooth Class: Main application controller
• Settings Management: Configuration and persistence
• Permission System: Camera and file system access
• Effect Engine: Real-time image processing
• Frame System: PNG overlay management
• Print Engine: Direct printing implementation

Key Methods

• initializeCamera(): Camera setup and permissions
• startCapture(): Photo capture with countdown
• applyEffect(): Real-time effect processing
• createCollage(): Automatic collage generation
• saveImageToFolder(): File system saving
• printCollage(): Direct printing implementation

Browser Compatibility

• Chrome 86+: Full support (recommended)
• Firefox 78+: Full support with some limitations
• Safari 14+: Full support
• Edge 86+: Full support

Performance Considerations

• Canvas Processing: Effects applied via canvas for performance
• Memory Management: Proper cleanup of streams and event listeners
• File Handling: Efficient blob handling for saving
• Print Optimization: Hidden iframe for direct printing

🐛 Troubleshooting

Common Issues

• Camera Not Working: Check browser permissions and camera availability
• Effects Not Applying: Ensure camera is initialized and canvas is working
• Frames Not Showing: Verify PNG files and folder permissions
• Print Dialog Appears: Browser may block direct printing, use print preview
• Files Not Saving: Check file system permissions and folder access

Debug Features

• Debug Button: Click "🐛 Debug Info" in settings for detailed state
• Console Logging: Comprehensive logging for troubleshooting
• Permission Status: Visual indicators for all permissions
• Error Handling: Graceful fallbacks for all operations

Browser-Specific Issues

• Chrome: Best compatibility, recommended for production use
• Firefox: May show print dialog, file system access works
• Safari: Good support, some permission differences
• Edge: Full support, similar to Chrome

📋 Testing Checklist

Core Functionality

• Camera access and device selection
• All effects apply correctly to live preview
• Frame overlays work on camera and captured photos
• Hotkeys cycle through effects and frames
• Full countdown (3-2-1) before each photo
• Photos save to selected folder automatically
• Collage creates and saves correctly
• Print function works without dialog
• Fullscreen modes work properly
• Settings persist between sessions
• Permission requests work correctly
• Responsive design on mobile devices

Edge Cases

• No camera available
• File system access denied
• Print permissions blocked
• Browser compatibility issues
• Memory management
• Error handling and recovery

🔄 Version History

Current Version (v1.0)

• Complete photobooth functionality
• Permission-based file system access
• Direct printing without dialogs
• Hotkey system with reverse cycling
• Fullscreen camera and preview modes
• Automatic collage creation and saving

Recent Updates

• Fixed countdown timing for all photos
• Added reverse cycling for effects and frames
• Implemented permission-based file saving
• Optimized printing to bypass dialogs
• Enhanced error handling and debugging

🛠️ Development Workflow

Code Standards

• ES6+ JavaScript: Use modern features (async/await, arrow functions)
• Modular Design: Organize code into logical methods within Photobooth class
• Error Handling: Always include try-catch blocks for async operations
• Console Logging: Include debug logs for troubleshooting
• Comments: Document complex logic and important features

Testing Process

1. Feature Testing: Test each feature individually
2. Integration Testing: Test feature interactions
3. Browser Testing: Test across different browsers
4. Permission Testing: Test with and without permissions
5. Error Testing: Test error conditions and edge cases

Memory Bank Updates

When making changes to the application:

1. Update the relevant sections in README.md
2. Add new features to the features list
3. Update the architecture section if needed
4. Document any new configuration options
5. Update the testing checklist
6. Note any breaking changes or new requirements

🧠 Memory Bank Information

This README.md serves as the project's memory bank, containing:

• Complete feature documentation
• Architecture and technical details
• Development guidelines and workflows
• Testing procedures and checklists
• Troubleshooting guides
• Version history and updates

Memory Bank Maintenance

• Always update README.md when adding new features
• Keep testing checklist current with new test cases
• Document breaking changes and migration steps
• Update browser compatibility information
• Maintain troubleshooting section with new issues

📄 License

This project is open source and available under the MIT License.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly using the testing checklist
5. Update README.md if adding new features
6. Submit a pull request

📞 Support

For issues, questions, or contributions:

• Check the troubleshooting section
• Use the debug button for detailed information
• Review browser compatibility requirements
• Test with different browsers and devices

---

Note: This README serves as the project's memory bank and should be updated whenever significant changes are made to maintain accurate documentation.