NTP Web Clock

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.

Features

• 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.
• Enhanced /api/time/sync endpoint 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.

Quick Start

cd ntp-web-clock
npm test
npm start

Default 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 start

Then open:

http://<SERVER_IP>:8080/

API

GET /api/time

Returns one calibrated time result.

Useful fields:

• epochMs: calibrated Unix timestamp in milliseconds.
• iso: ISO timestamp.
• source: ntp, ntp-stale, or system.
• 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.

Force a fresh backend NTP query:

/api/time?refresh=1

GET /api/time/sync

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.

GET /api/time.txt

Returns one plain-text timestamp line for scripts and simple devices.

GET /api/health

Returns service health, configured NTP sources, the latest sync result, and the latest error.

Deployment

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>

See DEPLOYMENT.md and 部署文档.md for full deployment instructions.

Development

See DEVELOPMENT.md for architecture, time-sync logic, frontend behavior, and maintenance notes.

Version And Upload Log

See TIMESTAMP_LOG.md. It records GitHub upload events, commit IDs, repository location, and handoff notes for switching between machines or repositories.