Appendix W: Tally Matrix Clock (Shop Manual)

Status: Live on the App Store. tvOS only. App Apple ID 6754099799. Current version 2.4 (submitted APR 02 2026). GPL v3. Public repo at github.com/fluhartyml/TallyMatrices (repo name differs from app name — historical). App Store: apps.apple.com/us/app/tally-matrix-clock/id6754099799. Tally Matrix Clock turns an Apple TV into a retro-futuristic ambient display. Time reads as illuminated colored squares in a matrix layout; music plays from the same 80+ station catalog that drives CryoTunes Player (Appendix M). Both apps share the CryoKit data layer (Appendix B).

What it is

An ambient tvOS clock that doubles as a music player. Four matrices on screen: one 1×3 column for the leading hour digit, three 3×3 grids for the remaining digits. Count the lit squares to read the time. Behind the matrices, an Apple Music stream plays whatever station was last selected, with the LCD ticker / weather / date elements visible on the same screen. Animated pattern shuffles and cascading glyph rain run during transitions — the visual language is borrowed from classic CRT terminals.

The CryoKit dependency — DIAMOND RULE

Same dependency, same rule, same reason as Appendix M. The shared CryoKit package carries the station catalog, playback hooks, and weather. Nothing in CryoKit changes without express written consent from Michael, and Claude may never remove or subtract code there. An edit that fits the iPhone music player can quietly break the tvOS clock and vice versa — the package is the load-bearing seam between the two apps.

CryoKit has no aesthetic control. All font modifiers were stripped from CryoKit views. Each app sets its own fonts, sizes, and button styles via parent view modifiers. CryoKit only accepts tint, accent, and border colors from the app. Tally Matrix Clock applies its 18pt minimum and tvOS-appropriate scaling at the view-tree level.

Architecture overview

Small project, tvOS-tuned. SwiftUI throughout; CryoKit is the data engine.

• App entry: Tally_Matrix_ClockApp.swift (the @main scene), ContentView.swift (the clock-face composition).
• Matrix views in TallyMatrixViews.swift:
  • SquareView — a single lit / unlit square primitive. Color, opacity, animation.
  • TallyMatrix1x3 — the 1×3 column for the hour's tens digit.
  • TallyMatrix3x3 — the 3×3 grid used three times for the ones digit, the minute's tens digit, and the minute's ones digit.
  Book 19 (Custom Views and Modifiers) uses these three together as its textbook example of composed custom views.
• Decorative views:
  • ClaudeStarburstView.swift — transition animation between station changes.
  • GlyphRainView.swift — cascading falling-glyph effect behind the matrices.
