A customisable live clock and focus timer with local media backgrounds, adaptive themes, recording overlays, and synchronised Picture-in-Picture.
Live: https://mes30004e.github.io/betterclock/
Betterclock is a browser-based clock, stopwatch, and countdown timer built with React, TypeScript, and Vite. It is designed for focused work, study sessions, desk displays, recordings, and full-screen ambient use. Timer and personalisation data stay on the device, and local media is never uploaded by Betterclock.
- Large-format clock with 12/24-hour time, dates, alignment, fullscreen, and Wake Lock where supported.
- Timestamp-accurate stopwatch and countdown with pause/resume, laps, completion alerts, and recovery after refresh or suspended tabs.
- Editable, optional focus titles and Standard, Immersive, or Recording Overlay presentations.
- Local image and video backgrounds, browser folder library, cached thumbnails, video audio, and compact media controls.
- Original dynamic wallpapers and live scenes: Sakura Breeze, Forest Light, Night City Glow, Ocean Mist, and Cozy Rain.
- Interactive Chromium Document Picture-in-Picture with synchronised backgrounds, real local video, responsive controls, and optional media preview.
- Compact Quick Settings plus a dedicated full-screen settings workspace.
- Adaptive Theme Engine with local palette analysis, contrast protection, presets, custom fonts, and per-background themes.
- Local persistence, responsive layouts, keyboard focus states, installable browser metadata, and GitHub Pages deployment.
Clock mode derives time from the device clock and supports optional seconds, date formats, location labels, sizing, alignment, colour controls, fullscreen, and Screen Wake Lock.
Timer mode provides stopwatch and countdown operation. It uses timestamps rather than counting interval ticks, so elapsed or remaining time stays accurate through throttled tabs, sleep, refreshes, and browser restarts. The focus title is optional and updates across the main timer, recording overlay, and Document PiP.
The Recording Overlay can be positioned in any corner and configured for size, opacity, labels, seconds, stopwatch milliseconds, controls, and compact or expanded layouts. It can inherit the active theme or retain one of its existing visual presets.
Open Full Settings → Media and choose Choose Folder to create a local background library. During development, a folder such as the following may be convenient:
/Volumes/My Passport/Morgan/Documents/Coding/Timer App/background
That path is only an example from the original development machine. Any folder the browser is allowed to read can be used.
Chrome and other compatible Chromium browsers use the File System Access API. Permission is requested by the browser after a user action, and the directory handle is remembered where the browser permits. Betterclock reads media in place, stores metadata and small thumbnails locally, and does not upload the files. If an external drive or folder becomes unavailable, use Refresh or Reconnect after restoring access. macOS sidecars such as ._* are ignored.
Common formats:
- Images: JPG/JPEG, PNG, and WebP.
- Video: MP4, M4V, MOV where supported, and WebM where supported.
Actual video playback depends on the codecs available in the browser and operating system. Browsers without persistent folder access can use the multi-file IndexedDB import fallback.
Local background videos can run muted or with audio. Betterclock provides mute/unmute, volume, play/pause, seeking, restart, progress, and per-video options. Media playback is separate from the timer: pausing a video does not pause the stopwatch or countdown.
The compact media preview includes a thumbnail, cleaned title, progress, mute and volume controls, expanded transport controls, and a shortcut to background settings. It can remain visible for muted media when requested.
Betterclock includes abstract/procedural wallpapers such as Aurora, Mesh Flow, Liquid Light, Starfield, Rain Glass, Sunset Drift, Deep Space, and Minimal Waves. A designer also supports configurable mesh, aurora, blobs, waves, particles, radial light, colour drift, and rain effects.
The animated live scenes are Sakura Breeze, Forest Light, Night City Glow, Ocean Mist, and Cozy Rain. These are original CSS/procedural compositions; Betterclock does not bundle third-party footage for them. Motion intensity, speed, direction, ambience, foreground detail, performance, and reduced-motion behaviour can be adjusted.
Theme modes include:
- Auto from background — derives a stable palette from the current background.
- Manual — uses global user-selected colours and fonts.
- Per-background — remembers an automatic or custom theme for each stable background ID.
- Betterclock default — restores the original Betterclock visual language.
Palette analysis runs locally. Images and videos use small representative or cached thumbnails; videos are not analysed frame by frame. Procedural scenes use their known configured colours. Generated palettes are cached and invalidated when relevant media or thumbnail metadata changes.
Automatic contrast protection uses relative luminance and contrast calculations to keep timer numerals, labels, surfaces, controls, and PiP readable. Timer contrast can also be forced to Light, Dark, or a custom colour. Eight built-in presets provide starting points without preventing further editing.
Full Settings can import WOFF2 (preferred), WOFF, and TTF/OTF where the browser supports them. Font files remain local, are stored in browser IndexedDB, and can be selected separately for timer numerals and the interface. Compatible custom timer fonts are also registered inside the Document PiP window.
If a font cannot load, Betterclock falls back to Manrope and system fonts. Only import fonts you have permission to use.
Chromium Document Picture-in-Picture provides an interactive floating timer with a primary Start, Pause, Resume, or Restart control. Full-card mode can also show Reset. Document PiP supports:
- Real local-image and local-video backgrounds.
- A muted duplicate of PiP video to prevent double audio.
- Approximate video-position and play-state synchronisation with the main window.
- Animated live scenes and procedural backgrounds.
- PiP appearance, motion, blur, dimming, theme, contrast, and font integration.
- An optional responsive media strip and layouts that adapt to small PiP windows.
The main Betterclock window remains the only audio source. Browser autoplay and codec rules still apply.
Standard video Picture-in-Picture is a non-interactive canvas fallback. It renders the timer only; timer controls remain in the main window.
Quick Settings contains frequently used timer, theme, background, media, audio, PiP, and display controls. It opens from contextual and left-side shortcuts.
Full Settings, opened from the main gear, is a dedicated full-screen workspace with General, Timer, Appearance, Media, Now Playing, PiP, and Advanced categories.
- Betterclock has no application backend.
- Local media is read only after browser-granted access and is not uploaded by Betterclock.
- Imported media and fonts stay in local browser storage.
- Timer state, settings, themes, and media metadata persist locally.
- Local media can continue working offline after access, subject to browser permission and drive availability.
- Remote media requires its external host and may be limited by CORS, availability, or codecs.
- The optional Spotify experiment requires Internet access when configured.
Clearing site data removes locally stored Betterclock data and imported blobs.
Chrome or a compatible Chromium browser provides the fullest experience. Core clock and timer functionality may work in other modern browsers, but support varies for the File System Access API, Document PiP, video codecs, autoplay, Wake Lock, notifications, fullscreen, and custom font formats.
git clone https://github.com/MES30004E/betterclock.git
cd betterclock
npm install
npm run devRun tests and a production build:
npm test
npm run buildVerify the GitHub Pages repository path:
VITE_BASE_PATH=/betterclock/ npm run build?debugWallpapers=1shows wallpaper, animation, visibility, and PiP scene state.?debugMedia=1shows non-sensitive local-library, playback, media-preview, and PiP state.?debugTheme=1shows the resolved palette, contrast, fonts, background ID, and PiP theme mode without exposing font data.
Spotify metadata support exists as an optional developer-configured experiment. It requires a Spotify developer application and eligible account/API access, is not needed for Betterclock, and is not presented as a standard supported feature. Audio remains in Spotify.
The included GitHub Actions workflow runs the test suite, builds with /betterclock/ as the Vite base path, and deploys dist/ when main is pushed or the workflow is started manually. In repository settings, GitHub Pages should use GitHub Actions as its source. Build output is generated by the workflow and is not committed.
Betterclock is an AI-assisted, vibe-coded project. Its design direction, feature decisions, testing, iteration, and final review are human-directed, while AI coding tools were used extensively throughout implementation and refinement. Generated changes are tested before being accepted.
Betterclock does not bundle a user's local wallpaper or video library. Users are responsible for having permission to use media and custom fonts they load. External user media remains the property of its respective rights holders.