🧘 Wisdom Timer

A beautiful, modern meditation timer with ambient sounds, interval bells, and a stunning gradient UI.

🌐 Live Demo: https://wisdomtimer.app/

✨ Features

✅ Custom timer - Specify any duration with minute/second inputs (default: 45 minutes) ✅ Preset buttons - Quick access to 30, 45, 60, 90 minute sessions ✅ Singing bowl start bell - Beautiful Tibetan singing bowl when meditation begins ✅ Woodblock interval bell - Gentle knock-on-wood for periodic reminders ✅ Gling end bell - Pure resonant tone (35.5s sustain) when meditation completes ✅ Enlightenment burst - Stunning 9-second sunburst animation on completion with three pulsing waves ✅ Ambient sounds - Rain, ocean, forest (seamless looping) ✅ Volume controls - Separate controls for bells and ambient sounds ✅ Keyboard shortcuts - Space to play/pause, R to reset ✅ Settings persistence - Automatically saves your preferences ✅ Responsive design - Beautiful on mobile, tablet, and desktop ✅ Modern UI - Warm gradient background with glass-morphism effects ✅ Smart audio loading - Bells preload before ambient sounds for instant playback

🚀 Getting Started

Prerequisites

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

Installation

# Install dependencies
npm install

# Start development server
npm run dev

Open http://localhost:5173 in your browser.

Build for Production

npm run build
npm run preview

🔊 Audio Files

The app includes the following audio files in the public/audio directory:

Audio Files Structure

public/
└── audio/
    ├── bells/
    │   ├── bell-start.mp3       # Plays when meditation starts
    │   ├── bell-interval.mp3    # Plays at intervals (if enabled)
    │   └── bell-end.mp3         # Plays when meditation completes
    └── ambient/
        ├── rain.mp3             # Rain ambience
        ├── ocean.mp3            # Ocean waves
        └── forest.mp3           # Forest sounds

⌨️ Keyboard Shortcuts

• Space - Play/Pause timer
• R - Reset timer

🛠️ Tech Stack

• React 19 - UI library with latest features
• Vite 7 - Lightning-fast build tool
• Tailwind CSS v4 - Utility-first CSS with custom theme
• Lucide React - Beautiful, consistent icons
• Context API + Reducer - State management
• LocalStorage - Settings persistence

📁 Project Structure

src/
├── components/
│   ├── Timer/              # Timer display and controls
│   │   ├── TimerDisplay.jsx
│   │   ├── TimerControls.jsx
│   │   └── CircularProgress.jsx
│   ├── Settings/           # Configuration components
│   │   ├── PresetButtons.jsx
│   │   ├── DurationSelector.jsx
│   │   ├── IntervalSettings.jsx
│   │   └── AmbientSoundSelector.jsx
│   └── UI/                 # Reusable UI components
│       ├── GlassCard.jsx
│       └── Button.jsx
├── hooks/                  # Custom React hooks
│   ├── useTimer.js         # Timer logic with accuracy
│   ├── useAudio.js         # Audio playback wrapper
│   └── useLocalStorage.js  # Persistent settings
├── context/                # State management
│   └── TimerContext.jsx    # Central state with reducer
├── utils/                  # Utility functions
│   ├── audioManager.js     # Audio system with fade effects
│   └── timeFormatter.js    # Time formatting utilities
├── constants/              # App constants
│   └── audioSources.js     # Audio file paths
├── App.jsx                 # Main application
├── main.jsx               # App entry point
└── index.css              # Global styles + Tailwind

🎨 Customization

Change Gradient Colors

Edit src/index.css:

@theme {
  --color-gradient-start: #FDE68A;  /* Light Yellow */
  --color-gradient-end: #F97316;    /* Vivid Orange */
}

Modify Preset Durations

Edit src/context/TimerContext.jsx:

const initialState = {
  duration: 2700, // 45 minutes default
  presetDurations: [1800, 2700, 3600, 5400], // 30, 45, 60, 90 min
  // Change to your preferred durations (in seconds)
};

Add More Ambient Sounds

1. Add audio file to public/audio/ambient/
2. Update src/constants/audioSources.js:

export const AMBIENT_SOUNDS = [
  // ... existing sounds
  { id: 'newSound', name: 'New Sound', path: '/audio/ambient/new-sound.mp3', icon: 'Music' },
];

🐛 Troubleshooting

Audio not playing

• Browser autoplay policy: Click the play button to initialize audio
• Missing files: Check that audio files exist in public/audio/ directories
• Check console: Open browser DevTools (F12) to see audio loading errors

Styling issues

• Tailwind not loading: Ensure @tailwindcss/postcss is installed
• Clear cache: Try npm run dev -- --force

Timer drift

• The timer uses Date.now() calculations to prevent drift from CPU throttling
• Should remain accurate even on slower devices or backgrounded tabs

📝 License

MIT License - feel free to use this project for personal or commercial purposes.

🙏 Audio Attribution

All audio files used in this project are licensed under CC0 1.0 Universal (Public Domain). While attribution is not legally required, we credit the following creators:

Bell Sounds

• Start Bell - "Singing Bell Hit 2" by ryancacophony Source: Freesound.org License: CC0 1.0 Universal (Public Domain)

• Interval Bell (Woodblock) - "Wood Block Hit" by thomasjaunism Source: Freesound.org License: CC0 1.0 Universal (Public Domain)

• End Bell - "Gling" by manuelsound Source: Freesound.org License: CC0 1.0 Universal (Public Domain)

Ambient Sounds

• Rain - "Light Gentle Rain" by Naturthusiast Source: Internet Archive License: CC0 1.0 Universal (Public Domain)

• Ocean Waves - "Birds With Ocean Waves on the Beach" by Naturthusiast Source: Internet Archive License: CC0 1.0 Universal (Public Domain)

• Forest - "Relaxing Nature Sounds - Birdsong Sound" by Naturthusiast Source: Internet Archive License: CC0 1.0 Universal (Public Domain)

🤝 Contributing

Contributions welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Share your audio recommendations

🌟 Future Enhancements

• Session history and statistics
• Multiple timer profiles
• Dark/light theme toggle
• Additional ambient sounds
• Guided meditation audio
• Progressive Web App (PWA) support
• Social sharing of meditation sessions
• Integration with meditation apps

---

Built with ❤️ for mindful moments

Enjoy your meditation! 🧘‍♀️✨