TickTune

A full-screen countdown with your own music — a desktop web app. Live at ticktune.net · GPL-3.0-only · Vietnamese, English and Japanese

Set a countdown, bring your own music — local files or YouTube links — and get a big seven-segment clock behind smoked glass, styled like a piece of broadcast studio hardware. When it reaches zero, a configurable End Behavior fires.

Your files never leave your browser.

Features

• Three sources. Single (one local file, looped), Playlist (up to 95 local files, reorderable by drag or Alt+↑/↓, shuffle and repeat) and YouTube (up to 50 links, played through YouTube's own embedded player, with each link's length looked up so "Match queue length" works there too).
• Crossfade: local tracks fade into each other over 0–5 s (2 s by default, 0 for a straight cut), and a single track can loop by fading into itself. Skips and pauses ramp rather than cut, so they no longer click.
• A countdown that is derived, never accumulated — endAt − now on every tick, so it does not drift. Below 60 s it shows milliseconds.
• End Behavior: fade-out, a synthesised chime, a screen flash, then stay, restart or loop. The countdown is exact while the tab is visible; in a background tab the elapsed time stays exact but the browser may hold the app back until you return — and the Finished screen then says when zero was actually reached rather than implying "now" (docs/04 §2).
• Visuals: solid, gradient, picture, slideshow or cover-art backgrounds with an adaptive scrim that solves for 4.5:1 contrast behind the digits; a bars / wave / ring visualizer; an ON AIR tally lamp that pulses to the beat; Focus mode.
• Two looks, two faces: the dark "LED" rack or a light "LCD" panel for daytime projection, and a 7- or 14-segment clock.
• Away from the tab: opt in, and the countdown's own worker shows a system notification at zero while the tab is in the background — generic text, never a track name, nothing sent anywhere.
• Installable, and it starts offline: /app/ installs as an app, and once visited it opens without a network; local files play as ever (YouTube needs one).
• Settings as a file: export them, import them on another machine.
• Keyboard first: Space play/pause, ←/→ tracks, ↑/↓ volume, M mute, F fullscreen, H Focus, S settings — the full table is in the app.
• Accessible: screen-reader milestones at 10 / 5 / 1 min, 10 s and zero, and the time remaining readable on demand; every control reachable by keyboard, with the single-key shortcuts switchable off; Windows Contrast themes and reduced motion respected. Target: WCAG 2.2 AA — details, known limitations and how to report a barrier in ACCESSIBILITY.md.

Desktop only, by design. Phones and tablets get a notice instead of the app (docs/07) — the experience is a large clock on a large screen.

Limits

Mode	Items	Per track	Total	Countdown
Single	1 local file	≤ 10:02	—	1 s – 24 h
Playlist	≤ 95 local files	≤ 10:02	≤ 91:00	1 s – 24 h
YouTube	≤ 50 links	—	—	1 s – 24 h

Missing metadata shows as N/A (text) or – (numbers), never as a blank.

Privacy

• Your files stay in your browser. They are held in memory for the session and never uploaded — there is no upload endpoint. Only your settings persist, locally, in IndexedDB.
• One analytics beacon: Cloudflare Web Analytics counts page views without cookies and shows only aggregates. It is disclosed in the Privacy Policy and on the consent screen, and it never sees your files.
• YouTube mode loads YouTube's player from youtube-nocookie.com; link titles and lengths are looked up through this site's own /api/yt/oembed and /api/yt/durations routes, which forward only the video IDs — from the server, with its own key — and cache each answer for a day. Pasted playlists (up to ten) go through /api/yt/playlists, which forwards only the playlist IDs and keeps what each holds for an hour.
• A finish notification is created by the tab itself: no push service, no subscription, nothing leaves the machine.
• The offline copy holds the app's own files only — never yours.

Development

Requirements: Node 26 LTS and pnpm 11 (npm install -g pnpm@11; Node 26 ships no corepack).