• Custom pickers: CryoStationPicker.swift and CryoSleepTimerPicker.swift — the same hand-built button trees CryoTunes uses, tvOS-styled here.
• Transport: CryoTransportControls.swift — transport row tuned for the Apple TV remote's focus engine.
• Settings + cloud: SettingsView.swift, CloudSettings.swift (CloudKit-backed user-preference container).
• Auxiliary: LocationManager.swift (WeatherKit location source), Models.swift (local data shapes that don't live in CryoKit).
• Notes: TallyMatrixClock_DeveloperNotes.swift (canonical roadmap, App Store Connect block, version history).

Reading the clock face

The clock displays time by lit squares. Each digit position has its own matrix:

• Hour tens digit — 1×3 column (values 0–2 in 12-hour mode).
• Hour ones digit — 3×3 grid (values 0–9).
• Minute tens digit — 3×3 grid (values 0–5).
• Minute ones digit — 3×3 grid (values 0–9).

The number of lit squares in each matrix equals the value of that digit. The visual pattern that lights up to represent a given count shuffles periodically (the "heartbeat" feature added in v2.4) so the screen stays alive even when the time hasn't ticked.

Music and weather

Same 80+ station catalog as CryoTunes Player (Popular Hits 1958–2025, plus Big Band & Swing, Early Jazz, Jazz Age, Ragtime). The station selection lives in CryoKit. The transport controls and now-playing surface in this app are the tvOS-tuned versions of CryoTunes's iPhone pieces — same names (CryoTransportControls, CryoStationPicker) tuned for the focus engine and remote.

WeatherKit drives a discreet weather strip on the clock face via LocationManager — same approach as CryoTunes's LCD ticker, scaled and positioned for a TV across the room.

tvOS-specific concerns

• Focus engine. tvOS apps drive interaction through Apple TV's focus engine, not touch. Every interactive control (transport buttons, station picker rows, settings entries) has to participate properly — right-size focus rings, focus-shift animations, no surprise focus jumps. Tally Matrix's transport row uses an HStack of focusable buttons with explicit focus management.
• 18pt minimum font. Tally Matrix is the source of the project-wide 18pt minimum rule. Apple TV display is across a room; smaller fonts disappear at that distance.
• App version on the clock face. The runtime version (from Bundle.main.infoDictionary["CFBundleShortVersionString"]) appears next to the Apple TV device name. Confirms which build is running on each TV in a multi-TV household.

Build + deployment

• App name: Tally Matrix Clock (App Store), package shipping under TallyMatrices repo.
• Subtitle: Matrix Clock for AppleTV.
• Category: Utilities / Entertainment.
• Platform: tvOS only.
• License: GPL v3.
• Frameworks: MusicKit (streaming via CryoKit), WeatherKit (weather strip), Core Location.
• Privacy: No ads, no tracking.
• Subscription disclosure: Apple Music subscription required, stated upfront in App Store copy.

Known gotchas

• CryoKit is read-only from this project. Shared with CryoTunes Player. Local SPM edits have to be reviewed for both apps before they ship.
• Repo name diverges from app name. The GitHub repo is TallyMatrices (plural, no "Clock"); the App Store name is Tally Matrix Clock (singular, with "Clock"). Historical; not worth a rename pass at this point but worth knowing when linking.
• v2.4 followed a hard reset. The MAR 31 CryoKit migration work was rolled back on APR 02 to a clean v2.3.1 baseline. Anyone reading the commit history through that window sees the rollback explicitly.
• Heartbeat shuffles run even when the minute hasn't ticked. By design — an unchanged screen reads as a frozen TV from the couch. The shuffle is a liveness signal.

Roadmap status (from TallyMatrixClock_DeveloperNotes.swift)

Shipped through v2.4 (Live)

• Matrix-based time display (1×3 + three 3×3 matrices).
• CryoKit data layer (clean from v2.3.1 baseline).
• 80+ station catalog with Popular Hits (1958–2025) + genre stations.
• Shuffle, Repeat All, Repeat One.
• Playlist reveal (My Music with song counts, Play All, individual tracks).
• Heartbeat pattern shuffle.
• Focus highlight visible across the focus engine.
• WeatherKit weather strip.
• App version displayed on clock face next to Apple TV device name.
• 18pt minimum fonts throughout.
• CryoTunes placeholder art for stations missing artwork.

v3 future (per project_tally_matrix_v3.md)

• M3U playlist import.
• GrooveWire client integration for Apple TV endpoints.
• Tally Matrix Clock leader / follower sync via CloudKit (cross-listed with CryoTunes Player v1.1+).

Sources

• Project source: github.com/fluhartyml/TallyMatrices (verified 2026-05-10).
• Live on App Store: apps.apple.com/us/app/tally-matrix-clock/id6754099799.
• Canonical roadmap: Tally Matrix Clock/TallyMatrixClock_DeveloperNotes.swift in the project repo.
• Shared data layer: Appendix B (CryoKit).
• Companion iPhone player: Appendix M (CryoTunes Player).
• Custom-view composition cross-reference: Book 19 (uses SquareView + TallyMatrix1x3 + TallyMatrix3x3 as its worked example).