A cross-platform desktop application that provides ambient soundscapes for productivity and relaxation. Built with Electron.js, HTML, TailwindCSS, and vanilla JavaScript.

• 5 Ambient Sounds: Rain, Forest, Ocean, Campfire, and Wind
• Individual Volume Controls: Mix multiple sounds with precise volume sliders
• Save Custom Presets: Save your favorite sound combinations
• Background Operation: Runs quietly in the system tray
• Auto-start Support: Launch automatically on system boot
• Dark/Light Themes: Beautiful, calming interface
• Timer Functionality: Set focus/relaxation sessions
• Offline-first: Works completely without internet
• Cross-platform: Windows, macOS, and Linux support

• Node.js (v16 or higher)
• npm or yarn

1. Clone the repository

   git clone https://github.com/iOnlyGhost/calmdesk.git
   cd calmdesk

2. Install dependencies

   npm install

3. Add Audio Files (Required for full functionality)

   Place the following audio files in the assets/sounds/ directory:

   • rain.mp3 - Rain/precipitation sounds
   • forest.mp3 - Forest birds and nature sounds
   • ocean.mp3 - Ocean waves and water sounds
   • campfire.mp3 - Crackling fire sounds
   • wind.mp3 - Wind and air movement sounds

   Audio Requirements:

   • Format: MP3 or WAV
   • Quality: 44.1kHz, 16-bit minimum
   • Duration: 30-60 seconds (seamlessly looped)
   • Volume: Normalized to prevent clipping

4. Add Icons (Optional)

   Place application icons in the assets/icons/ directory:

   • icon.ico - Windows icon
   • icon.icns - macOS icon
   • icon.png - Linux icon (512x512)
   • tray-icon.png - System tray icon (32x32)

5. Run the application

   npm start

• npm start - Run the application in development mode
• npm run dev - Run with development tools enabled
• npm run build - Build for all platforms
• npm run build-win - Build for Windows only
• npm run build-mac - Build for macOS only
• npm run build-linux - Build for Linux only
• npm run pack - Create unpacked builds for testing
• npm run dist - Create distribution packages

CalmDesk/
├── main.js              # Electron main process
├── index.html           # Main UI (based on ui_reference.html)
├── package.json         # Dependencies and build config
├── ui_reference.html    # UI design reference
├── js/                  # JavaScript modules
│   ├── preload.js       # Secure IPC bridge
│   ├── audio-manager.js # Web Audio API implementation
│   ├── ui-controller.js # UI state management
│   └── storage.js       # Settings and presets
├── assets/              # Static assets
│   ├── sounds/          # Audio files (add your own)
│   ├── icons/           # App icons (add your own)
│   └── README.md        # Asset requirements

Main Process (main.js)

• Handles app lifecycle and system integration
• Manages settings persistence with electron-store
• Creates system tray and auto-launch functionality
• Provides secure IPC communication

Renderer Process (index.html + JS modules)

• AudioManager: Web Audio API for seamless sound mixing
• UIController: Interactive UI state management
• Storage: Data persistence and backup utilities
• Preload: Secure bridge between main and renderer

• Electron.js: Cross-platform desktop framework
• Web Audio API: Professional audio mixing and playback
• TailwindCSS: Utility-first CSS framework
• Material Symbols: Consistent iconography
• electron-store: Persistent settings storage
• auto-launch: System startup integration

The interface follows a clean, modern design with:

• Color Palette: Calming green (#5ae7b8) with dark/light themes
• Typography: Inter font family for readability
• Layout: Responsive grid (2/3/5 columns) for sound cards
• Animations: Subtle transitions and hover effects
• Progressive Disclosure: Volume controls appear on interaction

1. Select Sounds: Click on sound cards to activate them
2. Adjust Volume: Use individual sliders to mix sounds
3. Save Presets: Click "Save Mix" to store favorite combinations
4. Set Timer: Use "Set Timer" for focus/relaxation sessions
5. Play All: Start/stop all sounds with current volume levels

When minimized, CalmDesk runs in the system tray:

• Double-click: Show/hide main window
• Right-click: Access context menu with controls
• Notifications: Timer completion alerts

• Auto-launch: Start with system boot
• Theme: Switch between dark/light modes
• Master Volume: Global volume control
• Sound Preferences: Individual sound settings

• Windows: %APPDATA%/calmdesk/config.json
• macOS: ~/Library/Application Support/calmdesk/config.json
• Linux: ~/.config/calmdesk/config.json

{
  "autoLaunch": false,
  "theme": "dark",
  "masterVolume": 0.7,
  "soundsEnabled": {
    "rain": false,
    "forest": false,
    "ocean": false,
    "campfire": false,
    "wind": false
  },
  "soundVolumes": {
    "rain": 0.5,
    "forest": 0.5,
    "ocean": 0.5,
    "campfire": 0.5,
    "wind": 0.5
  }
}

• electron-builder: For creating installers
• Platform-specific: Build on target OS for best compatibility
• Code Signing: Required for macOS/Windows distribution

The build process is configured in package.json under the build section:

• Windows: NSIS installer with desktop/start menu shortcuts
• macOS: DMG with proper app bundle structure
• Linux: AppImage for maximum compatibility

1. Update version in package.json
2. Test on all target platforms
3. Run platform-specific build commands
4. Sign binaries (production only)
5. Upload to distribution channels

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly on your platform
5. Submit a pull request

• Follow existing code style and structure
• Test audio functionality with real sound files
• Ensure cross-platform compatibility
• Update documentation for new features
• Add unit tests for new functionality

MIT License - see LICENSE file for details

App won't start

• Check Node.js version (v16+ required)
• Run npm install to update dependencies
• Verify no conflicting Electron processes

No sound playback

• Add actual audio files to assets/sounds/
• Check audio file format (MP3/WAV supported)
• Verify Web Audio API browser support

Tray icon missing

• Add proper icon file to assets/icons/tray-icon.png
• Check icon format and dimensions (32x32 PNG)
• Restart application after adding icon

Build failures

• Update electron-builder to latest version
• Check platform-specific build requirements
• Verify code signing certificates (if applicable)

• Keep sound files under 5MB each
• Use efficient audio formats (OGG/MP3)
• Monitor memory usage with large audio files
• Test with multiple simultaneous sounds

• Project Repository: https://github.com/iOnlyGhost/CalmDesk
• Documentation: Full docs available in the repository
• Issues: Report bugs via GitHub Issues
• Discussions: Feature requests and community support

Built with 💚 for productivity and relaxation