TheNoiseClock/PRD.md

TheNoiseClock - Product Requirements Document

Overview

TheNoiseClock is a SwiftUI-based iOS application that combines a customizable digital clock display with white noise playback and alarm functionality. The app is designed with a dark theme and focuses on providing a clean, distraction-free interface for time display and ambient sound management.

Core Features

1. Digital Clock Display

• Real-time clock with automatic updates every second
• Customizable time format: 12-hour or 24-hour display
• Optional seconds display with toggle control
• AM/PM badge for 12-hour format (optional)
• Segmented time display with colon separators that adapt to orientation
• Dynamic scaling that fits available screen space
• Portrait and landscape orientation support

2. Clock Customization

• Color customization: User-selectable digit colors with color picker
• Background color: Customizable background with color picker
• Glow effects: Adjustable glow intensity (0-100%)
• Size control: Manual scaling (0-100%) or auto-fit mode
• Opacity controls: Separate opacity for clock digits and overlays
• Random color mode: Automatically changes digit color every minute
• Preset themes: Quick "Night" (black/white) and "Day" (white/black) themes

3. Display Modes

• Normal mode: Standard interface with navigation and settings
• Display mode: Full-screen clock activated by long-press (0.6 seconds)
• Automatic UI hiding: Tab bar and navigation elements hide in display mode
• Smooth transitions: Animated transitions between modes

4. Information Overlays

• Battery level display: Real-time battery percentage with icon
• Date display: Current date in "d MMMM EEE" format (e.g., "7 September Mon")
• Overlay opacity control: Independent opacity for battery/date overlays
• Automatic updates: Battery and date update in real-time

5. White Noise Player

• Multiple sound options:
  • White Noise (white-noise.mp3)
  • Heavy Rain White Noise (heavy-rain-white-noise.mp3)
  • Fan White Noise (fan-white-noise-heater-303207.mp3)
• Continuous playback: Sounds loop indefinitely
• Simple controls: Play/Stop button with visual feedback
• Sound selection: Dropdown picker for sound selection

6. Alarm System

• Multiple alarms: Create and manage multiple alarms
• Time selection: Wheel-style date picker for alarm time
• Sound selection: Choose from system sounds (default, bell, chimes, ding, glass, silence)
• Enable/disable toggles: Individual alarm control
• Notification integration: Uses iOS UserNotifications framework
• Persistent storage: Alarms saved to UserDefaults
• Alarm management: Add, delete, and modify alarms

Technical Architecture

App Structure

• Main App: TheNoiseClockApp.swift - Entry point with WindowGroup
• Tab-based navigation: Three main tabs (Clock, Alarms, Noise)
• SwiftUI framework: Modern declarative UI framework
• Dark theme: Preferred color scheme set to dark

Data Models

• ClockStyle: Codable struct for clock customization settings
  • Time format preferences (24-hour, seconds, AM/PM)
  • Visual settings (colors, glow, scale, opacity)
  • Overlay settings (battery, date, opacity)
  • Background settings
• Alarm: Codable struct for alarm data
  • UUID identifier
  • Time and enabled state
  • Sound name
• Sound: Simple struct for noise file management
  • Display name and file name

Data Persistence

• AppStorage: ClockStyle settings persisted as JSON
• UserDefaults: Alarm data persisted as JSON
• Bundle resources: Audio files stored in app bundle

Audio System

• AVFoundation: AVAudioPlayer for noise playback
• Looping playback: Infinite loop for ambient sounds
• Error handling: Graceful handling of missing audio files

Notification System

• UserNotifications: iOS notification framework
• Permission handling: Automatic permission requests
• Calendar triggers: Daily alarm scheduling
• Sound customization: System sound selection

User Interface Design

Navigation

• TabView: Three-tab interface (Clock, Alarms, Noise)
• NavigationStack: Modern navigation with back button support
• Toolbar integration: Settings and add buttons in navigation bars

Visual Design

• Rounded corners: Modern iOS design language
• Smooth animations: 0.28-second easeInOut transitions
• Color consistency: Blue accent color throughout
• Accessibility: Proper labels and hidden decorative elements

Settings Interface

• Form-based layout: Organized sections for different setting categories
• Interactive controls: Toggles, sliders, color pickers
• Real-time updates: Changes apply immediately
• Sheet presentation: Modal settings with detents

File Structure

TheNoiseClock/
├── TheNoiseClockApp.swift          # App entry point
├── ContentView.swift               # Main tab navigation
├── ClockView.swift                 # Clock display and settings
├── ClockSettingsView.swift         # Settings interface
├── ClockStyle.swift                # Data model and color utilities
├── AlarmView.swift                 # Alarm management
├── AddAlarmView.swift              # Alarm creation
├── NoiseView.swift                 # White noise player
├── NoisePlayer.swift               # Audio playback logic
├── Sound.swift                     # Sound data model
└── Resources/                      # Audio files
    ├── white-noise.mp3
    ├── heavy-rain-white-noise.mp3
    └── fan-white-noise-heater-303207.mp3

Key User Interactions

Clock Tab

1. View time: Real-time clock display
2. Access settings: Tap gear icon in navigation bar
3. Enter display mode: Long-press anywhere on clock (0.6 seconds)
4. Exit display mode: Long-press again to return to normal mode

Settings

1. Time format: Toggle 24-hour, seconds, AM/PM display
2. Appearance: Adjust colors, glow, size, opacity
3. Overlays: Control battery and date display
4. Background: Set background color and use presets

Alarms Tab

1. View alarms: List of all created alarms
2. Add alarm: Tap + button to create new alarm
3. Toggle alarm: Use switch to enable/disable
4. Delete alarm: Swipe to delete

Noise Tab

1. Select sound: Choose from dropdown menu
2. Play/Stop: Single button to control playback
3. Continuous playback: Sounds loop until stopped

Technical Requirements

iOS Compatibility

• Minimum iOS version: iOS 15.0+ (SwiftUI features)
• Target devices: iPhone and iPad
• Orientation support: Portrait and landscape

Dependencies

• SwiftUI: Native iOS UI framework
• AVFoundation: Audio playback
• UserNotifications: Alarm notifications
• Combine: Timer publishers for real-time updates

Performance Considerations

• Efficient timers: Separate timers for seconds and minutes
• Memory management: Proper cleanup of audio players
• Battery optimization: Efficient update mechanisms
• Smooth animations: Hardware-accelerated transitions

Future Enhancement Opportunities

• Additional sound types: More white noise variants
• Volume control: Adjustable playback volume
• Sleep timer: Auto-stop noise after specified time
• Widget support: Home screen clock widget
• Apple Watch companion: Watch app for quick time check
• In-app purchases: Premium sound packs
• Custom sounds: User-imported audio files
• Snooze functionality: Enhanced alarm features
• Multiple time zones: World clock functionality

Development Notes

• Created: September 7, 2025
• Framework: SwiftUI with iOS 15+ target
• Architecture: MVVM pattern with SwiftUI
• Testing: Includes unit and UI test targets
• Version control: Git repository with staged changes