NTP Web Clock is a browser-facing exam clock and timer. The browser does not talk to NTP directly. A small Node.js backend queries configured NTP servers over UDP, exposes calibrated time through HTTP APIs, and the frontend uses that data to keep the displayed time close to the trusted time source.
It is designed for classroom screens, exam invigilation, meeting rooms, and internal web pages that need a readable clock with better stability than a browser-only timer.
- Large responsive clock for desktop, projector, and mobile views.
- Fullscreen mode that hides controls and keeps only the clock body.
- Time API backed by one or more configurable NTP sources.
- Multi-sample frontend sync with RTT filtering and offset smoothing.
- Monotonic clock progression and safe timer recovery after page reloads.
- Cross-source NTP consistency checks before selecting a low-delay source.
- Enhanced
/api/time/syncendpoint for callers that want server-side multi-sample NTP filtering. - Countdown and count-up timer modes.
- Timer controls for start, stop/end, pause, and reset.
- Diagnostics for NTP source, NTP delay, web round-trip time, last update, and server time offset.
- No external npm dependencies.
cd ntp-web-clock
npm test
npm startDefault runtime values:
HOST=0.0.0.0
PORT=8080
TIMEZONE=Asia/Shanghai
NTP_SERVERS=time.cloudflare.com,time.google.com,pool.ntp.org
For an internal deployment, override NTP_SERVERS with your own NTP hosts:
HOST=0.0.0.0 \
PORT=8080 \
TZ=Asia/Shanghai \
TIMEZONE=Asia/Shanghai \
NTP_SERVERS=<NTP_SERVER_1>,<NTP_SERVER_2>,<NTP_SERVER_3> \
npm startThen open:
http://<SERVER_IP>:8080/
Returns one calibrated time result.
Useful fields:
epochMs: calibrated Unix timestamp in milliseconds.iso: ISO timestamp.source:ntp,ntp-stale, orsystem.server: selected NTP source for this sample.delayMs: server-to-NTP UDP round-trip delay.offsetMs: server system clock offset against NTP.serverProcessingMs: HTTP request processing time on the server.
Request a backend NTP refresh (subject to the shared minimum sampling interval):
/api/time?refresh=1
Ordinary, forced, and text requests share a 1500 ms minimum NTP attempt interval (NTP_MIN_INTERVAL_MS), including failed attempts. During cooldown they reuse a valid calibration or return the documented stale/system fallback. HTTP responses themselves are not delayed by this cooldown.
Runs multiple NTP samples on the server, filters high-delay and outlier samples, and returns a more stable result.
/api/time/sync?samples=7
samples can be 1-9.
Concurrent requests share the active burst, which collects distinct samples. A fresh ordinary sample can count as its first sample. Bursts have a separate 10000 ms cooldown (API_SYNC_MIN_INTERVAL_MS); requests during that interval reuse the last usable burst, so the returned syncStats.totalSamples may differ from the requested count. Ordinary refreshes join a running burst.
The consensus field reports responding and agreeing source counts. With multiple usable sources, a majority must agree before delay-based selection. Disagreement invokes stale/system fallback; a single responding source remains usable but cannot be cross-checked.
Returns one plain-text timestamp line for scripts and simple devices.
Returns service health, configured NTP sources, the latest sync result, and the latest error.
The repository includes a user-level systemd unit at:
deploy/ntp-web-clock.service
Before deployment, edit these values for your environment:
WorkingDirectory=%h/apps/ntp-web-clock
Environment=HOST=0.0.0.0
Environment=PORT=8080
Environment=TIMEZONE=Asia/Shanghai
Environment=NTP_SERVERS=<NTP_SERVER_1>,<NTP_SERVER_2>,<NTP_SERVER_3>
Environment=NTP_MIN_INTERVAL_MS=1500
Environment=API_SYNC_MIN_INTERVAL_MS=10000See DEPLOYMENT.md and 部署文档.md for full deployment instructions.
See DEVELOPMENT.md for architecture, time-sync logic, frontend behavior, and maintenance notes.
See TIMESTAMP_LOG.md. It records GitHub upload events, commit IDs, repository location, and handoff notes for switching between machines or repositories.