pnpm install
pnpm dev          # astro dev → http://localhost:4321
pnpm build        # astro build + CSP hash + third-party notices + size budget
pnpm lint         # eslint + prettier --check
pnpm check        # astro check + svelte-check + worker tsc
pnpm knip         # unused files, exports and dependencies
pnpm test         # Vitest: unit + component + worker, with coverage
pnpm test:e2e     # Playwright: Chromium, Firefox, WebKit + the mobile gate
pnpm verify:csp   # the real CSP in a browser, under wrangler dev
pnpm lhci         # Lighthouse CI on the built static pages
pnpm test:visual:docker   # screenshots, in the pinned Playwright image (--update to rewrite)
pnpm perf:render  # the countdown's frame cost, headed (TT_PERF_SOFTWARE=1: no GPU)

pnpm fixtures regenerates the audio fixtures, pnpm demo re-records the landing page's hero video, and node scripts/make-brand-assets.mjs rasterises the favicon and the social card. The test/ folder is a local-only audio corpus for the audio spikes; it is git-ignored and guarded out of every commit.

How it is built

Astro 7 static pages, plus one Svelte 5 island at /app/, mounted by hand behind the mobile gate rather than with a client directive (docs/01 §3). The engines — timer, audio, import, queue, YouTube — are pure TypeScript under src/app/engine/; state lives in Svelte 5 runes stores. It is served by Cloudflare Workers Static Assets with three Worker routes — GET /api/yt/oembed, GET /api/yt/durations and GET /api/yt/playlists — the last two holding the YouTube Data API key as a Worker secret.

Releases

Production changes only when a signed vX.Y.Z tag is pushed: deploy.yml verifies the signature and that the tag is on main, runs the gates, deploys, and publishes the GitHub Release. Every other push only uploads a preview version (docs/14).

Documentation

The docs/ suite is authoritative; CLAUDE.md is its condensed contract.

Chapter	Contents
01-ARCHITECTURE	System shape, module map, the island mount
02-DATA-FLOW	State machine, track model, import pipeline, settings schema
03-UI-SPEC	The "Rack Unit" design system, layout zones, ToS carve-out
04-TIMER-ENGINE	Derived time, the worker tick, the background-tab promise
05-AUDIO-ENGINE	Web Audio graph, End Behavior, visualizer
06-YOUTUBE-INTEGRATION	IFrame Player, ToS constraints, error causes, oEmbed
07-MOBILE-GATE	The site-wide desktop gate
08-I18N	VI/EN/JA for the static pages and the app
09-SECURITY	Threat model, headers, CSP
10-CLOUDFLARE-SETUP	Zone, Worker and dashboard configuration
11-DEPENDENCIES	Versions, licences, the notices rule
12-CODE-STANDARDS	Conventions and the log-code registry
13-TESTING	Test tiers and the live-site checklists
14-CI-CD	Workflows, permissions, the release path
15-SPIKES	The validation spikes and their results
16-ROADMAP	Phases, exit reviews, what is next

AI-assisted development

TickTune is built with Claude Code, Anthropic's coding assistant: the Claude Opus 4.8 model for 0.2.0–1.0.0 (July 2026), Claude Opus 5.5 from 1.1.0 (October 2026). The developer directs and reviews every change, and each commit made with the assistant carries a Co-Authored-By trailer, so the history shows which. CLAUDE.md is the contract it works under. The app itself has no AI features and sends nothing to any AI service — the Disclaimer §7 says the same.

Contributing

Read CONTRIBUTING.md first — especially the hard invariants in CLAUDE.md, which no change may break.

Accessibility

ACCESSIBILITY.md is the accessibility statement: what is built in, what has been tested, what is known not to work, and how to report a barrier — the Accessibility barrier issue form, or [email protected].

Security

Please report vulnerabilities privately: [email protected], or GitHub's private vulnerability reporting. Details in SECURITY.md.

Contact

For	Address
Press	[email protected]
Collaboration	[email protected]
Privacy	[email protected]
Terms and legal	[email protected]
Licensing and attribution	[email protected]
Accessibility barriers	[email protected]

License

Copyright © 2026 poli0981.

TickTune is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License, version 3 only, as published by the Free Software Foundation. It is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See LICENSE.

Bundled fonts are under the SIL Open Font License 1.1; every third-party component is listed in Third-Party Notices, and the full licence texts ship at /THIRD-PARTY-NOTICES.txt.