Files
Chronos/docs/BRIEF.md
T
Alby96andClaude Opus 5.5 0075065884
CI / Build and test (push) Successful in 10m37s
CI / Windows tests and installer (push) Skipped
CI / YAML check (push) Successful in 9s
Release / Build, test and publish (push) Successful in 16m19s
CI / PostgreSQL 16 integration (push) Successful in 10m19s
CI / PostgreSQL 17 integration (push) Successful in 11m27s
CI / Docker image (push) Successful in 57s
Release / Server image (push) Successful in 1m34s
feat: work board, no usage data, archive folder tree, deploy guide (owner review 4 + owner review 1 phase 6) (#62)
Owner review 4 and owner review 1 phase 6.

- Work board in Videos (desktop and admin panel): Published and Workspace lanes (#29).
- Anonymous usage counts removed: Chronos sends nothing about its use (#30).
- The archive's whole folder tree is created inside any archive root, on the server and the desktop (#31).
- Video cards start with the preset; sizes keep number and unit together (#28).
- Deploy guide docs/deploy (Docker, Unraid, desktop), BRIEF §24, original documentation in docs/reference/original (#22).

Closes #22 #28 #29 #30 #31

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Alberto Balbo <alberto.balbo.96@gmail.com>
2026-11-06 18:46:22 +01:00

3474 lines
279 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Chronos — Build Brief for Claude Code
> This document is the complete specification and standing instruction set for building the
> Chronos time-lapse ecosystem from scratch. It is written to be read by Claude Code at the
> start of every session (via `CLAUDE.md`, see Appendix A) and to be the single source of
> truth for scope, architecture, constraints and delivery order.
>
> Working name: **Chronos**. Three shipped programs — **Chronos** (Windows desktop client),
> **Chronos Server** (Linux/Docker and Windows), **Chronos Uploader** (Windows) — sharing one
> engine. Target audience: photographers, astro/landscape shooters, construction and
> weather-cam operators, hobbyists worldwide.
---
## 0. How to work on this project (operating rules for Claude Code)
### 0.1 Kickoff message
Paste this as the first message in Claude Code, from an empty repository that contains only
this file at `docs/BRIEF.md` and the prototype dump at `docs/reference/chronos-prototype.md`:
```
Read docs/BRIEF.md completely before doing anything. It is the full specification for this
repository and it overrides your defaults. Then:
1. Create CLAUDE.md from Appendix A of the brief, and docs/DECISIONS.md, docs/CHANGELOG.md.
2. Execute Phase 0 exactly as described in §22, stopping at its phase gate.
At every phase gate, report: what was built, how to run it, test results on Windows and
Linux, open decisions. Do not ask questions before the gate unless a decision is
irreversible; otherwise decide, record it in docs/DECISIONS.md, and continue.
```
### 0.2 Standing rules
1. **Zero third-party packages, everywhere.** No `<PackageReference>` in any `.csproj`,
including tests, tools and build scripts. Anything that is not the .NET BCL, a Microsoft
shared framework that ships with the .NET SDK/runtime (`Microsoft.NETCore.App`,
`Microsoft.AspNetCore.App`, `Microsoft.WindowsDesktop.App`, the Windows SDK targeting
pack), or an operating-system API reached by P/Invoke or COM interop, is implemented
in-house. CI fails the build if a `PackageReference` appears (§19.2). The prototype in
`docs/reference/chronos-prototype.md` proves this is workable: it decodes images with WIC,
encodes video with Media Foundation, parses EXIF/TIFF/XMP with its own parsers, and
writes its own MP4 container.
2. **No external processes.** No FFmpeg, no ExifTool, no ImageMagick, no PowerShell
scripts at runtime. The only OS executables/dialogs the product may invoke are listed in
§8.6 (format-volume dialog, shell "open with", browser launch for links).
3. **Cross-platform core, Windows-only presentation.** `Chronos.Core`, `Chronos.Data`,
`Chronos.Protocol` and `Chronos.Server` target `net10.0` and must build and pass tests on
Linux. Windows-only code lives in `*.Windows` projects or the desktop apps.
4. **English everywhere in the codebase**: identifiers, comments, commit messages, docs.
The prototype is written in Italian; port the algorithms, not the language.
5. **Every user-visible string is a resource.** No literal UI text in code or XAML.
English is the source language; Italian is the first translation; all other languages
follow in Phase 8 (§16).
6. **UI copy rules (mandatory):** labels ≤ 3 words when possible; no helper text or
paragraphs anywhere in the UI; explanations live only in tooltips (≤ 2 sentences);
every actionable control has a tooltip; empty states are one sentence plus one button;
errors are one sentence saying what happened plus one action.
7. **Decide, record, continue.** When the brief is silent, choose the option that is
simplest, safest for user data, and consistent with the constraints; write one line in
`docs/DECISIONS.md` (date, decision, alternative, reason). Ask the human only at phase
gates, or before any irreversible or data-destroying design choice.
8. **User data is sacred.** Never delete, move or format anything without (a) a verified
hash match of every copied file and (b) an explicit user action. Every destructive
operation is dry-run-able and shows its plan first.
9. **Definition of Done for every phase:** CI green on Gitea Actions (§19.1: the Linux
jobs; the `windows` job once a Windows runner is registered, until then the Windows-only
tests run on a Windows PC; amended 2026-10-23, R3); all tests green; no new warnings;
`docs/DECISIONS.md` and `docs/CHANGELOG.md` updated; a short "how to try it" note in the
phase report; localization completeness check passes for `en` and `it`.
10. **Commit style:** Conventional Commits (`feat(core): …`, `fix(server): …`), small
commits, one concern each. Never commit generated binaries, fixtures downloaded by
scripts, or secrets.
11. **Reference prototype:** `docs/reference/chronos-prototype.md` is a Repomix dump of the
previous single-program prototype (C#/.NET 10, WinForms, zero packages). Its engine
(metadata parsing, deflicker, holy-grail transitions, optical flow, motion blur,
stabilization, virtual camera, time remap, stacking, Media Foundation encoding, MP4
muxing, self-tests) was validated on real material. Port those algorithms faithfully
into the new structure, with English names and unit tests; do not copy its UI
(WinForms) or its file layout. Search it with grep; do not try to read it whole.
---
## 1. Product vision
Chronos turns folders of photos (RAW, JPEG, HEIC…) into finished time-lapse videos and keeps
a lifetime archive of shoots organised, verified and searchable — on one PC or on a shared
server.
- **Import** memory cards with per-card rules, session detection, renaming and hash
verification; import directly into a local archive or straight to a server.
- **Analyse** every sequence deeply (metadata + pixels) and let the advisor set frame
timing, motion blur, deflicker, transitions and export presets — with a reason for every
choice, visible in a tooltip.
- **Render** with the in-house engine and GPU encoders (H.264/HEVC/AV1 via Media
Foundation) to purpose-built presets, from 720p previews to 8K 10-bit archives.
- **Archive** hundreds of thousands of photos across years and cameras, on local or network
drives, with an index that can always be rebuilt from the files themselves.
- **Share** through Chronos Server: central archive, users with logins, uploads from the
tiny Uploader, sync of projects, server-side jobs, render delegation to GPU-equipped
clients, and a web admin panel — deployable as a Docker container (Unraid template
included) or on Windows.
### 1.1 Goals (measurable)
- A first-time user imports a card, gets a recommended preset, and renders a 1080p preview
in under five interactions from launch.
- A library of 500,000 photos in 2,000 sequences: Library screen opens in < 1 s, scrolls at
60 fps, filters respond in < 200 ms, full index rebuild from sidecars in < 10 min.
- Rendering quality equals or exceeds the prototype's measured results (§20.4 regression
thresholds), with hardware encoding used whenever a hardware MFT exists.
- Every feature reachable without reading any documentation; every control explained by
its tooltip; UI available in ≥ 30 languages with RTL support.
- Server: 10 concurrent clients uploading at line speed; resumable uploads; zero data loss
on crash (append-only ingest + manifest commit).
### 1.2 Non-goals (v1)
- Audio tracks (P2: mux an external AAC file), HDR/PQ output, colour-managed display.
- macOS/Linux desktop clients (server only), mobile apps, browser-based editing.
- Cloud object storage backends (S3 etc.), multi-server federation.
- General RAW *development* beyond what the render pipeline needs (no Lightroom clone).
- GPU compute for image processing (CPU SIMD only in v1; keep interfaces open).
- Real-time tethered capture, camera control.
- Plugin system.
---
## 2. Hard constraints and allowed native surface
### 2.1 Language and platform decision
**C# on .NET 10 LTS** for every component. Reasons: one toolchain for a cross-platform
server and a first-class Windows desktop; WPF and ASP.NET Core ship with the SDK (no
packages); mature BCL for crypto, HTTP/2, WebSockets, JSON, compression and SIMD
(`System.Numerics.Vector<T>`, `Vector256`); direct P/Invoke/COM interop to WIC, Media
Foundation and `winsqlite3.dll`; the validated engine is already C#. Alternatives were
rejected: Python (stdlib GUI is dated, no GPU encode, no PostgreSQL driver), C++ (UI and
server cost), Rust/Go (no standard GUI, no SQLite/PostgreSQL in std), Java (JavaFX is
external).
Desktop UI: **WPF** with the built-in Fluent theme (`Application.ThemeMode`, available in
WPF since .NET 9, refined in .NET 10) for a Windows 11 look with dark/light/system modes and
system accent colour, plus in-house custom `FrameworkElement`s for charts, filmstrip,
curve editors and the virtualized photo grid. If the Fluent theme proves inadequate for any
control, restyle it with an in-house `ResourceDictionary` — never a package. Window chrome:
`WindowChrome` + `DwmSetWindowAttribute` (dark title bar, Mica/backdrop where available).
### 2.2 Allowed native/OS surface (Windows)
| Need | API (all OS components, no packages) |
|---|---|
| Image decoding incl. RAW/HEIC/WebP/AVIF when codecs installed | WIC (`IWICImagingFactory`… via COM interop) |
| Video encoding, hardware MFTs (NVENC/QSV/AMF) | Media Foundation (`MFStartup`, `MFTEnumEx`, `IMFTransform`, `ICodecAPI`) |
| Local database | `winsqlite3.dll` (ships with Windows 10 1709+ / Windows 11) via P/Invoke |
| Volume identity, device arrival | `GetVolumeInformationW`, `GetDriveTypeW`, `WM_DEVICECHANGE`, `SetupAPI` if needed |
| Format a card | `SHFormatDrive` (OS format dialog) |
| GPU name/VRAM for encoder capability display | DXGI (`CreateDXGIFactory1`, `IDXGIAdapter::GetDesc`) |
| Taskbar progress, toasts | `ITaskbarList3`; toasts via Windows SDK projection (`net10.0-windows10.0.19041.0` targeting pack) or in-house tray balloon |
| MTP cameras (P2) | Windows Portable Devices (COM) |
| Window chrome | `dwmapi.dll` |
Linux (server): BCL only. No `libsqlite3`, no `libva`, no FFmpeg. PostgreSQL is reached
through the in-house wire-protocol client (§6.3).
### 2.3 What this implies (and how the brief resolves it)
- **RAW decoding** without libraw is tiered (§8.2): full in-house decode for DNG/TIFF/
JPEG/PNG and a growing set of native RAW formats; embedded full-size JPEG previews as a
universal fallback (every major RAW format embeds one); on Windows, WIC with the free
Microsoft "Raw Image Extension" gives full decode of everything else.
- **Video encoding** on Linux has no OS encoder API; the server produces pure-managed
outputs (MJPEG-AVI, image sequences, GIF, APNG) itself and delegates MP4/H.264/HEVC/AV1
jobs to **render nodes** — Chronos clients that volunteer their GPU (§14.7). An in-house
intra-only H.264 encoder is a P2 universal fallback (§11.6).
- **Testing** uses an in-house runner (`Chronos.Testing`, §20.1), not xUnit/NUnit.
- **HEIC/HEIF** cannot be decoded in-house (HEVC intra decoder is out of scope): Windows
clients decode via WIC (HEIF + HEVC extensions); the server stores originals and relies on
proxies produced by a Windows client or render node.
---
## 3. Repository layout
```
chronos/ (Gitea repository BalboSoft/Chronos; amended 2026-10-23, R2)
├── CLAUDE.md operating rules (Appendix A)
├── Directory.Build.props version, LangVersion, nullable, warnings-as-errors, analyzers
├── Directory.Build.targets zero-package guard, resource generation hooks
├── Chronos.slnx
├── global.json pins .NET 10 SDK
├── src/
│ ├── Chronos.Core/ net10.0 — engine: Metadata, Imaging, Codecs, Analysis, Motion, Video (container/muxers), Archive model, Naming, Localization runtime
│ ├── Chronos.Core.Windows/ net10.0-windows — WIC decoder, Media Foundation encoder, DXGI, device APIs, winsqlite3 binding
│ ├── Chronos.Data/ net10.0 — IDatabase abstraction, SQL dialects, migrations, repositories, Postgres wire client (Chronos.Data.Postgres), SQLite driver surface (implemented by Core.Windows binding)
│ ├── Chronos.Protocol/ net10.0 — API DTOs, JSON contexts (source-generated), chunked upload protocol, sync manifests, WebSocket event schema, version negotiation
│ ├── Chronos.Server/ net10.0 — ASP.NET Core minimal API, auth, job engine, storage service, admin web UI (embedded static files), Docker entrypoint
│ ├── Chronos.App/ net10.0-windows — WPF desktop client
│ ├── Chronos.Uploader/ net10.0-windows — WPF uploader (tray-capable)
│ ├── Chronos.Setup/ net10.0-windows — in-house installer/uninstaller (self-extracting, Add/Remove Programs, shortcuts, file associations)
│ └── Chronos.Tools/ net10.0 — CLI: selftest, diagnose, make-icon, i18n export/check, fixtures fetch, changelog
├── tests/
│ ├── Chronos.Testing/ in-house test framework + runner (attributes, asserts, fixtures, JUnit XML)
│ ├── Chronos.Core.Tests/
│ ├── Chronos.Data.Tests/ includes PostgreSQL integration tests (skipped without CHRONOS_TEST_PG)
│ ├── Chronos.Server.Tests/ in-process Kestrel on a random port
│ ├── Chronos.App.Tests/ view-model tests + XAML lint (tooltip/resource rules) + screenshot smoke (`--capture`)
│ └── fixtures/ tiny checked-in samples; larger CC0 RAW samples fetched by `Chronos.Tools fixtures`
├── branding/ icon sources (SVG), generated ICO/PNG sets
├── i18n/ .resx sources (en) + translations, glossary, machine-translation notes
├── deploy/
│ ├── docker/Dockerfile, docker-compose.yml, entrypoint
│ └── unraid/chronos.xml
├── .gitea/workflows/ ci.yml, release.yml, docker.yml, perf.yml (amended 2026-10-23, R2)
└── docs/ BRIEF.md (this), DECISIONS.md, CHANGELOG.md, ARCHITECTURE.md (generated per phase), reference/chronos-prototype.md
```
Project references: `App` → `Core`, `Core.Windows`, `Data`, `Protocol`. `Server` → `Core`,
`Data`, `Protocol`. `Uploader` → `Core` (hashing, metadata light), `Protocol`. `Core` and
`Data` never reference anything Windows-specific; CI builds them on Linux.
---
## 4. Architecture
### 4.1 Component diagram
```
┌────────────────────────────────────────────────────────────────┐
│ Chronos (WPF client) │
│ Library · Edit · Import · Archive manager · Jobs │
│ Local mode: SQLite + local/network archive │
│ Server mode: REST/WS client, proxies cache, render node │
└───────┬───────────────────────────────────────┬────────────────┘
│ HTTPS REST + WebSocket │ Memory cards (USB/SD)
▼ ▼
┌───────────────────────────────────┐ ┌──────────────────────────┐
│ Chronos Server │ │ Chronos Uploader (WPF) │
│ Kestrel · API v1 · Auth · Jobs │◄───────────│ queue · watch folders │
│ Storage service · Admin web panel │ HTTPS │ resumable chunk upload │
│ Pure-managed encoders │ └──────────────────────────┘
└──────┬──────────────────┬─────────┘
│ │
▼ ▼
PostgreSQL (Docker) Archive volume (/archive: originals, sidecars, proxies, renders)
or SQLite (Windows)
```
### 4.2 Shared engine
`Chronos.Core` is the same assembly on client and server: metadata parsing, image codecs,
analysis advisor, render pipeline, container writers. Only the *decoder/encoder providers*
differ per platform, behind two interfaces:
```csharp
public interface IImageDecoderProvider { bool CanDecode(ImageFormatInfo f); DecodedImage Decode(DecodeRequest r); }
public interface IVideoEncoderProvider { IReadOnlyList<EncoderCapability> Capabilities { get; } IVideoEncoderSession Open(EncodeSettings s); }
```
Registered providers, in priority order: client → `WicDecoderProvider`, then
`ManagedDecoderProvider`; server → `ManagedDecoderProvider` only. Encoders: client →
`MediaFoundationEncoderProvider` (hardware first, software H.264 fallback), then
`ManagedEncoderProvider` (MJPEG/AVI, sequences, GIF, APNG); server → managed only, plus
delegation to render nodes.
### 4.3 Data flow: card → archive → render
```
Card ──scan(light metadata)──► Import plan (sessions, names) ──copy+hash──► originals/
──light analysis──► sequence.json sidecar + DB rows ──queue──► deep analysis job
──► proxies + thumbs ──► advisor recommendations + suggested presets
User opens sequence ──► settings (project JSON) ──render──► exports/ + DB render row
```
Frames are streamed to the server by the client or uploader through chunked, resumable,
hash-verified uploads; the server commits the frame into the archive layout and updates the
sequence manifest atomically (write temp → fsync → rename).
### 4.4 Modes of the client
| Mode | Storage | Index | Who renders |
|---|---|---|---|
| Local | local or network drive archive | SQLite | this PC |
| Server-connected | server archive; local proxies/thumbs cache | server DB via API; local SQLite caches only | server (managed formats), render nodes (MP4), or this PC after downloading originals |
| Mixed | both; each sequence has an `origin` and a `sync state` | both | as above |
Workspace and projects (amended 2026-10-26, R8). The desktop edits in a **workspace**, a folder
on a fast disk outside every library (default `%LOCALAPPDATA%\Chronos\workspace`, or
`.\data\workspace` for a portable copy), never inside the library. A sequence's **home** is
where it lives: this PC's archive (phase 5a) or a server (phase 5b). The home keeps the
sequence's **projects**: Main, which is the sequence's own settings, and other named sets of
edits ("4K landscape", "Vertical social"), each with a linear history of versions pushed and
pulled like git, with no branches. The workspace holds a working copy of a project: its
working state, its versions, the sequence's proxies and, when chosen, its originals. Final
renders run where the originals are: at the home, or on this PC for a project whose
originals the workspace holds, each such render then sent home with the project and the
version it shows. A local-only library works the same way, its archive being the home.
Workspace upkeep (amended 2026-10-26, R8). The workspace removes the media of projects in
step with their home that were not opened for a while or exceed its size limit, keeps in
its own trash what it cannot prove the home holds, and moves to another folder with its
projects only after a plan (§12.3, §12.8). Nothing it removes is the only copy: versions,
unsent work and local renders not sent stay.
Server home (amended 2026-10-26, R8). A Chronos Server whose `server/info` lists the
`projects` capability is the home of its sequences, with the same rules as this PC's
archive (§7, §14.3, §14.5). A server sequence opens in the workspace like a sequence of this
PC: its proxies are downloaded into the workspace, its versions are pushed to and pulled from
the server, and its renders and analyses run on the server. The server is reached only
through this PC's sign-in on the Server screen: a project of a server this PC is not signed
in to still opens from the workspace and reads Offline. An older server's sequences open
with proxies as before (§14.5).
---
## 5. Domain model
Primary entities (identical concepts in SQLite and PostgreSQL; ids are UUIDv7 stored as
`TEXT`/`uuid`; timestamps UTC ISO-8601/`timestamptz`):
- **Archive** — id, name, root path, layout templates, schema version, created, proxy policy.
- **Sequence** — id, archive id, title, folder (relative), camera make/model/serial, lens,
first/last capture, frame count, median interval, total bytes, status flags
(`analyzed_light`, `analyzed_deep`, `proxies_built`, `thumbs_built`, `rendered_count`,
`verified_at`), hero frame id, tags, rating, notes (short), settings JSON (project),
analysis report JSON (compact) + path to full report, origin (local/server), sync state,
version counters (`settings_version`, `frames_version`), owner user id (server).
- **Frame** — id, sequence id, index, relative path, file name, size, sha256, captured at
(with sub-second and source: EXIF/XMP/filesystem), exposure time, f-number, ISO, focal
length, exposure bias, white balance, orientation, width, height, format, embedded
preview info (offset/length), light stats (mean log-luminance, clip fractions) once
analysed, flags (missing, corrupt, duplicate, excluded).
- **Render** — id, sequence id, preset name, settings JSON, output relative path, codec,
width, height, fps, duration, bytes, created, produced by (client id / server / node),
project id and project version id (the project and version rendered, the version only
when the home holds it with the settings rendered; amended 2026-10-26, R8), sha256 and
kind (amended 2026-11-05, owner review 1 R3/R8/R9: the SHA-256 of a single-file render,
taken when it is recorded, null for an image sequence's folder, verified file by file when
copied, and for a render recorded before migration 0010, hashed the first time it is
copied, deleted or restored; kind null for a video or an image sequence, told apart by the
codec, or `still` for one frame saved as an image, with fps 0 and duration 0).
- **RenderCopy** (amended 2026-11-05, owner review 1 R3/R8/R9) — id, render id, path, sha256,
bytes, copied at, copied by: one hash-verified copy of a render in a videos folder
(§12.10). No foreign key to the render, so the copy of a server render downloaded to a PC
is recorded too and a copy outlives its render; Chronos never deletes a copy.
- **Project** (amended 2026-10-26, R8) — id, sequence id, name (1–60 characters, unique
among the sequence's live projects), is main (one live Main per sequence), head version
id and number, mirrored version id and mirrored settings version (Main: the version and
the settings version of its last mirror into the sequence's settings), created by,
created, updated, deleted. Derived from the project's sidecars (§7) and rebuilt from them.
- **ProjectVersion** (amended 2026-10-26, R8) — id (UUIDv7 made by the client), project
id, parent id, number (1…, unique per project), kind (commit, merge, restore, imported,
external), author, client name, note, settings JSON in the portable form (every frame
position parked by photo, canonical text, stored as text and never re-encoded), content
hash (SHA-256 of that text's UTF-8 bytes), settings format, frames version, restored
from, created, stored (when the home took it; none while only a workspace has it).
Immutable once stored.
- **Workspace** (amended 2026-10-26, R8) — no table: a folder that describes itself
(`workspace.json` and one folder per project, §12.3).
- **Job** — id, kind (scan, rebuild, verify, light-analyse, deep-analyse, proxies,
thumbs, render, import, upload-commit, maintenance; backup, cleanup, and the read-only
duplicates and orphans reports; empty-trash, stored as 18, which erases exactly the trash
entries of a confirmed plan, erases nothing when the trash changed since, and is never
scheduled: amended 2026-10-26, R6; move, stored as 14, a Reorganize that applies exactly a
confirmed plan of new folders, titles and file names to sequences of the archive, its target,
and holds the rest of it when paused, cancelled or failed: amended 2026-10-26, R7; convert,
stored as 19, a conversion of exactly the photos a confirmed plan lists, its targets the
sequences, each converted all or nothing into its own frames or a new sequence: amended
2026-10-26, R7; workspace-copy, stored as 20, the copy of a sequence's proxies (and
originals, when chosen) and deep report into a workspace project's media, run by the
desktop only: amended 2026-10-26, R8; workspace-render, stored as 21, a render on this PC
from the originals a workspace project holds; workspace-send, stored as 22, those renders
sent home with their project and version; workspace-move, stored as 23, the workspace
folder moved with its projects; all three run by the desktop only: amended 2026-10-26, R8;
video-copy, stored as 24, renders copied hash-verified into a videos folder, desktop and
server: amended 2026-11-05, owner review 1 R3/R8/R9), target ids, state (queued, running, paused, done, failed, cancelled),
progress (done/total, fps, eta), log tail, created by, node id, attempts, error, schedule id
(the schedule that queued it; amended 2026-10-26, R10).
- **Schedule** (amended 2026-10-26, R10) — id, system key (set, and unique, on a host's
system schedules, §14.6), name, action (scan, verify, thumbnails, proxies, analysis,
maintenance, backup, cleanup, duplicates, orphans), target (`current`: the host's
archive), parameters JSON, recurrence (text, no cron: `every:<n>m|h|d` from 5 minutes to
a day, 1–168 hours or 1–366 days; `daily:HH:MM`; `weekly:mon,thu@HH:MM`;
`monthly:<1–28>@HH:MM`; wall-clock times of the host's zone), catch-up, priority of its
jobs, enabled, next run (none while disabled), last run, last job id, last outcome
(queued, skipped-pending, skipped-offline, skipped-nothing, unavailable,
failed:<reason>), created by, created, updated.
- **FrameRemoval** (amended 2026-10-26, R6) — the tombstone of a photo removed from a
sequence: sequence id, sha256, replacement sha256 (the converted file that replaced it,
R7), reason (deleted, replaced), removed at. Written from the sidecar's `removed` list (§7)
at every index sync, so a rebuild keeps it, leaving out content a frame of the sequence
holds again; it goes with its sequence row and outlives the trash entry.
- **MediaCard** (client) — id, volume serial, filesystem label, capacity, nickname, camera
identity (Make/Model/BodySerial from first file), profile JSON, first/last seen, import
history (job ids).
- **User** (server) — id, username, display name, password hash (PBKDF2), role (admin,
editor, uploader, viewer), permissions bitmask, quota bytes, used bytes, disabled,
must-change-password, created, last login.
- **Session/Token** (server) — token hash, user id, client name, created, expires, last
used, revoked.
- **RenderNode** (server) — id, user id, client name, capabilities JSON (codecs, hardware
encoder names, max resolution), last heartbeat, state.
- **Setting** — key/value (typed JSON), scope (app, archive, user).
- **Tag**, **SequenceTag** — normalised for filtering.
- **AuditLog** (server) — who did what to which sequence/user, when.
Indexes: `frame(sequence_id, index)`, `frame(sha256)`, `frame(captured_at)`,
`sequence(archive_id, first_capture)`, `sequence(camera_model)`, tags, jobs by state and by
schedule, `schedules(enabled, next_run)` (amended 2026-10-26, R10),
`frame_removals(sequence_id, sha256)` (the key) and `frame_removals(sha256)` (migration 0008;
amended 2026-10-26, R6), `projects(sequence_id, name)` and `projects(sequence_id)` where
Main, both on live rows only, `project_versions(project_id, number)` (migration 0009, with
`renders.project_id` and `renders.project_version_id`; amended 2026-10-26, R8),
`renders(created)` and `render_copies(render_id)` (migration 0010, with `renders.sha256`,
`renders.kind` and the table `render_copies`, no backfill; amended 2026-11-05, owner review 1
R3/R8/R9).
Paging everywhere (keyset pagination on `(first_capture, id)`).
---
## 6. Data layer
### 6.1 `Chronos.Data` abstraction
```csharp
public interface IDatabase : IAsyncDisposable {
Dialect Dialect { get; } // Sqlite | Postgres
Task<IDbSession> OpenAsync(CancellationToken ct); // connection from pool
}
public interface IDbSession : IAsyncDisposable {
Task<int> ExecuteAsync(string sql, params DbParam[] p);
IAsyncEnumerable<DbRow> QueryAsync(string sql, params DbParam[] p);
Task<IDbTransaction> BeginAsync();
Task BulkInsertAsync(string table, IReadOnlyList<string> columns, IAsyncEnumerable<object?[]> rows); // COPY on PG, multi-row INSERT on SQLite
}
```
Hand-written SQL in repositories (`SequenceRepository`, `FrameRepository`, …); no ORM.
Migrations: numbered `.sql` files per dialect in `Chronos.Data/Migrations/{sqlite,postgres}/`,
applied at startup inside a transaction, recorded in `schema_migrations`. Dialect
differences (types, `RETURNING`, upserts) are confined to SQL files and a small `SqlDialect`
helper.
### 6.2 SQLite (client, and Windows standalone server)
- Binding: `Chronos.Core.Windows/Sqlite/WinSqlite3.cs` P/Invoke to `winsqlite3.dll`
(`sqlite3_open_v2`, `prepare_v2`, `step`, `reset`, `finalize`, `bind_*`, `column_*`,
`exec`, `errmsg`, `last_insert_rowid`, `changes`, `busy_timeout`, `libversion`,
`extended_result_codes`). UTF-8 marshalling by hand. Check `sqlite3_libversion() ≥ 3.31`
at startup; probe `PRAGMA compile_options` and never depend on FTS/JSON extensions.
- Pragmas: `journal_mode=WAL`, `synchronous=NORMAL`, `foreign_keys=ON`,
`temp_store=MEMORY`, `cache_size=-65536`, `mmap_size=268435456`.
- Location: `%LOCALAPPDATA%\Chronos\chronos.db` (never Documents/OneDrive-synced folders —
SQLite in a synced folder corrupts). Portable mode: `portable.txt` next to the exe puts
everything under `.\data\`.
- Backups: `VACUUM INTO` copies into `backups` next to the index, made by the Backup jobs of
the `index-backup` system schedule (§14.6: every day on the desktop, daily at 03:00 on a
server, both with catch-up; the first start after an upgrade copies at once when the
newest copy is a day old), by *Back up now* (Settings › Advanced) and *Back up database*
(Archive › Maintenance), and of the index a restore replaces. Every copy prunes the folder
to the largest *Copies kept* of the backup schedules (3 by default), so no schedule
deletes copies another one keeps. Restore from Settings › Advanced. (Amended 2026-10-26,
R10.)
### 6.3 PostgreSQL client (`Chronos.Data.Postgres`) — in-house wire protocol v3
- TCP + optional TLS via `SslStream` after `SSLRequest`; `sslmode` = disable | prefer |
require | verify-full.
- Startup (`user`, `database`, `application_name=chronos-server`, `client_encoding=UTF8`,
`TimeZone=UTC`); authentication: SCRAM-SHA-256 (`Rfc2898DeriveBytes.Pbkdf2`, HMAC-SHA256,
channel binding not required), MD5, cleartext, trust.
- Simple query, extended query (Parse/Bind/Describe/Execute/Sync) with parameters in text
format except `bytea` (binary), prepared-statement cache per connection, transactions,
`COPY … FROM STDIN` for bulk inserts, `LISTEN/NOTIFY` (used for multi-instance job
wake-ups, optional), cancellation via `CancelRequest`.
- Type mapping: `text, varchar, int4, int8, float8, bool, bytea, timestamptz, uuid, jsonb,
numeric(as string)`; arrays not needed.
- Connection pool (min/max, health check `SELECT 1`, idle eviction), typed
`PostgresException` carrying SQLSTATE, retry on transient errors (57P01, 08xxx).
- Test suite runs against PostgreSQL 16 and 17 service containers in CI (§19).
---
## 7. Archive format on disk
The archive is the source of truth; the database is an index that can be rebuilt from it.
```
<ArchiveRoot>/
├── .chronos/
│ ├── archive.json { id, name, schemaVersion, created, layoutTemplates, proxyPolicy }
│ ├── index-snapshot.bin optional accelerator for rebuild (all sidecars concatenated + hash); ignored if stale
│ ├── locks/ lease files for concurrent writers (server + client on same share)
│ ├── journal/ rename-<plan>.json: a mass rename or Reorganize being applied; convert-<job>.json, .staged, .pins, .photos: a conversion (below; amended 2026-10-26, R7)
│ ├── staging/ copies an import is filing; convert-<job>/<sequence>/: the files a conversion made, until they take their place (below; amended 2026-10-26, R7)
│ └── trash/ deleted sequences and photos, and originals a conversion replaced, kept until Empty; .erased/: what Empty erased that a replaced entry needs; videos/: deleted renders (below; amended 2026-10-26, R6, R7; amended 2026-11-05, owner review 1 R3/R8/R9)
├── 2026/
│ └── 2026-09-28 Canon EOS R5 - Harbour sunset/ folder = expanded FolderTemplate
│ ├── originals/ IMG_0001.CR2 … names = expanded FileTemplate
│ ├── proxies/ 0001.jpg … (JPEG, long edge per policy; optional, regenerable)
│ ├── exports/ 2026-09-28 Harbour sunset - 4K HEVC.mp4 …
│ └── .chronos/
│ ├── sequence.json sidecar manifest (below)
│ ├── analysis.json full deep-analysis report
│ ├── project.json render settings (the "project"; Main's head, below)
│ ├── projects/ <project id>/project.json + versions/000001-<version id>.json …; .trash/: deleted projects (below; amended 2026-10-26, R8)
│ ├── thumbs.pack packed thumbnails (one file per sequence, indexed; avoids 100k tiny files on SMB)
│ ├── rename-files.json the file renames of a Reorganize a crash interrupted (below; amended 2026-10-26, R7)
│ └── *.pending.json journals of an ingest, a photo deletion, a frame replacement (replace.pending.json, a conversion or its undo; amended 2026-10-26, R7) or a restore a crash interrupted (below)
```
The root-level folders above (`.chronos/` with `locks/`, `journal/`, `staging/`, `trash/`,
`trash/photos/` and `trash/videos/`) exist from the start (amended 2026-11-06, owner review 4
R3): whatever path is chosen as the archive root, on the desktop or the server (Docker or
Windows), gets them when the archive is created, adopted or opened, and only the missing
ones are made; nothing existing is touched. The root itself is created only for a new
archive. A create whose folders cannot be made fails with the reason (drive or share
unavailable, permission denied, read-only, a file in the way); an open never fails for it:
the problem is logged and shown (§14.8 dashboard, `/health`). Per-sequence folders and the
trash's `.erasing`/`.erased` are still made when needed.
`sequence.json` (canonical, versioned, written atomically):
`{ id, title, camera, lens, frames: [{ i, file, size, sha256, capturedAt, exposure, fNumber,
iso, focal, bias, wb, orientation, w, h, format, previewOffset, previewLength, flags, source? }],
tags, rating, notes, status, versions, createdBy, updatedAt, removed? }`. Amended 2026-10-26,
R6: `removed: [{ sha256, replacement?, reason: Deleted | Replaced, at }]` holds the tombstones
of the photos removed from the sequence (§5 FrameRemoval), left out when there are none;
`frames[].source: { sha256, format, file, size }` names the file a converted frame was made
from: a conversion's Replace writes it, and its undo and a conversion job that resumes read it
(amended 2026-10-26, R7). A build that does not know either field keeps it and writes it back
unchanged.
Trash (amended 2026-10-26, R6). Nothing in it is erased except by *Empty* (§12.5, §14.8):
- `trash/<id>[-<time>[-n]]/` with `<name>.json` beside it: a deleted sequence folder, whole
(originals, proxies, exports, sidecars), and its record (the index row, renders and
tombstones the sidecar may lack).
- `trash/photos/<id>-<time>[-n]/originals/…` with `<name>.json` beside it: photos deleted
from sequence `<id>`, each original with its XMP companion when no photo that stays shares
it, and the record: each photo's frame record, each file's former place, size and SHA-256,
the sequence's title and folder, who deleted them, when, and the kind (photos, or replaced
for originals a conversion replaced, R7: such an entry also keeps each photo's replacement
SHA-256, a copy of the sequence's `analysis.json` and the job that made it). A photo never
hashed is hashed as it goes; one whose original was already missing goes with its record
alone.
- `trash/videos/<render id>-<UTC ticks>/` with `<render id>-<UTC ticks>.json` beside it
(amended 2026-11-05, owner review 1 R3/R8/R9; §12.10): a deleted render's file (or image
sequence folder) under its own name, and its record: the render's row, the path it was
at, the sequence's id, title and archive-relative folder, the SHA-256 it is restored
against (each file's for a folder), who deleted it and when. Listed as entry
`videos-<render id>-<ticks>`, kind videos, titled by its sequence. The delete runs under
the sequence's lease: the record is written first as `<entry>.json.pending` (the journal,
never listed), the file moves (renamed on its volume; copied, verified and deleted from
another one, committed once the verified copy has its name), then the row goes and the
record takes its name; the next archive open completes a delete whose file reached the
trash and undoes the others. A source that could not be removed after its copy verified
(a file held open) stays whole beside a `<entry>.leftover` marker, removed after a re-hash
at the next open or restore, never over a render recorded there since. Copies in a videos
folder are never touched. Records live under `trash/videos/`, so an older Chronos never
reads them as sequences' and its *Empty* leaves them, the folder growing until a build of
this release empties it.
- `trash/.erasing/`: entries moved aside by Empty before they are deleted, so a listing never
sees half an entry; leftovers are deleted by the next Empty.
- `trash/.erased/<sequence id>.json` (amended 2026-10-26, R7): the record that Empty erased a
deleted sequence (its id, title, entry, when and by whom), written before the folder goes
while a replaced entry of that sequence stays in the trash, and never while the sequence also
lives (this index has it, or a folder's sidecar names it). Each Empty deletes the records no
listed replaced entry needs. The trash never lists them.
- In a sequence's `.chronos/`, `remove.pending.json` is written before a photo deletion's
first move and `restore.pending.json` before a restore's; until the sidecar is written the
entry's record is `<name>.json.pending`, which the trash never lists, restores or empties.
The next writer of the sequence (any `ReadLocked`, a scan, a sequence delete) undoes a
deletion the sidecar does not show yet (files back, record and folder gone) and completes
one it shows, and settles an interrupted restore under the entry's lease (files back into
the entry, or the record without the photos the sidecar lists again). A restore into a new
sequence stages each original in `<entry>/.restoring/` (never the archive's staging) and
puts it back on any failure.
- A replaced entry (amended 2026-10-26, R7) goes back by a swap: while every converted frame
still holds its conversion (re-hashed) and names the original as its `source`, the originals
take their frames' place again as a Replace does (below), the converted files going into a
replaced entry in turn and the entry's `analysis.json` back into the sequence; otherwise the
originals come back as a new sequence. *Empty* erases it only while each conversion of its
originals still hashes to its SHA-256 where the archive shows it now; of a conversion deleted
since, every copy the trash still holds must hash to it, and with none left nothing keeps the
entry. The archive is asked, never this host's index alone: the sequence's sidecar where the
index or the entry says it is, in the trash, or found by walking the archive's folders (once
per dry run or Empty, again only for a sequence no longer where the walk found it), followed
through its replaced tombstones. A conversion counts as deleted only on the archive's own
word: a deleted tombstone ending its chain in the sequence's sidecar, the sequence in the
trash, or the trash's record of erasing the sequence (`.erased/`), which outweighs a stale
row of this index but not a live sidecar. Anything else keeps the entry: a sidecar that holds
none of the conversion and no tombstone of it (one rebuilt by adoption), a sequence found
nowhere with no erasure record (the walk may have skipped its folder), a frame never hashed.
Deleting photos writes the sidecar without them (frames version + 1) and with a tombstone of
each SHA-256 no photo that stays holds, and clears what covered the frames (light and deep
analysis, thumbnails, proxies), which follow as jobs; proxies are renamed and `thumbs.pack`
is re-keyed so the frames that stay keep theirs (while a thumbnail pass holds the pack, that
pass draws them again). Filing a photo into the sequence again (an import, a restore, an
explicit upload again, §14.4) drops its tombstone; emptying the trash does not.
Reorganize (amended 2026-10-26, R7; §12.5, §14.8) applies a confirmed plan step by step, a
step being one sequence and the sequences nested in a folder that moves with it:
- `journal/rename-<plan>.json` holds the plan (its steps, templates and the sequences it was
made for), the steps completed and what they did; it is written before the first step and
deleted after the last. A plan whose job was paused, cancelled or failed is marked held and
waits for that job; any other is completed at the next archive open. A journal that cannot be
read is logged and left where it is: the archive opens, the plan is not resumed and its job
fails with the reason.
- Each step takes the leases of its sequences, then their thumbnail leases, and checks under
them, before anything of it moves, that the plan still fits: the sequences where the index
had them, nothing indexed since inside a folder that moves or at its new place, no sidecar of
a newer format to rewrite, the title the plan started from where it changes the title or
names the folder or files after it, the folder and title the templates give from the first
photo as it is now, and the file renames planned again from the sidecar (compared by digest).
What no longer fits refuses the rest of the plan, except photos changed since, whose
sequence keeps its names (§12.5).
- Then the folder moves (a change of case only through a temporary name, never onto another
folder of that exact name), and in one transaction the index follows: the sequence's folder
and title, its frames' paths and the paths of the exports that moved with the folder. Only
then are files renamed; once its folder moved, a step always goes to its end.
- A sequence of the plan that an earlier step left as it was inside a folder that moves later
(it changed after the plan, or the folder that was to carry it stayed) goes with that folder,
under the same leases, keeping its title and file names. Before a held plan resumes, a folder
that moves may hold only such sequences and those of the steps still to come; any other
refuses the plan, which is then given up.
- File renames run under `rename-files.json` in the sequence's `.chronos/`: every file first to
a hidden temporary name beside it (`.chronos-rename-<token>-<n>.tmp`), then every file to its
new name, so chains and swaps of names never meet a name another file holds and no file is
ever written over; then the sidecar names the new files (frame order and ids unchanged,
frames version + 1), then the index, then the journal goes. A failure while files move puts
every file back. After a crash the next writer of the sequence (any `ReadLocked`, the plan's
resume) completes the renames, safely run again from wherever it stopped: a new name taken
meanwhile sends that photo and its companions back together to their old names, or to the
first free `_2`, `_3`…, and the journal stays while a temporary file is left.
- Proxies (named by frame index), thumbnails (by index and content hash), tombstones and trash
records need nothing; a photo restored from the trash comes back under the name it had.
Conversion (amended 2026-10-26, R7; §8.7, §12.5, §14.8) writes over no original: Replace
moves each original into the trash, New sequence leaves it where it is.
- The photos a confirmation lists are written whole, before its job is queued, into
`journal/convert-<job>.photos` (one line per sequence, each frame id in plan order); the job
record keeps each sequence's digest alone, so it grows with the sequences, not the photos.
Without that file the job holds each sequence to its whole plan made again (the same digest).
- A `convert` job takes one sequence at a time. Under the sequence's lease, its sidecar settled
where the index has it then, it plans the sequence again and goes on only while the photos the
confirmed plan listed are there with the content confirmed; it pins them in
`journal/convert-<job>.pins` and from then on, a retry included, converts those alone, so
photos received or verified since stay as they are. A sequence another index moved away (its
folder gone, or holding another sequence) is left for the retry after this index's scan.
- Stage A, without the lease: each original is re-hashed against its record, converted and
verified (§8.7) into `staging/convert-<job>/<sequence>/`, several at once, and each staged file
is appended to `journal/convert-<job>.staged`; `journal/convert-<job>.json` records what each
sequence came to and whether the passes it needs were queued. Before each photo the free space
must hold it and every photo started whose converted file has not landed yet (a file lands
whole, by a rename, before it is verified). A resumed or retried job keeps the staged files
whose SHA-256 still verifies, settles a replacement a crash left half-way, and takes a
sequence it had replaced already as converted.
- Stage B, under the lease and while every photo pinned still holds its content, all or
nothing: Replace swaps the files of the frames (next point); New sequence files the converted
copies into a new sequence through the archive ingest (§12.5), and the journal names that copy
as soon as its photos are filed. A retry or resume finishes the copy it named (or finds by its
session key) once that copy holds every pinned photo, whatever changed in the source since; it
never remakes a copy deleted since (the sequence is then changed: plan again). A source that
another conversion copied in the same format after this one was confirmed gets no copy
(outcome superseded, in the job's log) once that conversion is done; while it is not, the
sequence is left for the retry.
- A Replace, and the undo of one, writes `replace.pending.json` in the sequence's `.chronos/`
first. Each swapped frame's original and its XMP companions go into one trash entry of kind
replaced; each converted file comes in under the name filing gives a photo of the sequence
(§7.1, with the target's extension), never onto a file there, those leaving included (`_2`…).
The frames keep their ids and indices; each record takes the converted file's size, SHA-256,
format, upright size and full-resolution tier, orientation 1, no preview, the flags of that
file and those the user set, and a `source` naming the original. The sidecar (its frames
version one higher, analyses, thumbnails and proxies cleared) gains a replaced tombstone per
original naming its replacement, and content that comes back loses its tombstone; then the
index follows, the proxies of the swapped frames are deleted and the passes the frames need
are queued. The journal records its phase (moving, written, undoing) and each frame's new
name: the next writer of the sequence completes a replacement whose sidecar lists a new name
and undoes any other, and an undo that fails stops that writer, as a deletion's recovery
does. Every writer that changes the frames (an ingest, a deletion, a restore, a Reorganize
step, a sequence deletion) settles it first, or waits while it cannot be settled yet (the
trash entry an undo takes its files from is busy); a scan settles it too, and reconciles
nothing in the folder while it stays.
- The job's journals and staging go once every sequence is final. Maintenance keeps a job's
staging while the job is queued, running or paused, removes it at once when the job is done
and otherwise once its files are a day idle, and removes the journal when the job is done. A
job this index does not know (another host's on a shared archive) keeps both while any of
their files was written within 90 days, then both go.
Projects (amended 2026-10-26, R8; §5, §12.3, §14.5). A sequence's projects live in its
`.chronos/projects/`, and the sidecars are the truth: a full scan or a rebuild takes them
back into the index, and every project operation first brings the index in line with them,
under the sequence's lease (a read waits at most 3 s for it, then answers from the index).
- `<project id>/project.json` is the record (`chronos-project-record` v1: id, sequence id,
name, is Main, head `{id, number}`, `mirrored` `{id, number}` for Main, created, created
by, updated, deleted). Its `updated` time never goes back: each write stamps now or 1 ms
past the record it replaces. Older builds ignore `mirrored`.
- `<project id>/versions/000001-<version id>.json` holds one immutable version
(`chronos-project-version` v1), its settings as a JSON string checked against its content
hash. A version file is at most 64 MiB, refused before it is written. A version is
written first, then the record, then the index in one transaction; a version file past
its record that follows the head is adopted, any other moved to `versions/.stray`.
Nothing is ever deleted.
- A deletion moves the project's folder into `projects/.trash/<id>-<ticks>`, then writes
the deleted record there. Main cannot be deleted. The projects' trash is never emptied
by Chronos (Empty trash does not see it); it leaves with its sequence's folder.
- A deletion is never inferred from a missing folder or a record that cannot be read: only
a record that says deleted, or a folder in the projects' trash, deletes. The trash is read
before the live folders, so a deletion is never undone; a version another PC pushed into
the live folder before the deletion reached it is moved beside the deleted record, into
the trash folder's `versions/`, never deleted. A record that cannot be read holds
its project back: listed as the index has it, nothing written for it, writes refused
until it reads again.
- Main mirrors the sequence's settings: its head is written to `project.json` and to the
index's settings, so analyses, the Library, renders and server sync keep reading them.
Main is made lazily, from the settings as they are, the first time a project of the
sequence is asked for. Settings another path writes (an older Chronos, the API, an
analysis, sync) become an *external* version of Main at the next project operation; a
mirror a crash cut short is completed, and if the settings also moved meanwhile, one
*merge* version is made in which the settings written meanwhile win where both changed.
A mirror never writes over settings written in `project.json` since this index last knew
what it held: it takes them in first. On the server, whose earlier releases wrote a
settings `PATCH` into the index alone, settings in the index that differ from
`project.json` are never dropped: Main is born with the index's in force over the file's,
and a Main another program made keeps them as a version.
- The index heals the sidecars from what it knows: a project whose folder is gone is
written back from the index; a record behind the index (a projects folder put back from
a backup) gets the missing version files, then the index's head and, when it is older,
the index's name; a record that is lost is written again from the index only once the
folder has looked the same for 2 minutes and no trash folder holds the project, so a
record a sync tool is still bringing wins. A folder with versions and no record, of a
project no index knows, is a creation cut short: it holds nothing back and is left as it
is. One Main per sequence is decided from the records (the oldest that says Main); any
other becomes an ordinary project with every version kept.
- A sequence with no folder yet (a server's sequence made before its first photo) keeps no
projects: it lists none, and every change is refused before anything is written (amended
2026-10-26, R8).
- On a server, a `PATCH` of a sequence's settings writes them to its `project.json` under
the sequence's lease first, then to the index, and puts the file back when the index does
not take them, so Main never takes an older file for the sequence's settings (amended
2026-10-26, R8).
Rules: originals are immutable (never rewritten; edits are settings; a conversion takes an
original out of its sequence only into the trash, amended 2026-10-26, R7); every write of a
sidecar goes to a temp file, `fsync`, rename; the folder name is derived from templates at
import time and never auto-renamed afterwards: only Reorganize, an explicit user action
behind a dry run, moves and renames what is filed, updating sidecars and DB together
(amended 2026-10-26, R7). Network drives: UNC or mapped paths; long-path aware
(`\\?\` prefix); no `FileSystemWatcher` reliance — periodic polling by mtime/size (the
*Archive scan* system schedule of each host, §14.6; amended 2026-10-26, R10) plus manual
rescan; offline detection with graceful read-only state.
### 7.1 Naming templates
`FolderTemplate` default `{year}/{date} {camera}`; `FileTemplate` default
`{date}_{time}_{n:0000}`. Tokens (localised descriptions in resources): `year, month, day,
date, time, hm, session, sessionstart, camera, lens, iso, shutter, aperture, n, nsession,
name, ext, title`. `{token:format}` passes the format to the .NET formatter. Illegal
characters are replaced, never passed through; templates are validated live in the UI with a
preview of the first three names.
One naming rule for import, upload and Reorganize (amended 2026-10-26, R7):
- A photo is named in its sequence with the sequence's camera and lens (its first photo's, or
the camera hint its creator gave): a second body in a whole-folder import, or a lens changed
during a session, does not show in the names. `{n}` is its place in the sequence, `{name}`
its name on the card, `{ext}` its file's extension (the card name's when the file lost the
extension of a photo), and a frame recorded without a capture time takes the sequence's
start (its first frame's time, else when it was made; never today's date). A name already
given, or held by a file that stays, gets `_2`, `_3`… before the extension. Folder and title
templates see the sequence's first photo as filing saw it.
- So a Reorganize with the archive's own templates changes nothing filing named. It gives
other names, which its dry run lists, where filing could not know the sequence as it is now:
`{session}` of a card's second session on (an import numbers its sessions, a sequence is
one), `{n}` after photos skipped mid-session as duplicates or filed out of capture order, and
a folder or title from a photo that is no longer first.
- Rules every template meets wherever it is typed or sent (Settings › Archive, Import,
Reorganize, the admin panel's Archive): a folder template may not write a level scans never
enter (starting with `.`, or `originals`, `proxies`, `exports`, `.chronos`); a file template
must keep the photo's extension (appended, or after `.{ext}`: `{n}{ext}` is refused), tell
the photos of a session apart (three sample photos two seconds apart must get three names)
and hold no slash. A level a value such as a title would hide that way is written with a
leading `_`. A file name longer than 200 characters is shortened before its `.{ext}`, never
through it. A title template gives text, not a file name (`Paris: night` stays), at most 200
characters. A template `archive.json` already holds, saved before these rules, is kept
through edits of other settings; changing it holds it to them, and a new archive meets them all.
---
## 8. Image pipeline
### 8.1 Supported input formats
| Family | Extensions | Metadata (in-house) | Pixels on Windows | Pixels on server (Linux) |
|---|---|---|---|---|
| JPEG | jpg jpeg jpe jfif | APP1 Exif/XMP, MPF | WIC or managed | managed (baseline + progressive) |
| PNG | png | eXIf, iTXt XMP | WIC or managed | managed |
| TIFF | tif tiff | IFDs | WIC or managed (never WIC for a compression it does not decode, a floating-point predictor or 32-bit integer samples, which it reads as black or noise; amended 2026-10-26, R7) | managed (strips/tiles; none/PackBits/LZW/Deflate/JPEG; gray, RGB and linear RAW samples only: a CMYK, CIELab or palette TIFF is unavailable, never read as gray; amended 2026-10-26, R7) |
| DNG (smartphones: Apple ProRAW, Android, Samsung; DJI; Insta360; Leica; Pentax; Ricoh; GoPro files converted by Adobe software) | dng | IFDs, MakerNote | managed full decode (amended 2026-10-16, R4) | managed full decode |
| Canon | cr2 cr3 | cr2: TIFF; cr3: ISO-BMFF `CMT1..4` | WIC (Raw ext.) → managed CR2 (P1) → embedded preview | managed CR2 (P1) → embedded full-size JPEG (CR3 track 1) |
| Nikon | nef nrw | TIFF | WIC → managed NEF (P1) → preview | managed NEF (P1) → preview |
| Sony | arw srf sr2 | TIFF | WIC → managed ARW (P1) → preview | idem |
| Fujifilm | raf | RAF header + TIFF | WIC → managed RAF uncompressed (P1) → preview | idem |
| Olympus/OM, Panasonic, Pentax, Samsung, Hasselblad, Phase One, Leica | orf rw2 raw pef srw 3fr fff iiq rwl | TIFF-like | WIC → managed (P1/P2) → preview | preview (P1: managed decoders as feasible) |
| GoPro | gpr (DNG+VC-5; a DNG is GPR only when its raw image is VC-5, amended 2026-10-16, R4) + jpg sidecar | IFDs | preview/sidecar JPEG; VC-5 out of scope | sidecar JPEG |
| HEIF/HEIC/AVIF (iPhone, Samsung, DJI) | heic heif hif avif | ISO-BMFF `Exif` item | WIC (HEIF + HEVC/AV1 extensions) | metadata only; pixels via client-made proxies |
| WebP | webp | RIFF `EXIF` chunk | WIC (WebP ext.) | metadata only (P2: managed VP8L) |
| JPEG XL, JPEG XR, BMP, GIF (single frame) | jxl jxr bmp gif | minimal | WIC if a codec exists | not supported |
Windows codec availability is enumerated at startup (`IWICImagingFactory::
CreateComponentEnumerator`). Missing codecs are surfaced as a one-line notice with an
"Install" button opening the Microsoft Store page (Raw Image Extension, HEIF Image
Extension, HEVC Video Extensions, AV1 Video Extension, WebP Image Extension; verify product
IDs at implementation time). The format table in Settings › Formats shows, per format,
which tier will be used on this machine.
### 8.2 Decode tiers (deterministic, logged per frame)
1. **Native full decode** (in-house or WIC) at working resolution, 16-bit linear light.
2. **Embedded preview** (largest JPEG found: TIFF `JPEGInterchangeFormat`/SubIFD strips,
RAF preview, CR3 full-size JPEG track, MPF). Marked `PreviewOnly` on the frame; the
sequence shows a chip with the count and the advisor caps output resolution to the
preview size unless the user overrides.
3. **Unavailable** → frame flagged `Undecodable`; excluded from render; listed in the
sequence warnings.
The tier is what the frame can give. Analyses, thumbnails, proxies and the editor's preview
take an embedded preview that is large enough when a RAW has one, by choice and without
changing the frame's tier; renders always decode natively. WIC counts as a native RAW
decoder only when the decoder it chose for the file is the Raw Image Extension (Windows'
in-box DNG decoder reads only the preview). (Amended 2026-10-16, R4.)
The in-house DNG pipeline (server and client): CFA/linear DNG, `Compression` 1/7 (lossless
JPEG SOF3)/8 (Deflate)/34892 (lossy JPEG), `LinearizationTable`, `BlackLevel` (+ repeat
dims, delta), `WhiteLevel`, `AsShotNeutral`/`AsShotWhiteXY`, `ColorMatrix1/2` +
`CameraCalibration`, `AnalogBalance`, Bradford adaptation to D65, demosaic **AHD** (default,
"perfect result" priority) with bilinear for Draft quality, highlight reconstruction (clip
+ desaturate), `ActiveArea`/`DefaultCrop*`, `Opcode` lists 1–3 (at least `GainMap`,
`WarpRectilinear`, `FixVignetteRadial`; unknown opcodes ignored with a warning),
`BaselineExposure`. Output: linear Rec.709/sRGB primaries float planes.
### 8.3 Managed codecs (all in `Chronos.Core/Codecs`, pure C#, SIMD where it pays)
- `JpegDecoder` (baseline, progressive, restart intervals, 4:4:4/4:2:2/4:2:0/4:1:1/gray,
12-bit optional, ICC ignored), `JpegEncoder` (baseline, quality 1–100, subsampling
choice, optimised Huffman tables optional, Exif/XMP APP1 embedding, an ICC profile in APP2
chunks: amended 2026-10-26, R7).
- `PngDecoder`/`PngEncoder` (all colour types, 8/16-bit, Adam7 decode, filters, zlib via
`System.IO.Compression.ZLibStream`).
- `TiffReader`/`TiffWriter` (as prototype: 16-bit TIFF, an ICC profile in tag 34675, linear DNG
writer with `PhotometricInterpretation=34892`, scene-referred for a conversion, §8.7: amended
2026-10-26, R7).
- `IccProfile` (amended 2026-10-26, R7): ICC profiles read and written (matrix/TRC and gray,
`curv`/`para` curves, `desc`/`mluc` text), an in-house Adobe RGB (1998)-compatible and a
Display P3 profile, the profiles a conversion makes for the values it writes (a profile's
colorants with the sRGB curve, a gray curve as RGB), and what a photo's headers say of its
colour space (JPEG APP2, PNG iCCP/sRGB, TIFF tag 34675, HEIF/AVIF `colr`, WebP ICCP, Exif
ColorSpace and Interop).
- `GifEncoder` (animated; median-cut palette + Floyd–Steinberg; frame differencing).
- `ApngEncoder`.
- `AviMjpegWriter` (RIFF AVI with `MJPG`, OpenDML index for > 2 GB).
- `Mp4Muxer` (port of prototype: streaming `ftyp`/`mdat`/`moov`, 90 kHz timescale,
variable durations, `avcC`/`hvcC`; add `av1C` + OBU handling in P1), `AnnexBParser`.
- `Bmff` reader (HEIF/CR3/AVIF boxes), `Riff` reader (WebP/AVI), `Raf` reader.
### 8.4 Image buffers
Port the prototype's `ImageBuffer`/`FrameBufferPool` (pooled float planes, linear light),
`FrameWindow` (sliding window, disk spill under a memory budget, read-ahead), and
`GeometryStage` (crop/aspect/affine with Catmull-Rom). Memory is governed by the window
size and budget, never by sequence length; the self-tests assert this.
### 8.5 Thumbnails and proxies
- Thumbnail: 320 px long edge JPEG q80, packed per sequence in `thumbs.pack` (header,
index table, entries), with an LRU in-memory cache and async loading for the UI.
- Proxy: JPEG at policy long edge (default 1920; options 1280/1920/2560/full), q92, Exif
orientation applied, capture time copied into Exif. Proxies are optional and regenerable;
they enable remote editing, server-side rendering of formats the server cannot decode,
and fast scrubbing.
### 8.6 The only OS executables/dialogs the product may invoke
`SHFormatDrive` (format card), `ShellExecute("open", url)` (links, Store pages),
`ShellExecute("explore", folder)` (reveal in Explorer). Nothing else.
### 8.7 Conversion (amended 2026-10-26, R7; §7, §12.5)
A conversion makes each photo a JPEG (baseline, 4:4:4, optimised Huffman tables, 8-bit,
quality 1–100, default 95), a 16-bit TIFF (RGB, Deflate with the predictor) or a linear DNG
(16-bit LinearRaw, lossless JPEG tiles), the archival choice.
- Decoding: at full resolution only, never from an embedded preview, upright. The managed
decoders come first for every format they read natively (a RAW developed in-house at float
precision, the same on every host), WIC only for what they do not read. A 16-bit target never
takes a RAW through a decoder that develops it at 8 bits (WIC's Raw Image Extension): such a
RAW converts to JPEG only. The server decodes with the managed decoders alone, so it converts
no CR3, HEIC or RAW body its developer does not support, nor a CMYK, CIELab or palette TIFF,
an unsupported compression or a file past their size limits: its dry run says to convert those
photos on a PC, which reads them through WIC. A photo another host flagged unreadable is asked
again where the conversion has other decoders (WIC on a PC) and planned when they decode it at
full resolution; a corrupt one stays out everywhere. WIC is never used for a TIFF whose
compression is not 1–5, 7, 8, 32773 or 32946, whose predictor is other than none or the
horizontal one on integer samples, or whose integer samples exceed 16 bits (WIC gives black or
noise for them without an error), in conversions and in every other desktop decode: the
managed reader takes it, or it is unavailable. A conversion's WIC probe reads the file's headers (the decoder, the
first frame's upright size, the pixel format), so the size bounds apply to what only WIC
reads; a file it cannot open is missing or held, never unreadable.
- A linear DNG keeps what a RAW develops: the values are stored in linear ProPhoto primaries
(colours outside sRGB stay positive), divided by the power of two, at most 2^4, that brings
their peak under white, which BaselineExposure gives back; ColorMatrix1 and ForwardMatrix1
describe that space (illuminant D65, AsShotNeutral 1/1/1). The as-shot white balance is baked
in and values below black are clipped. An export's DNG stays clipped linear sRGB (§11.3).
- Colour: what Chronos reads from a photo never changes. Its decoders read no profile: they take
code values through the sRGB curve and a float TIFF's values as they are. A converted file
holds the values they read from the original, as they read them back, within what the target
holds (a JPEG or TIFF-16 holds 0..1 and clips beyond; a DNG up to 4 stops above white), and
says truthfully what those values are:
- A JPEG or TIFF-16 keeps the codes of an RGB profile's code values and carries that profile.
Float values are written as sRGB codes with a profile made for them: the original's
colorants and media white with the sRGB curve ("<description> (sRGB curve)"). A lookup-table
profile named sRGB is carried; other float values in a lookup-table profile are refused. A
gray profile's codes are kept, its curve carried as an RGB profile with sRGB's colorants
("<description> (RGB)"); linear gray needs no profile.
- A linear DNG, whose matrices Chronos develops it with too, takes only values that are sRGB's
as read: no profile, an sRGB profile, float values in sRGB's primaries whatever the curve,
linear gray, gray codes on the sRGB curve. Any other profile (Adobe RGB, Display P3,
ProPhoto, a gamma-1.0 profile's code values) is refused as `color_profile`; TIFF-16 and JPEG
convert those photos with their profile.
- A matrix/TRC profile is sRGB by its numbers (its matrix within 2e-3 of sRGB's, its curves
within 2e-3 of the sRGB curve), by its name only when it has no colorant tags at all; one
whose colorants convert nothing, or that has no curves, is never sRGB.
- Exif Adobe RGB (uncalibrated with Interop R03) and a HEIF nclx box with P3 primaries get the
in-house profiles. Refused for every target: CMYK, Lab and other non-RGB profiles, Exif
uncalibrated without R03, other nclx primaries or an HDR transfer, a profile that does not
parse. A photo that records no colour space is sRGB.
- Damaged values: a photo whose decoded pixels hold NaN or infinite values fails as damaged
data, and nothing is written.
- Metadata: capture time (to the tick), offset, exposure, f-number, ISO, focal length, bias and
white balance from the sidecar; camera, serial, lens, 35 mm focal length, exposure program,
metering mode, flash, GPS, artist and copyright from the original, the sequence's camera and
lens where it names none. MakerNote and XMP are not carried; the orientation is 1.
- Size: a photo is not converted when the target cannot hold it (a JPEG side above 65535) or
the server's decoders could not read it back (a JPEG above 2^28 pixels; a TIFF-16 or DNG
above 2^29 samples, about 179 MP). Sizes are weighed without overflow, so a damaged header's
absurd size is too large, never a wrapped number.
- Each converted file is hashed as it is made and written atomically, then read back (the same
size and SHA-256), its metadata read again (format, capture time and offset) and decoded by
the server's decoders at full resolution and size; a file that fails any of these is deleted
and its photo fails.
---
## 9. Metadata model and parsers (`Chronos.Core/Metadata`)
Port and extend the prototype's binary parsers: container detection by signature; JPEG
segment scan (APP1 Exif, APP1 XMP + extended XMP, APP2 MPF); TIFF/IFD walker with on-demand
window reads (never load a whole RAW to read tags), SubIFD selection of the main image,
`0x02BC` XMP; ISO-BMFF walker (`meta/iinf/iloc` Exif item, CR3 `CMT` boxes, `PRVW`/`THMB`,
track sample tables for the CR3 JPEG); RIFF; RAF; PNG chunks. MakerNote parsing only where
it adds value: Canon/Nikon/Sony/Fuji/Olympus/Panasonic body serial, shutter count, lens
name, exposure mode, image stabilisation flag, intervalometer hints, sRaw flags.
Fields extracted per frame: DateTimeOriginal + SubSecTimeOriginal + OffsetTimeOriginal
(fallback: CreateDate, GPS time, file mtime — recorded with `TimestampSource`), ExposureTime,
FNumber, ISO, FocalLength (+35 mm equiv), ExposureBias, ExposureProgram, MeteringMode,
WhiteBalance mode + Kelvin if present, Flash, Orientation, dimensions, Make/Model/BodySerial,
Lens, GPS (lat/lon/alt), Artist/Copyright, Rating/Label from XMP, `Software`. All parsers
are fuzz-safe (no exception escapes; malformed input yields partial metadata + a warning).
`ExifWriter` (prototype) is kept for proxies, exports and converted photos: writes a minimal,
valid Exif block, with the exposure program, metering mode, flash and white balance when known
(amended 2026-10-26, R7).
---
## 10. Analysis advisor
Two passes; both deterministic, both explainable (every finding and every recommendation
carries a resource key + parameters that render as a localised reason in tooltips).
### 10.1 Light analysis (at import/scan, metadata only, seconds per 10k frames)
Cadence (median interval, jitter, gaps → session boundaries; `SessionGapMinutes` default
45, `MinimumSessionFrames` 8), total capture span, exposure series (EV =
log2(N²/t) − log2(ISO/100)), exposure step detection (ISO/shutter/aperture changes and
their EV amplitude), camera/lens identity, orientation consistency, resolution
consistency, timestamp sanity (clock resets, duplicates, non-monotonic), format tiers,
GPS → sunrise/sunset/civil twilight via an in-house solar-position calculation (NOAA
algorithm) → day/night/transition labelling.
### 10.2 Deep analysis (background job after import; "speed is not an issue")
Every frame decoded at analysis width (default half native, capped 2048): per-frame
trimmed log-luminance mean, histogram, clip fractions, per-channel means (WB drift), colour
temperature where applicable (McCamy with Planckian-locus validity check), sharpness
(Laplacian variance), noise estimate, phase-correlation shift vs previous frame (shake
magnitude, drift → panning), region mask (horizon by strongest row-luminance step, refined
per column; fallback by luminance), flicker spectrum (autocorrelation of luminance
residuals → deflicker window), exposure steps *as actually received* by the pixels,
star-field detection (small bright point density on night frames), cloud coverage estimate
(sky-region texture), scene-change detection (histogram distance), duplicate/black/white
frames, motion magnitude histogram (for motion-blur recommendation), suggested hero frame.
Results → `analysis.json` + compact summary in DB; charts in the Edit section (§12.3; amended 2026-10-16, R7).
### 10.3 Recommendations (rules, each with reason and confidence)
- Frame timing mode: Constant when jitter < tolerance; Adaptive when the intervalometer
paused deliberately; Interpolated when gaps are sparse and motion is smooth.
- Frame rate and time compression: choose 24/25/30/60 fps and duration targets from cadence
and motion magnitude; offer "fit to N seconds".
- Motion blur target shutter angle: from measured shutter angle (360×exposure/interval) and
motion magnitude; skip flow when exposure already exceeds the target.
- Deflicker window (4× flicker period), region deflicker when horizon confidence is high,
holy-grail transition length (half the typical distance between exposure steps), WB
smoothing, stabilization on/off (measured shake > 0.3 px) with crop cost, crop/aspect
suggestions from subject placement (on the view as shown: the aspect and the horizon's
place follow a turn, flip or straighten; amended 2026-11-04, owner review 1 R6), output
resolution cap from source/preview size and
codec level limits, quality profile.
- Auto-generated **sequence presets** ("Night sky — 4K 10-bit HEVC 24 fps, deflicker 41,
stabilise", "Holy grail sunset — 4K HEVC 30 fps, transitions 18", "Construction cam —
1080p H.264 30 fps, adaptive timing", "Social vertical 1080×1920") = full project settings
+ export preset; one click to apply; saveable as user presets.
### 10.4 Auto vs manual
Every deducible parameter shows an **Auto** indicator with the chosen value and a reason
tooltip; touching the control takes it manual; a small reset returns it to Auto. Per section
**Optimise** applies heavier decisions (module on/off) and reports what changed and why. Where
data is missing, the advisor says so and changes nothing.
---
## 11. Rendering engine and export
### 11.1 Render plan (port)
The engine walks a list of output frames, each with a (possibly fractional) source position
and a duration; constant, adaptive, interpolated and remapped timings all produce this one
shape. Fractional positions synthesise frames from the motion field; motion blur scales
with `√(target² − real²)` shutter angle composition (prototype rule).
Output program (amended 2026-11-05, owner review 1 R3/R8/R9). The export's playback
(`export.playback`: direction forward, reverse or boomerang; loops 1–10; fade in and fade
out 0–30 s; hold end 0–60 s) turns the plan into the frames the encoder receives, in order,
each with its duration on the 90 kHz clock and a fade gain (`OutputProgram`). Reverse is the
plan backwards; a boomerang plays forward then backward without repeating the turning
frame; loops repeat the pass, a boomerang's later passes starting at its second frame so the
joint is not doubled. The hold adds whole output periods to the last frame, so a
constant-rate output keeps its grid. Fade in and fade out together take at most half of the
program: longer, both are scaled by the same factor, with the warning
`Export.Render.FadesShortened`. A frame held across a fade is split into its output periods,
so the gain moves smoothly; the first and last frames are black. A fade goes to and from
black, applied after the look and the knee in linear light with the gain read through the
sRGB curve, so it looks even. Every pass is rendered again: render time, the estimate and
the progress count the program's frames, and the duration includes the hold. Median and
mean windows are per plan frame in either direction; star trails accumulate in program
order (reversed trails grow from the end) and start again at each loop; a boomerang with
star trails renders forward with `Export.Render.BoomerangStack`; an unknown direction plays
forward with `Export.Render.DirectionUnknown`. *Preview 10 s* stays the plan forward.
Still frame (amended 2026-11-05, owner review 1 R3/R8/R9). A render can save one source
frame as one image (PNG, JPEG or TIFF 16-bit, the TIFF always at 16 bits): the frame
whole, at the export's output size, with every correction of the frame itself (exposure,
geometry, look, knee) and no stacking, interpolation, motion blur or playback. Its file is
the export's name template, " - " and the 1-based frame number in four digits
(`2026-09-28 Harbour sunset - 4K HEVC - 0413.png`), recorded as a render of kind `still`.
### 11.2 Modules (port, keep the validated behaviour and its tests)
Colour science (linear light, sRGB transfer), orientation detection (declared vs decoded
size), deflicker (weighted local linear regression with Tukey robustness blended by
surviving-window fraction), region deflicker (horizon/luminance masks), holy-grail exposure
step redistribution (only steps the pixels actually received), WB smoothing (channel
ratios), optical flow (pyramidal differential, median filtered), motion blur (gather
filter), stabilization (phase correlation, nine patches, similarity fit, texture gating,
smoothed path), virtual camera (Bézier eased pan/zoom keyframes, composed with
stabilization into one affine), non-linear time remap (Fritsch–Carlson monotone spline),
temporal stacking (median, progressive max with decay), geometry stage, codec level limits,
disk spill, cancellation semantics.
Orientation and look (amended 2026-11-04, owner review 1 R5/R6). The project's quarter
turns, mirror (left↔right), flip (top↔bottom) and straighten (±15°, positive clockwise)
apply after Exif orientation, in that order, inside the one warp between stabilisation and
the virtual camera; pixels are never turned after decode, so the stabiliser, the sky mask
and the horizon stay in the raw frame. The crop and the keyframe centres are normalised in
the view frame: oriented, straightened and zoomed just enough that no corner shows (cover
zoom cos|θ| + max(W/H, H/W)·sin|θ|, about 1.43× at 15° on 16:9, folded into the decode
size; never stored). The look (None, Mono, Sepia, Warm, Cool, Vivid, Muted, Fade, with a
strength) is a built-in linear-light matrix, contrast power and lift, applied once per
output frame after stacking, interpolation and motion blur and before the highlight knee;
measuring, flow and stacking never see it. The render, the server, render nodes and the
editor preview call the same Core code (`RenderGeometry`, `RenderSize`, `FrameFinish`), so
they agree to the pixel. Library, filmstrip and admin thumbnails stay the raw photos.
### 11.3 Encoders and containers
| Output | Client (Windows) | Server (Linux/Windows) |
|---|---|---|
| MP4 H.264 (Baseline/Main/High, 8-bit) | Media Foundation: hardware MFT (NVENC/QSV/AMF) else Microsoft software encoder | render node; P2 in-house intra-only encoder |
| MP4 HEVC Main / Main10 (10-bit, P010) | hardware MFT only | render node |
| MP4 AV1 | hardware MFT only (Windows 11 + AV1 encoder) | render node |
| AVI MJPEG | managed | managed |
| Image sequence JPEG / PNG / TIFF-16 / linear DNG | managed | managed |
| Animated GIF, APNG | managed | managed |
Encoder session design as prototype: encoder MFT driven directly (not SinkWriter), NV12/P010
conversion in-house, Annex-B → MP4 samples, streaming muxer; rate control (VBR/CBR/quality),
GOP, B-frames, profile/level via `ICodecAPI`. Capability discovery (`MFTEnumEx` hardware
flag, friendly names, DXGI adapter) is shown in Settings › Rendering and used to hide
unavailable codecs. Amended 2026-11-05, owner review 1 R3/R8/R9: a value the export names
itself that the encoder refuses through `ICodecAPI` (rate control other than VBR, the
quality or a given bit rate, a given keyframe interval, B-frames other than 2 outside
Baseline) is a render warning (`Export.Encoder.Ignored.<Setting>`), never a failure; every
encoder commits its output without overwriting a file (a name another program took fails
the render); a still is one file (`StillImageSession`, managed on every host), written to a
temporary name first.
### 11.4 Presets (amended 2026-11-04, owner review 1 R5)
Presets bind a resolution class, codec, profile, bit depth, fps, bitrate (≈0.10 bpp/frame
H.264, 0.07 HEVC, 0.05 AV1; night-sky content is the most demanding), GOP and container.
Editing any value flips the name to "Custom"; matching values restore the preset name.
The chosen proportions win (amended 2026-11-04, owner review 1 R5): when the project's
aspect (manual, or the Auto's advised value) is not "source", a fixed-size preset is a box
and the aspect is fitted inside it, the box turned to portrait for a ratio below 1: 4K at
9:16 = 2160×3840, 1:1 = 2160×2160, 4:5 = 2160×2700, 21:9 = 3840×1646; 1080p at 9:16 =
1080×1920. "source" keeps the preset's own size. Sizes stay even for codecs that need it,
then the encoder's limits cap them, read as long edge × short edge. The preset's name does
not change; the Export step shows the size rendered as *Output size*.
Built-in presets: 8K UHD 10-bit HEVC archive · 4K UHD 10-bit HEVC archive · 4K UHD HEVC ·
4K UHD H.264 compatible · DCI 4K HEVC 24 fps · Cinema 21:9 4K HEVC 24 fps · 4K 60 fps ·
1440p H.264 · 1080p H.264 share · 1080p 60 · 1080×1920 vertical social · 1080×1350 4:5 ·
1440×1440 square · 720p quick preview (GOP 1 s) · AV1 4K · MJPEG AVI intermediate · PNG
sequence · JPEG sequence · TIFF-16 sequence · GIF preview (480 px) · APNG. Resolutions:
720p/1080p/1440p/4K UHD/DCI 4K/5K/6K/8K/custom; aspects 16:9, 21:9, 4:3, 3:2, 1:1, 9:16,
4:5, source, custom; fps 23.976/24/25/29.97/30/48/50/59.94/60/120.
Advanced encoding and standard resolutions (amended 2026-11-05, owner review 1 R3/R8/R9)
edit the export's existing overrides, so they raise no settings format and render on
nodes of earlier releases: rate control Variable, Constant or Quality (H.264, HEVC and AV1
only), bit rate for Variable and Constant, quality 1–100 for Quality; keyframes in seconds
(0.5–10 by 0.5, or Auto, the preset's), stored as whole frames at the output frame rate and
keeping their seconds when the frame rate changes; B-frames 0–4 or Auto (none for Baseline,
MJPEG, GIF, APNG and image sequences); the profiles the codec and depth allow (H.264
Baseline, Main, High; HEVC Main at 8 bits, Main 10 at 10; AV1 Main only). The managed
codecs have no rate control, keyframes or B-frames to choose. The Resolution choice is
Preset, Source, 720p, 1080p, 1440p, 4K UHD, DCI 4K, 5K, 6K, 8K or Custom: a standard one
writes its landscape box into the overrides and the chosen proportions are fitted in it (4K
at 9:16 = 2160×3840); Custom shows Width and Height. Any edit makes the export "Custom".
### 11.5 Export UI behaviour
Preview stays visible during encoding (optional live preview); single global progress bar
(frames, fps, elapsed, ETA) mirrored to the taskbar; cancel is always available and leaves
no partial files behind; output name from `{title} - {preset}` template; "Reveal in
Explorer" and "Render another preset" follow-ups; batch render of several presets in one
job; per-sequence render history. Amended 2026-11-05, owner review 1 R3/R8/R9: the render
history is the Videos section filtered on the sequence (§12.10), reached from the Export
footer's *Videos (n)* and the Render menu; the Render menu (§12.3) is the "Render another
preset" follow-up and *Save frame* saves a still; batch presets inherit the export's
playback.
### 11.6 P2: in-house H.264 intra-only encoder
Baseline profile, I-frames only, I_16x16/I_4x4 prediction, 4×4 integer transform, CAVLC,
fixed QP or simple rate control. Large files but universally playable; enables MP4 output
on a server without render nodes. Validate with the in-house MP4 inspector and a system
player smoke test on Windows CI.
---
## 12. Chronos desktop client — UI specification
### 12.1 Shell
```
┌────┬─────────────────────────────────────────────────────────────────────────────┐
│ ≡ │ ▮▮▮▮▮▮▮▮▮▮▮▮▮░░░░░░░ Building proxies · Harbour sunset · 1,240/3,600 · 12 fps · 3 min │ ⏹ │ ← global job bar, only while a job runs
│ ├─────────────────────────────────────────────────────────────────────────────┤
│ ▤ │ │
│Lib │ │
│ ⬇ │ section content (edge to edge) │
│Imp │ │
│ ✎ │ commands of the section live INSIDE the section, in one row above the │
│Edit│ content they act on; every command has a tooltip │
│ ▶ │ │
│Vid │ │
│ ▣ │ │
│Arch│ │
│ ☰ │ │
│Jobs│ │
│ ☁ │ │
│Srv │ │
│ │ │
│ ⚙ │ │
│Set │ │
│ ├─────────────────────────────────────────────────────────────────────────────┤
│ │ 412 sequences · 618,204 photos · 9.4 TB · ☁ Connected to "Studio NAS" · 3 jobs │ ← status strip
└────┴─────────────────────────────────────────────────────────────────────────────┘
```
- Left navigation rail (prototype pattern): Library, Import, Edit, Videos (amended
2026-11-05, owner review 1 R3/R8/R9), Archive, Jobs and Server at the top, Settings alone at the bottom (About is the last page of Settings, §12.9;
amended 2026-10-26, R5); full names in 200 px, collapsible to 48 px of icons with ≡ or
Ctrl+B (state saved at once; a collapsed icon's tooltip names its section before
describing it; amended 2026-10-16, R1), badge counts (warnings, running jobs), hover
tooltip with section description. The Settings icon is a toothed gear (8 teeth, centre
hole), the same in Chronos, the Uploader and the admin panel; the circle with rays is the
Sun icon only (amended 2026-10-26, R4).
- Fluent theme, system/dark/light, system accent; density "comfortable"; 8 px grid; one
typeface (Segoe UI Variable, system fallback for CJK/Arabic/etc.).
- Window chrome custom (dark title bar), min size 1200×760; per-monitor DPI.
- Keyboard: standard shortcuts, listed in tooltips ("Render · Ctrl+R").
- Videos (amended 2026-11-05, owner review 1 R3/R8/R9; §12.10) is a rail section after
Edit. The rail's shortcuts are Ctrl+1 Library, Ctrl+2 Import, Ctrl+3 Edit, Ctrl+4 Videos,
Ctrl+5 Archive, Ctrl+6 Jobs, Ctrl+7 Server and Ctrl+, Settings (Archive, Jobs and Server
were Ctrl+4…6 before).
- Notifications: unobtrusive toasts inside the window (bottom-right) for job completion,
card detected, server events; optional OS toast when minimised.
- Modals only for destructive confirmations and login.
### 12.2 Library (home)
```
│ [🔍 Search title, camera, tag] [Year ▾] [Camera ▾] [Status ▾] [Tags ▾] [Sort ▾] [⊞][☰][▦] [⟳] │
├──────────────────────────────────────────────────────────────────────────────────────────────┤
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ hero thumb │ │ │ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │
│ ├────────────┤ ├────────────┤ ├────────────┤ ├────────────┤ ├────────────┤ ├────────────┤ │
│ │Harbour sun…│ │2026-09-27 │ │… │ │ │ │ │ │ │ │
│ │3,600 · R5 │ │1,020 · GoPr│ │ │ │ │ │ │ │ │ │
│ │✓ ▣ ▶2 ☁ │ │✓ ▣ · ☁ │ │ │ │ │ │ │ │ │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
```
- Unit of the library = **sequence** (never a flat list of 600k photos). Views: grid
(default), list (sortable columns), timeline (year/month bands with density).
- Card: hero thumbnail, title (user title or `{date} {camera}`), count · camera · span,
status chips: `✓` analysed, `▣` proxies, `▶n` renders, `☁` synced/origin, `!` warnings.
Hover reveals quick actions: Open, Analyse, Render preset, Sync.
- Multi-select → mass actions bar (Analyse, Build proxies, Verify, Tag, Rate,
Reorganize…, Convert…, Upload, Download, Delete, Export list as CSV). Reorganize… (amended
2026-10-26, R7; formerly Move) and Convert… (amended 2026-10-26, R7) take the selected
sequences of one archive, never a server-only one, into their dialogs of §12.5; a selection
of two archives is refused with the reason.
- Filters are chips; saved views (e.g. "Night, 4K, not rendered"); search is instant
(indexed columns); everything virtualized (in-house `VirtualizingWrapPanel`).
- Photos deleted from a sequence (amended 2026-10-26, R6; on the admin panel, §14.8, or by
another program sharing the archive) leave it at its next index sync: its count follows,
a cover whose photo went is cleared, the project's positions on those photos (exclusions,
hero, keyframes) wait as pending frames until a restore brings the photos back, and the
others follow their photos without a settings edit. *Delete…* still moves whole sequences
into the archive's trash, which lists photo entries too (§12.5).
- Open (a card, the Archive manager's Open, Jobs' Open; amended 2026-10-26, R8) opens a
sequence of this PC in Edit as a project of the workspace (§12.3): the project of that
sequence opened last on this PC, else *Open in workspace* asks which. A server-only
sequence opens the same way, as a project whose home is the server, when the server keeps
projects and the account may edit; otherwise it opens with proxies (§14.5).
### 12.3 Edit (amended 2026-10-16, R7; formerly "Sequence editor"; amended 2026-10-26, R8; amended 2026-11-04, owner review 1 R5/R6)
```
│ ← Harbour sunset ▾ · [Main ● In sync ▾] · 3,600 frames · Canon EOS R5 · 2 s · 2 h 00 m [Analyse] [Optimise all] [Render ▾] │
│ ✓ Analysis ── ▲ Frames ── ✓ Exposure ── ✓ Motion ── ✓ Camera ── ✓ Time ── ⑦ Stack ── ⑧ Export │ ← the path
├──────────────────────────────────────────────────────────────────┬──────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────┐ │ Exposure │
│ │ PREVIEW │ │ Deflicker [●] Auto 41 ⓘ │
│ │ [◧ compare] [⊹ vectors] [▭ regions] [▦ crop mask] [1:1] [⛶] │ │ Strength ───●──── 0.8 │
│ └──────────────────────────────────────────────────────────────┘ │ Transitions [●] Auto 18 ⓘ │
│ ▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏ filmstrip + markers │ [Optimise section] [Reset] │
│ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ the step's measuring tool (charts, frame table, curves) │ │ [‹ Previous] 3 / 8 [Next ›] │
│ └──────────────────────────────────────────────────────────────┘ │ │
```
- One sequence at a time. Without an open sequence, or after **Change sequence** (the
title's ▾, Ctrl+O, or Next on the last step), Edit shows a picker: this PC's sequences
and the signed-in server's, newest first, searched by title, camera or tag, the open
sequence (else the one edited last) selected and in view; Enter (on what was typed) or a
double-click opens one, Esc clears the search, then goes back. The next sequence is read
first: the open one stays open behind the picker until another one opens (a server
sequence whose proxies are still coming, or one that cannot open, leaves it open), its
last edit saved first, or discarded on the user's word and then never written. The
Library, Jobs, the Server screen, project files and the command line still open
sequences in Edit; ← goes back to the Library. Amended 2026-10-26, R8: the picker has two
groups, *Workspace* (the workspace's projects, the one saved last first, each with its
state chip read from its home after the list shows) above *Library*; the search filters
both, and Enter opens a library match, a project only when no sequence matches. A
Workspace row's context menu and the Delete key offer *Remove local copy*, also for a copy
that cannot open.
- The steps form a guided path, freely navigable: **Analysis** (every finding of the
analyses with the step that deals with it; light, flicker, exposure steps received,
shake and flagged frames; Analyse), **Frames** (virtualized table: index, time,
exposure, ISO, f, size, tier, flags; exclude/include; set hero; the findings about
single frames), **Exposure** (deflicker, regions, holy-grail transitions, WB, look:
filter and strength) with luminance/waveform charts, **Motion** (blur, flow quality,
stabilization) with shake path chart, **Camera** (aspect, rotation, mirror, flip,
straighten, the crop drawn on the preview and locked to the aspect, virtual camera
keyframes with a spline editor; amended 2026-11-04, owner review 1 R5/R6),
**Time** (fps, timing mode, remap curve, fit-to-duration, plan chart), **Stack**
(median/max, trail length; optional), **Export** (preset, values, output name, batch
list, render history, sponsor slot — Phase 9 only; amended 2026-11-05, owner review 1
R3/R8/R9: the preset table, the Output, Encoding, Playback and File groups and the
footer, below; the render history is the Videos section, §12.10).
- Each step shows where it stands, by its own glyph as well as its colour: to do (its
number), done ✓ (nothing is missing: Auto, or Edited once a setting or value of the step
was set by hand), attention ▲ (a saved analysis of other frames or one that cannot be
read now, frames still flagged, data an Auto setting that applies lacks, a render
blocked or none made from the current settings), running ◐ (its analysis or render),
waiting ○ (it needs the deep analysis). Statuses guide; they never block a step.
Previous and Next (Ctrl+PgUp/PgDn), Alt+1…8 and the step bar (←/→) move between steps,
the keyboard following; each step's tooltip starts with its name and ends with its
shortcut, and screen readers hear the step and its state. The editor opens on the step
last shown for that sequence in this run; else on Analysis while the sequence has no
current deep analysis or one waits, runs or is paused; else on Frames.
- Preview always on top with tools: zoom/pan (1:1 shows raw pixels), wipe compare
original/corrected, motion-vector overlay, region boundary, crop mask ("what I lose" vs
"how it will look"; on the Camera step it is on by default and edits the crop, below),
full-screen native-resolution window with collapsible shot data.
- Every deducible control shows Auto/manual state (§10.4); every control has a tooltip
with the reason and the effect of moving it the wrong way.
- While a job runs on this sequence, settings that would change the rules mid-render are
disabled; viewing tools stay live.
Framing and look (amended 2026-11-04, owner review 1 R5/R6; §11.2, §11.4).
- The crop is edited on the preview. On the Camera step the preview shows the whole view
frame (turned and straightened, without stabilisation or camera moves), so the box is the
stored crop, always locked to the output's aspect. It has 8 handles while the project is
editable (not read-only, of a newer format or busy, and the preview already showing the
current orientation): a drag inside moves it, a corner resizes from the opposite corner,
an edge from the opposite edge, Alt about the centre; at least 10 % of the largest box,
always inside the frame; rule-of-thirds lines while dragging; Esc cancels; one drag is one
undo step. A press on the box or Enter selects it (an Accent ring): arrows move it 1 %,
Shift+arrows 10 %, + and − resize it 2 %, and Esc gives the arrows back to the frames.
Inside a box that spans the view both ways a press pans while zoomed; the middle button
always pans. Screen readers hear the crop's place and size. An aspect change refits the
box about its centre.
- Camera rows: Aspect; Rotation (Rotate left, Rotate right and the angle, each press a
quarter turn as the picture is seen, also under a mirror); Mirror and Flip (switches);
Straighten (−15…15° by 0.1°, a fine grid on the preview while dragged or focused); Crop
size (10–100 % of the largest box), Crop X and Crop Y (the box's place in the frame's
slack); the keyframes. A turn, mirror or flip keeps the content: the crop, the keyframe
centres and roll follow it and a non-square aspect transposes (16:9 ↔ 9:16); each press
is one undo step. *Reset framing* clears the crop, the offsets and the orientation,
undoing the presses so keyframes and aspect stay on their content; disabled when nothing
is set. The crop-margin and Offset X/Y rows are gone: a crop placed by offsets in an
earlier release renders as before and becomes a box at its first edit.
- Exposure ends with the Look group: Filter (None, Mono, Sepia, Warm, Cool, Vivid, Muted,
Fade) and Strength (1–100 %, n/a with None). The look shows on the corrected side of the
compare wipe and never triggers a new measure.
- Export: Width and Height edit the preset's box; *Output size* shows the size rendered
(§11.4), marked *capped* when the encoder shrinks it.
- Settings format: a project is written as settings format 2 only while it uses a turn,
mirror, flip, straighten or a look other than None; otherwise it stays format 1, text and
hash unchanged. An earlier Chronos opens a format-2 project read-only. A merge takes a
turn or mirror on one side and a framing change on the other (crop, keyframes, offsets,
aspect) as one conflict; straighten and the crop merge apart. A server that announces an
older settings format (`server/info`, §14.3) is not sent what it would get wrong: *Sync*
(push and pull), *Send and render*, the Library's *Render* of a remote card and a remote
editor's save are held, saying *This server's Chronos cannot read these settings; update
it*; a local render of a workspace project is not held. Proportions win (§11.4) changes
no stored format: a 9:16 project on a 4K preset stays format 1, but its server render
needs a server and a render node of this release (§14.7). Amended 2026-11-05, owner
review 1 R3/R8/R9: a project whose playback is not the default (§11.1) is written as
settings format 3 (the playback object and each of its members are left out at their
defaults, so every other project keeps its format, text and hash); Chronos 0.1.0-rc.12 and
earlier open it read-only, and the same gates hold it from a server that announces
format 2 or less. Advanced encoding and standard resolutions raise no format (§11.4).
Export and the Render menu (amended 2026-11-05, owner review 1 R3/R8/R9; §11).
- The header's **Render ▾** reads "Render" whatever the preset, at the same width in every
language (Ctrl+R renders now). Its tooltip gives the preset, the output size, codec and
depth, frame rate, estimated size and time, and the reason when rendering is blocked. Its
menu is built each time it opens: the recommended preset, the batch presets and up to
three recent presets of this sequence's render history (stills left out), then *Other
presets ›* with the presets grouped as Video, Social, Intermediate, Image sequence and Web;
each preset with a muted details line (size · codec · fps) and the current one checked
(no estimates: each costs a plan). Below a separator: *Render batch (n)*, *Add to queue*,
*Save frame ›* (PNG, JPEG, TIFF 16-bit) and *Videos*, which opens the Videos section on
this sequence. Every item has a tooltip.
- *Save frame* saves the frame under the preview's cursor as a still (§11.1), routed as the
sequence's renders are (this PC, the server, a render node; a workspace project with its
originals saves it here into `exports/` and sends it home with the renders, one with
proxies only has its home save it from the project's settings). It is disabled, the
reason in its tooltip, while the sequence is read-only, without a frame to save, or
against a server that announces a settings format below 3.
- The project ▾ menu has *Save project file*; the Export footer keeps it for a library
sequence.
- The Export step's measuring area is the **preset table**: one 28 px row per preset in its
group, each group header collapsible (a group with the preset in use or the recommended one
open at first, else the first group), columns batch ☐, Name with the *Recommended* chip,
Size, Codec, fps, Est. size and Est. time. A click on a row selects its preset, the check
box adds it to the batch.
- The Output panel is four **collapsible groups** that scroll, each with a muted one-line
summary of its values while collapsed: *Output* (Container, Codec, Resolution with Width
and Height for Custom, Output size, Frame rate with Auto, Colour depth; open), *Encoding*
(Encoder, Rate control, Bit rate or Quality, Keyframes, B-frames, Profile; collapsed),
*Playback* (Direction, Loops, Fade in, Fade out, Hold end; collapsed), *File* (File name,
Save to, Sync, Restore settings; open), then the notices. Open or closed is kept per group
for this user in the app's settings, never in the project. Rows that do not apply are
disabled with the reason in their tooltip (B-frames for Baseline, rate control and
keyframes for the managed codecs, Boomerang with star trails); a value set by hand has its
Reset. Fades and hold are sliders 0–10 s by 0.5 s with exact entry beyond.
- A fixed **footer** under the groups: the result line `<file name> · <size> · <time> ·
<duration> · <frames>` (loops and hold included), *Render now* (primary), *Add to queue*,
*Batch (n)*, and the links *Videos (n)* (this sequence's renders), *Reveal*, *Send again*
with *Not sent*, and *Save project file* for a library sequence.
Workspace (amended 2026-10-26, R8; §4.4, §7). Edit opens a sequence of this PC's archive only
as a project of the workspace, and never writes into the library; a capture (sample data)
keeps editing the library. A server sequence opens as a project of the workspace too when its
server keeps projects (server home, below); otherwise it opens with proxies as before.
- Which project: as Settings › Workspace › *Open project* says (amended 2026-10-26, R8):
*Last used*, the default, the one of that sequence opened last on this PC; *Main*; or
*Ask*, a list of the sequence's projects in the workspace (when it holds two or more),
the last used chosen first. Each opening is remembered for the clean-up. With none of
its projects in the workspace, *Open in workspace* asks: **Project** (an existing one,
Main first, made from the sequence's settings as they are; or New, with a name of 1–60
characters unique in the sequence) and **Media** (*Proxies*, or *Originals*: the proxies
plus the originals, to render on this PC; *Default media* chooses first, and *Originals*
is disabled, its tooltip saying why, when the drive lacks room for them), with the copy's
size, the originals' apart, and the drive's free space (*Not enough space* below the size
of the media chosen plus 0.5 GB). A Main this Chronos cannot read (saved by a newer
Chronos, or damaged) is listed disabled with the reason; asked for alone, or with nothing
else to offer, it is refused at once, a damaged one offering *Remove local copy*. The
project is then checked out and its media copied by a *Workspace copy* job, followed like a server sequence's proxies (the
picker line, a toast with a Jobs link); it opens when the copy is done, and the open
sequence stays open meanwhile.
- The workspace folder holds `workspace.json` and one folder per project:
`project.chronos` (the working state, a project file of format 2 with a `workspace`
section: project, name, Main, home, base version, media; format 3 while the media hold
originals, so an older Chronos refuses it; at most 64 MiB), `media/` (`media.json`,
format 2 while it holds originals or was cleaned; `proxies/`;
`originals/<frame id>-<first 8 hex digits of its SHA-256><extension>`; `analysis.json`),
`versions/` (the versions taken from the home and those not sent yet;
`versions/.replaced` keeps every version a sync replaced), `sync.json` (a conflict, a
restore, or the journal of a sync under way), `exports/` (the renders made on this PC and
their ledger `renders.json`: file, SHA-256, project, version, and whether it was sent),
and the lease `.lock.lease`. Beside the projects: `workspace.json`, `.trash`, and a move's
journal `.move.json` (below). A workspace folder inside a library is refused before
anything is written, with *Choose folder*.
- The editor writes only the working state, atomically under the project's lease a moment
after each edit, merged photo by photo with what a sync or a copy wrote. Where a sync and
the editor changed the same setting, it asks (keep mine, take the library's).
- Beside the title, the project button (its name; Main in the UI language) with a state
chip: In sync, Changed, Not sent, Library newer, Conflict, Offline, No media, Syncing,
Not in library (the home deleted it: its copy can only be discarded), Damaged (a version
saved here cannot be read: nothing is saved, sent or taken until it is repaired from the
home's copy). The chip is read again a moment after each edit. Its ▾ menu:
- *Save version…* (Ctrl+S): a note, Enter saves. With Sync automatically on, the version
is sent at once.
- *Sync*: take the library's new versions, then send yours. A push whose parent is the
library's head goes straight in; otherwise the library's versions are taken, yours are
replayed on them (a version that changes nothing once replayed is not sent) and the
working state is merged setting by setting, pending frames photo by photo.
- *History…*: the versions, newest first: number, kind (Saved, Merged, Restored,
Imported, Outside change), the PC, time, note, Not sent or Current. *Compare* lists the
settings that differ from now (heroes, exclusions and keyframes by name, several photos
counted); *Restore* makes a version the project as one undo step, unsaved changes saved
as a version first, and a toast offers Undo.
- *Open project…* (another project of the home), *New project…* (from this project's
last version in the library), *Rename…*, *Delete project…* (never Main; confirmed; it
sends everything first, then the project goes to the library's project trash with all
its versions).
- *Copy originals…* (amended 2026-10-26, R8): queues a *Workspace copy* of the originals
besides the proxies. *Proxies only…*: a plan (originals deleted, their size, those kept
in the trash) and a confirmation; each original is deleted only when the library holds
the same bytes, the others go to the workspace's trash. Both are refused while the
project has changes or its jobs run, and their tooltips then say why.
- *Remove local copy…*: a plan (files, size, versions not sent, unsaved changes,
conflict, renders made here not sent, originals the library no longer holds). *Remove*
only when everything is in the library, whose head and the base are read back and
checked against their hashes first; *Send first* sends what is missing (renders
through a *Send render* job, the removal waiting for it), then removes; *Discard
changes* asks for the project's name to be typed. The copy's files, every one but the
media, go to `<workspace>/.trash/<id>-<time>`; the media are deleted, but an original
goes there too unless the library holds its bytes (each file hashed now, never judged
by `media.json`). A removal that cannot move a file puts everything back and says so.
- Conflicts are asked only when a merge finds settings both sides changed, and list this
side's value as the working state holds it: *Keep mine*, *Take library's* (one undo step;
the toast's Undo brings back only those settings), *Save both* (your versions go to a
sibling project "<name> (<PC>)" and this one takes the library's) or *Later* (the chip
says Conflict, Save version is disabled and the next Sync asks again). A choice settles
only the conflict shown: if the library moved again, the dialog asks again. A conflict
met by an automatic sync waits for the open dialog to close. A project the library holds
in a newer Chronos's format is never merged: only *Save both* and *Later*; with nothing
unsent, the project takes it read-only.
- A project read-only (a newer Chronos's settings) says so with a toast and disabled
controls; an edit not stored yet when such settings arrive is kept in
`versions/.replaced` (*Edit kept aside*).
- When the library's photos changed since the copy (added, removed, converted, verified),
a banner offers *Update media*: the media are copied again and positions follow their
photos.
- Renders of a workspace project run on this PC's engine at the library, with the
originals and the project's portable settings embedded, one job per preset; they record
the project, and the version only while no version waits to be sent and the library
holds that version with the settings rendered.
Analyses run at the library; with Sync automatically on, Main takes an analysis' Auto
values.
- Local render (amended 2026-10-26, R8). A project whose media are *Originals* renders on
this PC whatever its home, as a *Local render* job (`workspace-render`): from the
originals the workspace holds (refused, with the count, while a frame placed has none),
into the project's `exports/`, each output hashed and recorded in `renders.json` under
the render id it keeps at the home. It names its version only when `versions/` holds it
with the content hash of the settings rendered. With *Version on render* on, changes not
saved are saved as a version (noted *Render*) and, with Sync automatically on, sent
first; a failed save or a conflict holds the render. Then a *Send render* job
(`workspace-send`) sends every render of the project not sent yet: each file hashed again
(one changed since is refused and stays), its version pushed first when the home lacks
it (a version a replay stored under another id is found by its content hash, else the
render goes with its project alone), then filed in the library after a read-back, or
uploaded to the server with its project and version (§14.3); a render the home holds
already is only marked sent. A server takes one file per render, so an image sequence
stays in the workspace, failed. The Export step lists renders not sent as *Not sent*,
with *Send again*; the files stay in `exports/` until the clean-up.
- `.chronos` files: format 2 opens its workspace project (a copy of one gives it its
settings as one undo step; a project the library lacks falls back to Main); format 1
gives its settings to the sequence's Main. *Save project file* still writes format 1.
- Server home (amended 2026-10-26, R8; §4.4, §14.3, §14.5). A sequence of a server that
keeps projects (the `projects` capability) opens as a project whose home is that server,
through this PC's sign-in:
- *Open in workspace* lists the server's projects (Main first, or New) and the media
(*Proxies* or *Originals*, amended 2026-10-26, R8); the copy's size is estimated (1.5 MB
a proxy, the originals from the server's frame sizes), and the copy checks the drive's
free space as it goes. A project of the sequence already in the workspace opens from
there, the server reachable or not. A project asked for (a `.chronos` file) that the
server does not have opens the sequence's Main instead.
- An account without Edit gets the sequence with proxies, read-only, and nothing is
checked out. A copy the workspace already holds still opens; its pushes are refused
(*Your account cannot change the projects of this server.*).
- The *Workspace copy* job downloads through the signed-in session, never through this
PC's archive: the frames of one frames version with the aliases of the server's
conversions, each frame's proxy, or its thumbnail while the server has none (a later
copy, *Update media*, takes the proxy once the server has it), and the server's deep
report, and with *Originals* each frame's original (a frame whose original the server
refuses or lacks keeps its proxy). Each file is hashed as it arrives and checked on
disk, four at a time, resumable. On a metered connection, with *Pause metered
transfers* on (§12.7), the copy waits (amended 2026-10-26, R8).
- Texts name the server (*Server newer*, *Not on server*, *Take server's*). The chip and
the picker's rows of the server's projects follow its `projectChanged` at once; after a
lost event stream, and when the sign-in starts or ends, every project of that server
reads its state again. A project the server deleted reads *Not on server*; its copy and
unsent versions are kept. A rename on the server reaches the copy at once, and at every
pull.
- Renders run on the server and render what it holds, unless the workspace holds the
originals (a local render, above, sent to the server). Changes not saved as a version, or
versions not sent, are offered first: *Send and render* saves and sends them, *Keep*
renders nothing. The job names the version the server holds, without settings, and the
server renders it with the job's export. Offline, *Not on server*, Damaged or media
removed: nothing is rendered and a toast says why. Analyses run on the server; with
Sync automatically on, Main takes their Auto values when the server tells its next
change (within 2 minutes).
- The editor connects with the sign-in in use at each render or analysis, so a project
opened signed out renders once signed in. Projects name the server by the address they
were made with: signed in to the same server through another address, they read
Offline.
- Clean-up (amended 2026-10-26, R8). The *Workspace clean-up* schedule (§14.6) removes the
media of projects not opened past *Clean after*, then of the least recently used while
the projects take more than *Size limit*, which also runs after each copy (never on the
project just copied). A project is cleaned only when it is in sync with its home, asked
now, not open, with no copy, render or send of it waiting or running, and no render not
sent; it loses its proxies, its originals and the renders the home took, never its
working state, versions, sync state or deep report, and reads *No media* until opened
again, which copies them again. An original is deleted only when the home holds the same
bytes; otherwise it goes to the workspace's trash.
- The workspace's trash (`<workspace>/.trash`) keeps removed copies and originals set
aside, each entry filled under a hidden staging name and listed once whole. Only Settings
› Workspace › *Empty…* erases it: the entries and their size listed, their number typed,
and nothing erased when the trash changed since the list.
- Moving the workspace (amended 2026-10-26, R8). *Move…* shows a plan (projects, files,
size, free space at the target, same drive or not, projects with work not sent) and
queues a *Move workspace* job (`workspace-move`), refused when the target is the folder or
inside it, inside a library, already holds a workspace or one of its projects, lacks
room, or while a workspace job waits. The open project closes first, and Edit waits. On
one drive each project folder is renamed; across drives each file is copied, hashed on
both sides and named only once both agree, and no source file goes before every one is
verified and the new folder is in use. A journal (`.move.json`) lets a stopped move go on;
one that fails before the switch is undone, a cancel too. A move left unfinished is
offered again at start and in Settings (*Resume*); until then Change… and Move… wait, and
workspace jobs queued before the move work in the folder that now holds their project.
### 12.4 Import (cards)
```
│ Devices │ Profile "EOS R5 · card A" (SD 128 GB · serial 3F2A-9C11 · Canon EOS R5 #0431) [Edit ▾] [New] │
│ ● SD 128 GB EOS R5 card A ▲ │ Destination (•) Archive ( ) Folder [D:\Shoots …] ( ) Server ☁ "Studio NAS" │
│ ● microSD 64 GB GoPro 12 │ Scan [✓] Subfolders Sessions [✓] gap [45] min · min [8] frames [✓] Verify hashes │
│ ○ E:\ no DCIM │ Names {year}/{date} {camera} / {date}_{time}_{n:0000} → 2026/2026-09-28 Canon EOS R5/2026-09-28_18-02-11_0001.CR2 │
│ ○ Folder… │ On existing (•) Skip ( ) Rename ( ) Overwrite │
│ │ After import (•) Keep card ( ) Delete imported ( ) Format card [✓] Eject [✓] Deep analysis │
│ [✓] Import automatically when │ Plan 3 sessions · 4,812 photos · 96.2 GB · 12 min [Show plan] [ Import ▶ ] │
│ a known card is inserted │ │
```
- Devices list: removable volumes and any volume with `DCIM`; identity = volume serial +
label + capacity, camera identity from the first file; known cards show their nickname
and profile; unknown cards prompt for a nickname (one field).
- Plan before touching disk: sessions, folders to be created, first three file names,
duplicates already in the archive (by hash), disk space check.
- A picked folder (`Folder…`, and Archive › Adopt folder › Copy into archive…) adds a
**Group** row: *Sessions* (as for a card) or *Whole folder* (amended 2026-10-26, R9).
Whole folder makes the folder (its subfolders too while Subfolders is on) one sequence
per file format: camera bodies and pauses are ignored, formats are not (RAW+JPEG of the
same shots stays two sequences, so no frame is doubled). Sessions, gap and minimum are
then disabled, their tooltips saying why. The title defaults to the folder's name (a
typed title wins; it also fills `{title}`); a repeated import gives the folder's name
only to a sequence without a title, so a rename made since survives. Each plan row shows
the camera, or "n cameras", and the format, and both dates when its photos span several
days; Split in Show plan cuts a part off, Merge joins it back. A folder
starts on Sessions every time (folders have no profile); cards, drives and the admin
panel have no Group choice.
- Copy with hash while streaming; verify by re-reading destination; only then delete or
format (OS dialog); eject via `IOCTL_STORAGE_EJECT_MEDIA` after `FSCTL_LOCK_VOLUME`.
- Import copies every photo byte for byte and converts nothing (amended 2026-10-26, R7; the
sketch's former *Convert* row is gone): deleting imported photos and formatting the card
need archived copies that re-hash to the card's files, which a converted file never does,
and originals are immutable. Converting is a separate, explicit step after import, behind a
dry run (*Convert…*, §12.5, §14.8); a photo converted since keeps its card copy (§13).
- Destination "Server" streams frames through the client to the server (§14.4); the
server confirms each hash before the client counts it as imported.
- Auto-import on insertion (per card), with the OS toast "Card X detected — Import".
### 12.5 Archive manager
```
│ [Archive: D:\ChronosArchive ▾] [Scan] [Rebuild index] [Verify] [Duplicates] [Orphans] [Adopt folder…] [Maintenance ▾] │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 618,204 photos · 412 sequences · 9.4 TB · 14 cameras · 2019–2026 │
│ ▆▇█▅▂▁▃▆ photos per month (heatmap) ██████░░ storage by year ▉▉▉▍ by camera ▉▉▎ by format │
│ Index health: ✓ sidecars 412/412 · ⚠ 3 sequences without proxies · ⚠ 1 unverified since 90 days │
│ Recent maintenance: 2026-09-20 verify ✓ · 2026-09-01 vacuum ✓ │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Mass operations on filtered set (412): [Analyse] [Proxies] [Thumbnails] [Verify] [Reorganize…] [Convert…] [Retag] [Export CSV] [Delete] │
```
Operations: **Scan** (incremental, mtime/size), **Rebuild index** (from sidecars; falls
back to full metadata scan; never deletes originals), **Verify** (hashes; bit-rot report),
**Duplicates** (by hash across sequences), **Orphans** (files not indexed / rows without
files, with fix actions), **Adopt folder** (index an existing tree in place or copy into
the layout), **Merge/split sequences**, **Move archive** (relink), **Maintenance**
(SQLite vacuum/backup/restore, cache cleanup, proxy purge/rebuild, thumbnail pack
compaction, log rotation). Statistics drawn with in-house chart elements. Every operation
is a Job (resumable, cancellable, logged). Recurring scans, integrity checks, thumbnails,
proxies, analyses, maintenance, backups, clean-ups and reports are schedules in Jobs ›
Scheduled (§12.6, §14.6); the buttons here run them once (amended 2026-10-26, R10).
Maintenance › *Trash…* (amended 2026-10-26, R6) lists the archive's trash (§7), newest
first: deleted sequences and photos deleted from sequences, each with its kind, photos,
size, folder and when it went, and *Restore*. A sequence goes back as its folder is (into
its old place, or "folder (2)" when that is taken; its photos are not re-hashed, Verify does
that). Photos are re-hashed against their record and go back into their sequence with their
frame records (a name taken since gets `_2`, its companion following), or into a new
sequence when theirs is gone, every entry of that sequence joining the same new one. A photo
that stays in the trash says why (its files no longer match their record, they could not be
moved back, the sequence holds that content already, or its file was missing when it was
deleted): one sentence on the dialog's line, or how many stayed when the reasons differ, and
the tooltip with each reason and the first names. When no file of an entry matches, nothing
moves and the line says so. *Empty…* measures every entry (dry run), lists them, asks for the
number of entries to be typed, then queues the *Empty trash* job. The job erases exactly
those entries and nothing when the trash changed since; an entry that changes while it runs
is kept, and the job then fails after erasing the others. It is the only way the product
erases trash entries; no schedule runs it (§14.6).
Deleted videos (amended 2026-11-05, owner review 1 R3/R8/R9; §7, §12.10) are listed as kind
*Videos*, titled by their sequence, with the path they were deleted from. *Restore*
re-hashes the file against its record (refused when it no longer matches), moves it back
under a free name when its own is taken (names a render is writing count as taken) and
records it again with the same render id; it fails while its sequence is not in the library
(restore the sequence first). *Empty…* measures and erases video entries with the rest.
Originals a conversion replaced (amended 2026-10-26, R7; §7) are listed as *Replaced
originals*. *Restore* swaps them back into their sequence while its converted frames are
unchanged, the conversions going to the trash in turn, and otherwise brings them back as a
new sequence. *Empty…*'s list names first, wherever the trash lists them, the entries whose
conversion the archive itself shows deleted since (§7; *conversion deleted*: they may hold the
last copy of their photos), the others filling its six lines and the rest counted. The job
keeps, each logged with why and what settles it, an entry changed since the plan, one whose
sequence is busy, one whose conversion no longer matches, one with a photo never verified
(verify the sequence), one where a sidecar that may hold the sequence is missing or
unreadable (scan the archive), one whose sequence the index lists but the archive no longer
holds (rebuild the index), and one whose conversion's fate the archive does not show (restore
it to keep its photos; a frame missing or corrupt, which no verify hashes, counts here).
*Reorganize…* (amended 2026-10-26, R7; it replaces Rename… and Move…) applies new templates
to sequences already filed: the set (online), the Library's selection (§12.2), or every
sequence of the archive from the toast of Settings › Archive (§12.8). The admin panel offers
the same (§14.8), through the same engine and job.
- An in-window dialog: Folders (`{title}` is the new title), File names (as filing names
them, §7.1) and Titles (`{title}` is the current title), each with its switch and field,
checked as it is typed against the rules of §7.1; a template switched off never blocks the
others. Folders and File names start on with the archive's templates, read again when the
dialog opens; Titles starts off, with `{title}`.
- The dry run (nothing touched) follows the typing (400 ms; Enter, or leaving a field, at
once) and lists, in the order the changes apply, each sequence with its folder, title and
first three file names before → after, *Follows its folder* for a sequence nested in a folder
that moves, how many files get a new name, and the photos that keep their names with why:
kept in place outside `originals/` (a tree someone else keeps), never verified (verify the
sequence first), missing; or that the sequence stays as it is, with every folder around it,
because its sequence file cannot be read (damaged, another sequence's, or from a newer
Chronos). The summary reads "12 of 36 change · 3,600 files renamed · 20 names kept".
- *Apply* (enabled only for the dry run of the templates on screen, when something changes)
queues the *Reorganize* job of exactly that plan at user priority; the dialog closes and a
toast links to Jobs. Cancel is the default button.
- The job (desktop and server) plans again and applies the plan only while it is the one
confirmed (its fingerprint, §14.3); otherwise it fails and nothing changes, a sequence
deleted since named in its log. It changes one step at a time. Pause or cancel stops
between two steps and holds the rest for the job's resume or retry; a failed job holds it too
(also when the archive's volume went away), and its retry completes it while it still fits.
A retry while the archive is still offline fails as offline and keeps the plan: a plan
journal it cannot reach is never taken for one completed.
An archive open completes a plan an interruption left (a crash, a yield to another job, the
program closing), not one its job holds.
- What changed after the dry run: a sequence moved or gone, one indexed inside a folder that
moves, a new folder taken, a title edited that the plan changes or names a folder or files
after, a sidecar of a newer Chronos it would rewrite: the rest of the plan is refused, the
steps done stay, and a new dry run is needed. Photos changed since (a sequence still
receiving them) refuse nothing: that sequence keeps its file names, and its folder and title
change while the templates still give them from its first photo as it is now, otherwise it
stays as it was, and so do the sequences its folder was to carry. A sequence left as it was
inside a folder that a later step moves goes with that folder, keeping its title and file
names, so the folder around it still moves. A photo in use or a new name taken keeps that
sequence's file names (every file back). These sequences are listed in the job's log, and
the job fails at the end, after the others changed, saying how many; its retry plans again.
- Deleting sequences of the archive is refused while a Reorganize job runs or is paused. The
Archive and Library screens read the archive again when it ends; an editor open on a
sequence it changed reloads where the sequence is now after that sequence's step.
*Convert…* (amended 2026-10-26, R7; §7, §8.7) converts the photos of sequences already filed
to JPEG, 16-bit TIFF or linear DNG: the set (online), or the Library's selection (§12.2). The
admin panel offers the same (§14.8), through the same engine and job.
- An in-window dialog: Format (JPEG, TIFF 16-bit, Linear DNG; Linear DNG, the archival choice,
chosen first), Quality (JPEG only, 1–100, 95) and Mode, *Replace* (the converted files take
the photos' place in their sequences; the originals go to the archive's trash, restorable
until it is emptied) or *New sequence* (converted copies in a new sequence beside each source;
the originals stay as they are). The mode is chosen at every run: it starts unchosen at every
open and is never remembered. Each choice's tooltip says what becomes of the originals.
- The dry run (nothing touched) follows the choices (400 ms after typing the quality; Enter at
once) and lists each sequence that converts, skips photos or stays whole: its photos and size
before → after (an estimate), the photos that stay as they are and why (already in that
format; a format this computer cannot read at full resolution; read only from an embedded
preview; a RAW developed here at 8 bits only, for a 16-bit format; a colour profile the format
cannot keep, for a linear DNG any but sRGB (§8.7); larger than the format holds or Chronos
reads back; unreadable; missing; never verified; held open by another program or not
openable), or why the whole sequence stays (a job works on it, or a conversion of it waits;
the archive offline or read-only; its sequence file unreadable). With New sequence, the photos
a copied sequence skips are *not copied* into its new one. A summary ("12 of 36 change · 3,600
photos · 41 GB → 32 GB · 20 skipped") and the space line follow ("Needs 12 GB, free 340 GB":
the estimate with a 15 % margin and a 512 MiB reserve, against the free space where the
conversion writes); a volume without the space blocks Apply. The mode does not change what
converts, so choosing it plans nothing again.
- *Apply* (enabled for the dry run of the choices on screen when it converts something and the
space is there, once a mode is chosen, which is asked last) asks a Replace to type the number
of photos it replaces, and confirms a New sequence with how many photos the new sequences
lack; it then queues the *Convert* job of exactly that plan at user priority, and the dialog
closes. A conversion of one of its sequences already queued or running refuses it: the dry
run is made again and shows those sequences busy. Cancel is the default button.
- The job (desktop and server) converts one sequence at a time, all or nothing: the photos the
dry run listed alone, each only while it holds the content confirmed; photos received since
stay as they are. It checks the free space before it starts, before each sequence and before
each photo (counting every photo still being written), and stops before the volume fills.
Paused, resumed or retried in Jobs, it keeps what it converted. A sequence whose confirmed
photos changed is left as it is, and a retry leaves it too (plan again); one busy, moved away
by another program or with a photo held open waits for the retry; one with a photo that cannot
be converted is left as it was, what it converted kept for the retry. The job's log says each,
and the job fails at the end saying how many.
- New sequence: titled "title (JPEG|TIFF|DNG)", in a folder from the archive's template, its
photos named as filing names them, owned as its source is, with its source's tags, rating,
notes and project (the positions on photos it lacks wait as pending frames). It holds the
converted copies alone; the job log says how many photos stayed in the source alone. A retry
finishes the copy the job made and never makes a second; a source another conversion copied
in the same format since this one was confirmed gets no copy (the job log says so), and waits
for the retry while that conversion has not finished.
- When a Replace job ends, its toast offers *Undo* (once, never from the Windows notification):
the replaced entries that job made go back (swapped back, or as a new sequence for one that
changed since). Later, *Trash…* › *Restore* does the same, and the admin panel's trash view
for a conversion the server ran.
- A running or paused conversion makes its sequences busy. The Library and Archive screens read
the sequences again when it ends (a failed one converted the others); an editor open on a
converted sequence reloads.
### 12.6 Jobs
Two tabs, a *Queue | Scheduled* segmented control first in the toolbar (amended 2026-10-26,
R10; a tab, not a rail entry, so a schedule and the jobs it queued are side by side):
- **Queue**: queue + history table: kind, target, progress, fps, ETA, node, state;
pause/resume/cancel/retry; log tail on expand; filters. A job a schedule queued carries a
*Scheduled* pill. The history line gives the job-history days of the Housekeeping schedule
(*Full history kept* while it is off or at 0).
- **Scheduled**: every schedule of this PC, the system ones first: *Archive scan* (every 10
minutes, or the interval the former Settings › Archive › Rescan every had, no catch-up; a
scan follows Settings › Analysis › After a scan at every run; it also runs once after the
archive is reopened at start and when an unplugged archive is back), *Index backup*
(every day, catch-up, 3 copies kept) and *Housekeeping* (daily at 04:00, catch-up:
job history older than 90 days, the cache trimmed to Settings › Storage › Cache limit,
oldest files first, never files in use, synced proxies, the render node's cache or import
staging). Each row: an on/off switch, name (a system schedule by its key, in the UI
language), action, when (in the UI language), next run (Today, Tomorrow or a date, and a
time), last result (the state of the job it queued, else the outcome), Run now, Edit, and
Reset (system schedules) or Delete (the user's), both confirmed. Selecting a schedule
lists its last runs; *Show in queue* opens the job in the Queue tab with its log. Which
actions this PC runs is read again when the tab is shown and after a Run now that finds
one unavailable; without an index the tab says the schedules do not run.
- *New schedule* (the toolbar's end) and Edit open an in-window editor: name (a system
schedule keeps its name and action); action (those this PC cannot run disabled, the reason
in the tooltip); *Repeat* Every / Daily / Weekly / Monthly with their fields (interval 5
minutes to a day, 1–168 hours or 1–366 days; a time of this PC's clock; days of the week
in the UI language's order; day 1–28 of the month); the action's parameters (full scan,
rebuild all, deep analysis, unverified for or older than n days, at most a share of the
sequences, report only, copies kept, clean-up steps); priority; catch-up; on. Every field
is checked as it is typed.
- No work recurs out of sight: every timer that queues work is a schedule here (§14.6). A
schedule's background run raises a toast only when it fails, unless it is upkeep the next
run repeats (scan, thumbnails, proxies, light analysis, clean-up); Run now raises one only
when it queued nothing.
- *Workspace copy* jobs (amended 2026-10-26, R8; §12.3) are listed like any job; Open opens
their sequence in Edit. Cancelling a first copy removes the media it wrote, once it has
stopped and only while no other copy of that project waits or runs; a paused copy keeps
them and resumes.
Global job bar mirrors the active job.
### 12.7 Server (client side)
```
│ Server [https://nas.local:8443 ……] [Connect] Status ● Connected · v1.3 · TLS fingerprint 9A:… (trusted 2026-09-01) │
│ Signed in as alberto · Editor · 2.1 TB of 5 TB used [Sign out] │
│ [✓] Offer this PC as render node (NVENC HEVC/H.264, AV1) [✓] Keep proxies of synced sequences offline │
├───────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Sequence Local Server State Action │
│ Harbour sunset ✓ originals ✓ in sync — │
│ Comet 2026-08-13 ✓ originals ✗ local only [Upload] │
│ Construction cam wk 38 proxies ✓ remote [Download originals] [Open with proxies]│
```
First connection shows the certificate fingerprint (trust-on-first-use); login modal;
per-sequence sync actions and states; conflict resolution only for settings JSON (keep
mine / take server / save both). The address field, here and in the Uploader (§15), reads
one rule: no scheme means HTTPS, and then no port means 8443, the server's HTTPS port;
`https://<name>` alone keeps 443 (a reverse proxy); a typed port is kept; a bare IPv6
address gets its brackets; a link-local one with a zone index is refused. An address that
answers but not as a Chronos Server (any redirect, an answer that is not JSON, an error
without Chronos's `X-Chronos-Api` header and error code, JSON of another shape, more than
1 MB, or plain HTTP on a port reached over HTTPS) fails with one sentence naming the
address and the port to check; behind a certificate not
trusted yet, `server/info` is read once without checking it and without credentials, and only
a Chronos answer leads to the fingerprint question, so another service's certificate is never
offered for trust (amended 2026-11-04, owner review 3).
Row actions of a server sequence (amended 2026-10-26, R8). On a server that keeps projects
(§4.4), an account with Edit gets *Open in workspace* (§12.3) in place of *Open with
proxies*; *Download originals* stays for an account that may download them. An account
without Edit gets *Open with proxies*. On an older server, *Open in workspace* is shown
disabled after the other actions, and its tooltip says the server needs an update.
*Pause metered transfers* (amended 2026-10-26, R8; formerly *Pause uploads on metered*):
while Windows reports the connection as metered, every transfer with a server pauses after
its current chunk or file and resumes by itself afterwards: uploads, the sync's downloads,
the workspace's copies from a server and its renders sent to one. Copies from and sends to
this PC's archive never wait.
### 12.8 Settings
Sections (list on the left, controls on the right, no descriptions — tooltips only):
General (language, theme, startup, notifications), Archive (root, templates, proxy policy,
thumbnail size; *Videos folder* with *Browse* and *Open*, where Videos › *Copy to folder*
puts copies, `%USERPROFILE%\Videos\Chronos` by default, never the archive root, the
workspace or a folder inside them (§12.10): amended 2026-11-05, owner review 1 R3/R8/R9;
the rescans are the Archive scan schedule of Jobs › Scheduled, §12.6, so
*Rescan every* is gone; amended 2026-10-26, R10; a new folder or file template names only what
is filed next, so once the archive took it, and holds sequences, a toast offers *Reorganize…*
for every sequence with the changed templates switched on, a change made while that archive's
toast is up joining it; on the Archive screen it never replaces an open dialog, and opens once
that one closes: amended 2026-10-26, R7), Import (defaults, session rules, verify,
post-actions), Analysis (widths, thresholds, deep analysis auto-run), Rendering (quality
profile, memory budget, spill folder, parallelism = photos the running job processes at once, priority queue
with a level per job kind, encoders detected, hardware preference; amended 2026-10-16, R2;
Workspace copy listed, high by default, as Download, and Local render high, Send render
normal and Move workspace high: amended 2026-10-26, R8; Copy videos high: amended
2026-11-05, owner review 1 R3/R8/R9),
Formats (per
format tier on this PC, codec install links), Storage, Workspace (amended 2026-10-26, R8:
*Folder*, the path read-only with *Open* and *Change…*, which shows a plan (projects left,
projects found), closes an open workspace project and moves nothing, the old folder's
projects coming back when it is chosen again; *Sync* *After each version*, on by default:
each saved version is sent at once and the library's new ones taken; *Kept versions* 5, 10,
20, 50, 100 or 200, default 20: how many of the library's versions each project keeps on
this PC besides its base and those not sent, an older one dropped only once the library
gives it back unchanged. Rows in order (amended 2026-10-26, R8): *Folder* with *Open*,
*Change…*, *Move…* (§12.3) and *Resume* while a move is unfinished, and what the folder
takes (*{0} used*, its trash included); *Size limit* 25, 50, 100, 200, 500 or 1,000 GB or
*No limit*, default 100 GB; *Default media* *Proxies* (default) or *Originals*; *Sync*;
*Version on render* on by default (§12.3); *Kept versions*; *Clean after* 7, 14, 30, 60 or
90 days or *Never*, default 30 days; *Open project* *Last used* (default), *Main* or *Ask*;
*Trash* (entries and size, *Empty…*, disabled while empty). Reset restores every row but
the folder and the trash; Reset all and Import keep the folder and the projects opened
last and when, Export leaves them out), Server (last servers, trusted fingerprints,
render node), Updates (check on start; latest version: check now, download, releases page),
Advanced (portable mode, data folder; logs: the logs folder, *Log level* (Trace…Error,
default Info), *Keep logs* (1–365 days, default 14), *File size* (MB, default 50, or No
limit), *Logs total* (MB, default 1,024, or No limit; never below the file size),
*Rotation* (Daily or Hourly, UTC), *Diagnostics logs* (MB of the end of each log in the
bundle, default 4), applied to the log files from their first line and at once when
changed; diagnostics bundle, database backup/restore (*Back up now* keeps as many copies as
the backup schedules, §6.2, R10), reset; Reset restores the log rows; amended 2026-10-26,
R11), About last (§12.9). Each action has one place in Settings
(amended 2026-10-26, R5).
Import/export settings as JSON.
### 12.9 About
The last page of Settings (§12.8), no longer an entry of the rail (amended 2026-10-26, R5):
version, build, runtime, system, licence/EULA link, third-party notice (none) and, in every
language but English, the machine-translation notice with its review link. Nothing is
offered twice: the update check, its notice and the releases page are on Updates, the data
folder and the diagnostics bundle button (zips logs + environment report) on Advanced. The
update check on start (§18) runs whatever screen is open.
### 12.10 Videos (amended 2026-11-05, owner review 1 R3/R8/R9)
One list of every render: this PC's archive, the signed-in server's and the workspace's
renders not sent yet, merged by render id (a synced render is one row, *Here* and *On
server*). The files stay in each sequence's `exports/` (§7); the section never moves one
except into the trash.
- Toolbar: search (title, preset, file name), Kind (All, Videos, Stills, Sequences), Codec
and Year (the values present), Source (All, This PC, Server, Not sent), Order (Newest,
Oldest, Largest, Title), cards, list or board (kept; board amended 2026-11-06, owner
review 4 R1), *Refresh*, *Clear filters* and the
selection count. The Export footer's *Videos (n)* and the Render menu's *Videos* open it
on one sequence, shown as a chip whose × clears that filter only.
- The board (owner review 4 R1): the work done in two lanes, *Published* (this PC's and
the server's renders) and *Workspace* (the workspace's renders, sent or not), newest
first, each with its count, under the same filters, selection and actions; a sent
workspace render is in both lanes, its workspace card marked *Sent*.
- A card: the poster (the sequence's cover, or the still itself), title, a line starting
with the preset (preset · codec · duration · bytes, amended 2026-11-06), date, and chips *Here*, *On server*, *Copied*, *Missing*, *Not
sent*. The list has the same columns, Preset, Format and Date hidden while the player is
open (the row's tooltip keeps them).
- Actions on the selection (toolbar) or a row (its menu, on the selection when the row is
part of it): *Play*; *Show in folder*; *Copy to folder* (this PC's renders) or *Download*
(the server's alone) into the videos folder of Settings › Archive (§12.8), a hash-verified
`video-copy` job of this PC; *Copy on server* (the server's videos folder, Edit
permission); *Delete…*; *Open in Edit*; *Send* for a workspace render not sent (its rows
are read-only otherwise). A disabled action says why in its tooltip.
- *Delete…* runs the dry run first (this PC's renders and the server's planned apart), then
one confirmation naming what goes, its bytes, what stays and why (a render being sent,
uploaded or copied) and that copies in the videos folder stay; the delete
sends each plan's fingerprint back, and a changed plan moves nothing. A render whose file
is missing loses only its row. Deleted videos are restored from Archive › Maintenance ›
*Trash…* (§12.5).
- The player is a pane on the right, in-process (no other program, §8.6): Windows Media
Foundation (WPF `MediaElement`) for videos, an image view for stills and the first frame
of a GIF or APNG. A file Windows cannot decode (HEVC without its extension) says *Cannot
play here*, *Show in folder* staying offered. A server's video plays from a copy
downloaded to this PC; without one, *Play* says to copy it here first.
- Without a signed-in server, against a server without the `videos` capability (§14.3) or
one out of reach, the list holds this PC's videos and says why. *No videos* when there
are none, with *Clear filters* when the filters hide them.
- Copies (`video-copy`, §14.6): free space checked first; each file copied to
`.incoming-<id>.part` in the videos folder and flushed, hashed and compared with the
render's SHA-256 (the source hashed first when it has none, an image sequence file by
file), then renamed without overwriting, " (2)" on a name collision; the folder is flat. A
mismatch removes the part file and fails the item; the source is never touched. A server
render is downloaded and compared with the server's SHA-256. Each copy is recorded
(`render_copies`, §5) and Chronos never deletes one.
---
## 13. Card import — behaviour details
- Detection: `WM_DEVICECHANGE` (`DBT_DEVICEARRIVAL`/`REMOVECOMPLETE`) + `DriveInfo` poll
fallback; card identity `{volumeSerial}-{label}-{capacity}`; camera identity from EXIF
Make/Model/BodySerial of the first image found.
- Card pool (`media_cards`): nickname, profile, history; profiles copyable; a card can
inherit a "camera profile" (rules shared by all cards of that camera).
- Session detection: gap > `SessionGapMinutes`; groups with < `MinimumSessionFrames` merge
into the previous session (test shots); each session becomes a sequence; the user can
merge/split in the plan. A folder imported as **Whole folder** (§12.4) skips detection:
one session per file format whatever the bodies and pauses, broken only by the user's
splits. Its session key is `folder-` + the first 16 hex digits of SHA-256(PC name | full
path without trailing separator, upper-cased on Windows | format), plus
`-yyyyMMdd-HHmmss` of its first photo for a part split off; so an interrupted import
resumes into the same sequence and a later import of the folder adds to it. The PC name
is in the key because the server files uploads by session key for every user alike
(amended 2026-10-26, R9).
- Duplicate handling: hash lookup against the archive index (skip/rename/overwrite);
"already imported" state remembered per card + file (path, size, mtime) for fast
re-inserts.
- Rename during import: templates (§7.1) with live preview; original name kept in the
sidecar. Every photo of a session is named with its first photo's camera and lens, the ones
its sequence carries, as Reorganize names it (amended 2026-10-26, R7).
- Post-actions: keep / delete imported files (only those verified) / format card (OS
dialog) / eject; run deep analysis automatically (default on, background, low priority).
A photo whose archived frame a conversion replaced since no longer matches its card file,
so a delete keeps it on the card and a format is refused while it is there (amended
2026-10-26, R7).
- Failure handling: card removed mid-copy → partial files deleted, plan resumable on
re-insert; errors listed per file, never a modal per error.
---
## 14. Chronos Server
### 14.1 Stack
ASP.NET Core minimal API on Kestrel (`Microsoft.AspNetCore.App` shared framework, no
packages), `System.Text.Json` source-generated contexts from `Chronos.Protocol`, WebSockets
for events, in-house structured file logging (`Microsoft.Extensions.Logging` abstractions
are part of the shared framework; the file provider is in-house), in-house rate limiting for
login and uploads, health endpoint, graceful shutdown (jobs checkpoint).
Logging (amended 2026-10-26, R11): files `/data/logs/server-yyyyMMdd.log`, or
`server-yyyyMMdd-HH.log` with hourly rotation (UTC). A file that reaches the size limit (50
MB by default, MB of 2²⁰ bytes; 0 = no limit) continues in `.1.log`, `.2.log`…, and a
restart continues the period's newest part. At every new file, and when the settings
change, files older than the retention (14 days) are deleted, then the oldest while all
the files exceed the total limit (1,024 MB; 0 = no limit; never below one file), never
the file being written and never a name the sink did not write. The console and the files
have their own levels (Information by default), which the logging filters read at every
line, so a change in the admin panel applies at once; ASP.NET Core's own categories never
write below Warning, the host's lifetime never below Information; the engine's level is
the lower of the console's and the files'. Logging never fails what logs: a line that
cannot be written (the folder removed, a full disk) is dropped and the next one tries the
file again (a removed folder is not created again), so a job still ends Failed and the job
engine and the scheduler go on. The desktop programs use the same sink (`chronos-`,
`uploader-`, `setup-` files, with the default limits; Chronos takes its own from Settings ›
Advanced, §12.8).
### 14.2 Security
- TLS: `auto` (self-signed cert generated at first start with `CertificateRequest`, stored
in `/data/tls`, fingerprint printed in logs and shown in admin), `pem` (cert + key
paths), `proxy` (HTTP behind a reverse proxy, `ForwardedHeaders` middleware, admin warns
if not local).
- Passwords: PBKDF2-SHA512, ≥ 210,000 iterations, 16-byte salt, versioned hash format;
minimum length 10; admin-created users get `mustChangePassword`.
- Tokens: 32 random bytes, stored as SHA-256, `Authorization: Bearer`; sliding expiry
(default 30 days), per-client name, revocation list; web admin uses an `HttpOnly; Secure;
SameSite=Strict` cookie session + double-submit CSRF token.
- Authorization: roles admin/editor/uploader/viewer + permission bits; sequence ownership;
admin-only management endpoints; path traversal impossible (ids → paths via DB only).
- Limits: max upload size, chunk size (default 8 MiB), per-user quota, request timeouts,
login rate limit (5/min/IP), audit log.
### 14.3 API v1 (JSON; errors as `{ code, message, details }`; `X-Chronos-Api: 1`)
```
POST /api/v1/auth/login {username,password,clientName} → {token,user,mustChangePassword}
POST /api/v1/auth/logout · POST /auth/password · GET /auth/me
GET /api/v1/server/info name, version, apiVersion, capabilities, tlsFingerprint, formats, limits, extensions, settingsFormat
GET /health
GET /api/v1/users · POST · GET/PATCH/DELETE /users/{id} · POST /users/{id}/reset-password (admin)
GET /api/v1/sequences?year&camera&status&rendered&tag&q&cursor&limit
GET /api/v1/sequences/facets years, camera models (with their label) and tags of the archive, each with its count
POST /api/v1/sequences create (title, camera hint) → id
GET /api/v1/sequences/{id} · PATCH (title, tags, rating, settings) · DELETE
GET /api/v1/sequences/{id}/manifest frames with hashes/sizes/versions, tombstones (sync)
GET /api/v1/sequences/{id}/analysis · GET /stats · GET /renders
GET /api/v1/sequences/{id}/frames?cursor&limit
GET /api/v1/sequences/{id}/thumb the hero frame's thumbnail, else the first frame's (ETag, 304)
POST /api/v1/sequences/{id}/frames/delete {frameIds, expectedFramesVersion, dryRun} → {photos, bytes, framesVersion, frameCount, trashEntry}
POST /api/v1/sequences/bulk/delete {ids, dryRun} · /bulk/retag {ids, add, remove} · /bulk/jobs {ids, kind} → an item per id
GET /api/v1/frames/{id}/original · /proxy · /thumb (streamed, Range supported)
GET /api/v1/renders/{id}/file the render's file (streamed, Range supported)
GET /api/v1/videos?q&kind&codec&year&sequence&sort&cursor&limit · GET /videos/{id} (amended 2026-11-05, owner review 1 R3/R8/R9)
POST /api/v1/videos/delete {ids, dryRun, fingerprint?} → plan | trash entries · POST /videos/copy {ids} → 202 {jobId}
GET /api/v1/sequences/{sid}/projects live projects, Main first · POST {name, fromVersionId?} → 201 project
GET/PATCH {name}/DELETE /sequences/{sid}/projects/{pid} · GET …/{pid}/head · GET …/{pid}/versions?before|after&limit&summary · GET …/{pid}/versions/{vid}[?stored=true]
POST /api/v1/sequences/{sid}/projects/{pid}/versions push → 201 stored | 200 already_stored | 409 project_diverged | 422 hash_mismatch, newer_format, invalid_version, too_large
GET /api/v1/sequences/{sid}/projects/frames every frame and the photo aliases of replaced tombstones, of one frames version · GET …/frames/stamp
POST /api/v1/uploads {sequenceId|null, fileName, size, sha256, capturedAt?, sessionKey?, restore?} → {uploadId, chunkSize, received[]} | 200 {alreadyExists, frameId?}
PUT /api/v1/uploads/{id}/chunks/{n} body bytes (idempotent) → {received}
POST /api/v1/uploads/{id}/complete[?restore=true] → frame id (server verifies sha256, commits into layout, updates manifest)
GET /api/v1/uploads/{id} resume state
DELETE /api/v1/uploads/{id}
GET /api/v1/jobs?state · POST /jobs {kind, target, params} · GET /jobs/{id} · POST /jobs/{id}/cancel · /retry
GET /api/v1/schedules schedules (system ones first), actions with availability, time zone, clean-up steps (admin)
POST /api/v1/schedules · GET/PUT/PATCH/DELETE /schedules/{id} · POST /schedules/{id}/run · /reset · GET /schedules/{id}/runs?cursor&limit
WS /api/v1/events {type: jobProgress|jobState|sequenceChanged|cardEvent|nodeState|scheduleChanged|projectChanged, …}
POST /api/v1/nodes/register · POST /nodes/{id}/heartbeat · POST /nodes/{id}/claim → job · POST /nodes/{id}/jobs/{jobId}/result (chunked upload of output)
GET/PUT /api/v1/archive/settings · POST /archive/scan · /rebuild · /verify · GET /archive/stats · POST /archive/maintenance (admin)
POST /api/v1/archive/reorganize {sequenceIds|all, folderTemplate?, fileTemplate?, titleTemplate?, dryRun, fingerprint?} → plan | 202 move job (admin)
POST /api/v1/archive/convert {sequenceIds|all, target, quality?, mode, dryRun, fingerprint?} → plan | 202 convert job (admin)
GET /api/v1/archive/trash · POST /archive/trash/{name}/restore · POST /archive/trash/empty {names?, dryRun, fingerprint} (admin)
GET /api/v1/i18n/{culture} strings for the web admin
```
Library and trash (amended 2026-10-26, R6):
- `frames/delete` needs the Delete permission and the sequence's owner or an admin, like
deleting the sequence. It takes 1–100,000 ids, under a body limit of its own (100,000 × 48
bytes + 4 KiB, about 4.8 MB; other JSON bodies stay at 1 MiB); a dry run answers the
photos, bytes and the frames version now, a deletion the frames version after it (the next
request's `expectedFramesVersion`), the frame count and the trash entry's name. Errors: 400
`bad_request` (`frameIds`); 404 `not_found` (`sequence`); 409 `frames_conflict` (the frames
changed since `expectedFramesVersion`, or an id is not the sequence's; details: the frames
version now), `sequence_busy` (a job works on it, as for deleting it), `would_empty` (every
photo would go: delete the sequence), `photo_unreadable` (a photo never hashed whose
original is on disk but cannot be read, so it could leave no tombstone; details: how many,
the message naming the first), `sidecar_mismatch`, `folder_in_use`; 413 `too_large`; 503
`archive_offline`. Audited `frames_deleted`; publishes `sequenceChanged` `frames`.
- The bulk routes take 1–1,000 distinct ids and answer `{items, ok, skipped, dryRun, photos,
bytes, job}`, one item per id in the request's order: `ok`, or `skipped` with the reason's
code and sentence. *delete* (Delete) moves each sequence as `DELETE /sequences/{id}` does,
whole or not at all, and skips `not_found`, `forbidden` (another user's, unless an admin),
`sequence_busy`, `archive_root`, `contains_sequences`, `sidecar_mismatch`, `folder_missing`,
`archive_offline`, `folder_in_use`. *retag* (Edit) is the PATCH tag edit (trimmed, at most
64 characters, at most 50 a sequence, case-insensitive, up to 3 attempts on a settings
conflict) and skips `not_found`, `bad_request`, `settings_conflict`. *jobs* (Edit; kind
`analyse`, `deep`, `proxies`, `thumbnails` or `verify`) queues one job at user priority over
the sequences found (202; 200 when none), a verify targeting their archive with the
sequences in its parameters, as `POST /jobs` with `verify` now does too; 400
`invalid_job_kind`, 409 `job_unavailable`. 400 `bad_request` (`ids`, `tags`).
- `GET /archive/trash` (ManageArchive, like the rest of the trash) answers the entries newest
first, `{name, kind: sequence|photos|replaced, sequenceId, title, folder, photos, files,
bytes, deletedBy, deletedAt}`, and their total bytes. A name is
`<32 hex>[-<14 digits>[-n]]` (a sequence) or `photos-<32 hex>-<14 digits>[-n]` (photos),
checked against that shape and never a path.
- Restore answers `{name, kind, sequenceId, photos, kept, newSequence, keptReasons,
message}`: the photos that stayed and, in the same order, why (`mismatch`, `not_moved`,
`in_sequence`, `no_file`), with one sentence per reason in the request's language. Errors:
404 `not_found` (`trash_entry`); 409 `sequence_in_library`, `sequence_busy`,
`sidecar_mismatch` (the sidecar of the sequence the photos return to is damaged or
another's), `folder_in_use`; 422 `trash_mismatch` (no file matches its record any more, or a
deleted sequence's own sidecar no longer names it); 503 `archive_offline`. Audited
`trash_restored`; publishes `sequenceChanged` `created` (a sequence, or a new one) or
`frames`. A replaced entry (amended 2026-10-26, R7) answers kind `replaced`, with
`newSequence` false once its originals swapped back in place of their conversions, true when
they came back as a new sequence.
- Empty: a dry run answers the entries measured on disk, their photos, files and bytes, the
plan's `fingerprint` and the names asked for that the trash does not hold (`unknown`); a
replaced entry whose conversion the archive shows deleted carries `conversionDeleted: true`,
which the fingerprint covers (amended 2026-10-26, R7). The erase sends the fingerprint back
and answers 202 with the `empty-trash` job. Errors: 400 `bad_request` (`names`,
`fingerprint`); 409 `trash_changed` (details: the fingerprint now), `job_unavailable`; 503
`archive_offline` (offline, and for the erase also read-only; the listing answers it too,
offline). The request is audited `trash_empty_requested`; what the job erased, and why it
kept an entry, is in its log.
- The manifest gains `removed: [{sha256, replacement, reason: deleted|replaced, at}]` (null
when there are none; covered by its ETag, since a deletion moves the frames version).
Reorganize (amended 2026-10-26, R7; ManageArchive; §7, §12.5, §14.8):
- The request names exactly one of `sequenceIds` (1–1,000) and `all`; a null template keeps
that part, at least one is given, each usable and within the rules of §7.1. A dry run
answers `{steps, sequences, files, kept, fingerprint}` and changes nothing: a step for each
sequence that changes, is carried or keeps photo names, in the order they apply,
`{sequenceId, fromFolder, toFolder, fromTitle, toTitle, carried, framesVersion, fileChanges,
fileSamples: [{from, to}] (at most 3, relative to the sequence folder), blocked: [{reason:
in_place|unhashed|missing|unreadable, photos, message}]}` (`unreadable`: the whole sequence
stays, 0 photos; the message in the request's language). The change sends the dry run's
fingerprint back and answers 202 with the `move` job. Errors: 400 `bad_request`
(`sequenceIds`, `templates`, `fingerprint`), `invalid_template` (below); 404 `not_found`
(`sequence`); 409 `nested_target` (details: the folder that would lie inside a sequence's
folder), `plan_changed` (details: the fingerprint now), `job_unavailable`; 503
`archive_offline`, `plan_dropped`. Audited `archive_reorganized` (sequences, files renamed,
templates). The job publishes `sequenceChanged` with the change `reorganized` for each
sequence once its step is journaled (at once for a step that failed after its folder moved
and its index rows followed); a plan the server completes as it starts tells no one, as no
client is connected yet.
- The fingerprint is a SHA-256 of the steps as the dry run shows them (folders, titles,
carried, file counts, samples, what stays and why), every file rename by its digest, and the
file template; not the frames version, so photos a sequence receives under the names the
plan leaves them keep it.
- The server keeps a dry run's plan, and a refusal (`nested_target`, `not_found`), for 5
minutes, keyed by the archive, the selection (all, or the ids in their order, which decides
which folder gets " (2)"), the templates, and a stamp of what the plan reads from the index:
every sequence's id and folder; the planned sequences' title, first capture, camera, lens,
photo count, frames version and how many of their photos are hashed; the title of the others
inside their folders. The same dry run again, and its confirmation, take the kept plan. A
plan is made apart from its request (one a proxy cuts off leaves it to be made, and asking
again waits for it), at most 2 at once and 8 kept or being made (Convert's dry runs counted,
R7); one still being made 15 minutes after it was asked, let go for newer ones, or when the
server stops is stopped, and its requests answer 503 `plan_dropped`. A change made on disk
alone is not in the stamp: the confirmation then answers 202, and the job, which plans again,
fails without changing anything.
- `invalid_template`, here and from `PUT /archive/settings`: the details name the field and,
after a colon, the rule a template that parses breaks (`folderTemplate:reserved_folder`,
`fileTemplate:file_separator`, `fileTemplate:extension`, `fileTemplate:not_unique`), the
message saying why in the request's language (`Errors.Template.<Rule>`); a blank, invalid or
unusable template keeps the bare field and the generic message. `PUT /archive/settings` holds
a template to the rules only when the save changes it; every template must still parse and
expand.
- Writers that file into a sequence's folder take it from the index row read under the
sequence's lease, so they write where a Reorganize put it. Completing a render upload or a
render node's result that cannot be filed for now answers 503 and keeps the upload
receiving, to be completed again: `sequence_busy` (the sequence held past the lease wait),
`archive_offline` (the archive offline or read-only) or `folder_moved` (the sequence's folder
not where the index has it, or holding another sequence, after another program moved them;
the server's next scan finds it). The node keeps its job while it retries. A proxy upload
answers 503 `sequence_busy` while the sequence is held, 404 `frame` when the sequence or its
folder is gone, or the folder is another sequence's.
Convert (amended 2026-10-26, R7; ManageArchive; §7, §8.7, §12.5, §14.8):
- The request names exactly one of `sequenceIds` (1–1,000) and `all`, a `target` (`jpeg`,
`tiff16`, `linear-dng`), a `quality` (1–100, default 95; it counts for a JPEG only) and a
`mode` (`replace` or `new-sequence`). A dry run answers `{target, quality, mode, steps,
sequences, photos, skipped, bytesBefore, bytesAfter, space, fingerprint}` and changes nothing:
a step per sequence asked, in order, `{sequenceId, title, folder, framesVersion, photos,
bytesBefore, bytesAfter (an estimate), skipped: [{reason: same_format|convert_on_pc|
undecodable|missing|unhashed|eight_bit|color_profile|too_large|inaccessible, photos,
message}], blocked: [{reason: busy|offline|unreadable, message}]}`, each message in the
request's language. `convert_on_pc` is a format or file the server cannot read at full
resolution ("convert these photos on a PC"); of a sequence `new-sequence` copies, a message
says the new sequence lacks those photos. `space` is `{required, free, enough, message}`:
the estimate × 1.15 plus 512 MiB, counted in both modes, against the free space where the
conversion writes (the tighter of the space path's volume and the archive's own, §14.9).
- The change sends the dry run's fingerprint back and answers 202 with the `convert` job, whose
parameters name each sequence's digest (its photos are kept beside the job's journal, §7).
Errors: 400 `bad_request` (`sequenceIds`, `target`, `quality`, `mode`, `fingerprint`); 404
`not_found` (`sequence`); 409 `plan_changed` (details: the fingerprint now; none when a
conversion of these sequences was queued meanwhile), `nothing_to_convert`, `not_enough_space`
(details: the bytes needed), `job_unavailable`; 503 `archive_offline`, `plan_dropped`. Audited
`archive_converted` (sequences · photos · target · mode). The job publishes `sequenceChanged`
`converted` for each sequence whose frames it replaced and `created` for each new sequence, as
each one completes.
- The fingerprint is a SHA-256 of the options, the mode, and each sequence with its frames
version, its photos' count and bytes, their digest (each frame id with the SHA-256 of its
content), what it skips and what blocks it.
- The server keeps a dry run as it keeps Reorganize's, in one cache for both (2 made at once,
8 kept, 5 minutes, stopped after 15 with `plan_dropped`), keyed by the archive, the selection,
the target with the quality that counts (none for a lossless target) and a stamp of the index:
Reorganize's, and of the planned sequences' photos their count, sizes, formats, pixel sizes
and how many are flagged missing, corrupt, preview-only or undecodable. Not the mode, which is
set on the kept plan, nor the busy sequences and the free space, measured again at every
request. A plan made while the archive was offline is not kept. A confirmation takes only the
plan kept for the index as it is now and never plans inside its own request: with none kept
it answers 503 `plan_dropped` (ask the dry run again), with a kept plan that differs 409
`plan_changed`. A change made on disk alone is found by the job, which converts the photos
confirmed only while each holds the content confirmed.
Uploads (amended 2026-10-26, R3, R6): `server/info` lists `extensions`, the photo file
extensions the archive files (lower case, no dot), which the admin panel's dialog keeps to. A
frame upload whose file name starts with `.` is 400 `invalid_file_name`. A start whose
SHA-256 the target sequence tombstoned (and none of its frames holds) answers 200
`alreadyExists` without a `frameId`, unless `restore` is true; the completion checks again
unless `?restore=true` and answers 409 `photo_removed`, the upload cancelled (§14.4). An
original a conversion replaced in the target sequence is tombstoned too; sent with `restore`,
it files nothing and its completion answers the frame that holds its conversion (amended
2026-10-26, R7).
Settings format (amended 2026-11-04, owner review 1 R5/R6; §12.3, §14.7): `server/info`
gives `settingsFormat`, the highest project settings format the server reads (2 in this
release; absent from an older server, which reads 1). The server checks no settings: a
project push of a higher format answers 422 `newer_format` as before, and a render job whose
settings it cannot read fails with *These settings need a newer Chronos*. A render job
is sized from its resolved preset box adapted to the sequence's settings (§11.4) and carries
the settings format it needs (`requiredSettingsFormat`: format 2 for a format-2 project or
when the adapted size differs from the preset's fixed size); clients and servers that do not
know the members ignore them. Amended 2026-11-05, owner review 1 R3/R8/R9: `settingsFormat`
is 3 from this release; a render job needs format 3 when its own export (a batch preset's
included) has a playback other than the default, and every still job needs 3, so an older
node never renders a whole video for a still; the required format is never below the
format of the settings text the job carries.
Videos (amended 2026-11-05, owner review 1 R3/R8/R9; §12.10, §14.8). `server/info` lists the
capability `videos`. A client without it, or a server without it, keeps to the sequence's
renders as before.
- `GET /videos` (Read) pages every render of the server, newest first or by `sort`
(`newest`, `oldest`, `largest`, `title`), filtered by `q` (title, preset, file name),
`kind` (`video`, `still`, `sequence`), `codec`, `year` (UTC) and `sequence`; `limit`
1–500 (default 100) and `cursor` from `next`. A `VideoDto` is the `RenderDto` members
plus the sequence's title and first capture, the project's name and version number, the
file name, `state` (`ok`, or `missing` when the file is not where it was recorded) and the
copies (`path`, `copiedAt`); its `kind` is never null (`video`, `still` or `sequence`; a
still an older server recorded without kind is recognised by its image codec, fps 0 and
duration 0). `GET /videos/{id}` is one of them.
- `POST /videos/delete` (Delete) takes up to 500 ids. A dry run answers the items (id,
sequence, title, file name, bytes, `missing`), their bytes, the renders that stay
(`blocked`: `busy` while a send, upload or copy of it runs, `not_found`) and the plan's
`fingerprint`; the delete sends the fingerprint back (400 `bad_request` without it, 409
`plan_changed` with nothing moved when the plan changed) and answers the trash entries
made. Errors 409 `sequence_busy`, `folder_in_use`; 503 `archive_offline`. Audited
`videos_deleted` (how many, their bytes, the first five names); publishes
`sequenceChanged` `renders`. Copies in the videos folder stay.
- `POST /videos/copy` (Edit, as render uploads) queues one `video-copy` job into the
server's videos folder (202 `{jobId}`): 409 `videos_folder_unset` without one, 422
`videos_folder_invalid`, 507 `videos_no_space`, 404 `render`. Audited `videos_copied`.
- Trash: a video entry is named `videos-<32 hex>-<ticks>`, of kind `videos`; restore (the
same route, ManageArchive) answers 422 `trash_hash_mismatch` when the file no longer
matches its record and 409 `sequence_gone` while its sequence is not in the library.
- `RenderDto` (`GET …/renders`, the manifest) gains `sha256` and `kind`, trailing and
optional; render uploads and node results carry the verified hash and the kind, and a
render Sync downloads is hashed on arrival and compared with the server's (fetched once
more, then the job fails). `GET /renders/{id}/file` serves Range requests, and `.webm`,
`.m4v` and `.apng` with their media types, so a browser's `<video>` seeks.
Schedules (amended 2026-10-26, R10; ManageArchive, every change audited): `PUT` and
`PATCH` change the fields given; an invalid field is 400 `invalid_schedule` with the field
as details (`name`, `recurrence`, `parameters.percent`…); a system schedule is never
deleted (409 `schedule_system`) and keeps its name and action; run now is refused while the
schedule's last job is queued, running or paused (409 `schedule_pending`, nothing recorded);
only system schedules reset (409 `schedule_no_defaults`); changing an age limit an
environment variable fixes, or turning that schedule off while the limit is above 0, is 409
`setting_locked`.
`JobDto.scheduleId` names the schedule that queued a job; `POST /jobs` with kind
`duplicates` or `orphans` queues a read-only report job. `scheduleChanged {scheduleId,
deleted}` follows every create, edit, reset, delete and run (also one that queued nothing)
and every move of a next run; older clients ignore it. `GET/PUT /server/settings` carries
the log group `logs` (R11; a `PUT` without it keeps the log settings) and `lockedBy`, the
environment variable that fixes each locked setting (ignored when saving).
Projects (amended 2026-10-26, R8; §7, §12.3, §14.5). The server keeps its sequences'
projects as this PC's archive does (§7), and `server/info` lists the capability
`projects`. A server without it answers 404 `not_found` with no details.
- Reading needs Read; making, renaming and pushing need Edit. Deleting needs Delete and an
admin, the sequence's owner or the project's maker (the same username, on an account made
no later than the project); otherwise 403 `forbidden`. Main is never deleted (409
`main_cannot_be_deleted`); the API can rename it.
- The list makes Main from the sequence's settings the first time it is read (503 when that
cannot be done now). A sequence with no photo yet lists no projects, and every change
answers 409 `sequence_empty`.
- Errors: 404 `not_found` with details `sequence`, `project` or `version`; 400
`invalid_name` (1–60 characters after trimming, no control characters); 409 `name_taken`
(any case, among live projects); 503 `archive_offline`, `sequence_busy`, `folder_moved` or
`projects_unreadable` for writes (reads wait at most 3 s for the lease, then answer from
the index); 409 `folder_in_use` when a project's file cannot be written.
- A deleted project answers 404 `project` to its GET, head, rename, push and delete; its
versions can still be read.
- Version pages: newest first below `before` (default 50), or oldest first above `after`
(default 100); `limit` 1–200; `more` when more follow. A page also ends before its
settings pass 4 Mi characters (one version always goes). `summary=true` leaves the
settings out. `?stored=true` answers a version only when its file on the server reads back
with its content hash (404 `version` otherwise, `project` for a deleted project).
- A push body may be up to 65 MiB (the 64 MiB version limit plus 1 MiB; 413 `too_large`
above). The server numbers the version head + 1 and records the pushing account as its
author, and the version's client name, else the token's. Answers are `{outcome, version,
head, code, message}`: 201 `stored`; 200 `already_stored` (the same id and hash again);
409 `diverged` / `project_diverged`, with the head; 422 `hash_mismatch`, `newer_format`,
`invalid` / `invalid_version` (not portable, or another project's id) and `too_large` (a
version file over 64 MiB). A version of Main is mirrored into the sequence's settings.
- `…/projects/frames` answers every frame in index order and the replaced tombstones as
photo aliases, of one frames version; `…/frames/stamp` answers a short stamp of them
(frames version, hashed photos and their checksum, removals), so a workspace reads the
frames again only when it moved.
- Creations, renames (when the name changed) and deletions are audited `project_created`,
`project_renamed`, `project_deleted`; every push is logged.
- `projectChanged {sequenceId, projectId, change: created|renamed|deleted|pushed,
headNumber, headVersionId}` goes to every signed-in subscriber after each change: the
API's own, Main made at the first read, Main's external or merge versions, and projects
and versions another program wrote, found in the sidecars by a project call, a full scan
or a read-only catch-up. Main passing to another project reads as `renamed`. Main's head
written into the settings also sends `sequenceChanged` `settings`. Older clients ignore it.
- A `PATCH /sequences/{id}` that carries settings writes them under the sequence's lease
(§7), waiting 20 s for it, and can answer 503 `archive_offline`, `sequence_busy` or
`folder_moved`, or 409 `folder_in_use`, with nothing changed. A `PATCH` of title, tags,
rating or notes alone writes the index only.
- Renders sent from a workspace (amended 2026-10-26, R8): `POST /sequences/{id}/renders`
`{renderId, fileName, size, sha256, presetName, codec, width, height, fps,
durationSeconds, producedBy, projectId?, projectVersionId?}` starts a chunked upload and
`POST …/renders/{uploadId}/complete` files it. The project and version are checked when
the upload starts and again when it completes (422 `project_mismatch`: the project not
one of the sequence's, deleted ones included, or the version not one of the project's; a
version alone names its project) and recorded with the render; without them a render is
filed as before. A render id already filed answers `alreadyExists` for the same
sequence, 409 `render_exists` for another. `RenderDto` (`GET …/renders`, the manifest)
carries the render's `projectId` and `projectVersionId`, null when none. An older server
ignores both fields; the desktop notes it in the job's log.
### 14.4 Upload and ingest
Client computes SHA-256 while reading; `POST /uploads` short-circuits if the hash exists;
chunks are written to `/data/uploads/{id}.part` with a received-bitmap; `complete` verifies
the hash, moves the file into `originals/` under the layout templates (temp → fsync →
rename), extracts metadata, appends to `sequence.json`, inserts the DB row, enqueues
thumbs/proxies/light analysis, emits `sequenceChanged`. Frames without a target sequence
are grouped by the same session rules (§13) into auto-created sequences. Card imports from
a connected client use exactly this path. `POST /uploads` answers 507 `insufficient_storage`
when `/data` lacks the upload's size plus a 64 MiB reserve; before its staging copy,
`complete` checks the archive's own volume (never the space path, §14.9) the same way and
answers 507 with the upload still receiving, so the client completes it again once there is
room; render uploads and render-node results are checked the same way at completion, and a
volume that cannot be measured refuses nothing (amended 2026-10-26, R2).
Deleted photos (amended 2026-10-26, R6): a photo deleted from a sequence is not filed into it
again by an upload. `POST /uploads` answers a SHA-256 the target sequence tombstoned, and none
of its frames still holds, with `alreadyExists` and no frame id, so an old client syncing a
copy that still has it, or a watch folder sending it again, neither sends it nor counts a
failure. `complete` checks again once the upload stops receiving, and the ingest checks the
sidecar's tombstones a third time under the sequence's lease, which a deletion takes: a photo
deleted while its bytes were on the way is not filed, its upload is cancelled and the answer
is 409 `photo_removed` (the protocol client reports it as not sent). Only an explicit user
action brings such a photo back by upload: `restore: true` on the start and `?restore=true`
on the completion, sent by the admin panel's *Upload again* alone (never by sync, the
Uploader or a card import); it is then filed into its own sequence whatever other sequences
hold, and filing it drops the tombstone, also after the trash was emptied. A frame upload
whose file name starts with `.` (the AppleDouble `._` files a Mac leaves on cards, hidden
files) is refused for every client (400 `invalid_file_name`), as the archive scanner leaves
such files out.
Replaced photos (amended 2026-10-26, R7): a photo a conversion replaced in a sequence is in it
as its conversion. The ingest answers its original (a card or a folder imported again, a
download, an upload sent with `restore`) as a duplicate of the frame that holds the conversion,
followed through later conversions, and keeps the tombstone that makes sync count both as one
photo; once no such frame is intact, the original is filed again. A batch files nothing into a
sequence while a restore from the trash or a frame replacement of it is not settled (its trash
entry busy): an upload's completion answers 503 and the client tries again.
The admin panel uploads through the same path (amended 2026-10-26, R3; the dialog, §14.8):
- It hashes each photo in the browser with an in-house incremental SHA-256 (FIPS 180-4,
`sha256.js`) in a same-origin module worker (`hash-worker.js`, under the panel's
`script-src 'self'`) that reads the file in 8 MiB blocks. Before its first hash the worker
runs the FIPS 180-4 known answers (the empty message, "abc", the 448- and 896-bit messages,
one million "a"), whole and fed in uneven pieces, and, where `crypto.subtle` exists,
compares a 1 MiB random buffer with it; on any mismatch it refuses every hash and the
dialog uploads nothing (fail closed). The server verifies every upload again.
- Each start carries the photo's capture time: the Exif DateTimeOriginal of a JPEG or a
TIFF-based file (TIFF, DNG, most RAW formats) read from its first 256 KiB, else the file's
modification time as local wall time without an offset; the ingest uses it only for a
photo that records no time of its own (a PNG, an export stripped of Exif).
- At most two photos and two chunks per photo travel at once (four requests, half the
server's eight per account). A call that got no answer, 429 or 503 is retried after 1, 2
and 4 s; a completion refused with 409 `upload_state` (another completion is filing that
upload) is read again after 1, 2, 4 and then every 8 s, about a minute in all. Two copies
of one photo in a run go one after the other, so the second finds the first.
- `alreadyExists` with a frame is *Already there*; without one, *Deleted before*, whose row
offers *Upload again* between runs (the `restore` above). A quota or permission refusal
(401, 403), no space (507), the target sequence gone (404 `sequence`) or a failed self-test
stops the remaining photos (*Not sent*) with the server's message. A new target sequence is
created once (`POST /sequences`, never retried) and stays the dialog's target.
- Cancel aborts, stops the worker and deletes the uploads the run started and did not
complete; a photo that failed otherwise keeps its upload receiving, so the next run resumes
it, and abandoned uploads expire after the upload retention. While photos are sent, leaving
the page asks first and Esc is held, so only Cancel stops the run.
- Only files whose extension `server/info` lists, not empty, not starting with `.` and no
larger than `limits.maxUploadBytes` are taken. Folders dropped on the dialog are counted
(*Folders skipped*) and left out, and it has no folder picker: importing a whole folder
stays a desktop feature (R9).
### 14.5 Sync
Manifest diff per sequence: originals are content-addressed (never conflict); settings and
tags carry version counters (last-writer-wins with an explicit conflict prompt in the
client when both changed); proxies/thumbs are regenerable and never synced upward; renders
are uploaded on request. "Edit with proxies, render where the originals are": a client can
open a remote sequence with proxies only and submit a render job to the server, which runs
it itself (managed formats) or hands it to a render node.
Removed photos (amended 2026-10-26, R6). A photo deleted on one side leaves a tombstone there
(sidecar `removed`, index `frame_removals`, manifest `removed`), and sync never offers it back:
no upload of a photo the server deleted, no download of one this PC deleted; sync never
deletes local files either way. A tombstone leaves a photo out only while its own side holds
no matching photo (by hash, or by size and capture time while unhashed), so a duplicate that
stays or a file put back by hand still syncs. A photo replaced by a converted file (R7) is
the same photo as its replacement on both sides, for the comparison, the transfers and the
frame positions (below). Content known only once hashed is checked then: a download skips an
unhashed server frame this PC deleted (or holds as its replacement), and an upload skips an
unhashed local frame the server deleted and then runs the archive verify, so the index gets
the hashes and the next comparison leaves it out.
Known limitations: until the server verifies such a frame, the sync table still counts it as
missing here and *Download* fetches and drops it each time; a photo never hashed whose
original was already missing when it was deleted leaves no tombstone, so a copy elsewhere
(another PC, a card) is not known to be deleted and can come back.
Converted photos (amended 2026-10-26, R7). Every replaced tombstone of either side links two
encodings of one photo, and the encodings these links join (a conversion, a conversion of it,
its undo, each side converting its own copy) compare, transfer and translate as one photo,
under the smallest of their SHA-256s; a deletion on either side covers every encoding. Linking
a local sequence to a server one by content and the proxies this PC sends follow them (a frame
this PC converted makes the proxy of the server's original). A download for a frame flagged
missing here whose photo the server holds only in another encoding puts that file in the
frame's place (the same id, nothing to the trash, a replaced tombstone linking the two), after
the transfers and only in the folder the index has for the sequence, and queues the passes the
swap cleared even when the job is stopped meanwhile; a frame that changed meanwhile keeps its
place and the copy is dropped.
Folders moved by another program (amended 2026-10-26, R7). When a desktop and a server share
an archive, a Reorganize by one index (or a folder moved by hand) is found by the other's next
scan, which moves the sequence's row, its frames and the paths of the exports that moved with
the folder (a file or, for an image sequence, a folder; an export written at the old place
after the move keeps its path there, and another sequence's export saved inside follows only
when it moved with the folder). The other program may also have moved another sequence into
the old folder (its sidecar names that sequence): the moving sequence's exports then follow to
its new folder, and an export of the sequence that took the old folder never follows, so no
row names another sequence's file. Until that scan nothing writes into the old place, which
would create it again, nor into another sequence that took it: *Save both* and *Take server*
answer that the folder is not where the index has it (try again after the next scan), and so
do a render job as it starts, exports fetched by sync, a proxy pass, and a thumbnail pass that
finds another sequence's sidecar there; the editor's save says the sequence is no longer in
the archive, and a deep analysis that loses its folder records nothing. A render of the other
program whose folder moves while it runs is not stopped. Known limitation: an export a
sequence saved into another sequence's folder (the Export folder picker), before the other
program moved that sequence away and the first one into its folder, keeps naming the old
path; the file is intact, moved with the other sequence.
Projects (amended 2026-10-26, R8; §7, §12.3). A project's history is linear, with no
branches, and its home numbers the versions. A workspace pushes its versions in order; a
push is stored only when it names the head as its parent, is portable, of a settings format
the home knows, matches its content hash and fits 64 MiB, and a repeat of a stored version
is answered as stored. Otherwise the workspace pulls the home's new versions, replays its
own on them and merges the working state field by field (pending frames photo by photo);
only settings both sides changed are a conflict. Versions are compared and placed by photo
(the portable form), so photos added, a copy's other frame order, a Verify that hashed a
photo or a conversion that replaced one never move a position. Only Main's head is
mirrored into the sequence's settings, so only Main crosses to a linked server copy,
through the settings sync above; other projects never leave their home. A home that is
read-only or out of reach leaves the versions waiting in the workspace. The home is this
PC's archive or a server (§14.3).
Server home (amended 2026-10-26, R8; §12.3, §14.3). A server's projects work as on a PC's
archive:
- Settings a `PATCH`, an analysis's Auto values or a conversion's Replace write become
Main's next (external) version soon after, in the background, told as `projectChanged`
`pushed`. This holds only for sequences that already have a Main; Main is still made
from the settings at the first read. A busy sequence is tried again after 5 s, 30 s and
2 minutes, then left to the next project call.
- Other projects never leave the server; a desktop's linked copy still syncs Main through
the settings.
- The desktop takes `projectChanged` from its sync connection. After a lost event stream it
reads the state of that server's projects again only once the stream is open again and a
comparison made after that reached the server.
- A workspace reads the server's versions page by page, reading on past a page the server
ended early, and prunes a kept version only after reading it back from the server's file
(`?stored=true`).
Workspace originals and local renders (amended 2026-10-26, R8; §12.3, §14.3). A workspace
copies originals from its home only on request (media *Originals*): read from this PC's
archive, which it never writes, or downloaded from a server through `/frames/{id}/original`
(Edit or RenderNode), each hashed as it is copied and checked against the home's SHA-256,
resumable. A render
made from them on this PC goes home with its render id, project and version, filed in the
archive after a read-back or uploaded to the server (§14.3), never twice: a home that holds
the id already is only marked as having it. Before anything of the workspace is deleted
(Proxies only, the clean-up, Remove local copy), each original is hashed again and the
home's frames read: only what the home holds with the same SHA-256 goes, the rest goes to
the workspace's trash. With *Pause metered transfers* on, every transfer with a server
waits on a metered connection: uploads, downloads, workspace copies and renders sent
(§12.7).
### 14.6 Job engine
Persistent queue in the DB; jobs run one at a time, and the parallelism (configurable,
default = cores/2) is how many photos the running job processes at once; job kinds in §5;
checkpoints every 5 s (progress + resumable cursor); crash-safe restart; priorities
(user-initiated > background analysis); cancellation cooperative; logs per job; finished
jobs kept 90 days by the housekeeping schedule, below (amended 2026-10-26, R10). By default
a new job waits its turn, and pausing the running job lets the next one start. An optional
priority queue (Settings › Rendering on the desktop, the admin panel's Settings on the
server) gives each job kind a level (high, normal, low):
higher kinds are claimed first, and a queued job of a higher level makes the running job
of a lower level yield without asking; that job returns to the queue with its checkpoint
and resumes by itself afterwards. Jobs of the same level never interrupt each other, and a
job's own follow-ups never interrupt it. (Amended 2026-10-16, R2.) The desktop's *Workspace
copy* (`workspace-copy`, stored as 20) is high by default, as Download is, since Edit waits
for it; a server never runs it, because it writes into the folder its parameters name. So
do *Local render* (`workspace-render`, 21, high), *Send render* (`workspace-send`, 22,
normal) and *Move workspace* (`workspace-move`, 23, high), which a server never runs
either; a copy, render or send queued before the workspace moved works in the folder that
holds its project now, and fails, to be retried, while a move is under way. *Copy videos*
(`video-copy`, stored as 24; amended 2026-11-05, owner review 1 R3/R8/R9) runs on the desktop
and the server, high by default as a download is: it copies the renders its parameters
name into the host's videos folder, checking that folder again when it runs (never the
archive, the data folder or the workspace), each file verified by hash before it takes its
name (§12.10), and resumes after the copies it finished. A
handler may clean up after a cancel: cancelling a paused or failed job no handler runs calls
it, and cancelling a paused job whose run has not ended waits for that run to end first
(amended 2026-10-26, R8).
Scheduled jobs (amended 2026-10-26, R10). Recurring work is queued only by schedules (§5),
shown in Jobs › Scheduled on the desktop (§12.6) and the admin panel (§14.8): no job is
pre-scheduled out of sight. Each host runs one scheduler beside its job engine. Every timer
that used to queue work is a **system schedule**: seeded at start by its key when missing
(`INSERT … ON CONFLICT (system_key) DO NOTHING`), so the user's edits survive restarts and
upgrades; it can be edited, turned off and reset to the host's defaults (the options as
they are then), never deleted, and it keeps its name and action. On the server:
| Key | Action | When | Catch-up | Notes |
|---|---|---|---|---|
| `archive-scan` | incremental scan, background | every 10 min, and once at start | no | |
| `upload-cleanup` | `uploads` step: uploads idle for `UploadRetentionHours` (48) expire, orphan part files and day-old staging files go, records of uploads finished over 90 days ago and expired tokens are purged | every 6 h | yes | an idle upload expires up to 6 h after its 48 h |
| `index-backup` | backup, 3 copies kept | daily 03:00 | yes | SQLite only (PostgreSQL uses its own tools) |
| `housekeeping` | `job-history` step, `JobHistoryDays` (90) | daily 04:00 | yes | |
| `audit-cleanup` | `audit` step, `AuditRetentionDays` (0) | daily 04:30 | yes | off at 0: the audit log is kept |
The server's options are what its system schedules are seeded and reset with. The audit
retention has one source, the `audit-cleanup` schedule: Settings › Logs › *Keep audit*
shows its age limit (0 while it is off) wherever it was last set, and saving another value
sets it (on with that limit, off at 0, no restart) and stores it as `AuditRetentionDays`,
the reset default. `CHRONOS_AUDIT_RETENTION_DAYS` is put into the schedule at every start
before the first pass, so a run caught up at start already uses it, and locks it (§14.3).
`JobHistoryDays` is likewise only the `housekeeping` schedule's reset default.
On the desktop: `archive-scan` (every 10 minutes, seeded from the former Rescan every; no
catch-up; also once after the archive is reopened at start and when an unplugged archive is
back), `index-backup` (every day, catch-up, 3 copies), `housekeeping` (daily 04:00,
catch-up: `job-history` 90 days and `cache-trim`) and `workspace-cleanup` (daily 04:30,
catch-up: `workspace-clean`, the workspace's Clean after and Size limit, §12.3, and
`workspace-trash`, which only reports the workspace's trash; it needs no archive; amended
2026-10-26, R8). A system schedule whose work was last
done a whole period ago (the newest index copy, for `index-backup`) is seeded due at once,
so the first start after an upgrade copies an index whose newest copy is a day old;
otherwise a new schedule first runs at its recurrence's first occurrence (an interval one
interval after it is created). Times are wall-clock times of the host's zone: the PC's, or
the container's `TZ` (UTC, with a warning, when the image does not know it), which the
admin panel's Scheduled tab names.
The scheduler looks every 30 s (the desktop's also at once when its archive is back or its
job settings are saved). A run is claimed by moving its next run with a compare-and-set on
`next_run`, so processes sharing a database fire it once (a crash between the claim and the
queueing loses that one run). A run queues the action's jobs at the schedule's priority
with `jobs.schedule_id`, at most 500 sequences per job; it queues nothing, and records why, while
the schedule's previous job, or a job doing the same work on the archive, is queued, running
or paused (`skipped-pending`), while the archive is missing or offline (or read-only, for an
action that writes: `skipped-offline`), when there is nothing to do (`skipped-nothing`), or
when the host cannot run the action (`unavailable`: no handler, PostgreSQL or an index
without a file for backups, proxies turned off). A run more than 5 minutes late (the host
was off, the PC slept) was missed: with catch-up it fires once, otherwise the schedule moves
to its next occurrence; intervals stay on the grid of their due times. A time a
spring-forward gap skips moves forward by the gap; a time the clocks go back over runs once,
at its first occurrence; a next run more than two periods ahead means the clock went back
and is computed again. Run now queues at once, also for a disabled schedule, without moving
the next run.
Actions: *scan* (`force`: full; `deep`: deep analysis of what it indexes, unset: as the host
says at the run, Settings › Analysis › After a scan on the desktop, off on the server),
*verify* (`percent` of the sequences per run, never-verified then least recently verified
first, those unverified for `olderThanDays`), *thumbnails* and *proxies* (missing ones, or
`force` all; proxies only when the archive makes them), *analysis* (light, or `deep`),
*maintenance* (`dryRun`), *backup* (`keep`), *cleanup* (`steps`, `olderThanDays`) and the
read-only *duplicates* and *orphans* reports in the job log. Clean-up steps: `job-history`
(finished jobs; the engine no longer purges them at start), `audit` (0 days keeps
everything), `trash-report` (lists trash entries older than the limit with their sizes and
never deletes: emptying the trash stays a user action, §0.2 rule 8), and the host's own
(`uploads` on the server, `cache-trim` on the desktop). A step that fails fails the job after
the others ran.
Live services are not schedules: they queue no recurring work and change no user data,
they keep a connection, a device or the archive's settings current from moment to moment,
and they show in their own screens. On the server: the read of archive.json every 10
minutes, whatever the scan schedule does (it only takes the settings a desktop sharing the
archive wrote, so uploads follow them while scans are pending, rare or off), the
render-node monitor and the LAN beacon. On the desktop: the sync agent (the transfers it
decides are jobs in the queue), the render node, card and drive detection, the look for an
unplugged archive every minute and the update check at start. The log files prune
themselves (§14.1).
### 14.7 Render nodes
A Chronos client with "Offer this PC as render node" registers its encoder capabilities
and polls/claims render jobs matching them, downloads what it needs (proxies or originals
per job settings), renders with its GPU, uploads the result as a render of the sequence.
Node state shown in admin › Jobs; the server falls back to managed formats when no node is
available and says so in the job log.
Project versions (amended 2026-10-26, R8). A render job may name `projectId` and
`projectVersionId`. `POST /jobs` checks them against the target sequence (404 `not_found`
`project` or `version`): a version must belong to a project of the sequence and names its
project; a project alone, without settings of its own, is pinned to its head when the job is
queued; a deleted project's versions still render. The server's own render and a node's claim
get that version's settings (or the job's own portable settings) placed on the sequence's
frames; a node gets them placed on the frames its claim lists, read as one frames version.
The render records the project and the version. Jobs without them render as before.
Settings format (amended 2026-11-04, owner review 1 R5/R6; §14.3). A node registers the
highest settings format it reads (`settingsFormat`; a node of an earlier release reads as 1)
and is never given a job that needs more: the claim and the wait for a node both route the
job again from the sequence's settings of the moment (size adapted, format required), and a
job no online node can take goes to the server's managed fallback instead of waiting. A node
of this release reads its encoder limits as long edge × short edge, so a 2160×3840 job fits a
4096×2304 encoder; an older node is held to its limits as announced. Amended 2026-11-05,
owner review 1 R3/R8/R9: a node of this release reads format 3, renders the output program
(§11.1) and saves stills; a node of an earlier release is never given a playback or still
job (§14.3), which goes to a node of this release or the server's managed fallback.
### 14.8 Admin web panel (`/admin`, vanilla HTML/CSS/JS, ES modules, no build step, same API)
```
┌─────────────┬────────────────────────────────────────────────────────────────────────────┐
│ Chronos │ Dashboard │
│ ● Dashboard │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ Library │ │ 9.4 TB │ │ 412 seq │ │ 3 jobs │ │ 2 nodes │ │
│ Users │ │ of 16 TB │ │ 618k pho │ │ running │ │ online │ │
│ Archive │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ Jobs │ Storage by year ▁▂▃▅▇█ Uploads last 30 days ▂▁▃▆▇▅▂ │
│ Logs │ Recent: alberto uploaded 1,020 frames · node "studio-pc" rendered 4K HEVC │
│ │ │
│ Settings │ │
│ (A) admin ⏻ │ │
└─────────────┴────────────────────────────────────────────────────────────────────────────┘
```
Pages: Login · Dashboard · Library (amended 2026-10-26, R6; below) · Videos (amended
2026-11-05, owner review 1 R3/R8/R9; below) · Users (table;
create/edit/disable/reset/roles/quota) · Archive (path, templates, proxy policy,
scan/rebuild/verify, stats, and *Trash*, which opens the Library's trash view; R6; a save
that changes a template offers Reorganize, R7) · Jobs
(two tabs in the header, amended 2026-10-26, R10: *Queue*, the queue/history/nodes with
cancel/retry, where
`#/jobs?job=<id>` opens a job's log and a job a schedule queued carries a *Scheduled* pill
linking to it; *Scheduled* (`#/jobs?tab=schedules`), every schedule of the server, its
system schedules first and marked System, with when it runs (in the panel's language), its
next run and last result (every time on the tab in the server's time zone, named there), an
on/off switch, Run now, Edit, and Delete (user schedules) or Reset (system schedules), both
confirmed, its runs paged under it, each linking to its job; *New schedule* and Edit open a
side panel: name, action (those the server cannot run disabled, the reason in the
tooltip), recurrence (interval, daily, weekly, monthly), the action's parameters, priority,
catch-up, on; a field the server refuses is marked; the tab follows `scheduleChanged` and
`jobState` events, so skipped runs and other administrators' edits appear at once) · Logs
(tail, download; schedule changes and runs in words, a system schedule by its name in the
panel's language) and, docked at the foot of the sidebar above the account, Settings
(server name, ports, TLS mode + fingerprint, discovery, jobs: parallelism and priority
queue, limits, language, retention (tokens, uploads; job history is the *Job history
clean-up* schedule's age limit, R10), Logs (amended 2026-10-26, R11: file level and console
level (Trace…None, default Information), keep logs (days), file size (MB), logs total (MB),
rotation (daily or hourly, UTC), keep audit (days; the *Audit log clean-up* schedule's age
limit, §14.6), diagnostics logs (MB), applied without a restart), Videos folder (amended 2026-11-05, owner
review 1 R3/R8/R9: `videosPath`, an absolute folder outside the archive and the data folder;
empty turns copying off; sent only when changed)). A field an environment
variable fixes is read-only, its tooltip naming that variable (`lockedBy`, §14.3; R11).
Network and TLS (amended 2026-11-04, owner review 3): HTTP port and HTTPS port (in a
container *Container HTTP/HTTPS port*, read-only: the template maps them to host ports),
*Public HTTP port* and *Public HTTPS port* (empty: the listening port, shown as placeholder;
applied at once to LAN discovery and the HTTPS redirect), and a read-only *Client address*
with Copy: `https://<the host name the browser used>:<the HTTPS port the page came through,
else the public HTTPS port>`, the proxy's address in TLS mode proxy, which is what users type
in Chronos and the Uploader; when the page's HTTPS port is not the saved one, a *Use <port>*
button fills it in as the Public HTTPS port, and saving a Public HTTPS port other than the
page's asks first, as the redirect follows it at once; the discovery tooltip says that a
container needs network type Host for it. The
last group of Settings, About, is read-only: version, API version, database and uptime (the
server name and the fingerprint are in the groups above); an old `#/about` link opens Settings on it (amended 2026-10-26,
R4, R5). Same UI rules: tooltips only, light/dark, localised via `/api/v1/i18n`, keyboard
accessible. The sidebar is 256 px and collapses to its icons with ≡ or Ctrl+B like the
desktop rail, the choice kept in the browser and the links' tooltips then naming their page;
on narrow screens it stays the top bar, Settings at its end (amended 2026-10-16, R1;
2026-10-26, R4). Settings has the desktop's gear icon (§12.1).
Library (amended 2026-10-26, R6), the second page of the sidebar. The panel manages the
library and never edits a video: it has no project settings and no render. It browses,
views and deletes sequences and photos, restores them from the archive's trash and runs mass
operations; it queues no deep analysis (the API's `bulk/jobs` takes `deep`).
- `#/library` lists the sequences as cards (DESIGN §4: 16:9 cover, count badge, status
glyphs, check box) or a list, the choice kept in the browser; search over title, camera
and tag; Year, Camera, Status and Tag filters whose menus come from
`GET /sequences/facets`, each value with its count (a camera named as on the desktop, the
brand once), Status offering analysed or not, proxies or none, rendered or not, verified or not,
warnings and errors; sort newest, oldest, title, most photos, largest; *Load more* by
cursor. The filters live in the address, so Back from a sequence finds them again. A cover
is the sequence's thumbnail at an address that changes with its cover and its frames
version, cached an hour.
- Selection by check box, Shift range or the keyboard (one tab stop for the grid, arrows,
Space, Shift+Space, Enter opens, Ctrl+A, Esc), and *Select all N* of the filter. The
selection's bar: *Analyse*, *Proxies*, *Thumbnails* and *Verify* (one job per 1,000
sequences, the toast saying how many were queued), *Tags…* (add and remove), *Export CSV*
(title, camera, photos, bytes, first and last capture, tags; built in the browser, a cell
a spreadsheet would run as a formula starting with an apostrophe) and *Delete…* (a dry
run, then a dialog listing the sequences that cannot go with why, then those that go, at
most 500 names; no typed confirmation, since the trash keeps them). Bulk requests are sent
in chunks of 1,000.
- `#/library?id=<sequence>`: title (edited in place), tags, rating and notes, saved with the
same conflict-checked PATCH as the desktop; its facts; its photos in pages of 500 with lazy
thumbnails; a photo viewer (the proxy, else the thumbnail; ← and →, Esc; time, exposure,
aperture, ISO, focal length, size in pixels and bytes, format, flags, SHA-256); *Set
cover*; *Download* the original; *Delete…* of the selected photos (a dry run, then a
confirmation that asks for their number to be typed when more than 20 go, the sequence's
frames version sent so a changed sequence refuses); *Delete…* of the sequence; its
renders, to download; *Add photos* (the upload dialog, R3).
- *Projects* on a sequence's page (amended 2026-10-26, R8; §14.3): the sequence's projects,
Main first, named in the panel's language while it keeps the name Main and marked *Main*
once renamed; each with its newest version number and who changed it last and when. A
click on a project opens its versions (number, kind: Saved, Merged, Restored, Imported,
Outside change; author or client, note, time; the head marked *Newest*), 20 at a time
with *Load more*, read without their settings. *Rename…* and *Delete…* only for projects
other than Main; Delete asks for a confirmation naming the project, which goes with its
versions into the sequence's project trash. The section makes no project, pushes,
restores or edits nothing. It follows `projectChanged` of the sequence, reading again only
the changed projects' open versions (as many as are shown), and reads everything again
after a reconnection. The table drops columns at narrow widths.
- `#/library?view=trash`, also opened from Archive: the trash's entries (kind, sequence,
photos, size, deleted by and when), each with *Restore*, whose answer says which photos
stayed and why; *Empty…* measures the trash (dry run), lists what goes, asks for the word
"empty" in the panel's language (any case), sends back the plan's fingerprint and follows
the empty-trash job to its end, reading it again after a reconnect of the events or when
it ended before the request answered.
- The pages follow `sequenceChanged` and `jobState`: the list reads every loaded row again
(1,000 a request) with its filters; a sequence reads itself and its renders again after a
job ends (at most every 1.5 s), redraws only what changed, keeps the keyboard focus, and
asks again for thumbnails not built yet (from 2 s up to 60 s apart, at most 8 times).
`jobState` carries no kind or target, so a page reacts to any job that ends.
- The audit log and the Dashboard name photo deletions, trash restores and emptyings asked
for.
Videos (amended 2026-11-05, owner review 1 R3/R8/R9; §12.10, §14.3), the page after Library
in the sidebar. It manages the server's renders and never edits: nothing on it renders or
changes a project (owner review 2, R6).
- `#/videos` lists every render of the server as cards, a list or a board (kept in the
browser; the board amended 2026-11-06, owner review 4 R1: lanes *Published* and
*Workspace*, the latter holding project renders produced by another machine than the
server, per `producedBy`):
search, Kind, Codec, Year and Order, the filters in the address; `#/videos?sequence=<id>`
shows one sequence's, named by a chip whose × clears that filter only (the sequence named
from its own record when none of its videos is on the page); *Load more* by cursor.
- Selection by check box, Shift range or the keyboard, as in the Library. The selection's
bar: *Download* (one render; disabled for an image sequence, a folder, and a missing
file), *Copy to folder* (a `video-copy` job into the server's videos folder; disabled,
saying why, without the Edit permission or without a folder) and *Delete…* (the dry run:
what goes and its bytes, what stays and why, "copies in the videos folder stay"; then the
delete with the plan's fingerprint; Delete permission).
- *Play* opens a dialog: a `<video controls>` for MP4, M4V, MOV and WebM (the session cookie
authorises the file's GET, Range for seeking), an image for stills, GIF and APNG, a
download link otherwise, and *Cannot play here* when the browser cannot decode it.
- A sequence's page lists its renders with their kind and a short hash (the whole one in
the tooltip) and links *All videos* to `#/videos?sequence=<id>`.
- The Library's trash view lists deleted videos as kind *Videos*, titled by their sequence,
with their own *Restore* message; restoring a video happens there only.
Reorganize (amended 2026-10-26, R7), the panel's way to the Reorganize of §12.5 through
`POST /archive/reorganize` (§14.3):
- The Library's selection bar has *Reorganize…*: the selected sequences, up to 1,000 (one
plan, one job); above that, every sequence of the archive, only while the selection is
exactly *Select all* without a filter and the archive still holds as many; any other larger
selection is refused with a message, never split.
- On Archive, a save that changes the folder or file template, when the archive has
sequences, shows *Saved* with *Reorganize…*: the dialog for every sequence, with the saved
templates and only the changed parts switched on. Saving alone never renames anything.
- The dialog: Folders (`{title}` the new title), Files (named as filing names them) and Titles
(`{title}` the current title), each with its switch and field, from the archive's settings;
Titles starts off and empty. Each change asks the server for a dry run 400 ms after typing
stops (Enter at once), one at a time, a change made meanwhile planned right after. The
table shows each sequence in the order the changes apply, 200 at a time: title, folder and
renamed files before and after (up to three samples), *Carried* for a sequence that moves
only with a folder it is inside, and the photos that keep their names with why, or why the
sequence stays as it is; totals of sequences changed, files renamed and names kept. A refused
template is marked on its field with the server's reason; a nested target on Folders.
- *Apply…* (enabled only while the table is the plan of the fields and changes something)
asks for a confirmation that counts the sequences, folders and photos (nothing is deleted,
so nothing is typed), then sends that plan's fingerprint; the toast offers *Open job*. When
the archive changed meanwhile (`plan_changed`), or a new plan answered during the
confirmation, the dialog shows the new plan and Apply waits.
- A toast with an action stays 15 s and pauses under the pointer or the keyboard focus. The
audit log and the Dashboard read "… reorganized the archive · N sequences · M files renamed
· templates".
Convert (amended 2026-10-26, R7), the panel's way to the Convert of §12.5 through
`POST /archive/convert` (§14.3):
- The Library's selection bar has *Convert…*, after *Reorganize…*, for the same selection: up
to 1,000 sequences, or every sequence after *Select all* without a filter (one plan, one job).
- The dialog: Format (JPEG, TIFF-16, Linear DNG, the archival choice, chosen first), Quality
(JPEG only, 1–100, 95) and Mode (Replace or New sequence), never preselected; each choice's
tooltip says what becomes of the originals. Each change asks the server for a dry run, one at
a time (400 ms after typing the quality). Until a mode is chosen it is asked in Replace's
words; New sequence asks again, answered from the plan the server keeps. The table shows each
sequence, 200 at a time: photos converted, those left as they are with why (what blocks the
whole sequence first; *Not copied* with New sequence) and the size before → after; then the
totals and the server's space line. A dry run a proxy cut off is asked again every 2 s for up
to 16 minutes, the totals saying how long it takes.
- The dialog's *Convert…* (enabled while the table is the plan of the fields, converts
something, has the space and a mode is chosen; its tooltip says what is missing) asks a
Replace to type the word "replace" in the panel's language, and confirms a New sequence with
how many photos the new sequences lack, each sequence listed with its own count. It then
asks the dry run again (Close stays: nothing is sent yet) and sends that plan's fingerprint
only while it is the one confirmed; the toast offers *Open job*. `plan_changed`,
`plan_dropped`, `not_enough_space` and `nothing_to_convert` show the new plan and the button
waits; a request that got no answer is not sent again, as its job may be queued (the Jobs
page says).
- The trash view lists replaced originals as *Replaced*, whose *Restore* swaps the originals
back in place of their conversions while those are unchanged, else restores them into a new
sequence. *Empty…* lists first the entries whose conversion the archive shows deleted, each
saying so.
- The audit log and the Dashboard read "… queued a conversion · N sequences · M photos ·
format · mode".
Upload (amended 2026-10-26, R3): Library › *Upload* (no sequence) and a sequence's *Add
photos* open the upload dialog (§14.4), a module the pages import only on demand.
- Target: the given sequence, or a choice between an existing sequence (a search box, then a
list) and a new one (title optional), fixed once the first run starts.
- Photos: the file picker (several files, the photo extensions only) or a drop on the dialog.
Folders, files that are not photos (hidden dot files among them) and files above the size
limit are counted in chips and left out.
- Each photo shows its state: waiting, hashing %, starting, uploading %, verifying, uploaded,
already there, deleted before (with *Upload again*), failed (the reason in the tooltip),
cancelled, not sent; a total bar shows photos and bytes.
- Buttons: *Upload*, which sends whatever is not on the server yet; *Cancel* while sending;
*Close* otherwise. Esc closes only while nothing is being sent.
The panel's files (amended 2026-10-26, R6) are served with `Cache-Control: no-cache` and an
ETag of their content: the browser asks again before each use and an unchanged file costs a
304 (`If-None-Match` lists, weak `W/` tags and `*` count), so after an upgrade it never runs
new modules next to old cached ones.
Storage (Dashboard and Archive) shows the space volume: the folder `CHRONOS_SPACE_PATH`
names (§14.9) when it can be measured, else the archive's own volume. When a space path is
in use and the archive's own volume (the write volume, where uploads land; on Unraid the
share's primary storage, often the cache) has other figures (another size, or free space
more than 64 MiB apart), a second line *Write volume* shows its free space. The figures'
tooltip names the volume and its file system (on Linux the mount's type from
`/proc/self/mountinfo`, so an Unraid share reads `fuse.shfs`); on such a share without a
space path it says the figures are the share's primary storage and to map the share's array
view (`/mnt/user0/<share>`) to `/space` and set `CHRONOS_SPACE_PATH=/space`. The server's
diagnostics report lists the archive, the space path and `/data`, each with free space,
file system and mount (amended 2026-10-26, R2).
### 14.9 Configuration and Docker
Environment variables (also readable from `/data/server.json`):
`CHRONOS_ADMIN_USER`, `CHRONOS_ADMIN_PASSWORD` (used only when no admin exists; forced change
at first login), `CHRONOS_ARCHIVE_PATH=/archive`, `CHRONOS_DATA_PATH=/data`,
`CHRONOS_SPACE_PATH` (`SpacePath` in `server.json`; optional: a folder, e.g. `/space`, whose
volume's free space the admin panel shows instead of the archive's; one that cannot be
measured falls back to the archive's with one warning, logged at start and again only once
it has worked in between; uploads always check the archive's own volume, §14.4, and a
conversion the tighter of the two, §14.3: amended 2026-10-26, R7),
`CHRONOS_VIDEOS_PATH` (`VideosPath` in `server.json`, the admin panel's *Videos folder*;
amended 2026-11-05, owner review 1 R3/R8/R9: the folder *Copy to folder* copies renders into,
hash-verified, flat, " (2)" on a collision; an absolute folder, else the start stops naming
it, outside the archive and the data folder, else the admin panel does not save it and a
copy answers 422 `videos_folder_invalid`; unset by default, which turns copying off with
`videos_folder_unset`; set, it locks the setting; Docker: `/videos`; Chronos never deletes
what it copied there),
`CHRONOS_DB=postgres|sqlite` (Linux: postgres only), `CHRONOS_DB_HOST`, `CHRONOS_DB_PORT=5432`,
`CHRONOS_DB_NAME`, `CHRONOS_DB_USER`, `CHRONOS_DB_PASSWORD`, `CHRONOS_DB_SSLMODE=prefer`,
`CHRONOS_HTTP_PORT=8080`, `CHRONOS_HTTPS_PORT=8443` (in a container, where
`DOTNET_RUNNING_IN_CONTAINER=true`, the listening ports are the template's: only these
variables change them, which network type Host needs when another service uses 8080 or
8443; the admin panel shows them read-only and a `server.json` value is ignored with a
warning and removed at the next save), `CHRONOS_PUBLIC_HTTP_PORT` and `CHRONOS_PUBLIC_HTTPS_PORT` (the host
ports clients use when a container's ports are published as others: LAN discovery, the HTTPS
redirect and the admin panel's client address use them; also the admin panel's *Public
HTTP/HTTPS port*, `PublicHttpPort`/`PublicHttpsPort` in `server.json`, applied at once;
amended 2026-11-04, owner review 3), `CHRONOS_TLS_MODE=auto|pem|proxy`,
`CHRONOS_TLS_CERT`, `CHRONOS_TLS_KEY`, `CHRONOS_TRUSTED_PROXIES=127.0.0.0/8, ::1/128` (TLS
mode proxy: the addresses or CIDR networks whose `X-Forwarded-*` headers count; listed here
on 2026-11-06, owner review 1 phase 6, as the server already read it), `CHRONOS_SERVER_NAME`, `CHRONOS_LANG=en`,
`CHRONOS_PARALLELISM` (photos the running job processes at once; `CHRONOS_WORKERS`, its former
name, still sets it), `CHRONOS_PRIORITY_QUEUE=false`, `CHRONOS_DISCOVERY=true` (LAN UDP beacon; it leaves a
container only with host networking, Unraid network type Host: amended 2026-11-04, owner
review 3),
`CHRONOS_LOG_LEVEL` (Trace|Debug|Information|Warning|Error|Critical|None, also `info`,
`warn`, `off`; default Information: sets the level of the log files and of the console and
locks both in the admin panel), `CHRONOS_LOG_CONSOLE_LEVEL` (the console alone, read after
it, so it wins for the console), `CHRONOS_LOG_RETENTION_DAYS=14` (1–3650),
`CHRONOS_LOG_MAX_FILE_MB=50` (0–10240, 0 = no limit), `CHRONOS_LOG_MAX_TOTAL_MB=1024`
(0–1048576, 0 = no limit, not below the file size), `CHRONOS_LOG_ROTATION=daily|hourly`,
`CHRONOS_AUDIT_RETENTION_DAYS=0` (0–3650 days of audit log the *Audit log clean-up*
schedule keeps, 0 = forever; set, it is applied to that schedule at every start and locked
there), `CHRONOS_DIAGNOSTICS_LOG_MB=4` (1–1024 MB of the end of each log file in the
diagnostics zip); in `server.json` `LogLevel` sets the files only and `ConsoleLogLevel` the
console; a value out of range stops the start naming it (R11). `PUID`, `PGID`, `TZ` (also
the time zone of the schedules, R10). A variable fixes its setting: the admin panel shows
it read-only and names the variable. (Amended 2026-10-16, R2; 2026-10-26, R2, R10, R11.)
Dockerfile: multi-stage on `mcr.microsoft.com/dotnet/sdk:10.0` → `aspnet:10.0`, non-root
user via `PUID/PGID` entrypoint, volumes `/archive` and `/data` (the optional read-only
`/space` bind mount is not a declared volume; amended 2026-10-26, R2; nor is `/videos`, a
folder the image makes for an optional videos volume, which the entrypoint checks: a
`/videos` that is not a mounted volume, or that `PUID:PGID` cannot write, only warns, since
copying is optional; amended 2026-11-05, owner review 1 R3/R8/R9), `HEALTHCHECK` on
`/health`, `linux/amd64` (the Dockerfile can also build `linux/arm64`, but releases publish amd64 only; amended 2026-11-06, phase 6). `docker-compose.yml` with a PostgreSQL 17 service
(amended 2026-11-05, owner review 1 R3/R8/R9: and the videos folder, `${CHRONOS_VIDEOS:-./videos}`
at `/videos` with `CHRONOS_VIDEOS_PATH=/videos`; remove both to turn copying off).
Windows: `Chronos.Server.exe` runs as console or Windows Service (`sc create`), SQLite or
PostgreSQL.
The deploy guide `docs/deploy/` (README, `docker.md`, `unraid.md`, `desktop.md`) documents
every variable above with its default, the volumes, the ports and public ports, the TLS
modes and the fingerprint, upgrades (`:latest`, `:<version>`, `:nightly`; migrations at
start, forward only), backup and restore, PostgreSQL and troubleshooting; the compose file,
the Unraid template and `deploy/releases-repo/README.md` say the same, and a change to one
updates the others (amended 2026-11-06, owner review 1 phase 6).
---
## 15. Chronos Uploader
Single small window (tray-capable), zero analysis: connect + sign in (token saved with
DPAPI), drop zone (files/folders/cards), queue with per-file state, pause/resume, bandwidth
limit, retry with backoff, resumable across restarts (queue persisted in a JSON file next to
the app data), hash verification, optional "delete source after server confirms" (off by
default, confirmation), watch folders (poll + `FileSystemWatcher` where reliable; upload
new files after they stop growing), run at startup, minimise to tray, per-session target
(auto-group / choose sequence / new sequence with title). P2: "make proxies here" toggle
for HEIC/RAW so the server can render without a node.
```
│ Chronos Uploader ☁ https://nas.local:8443 · alberto · ● Connected [⚙] │
│ ┌────────────────────────────────────────────────────────────────────────────────┐ │
│ │ Drop photos, folders or a card here │ │
│ └────────────────────────────────────────────────────────────────────────────────┘ │
│ Target (•) Group into sessions automatically ( ) Sequence [Harbour sunset ▾] ( ) New │
│ Queue 4,812 files · 96.2 GB · 38 MB/s · 41 min left [⏸] [⏹] Limit [50] MB/s │
│ ▮▮▮▮▮▮▮▮▮▮▮▮▮▮░░░░░░░░░░░░░░░░ 2026-09-28_18-02-11_0413.CR2 │
│ Watch folders D:\Cam\Roof (every 60 s) ● [+] │
│ [✓] Delete source after verified upload [✓] Start with Windows │
```
---
## 16. Localization
- Source strings in `i18n/en/*.resx` (one file per area: `Shell`, `Library`, `Editor`,
`Import`, `Archive`, `Server`, `Settings`, `Tooltips`, `Errors`, `Advisor`, `Admin`).
Keys are stable identifiers (`Library.Filter.Year`), never English sentences.
- Runtime: `ResourceManager` + a `Loc` XAML markup extension and `L("key", args)` helper in
`Chronos.Core/Localization`; culture switch at runtime without restart (rebinding via a
`LocalizationChanged` event); web admin receives `/api/v1/i18n/{culture}` generated from
the same resx by `Chronos.Tools i18n export`.
- Plurals: an in-house minimal CLDR plural-rule table for the shipped languages
(`one/few/many/other`), keys with suffixes (`Photos.Count.one`, `.other`).
- Dates/numbers/units via `CultureInfo`; file sizes localised; RTL via `FlowDirection`
for `ar`, `he`, `fa`, `ur` (mirrored rail and icons where directional).
- Languages (Phase 8, all machine-translated by Claude Code with a glossary, marked as such
in About and open to community review via the releases repository): `en` (source), `it`,
`de`, `fr`, `es`, `pt-BR`, `pt-PT`, `nl`, `pl`, `cs`, `sk`, `hu`, `ro`, `sv`, `da`, `nb`,
`fi`, `ru`, `uk`, `tr`, `el`, `bg`, `hr`, `sl`, `lt`, `lv`, `et`, `ja`, `zh-Hans`,
`zh-Hant`, `ko`, `ar`, `he`, `hi`, `id`, `ms`, `vi`, `th`. Add more if effort allows.
(Amended 2026-10-23, R2.)
- `Chronos.Tools i18n check` fails CI when a key is missing in `en` or `it`, when a
placeholder count differs between languages, or when a string exceeds the layout budget
(tooltips ≤ 200 chars, labels ≤ 30 chars unless flagged).
- UI is written to survive +40 % text expansion (German, Finnish): no fixed-width labels.
---
## 17. Branding and icon
- Mark: a **time-lapse aperture-clock** — a circle of 12 short arc segments increasing in
opacity clockwise (the sequence of frames) around a solid sun disc slightly off-centre,
reading as camera aperture, clock and sun path at once; single accent colour on a rounded
square (dark) tile; no text. Works at 16 px (segments merge into a ring; the disc
remains).
- Generated programmatically (`Chronos.Tools make-icon`): in-house PNG encoder + ICO
container (16/20/24/32/48/64/128/256), SVG source kept in `branding/`; variants: Server
(mark + three horizontal bars badge), Uploader (mark + up-arrow badge). Also favicon
for the admin panel and a 1024 px PNG for listings. Prototype `IconGenerator` shows
the ICO writer approach.
- App name in title bar only; no splash screen; first-run screen is the empty Library
with one sentence and two buttons (Import a card · Open an archive).
---
## 18. Installer, distribution and updates
- Builds: `dotnet publish -c Release -r win-x64 --self-contained -p:PublishSingleFile=true
-p:PublishReadyToRun=true` for App, Uploader, Setup; server as framework-dependent
Docker image and a self-contained Windows zip/installer. (No trimming: WPF does not
support it.) The Windows programs are cross-compiled on the Linux runner
(`EnableWindowsTargeting`), and `Chronos.Tools pe-check` stops a release whose executables
lost the GUI subsystem, the icon, the version information or the PerMonitorV2 manifest
(amended 2026-10-23, R3).
- `Chronos.Setup` (in-house, WPF, ~one screen): choose components (Chronos, Uploader,
Server for Windows), folder, shortcuts, file associations (`.chronos` project bundles),
installs to `%LOCALAPPDATA%\Programs\Chronos` per user (no admin) or `Program Files`
(elevated), registers Add/Remove Programs entry with uninstaller, silent mode
(`/S /DIR=`), upgrade in place, keeps user data. Payload appended to the setup exe as a
compressed archive (in-house format on `DeflateStream`) with a manifest and per-file
hashes. If the human later permits a build-time tool, Inno Setup/MSIX are acceptable
alternatives; default is in-house.
- Code signing hook in the release workflow (Authenticode with `osslsigncode`, the Linux
counterpart of `signtool`; amended 2026-10-23, R3) using secrets when present; unsigned
builds are still produced.
- Updates: on start (opt-out) the client calls the Gitea releases API of the **releases
repository** (§19.4), `<server>/api/v1/repos/<owner>/<name>/releases?draft=false&pre-release=false`,
takes the highest version (a pre-release build is offered the final release of its own
version; a 404, a repository the client cannot see, is a failed check, not "up to date"),
builds the release page and download links from `ChronosReleasesUrl` (Gitea writes its own
with its ROOT_URL, which clients may not reach), and shows a one-line notice with "Download" (P1: download
installer, verify SHA-256 from `SHA256SUMS`, run it). The repository is the build
property `ChronosReleasesUrl` (default `https://gitea.encke-hake.ts.net/BalboSoft/Chronos`),
which also gives the licence link (`<repository>/src/branch/main/EULA.md`), the issues
link (`<repository>/issues`) and the Add/Remove Programs `URLInfoAbout`. (Amended
2026-10-23, R2.)
- Distribution: installers, zips and `SHA256SUMS` on the Gitea release of the releases
repository; Docker images in the Gitea container registry
(`gitea.encke-hake.ts.net/balbosoft/chronos-server`); Unraid template in the repository
(§19.6); who can reach them today: §19.4. (Amended 2026-10-23, R2.)
---
## 19. CI/CD, Docker, Unraid
### 19.1 `ci.yml` (push to `main`, pull requests, manual; amended 2026-10-23, R3)
Gitea Actions in `.gitea/workflows`. The runner is act_runner in Docker mode on the Linux
server that also hosts Gitea, label `ubuntu-latest`, one job at a time. The .NET jobs run
in the container `mcr.microsoft.com/dotnet/sdk:10.0` and check out with plain `git` (the
image has no Node.js, so no JavaScript actions such as `actions/checkout`); no artifacts
and no caches are used; builds use 4 cores (`BUILD_CPUS`). Gitea shows no job summary and
no annotations: `::warning`/`::error` lines appear in the log only. Jobs:
- `build`: `dotnet --info`, build with warnings as errors, zero-package guard,
`Chronos.Tools i18n check`, XAML lint, format check, CC0 RAW fixtures fetched by
`Chronos.Tools fixtures` (a missing sample is a warning in the log and its tests skip),
`Chronos.Testing` for the Core, Data (SQLite), Server and Tools tests (JUnit XML), and the
Windows programs (App, Uploader, Setup) cross-compiled for win-x64, packed with
`pack-installer` and checked with `Chronos.Tools pe-check`.
- `postgres`: PostgreSQL 16 and 17 service containers (host name `postgres`) for
`Chronos.Data.Tests` and `Chronos.Server.Tests`; `Chronos.Tools postgres-ci` prepares the
MD5, cleartext and trust roles and TLS through SQL only, because Gitea gives no id of the
service container.
- `docker`: builds the image with the host's daemon (no push) and smoke-tests `/health`
with PostgreSQL 17 on a network of the run.
- `yaml`: in `ruby:3.3-alpine`, with the sources from the Gitea archive API; checks the
workflows, the `.gitea/ISSUE_TEMPLATE` forms and the compose file.
- `windows` (optional): runs only when the repository variable `WINDOWS_RUNNER` names the
label of a Windows act_runner in host mode with the .NET SDK, Git for Windows (in
`C:/Program Files/Git`, whose bash the job names by path) and PowerShell 7: the Core.Windows and App tests, the `--capture` screenshots and their diff,
and the installer test. Without a Windows runner the Windows-only tests are run locally on
a Windows PC.
`perf.yml` runs the performance gates weekly on SQLite and on PostgreSQL 17 in a service
container; the timings are printed at the end of the log.
### 19.2 Zero-package guard
`Directory.Build.targets` target `AssertNoPackageReferences` fails the build if any
`PackageReference` exists; CI also greps `**/*.csproj` and `**/*.props` and checks that
`obj/project.assets.json` lists no packages. The workflows use only shell (`run`) steps: no
third-party actions at all (amended 2026-10-23, R3).
### 19.3 `release.yml` (tag `v*`, or manual re-publish of an existing tag; amended 2026-10-23, R3; amended 2026-10-26, R1)
Job `release`, in the SDK container: the version from the tag
(`vMAJOR.MINOR.PATCH[-PRERELEASE]`, SemVer 2.0 as `release-channels` reads it, checked
before anything is built) passed as `-p:ChronosVersion`, with
`-p:ChronosReleasesUrl` (the releases repository's address, §18); build and the Linux
tests; self-contained single-file win-x64 publish of App and Uploader (ReadyToRun), Server
and Setup (ReadyToRun), cross-compiled on Linux; `Chronos.Tools pe-check` (GUI subsystem,
icon, version information, PerMonitorV2 manifest); Authenticode signing with
`osslsigncode` when the secrets `SIGN_PFX_BASE64` and `SIGN_PASSWORD` exist; the
installers `Chronos-Setup-<ver>.exe` (components Chronos, Uploader, Server) and
`Chronos-Uploader-Setup-<ver>.exe`, `Chronos-Server-win-x64-<ver>.zip` and
`Chronos-win-x64-portable-<ver>.zip` (with `portable.txt`); release notes
(`Chronos.Tools changelog` from Conventional Commits) and `SHA256SUMS`; the Gitea release
made by `Chronos.Tools gitea-release` (a draft first, every file uploaded and its size
verified, then published). Then `Chronos.Tools release-channels` decides what the tag moves
(amended 2026-10-26, R1): it reads every page of the target repository's published releases
(`releases?draft=false&limit=50&page=<n>` up to the first empty page, at most 100), stable
and pre-releases alike, ignores drafts and tags that are not `v` + SemVer 2.0, always counts
the tag itself, takes a release Gitea flags as a pre-release for one, and compares by
SemVer 2.0 precedence (not Gitea's `releases/latest`, which is the most recently created
release; equal precedence counts as highest). `latest` is true for the highest stable
release and moves the releases repository's content (§19.4); `image_latest` is true for
the highest stable release or, while no stable release exists, the highest pre-release,
and moves `:latest`. Re-publishing an older tag, or a pre-release once a stable release
exists, moves neither. When the channels cannot be decided (a page unreadable or not a
list, or a tag older than `release-channels`, whose own `Chronos.Tools` lacks it) the tag
moves neither, with a warning. Then job `image`, in the runner's default image with the
docker CLI and the host's daemon: it builds `linux/amd64` only (arm64 would need QEMU on
the host) and pushes
`gitea.encke-hake.ts.net/balbosoft/chronos-server:<ver>`, plus `:latest` when `image_latest`
is true. Pushing needs the repository secret `REGISTRY_TOKEN`, an access token of a user who
can write the owner's packages (scope "package: read and write"): the workflow's own token
(user `gitea-actions`) is refused by the organisation's registry. Pre-releases (tags with a
`-`) are published as Gitea pre-releases; the in-app update check ignores them.
Variables, all optional: `PUBLIC_URL` (default `https://gitea.encke-hake.ts.net`),
`RELEASES_REPO` (§19.4), `REGISTRY` (default the host of `PUBLIC_URL`), `REGISTRY_USER`
(default the user who pushed the tag), `WINDOWS_RUNNER` (§19.1). Secrets:
`REGISTRY_TOKEN` (needed for images), `RELEASES_TOKEN` (only with `RELEASES_REPO`),
`SIGN_PFX_BASE64` + `SIGN_PASSWORD` (optional signing).
### 19.4 Releases repository (amended 2026-10-23, R2)
By default releases are published in `BalboSoft/Chronos` itself: on the owner's own Gitea
the owner decides who sees the organisation, its releases and its packages, and one
repository needs no second token and no copy step. A separate public repository stays
optional, for when the sources must stay hidden while the releases are public: with the
repository variable `RELEASES_REPO` (owner/name of another repository on the same Gitea)
and the secret `RELEASES_TOKEN`, the release goes there, and for the newest stable release
`release.yml` copies into it `deploy/releases-repo/README.md` (what it is, screenshots,
requirements), `EULA.md`, `SECURITY.md`, `.gitea/ISSUE_TEMPLATE`,
`deploy/unraid/chronos.xml` and `branding/chronos-server.svg` (as `unraid/`), the compose
file and `.env.example` (as `docker/`), `i18n/` translations for community review and
`SHA256SUMS`, rewriting the links to that repository and its image; nothing is developed
there. `EULA.md` and `SECURITY.md` live at the repository root, the issue forms in
`.gitea/ISSUE_TEMPLATE` (Gitea issue-form YAML: name, about, title, labels, body).
Today the `BalboSoft` organisation is not visible to anonymous visitors, so the update
check, release downloads and image pulls work for other people only once the owner makes
the organisation (and its packages) public, or publishes to a public `RELEASES_REPO` (the
image stays in the organisation's registry either way); while it is private,
`docker login gitea.encke-hake.ts.net` is needed before pulling. Gitea has no private
vulnerability reporting: security problems are reported privately to the maintainers (the
contact on the owner's Gitea profile, or an e-mail to them), never in a public issue.
### 19.5 `docker.yml`
Nightly build of `main` (02:17 daily) to
`gitea.encke-hake.ts.net/balbosoft/chronos-server:nightly` in the Gitea container registry,
with the host's daemon and the `REGISTRY_TOKEN` secret as in §19.3 (amended 2026-10-23, R3);
`deploy/docker/docker-compose.yml` for users (server + PostgreSQL + volumes), downloaded
from `https://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/deploy/docker/docker-compose.yml`
together with `.../deploy/docker/.env.example`. `:nightly` is never a release: it carries
`main` as it was that night (version `0.0.0-nightly.<run>`), for testing only; users follow
`:latest` or pin `:<ver>` (amended 2026-10-26, R1).
### 19.6 Unraid template (`deploy/unraid/chronos.xml`)
Community Applications XML: repository `gitea.encke-hake.ts.net/balbosoft/chronos-server:latest`
(the newest release: the highest stable release, or the highest pre-release until the first
stable one, §19.3; never `:nightly`, so the template finds an image from the first
pre-release on; amended 2026-10-26, R1), WebUI `http://[IP]:[PORT:8080]/admin`, ports
8080/8443, paths `/archive` → `/mnt/user/Timelapse`, `/space` → `/mnt/user0/Timelapse`
(*Array view*, read-only, optional: the same share seen on the array only, so the admin
panel shows the array's free space, §14.8), `/data` → `/mnt/user/appdata/chronos`,
variables from §14.9 (admin user/password, DB host/port/name/user/password, TLS mode,
*Space path* `CHRONOS_SPACE_PATH=/space` (advanced), PUID/PGID, TZ; amended 2026-10-26, R2;
the log variables, *Log level* `CHRONOS_LOG_LEVEL` included, and *Audit retention*
`CHRONOS_AUDIT_RETENTION_DAYS` are advanced and empty by default (each description gives
the default), so the admin panel's Settings › Logs chooses them; a value given in the
template locks its setting; TZ also sets the time zone of the schedules; amended
2026-10-26, R10, R11), *Public HTTP port* `CHRONOS_PUBLIC_HTTP_PORT` and *Public HTTPS port*
`CHRONOS_PUBLIC_HTTPS_PORT`, empty by default, next to the ports, whose descriptions say to
enter the same host port there when it changes and that network type Host ignores the mapping (the
server then listens on 8080 and 8443 itself; the user guide says to add `CHRONOS_HTTP_PORT` /
`CHRONOS_HTTPS_PORT` when another service uses either); the overview names the client address and
that LAN discovery needs network type Host (amended 2026-11-04, owner review 3), *Videos*
`/videos` (optional, empty by default, not inside the archive) and *Videos path*
`CHRONOS_VIDEOS_PATH`, empty by default, `/videos` once that path is mapped (amended
2026-11-05, owner review 1 R3/R8/R9), description ≤ 2 sentences.
Registry and Project `https://gitea.encke-hake.ts.net/BalboSoft/Chronos`,
Support `https://gitea.encke-hake.ts.net/BalboSoft/Chronos/issues`, TemplateURL
`https://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/deploy/unraid/chronos.xml`,
Icon `https://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/branding/chronos-server.svg`;
`release.yml` rewrites these exact prefixes for a separate releases repository (§19.4), so
they stay verbatim. (Amended 2026-10-23, R2.) Document (in the README) how to install the
template as a user template (Unraid's template repositories read GitHub and GitLab
addresses, not Gitea's) and to pair it with the official PostgreSQL template; `docs/deploy/unraid.md`
gives the whole procedure, the fields, host ports other than 8080/8443 with their public
ports, the array view, upgrades and backup (amended 2026-11-06, owner review 1 phase 6).
---
## 20. Testing and quality
### 20.1 `Chronos.Testing` (in-house)
Attributes `[Test]`, `[Theory]` + `[Case(...)]`, `[Skip(reason)]`, `[Timeout(ms)]`,
`[Category]`; assertions with expressive messages (`Assert.Equal`, `Approximately`,
`Throws`, `SequenceEqual`, `Monotonic`, `Within(px)`); fixtures (temp dirs, synthetic
sequences, in-process server, database per test); parallel execution; filters by name/
category; console output + JUnit XML; exit codes; `dotnet run --project tests/X -- --junit
out.xml --filter core`.
### 20.2 Test layers
- Unit: parsers (fuzz corpus: truncated/garbage files must not throw), codecs (round-trip
PSNR thresholds), analysis rules (synthetic sequences with known answers — port the
prototype's 63-check self-test as tests), naming templates, SQL repositories (SQLite
in-memory), PostgreSQL wire client (against service container), protocol (chunk resume,
hash mismatch, idempotency), advisor recommendations (golden JSON).
- Integration: import a synthetic card folder → archive layout + sidecars + DB; rebuild
index from sidecars equals original DB; verify detects a flipped byte; server ingest via
API; sync round trip; render node claim/complete; job resume after simulated crash.
- Windows: WIC decode of fixtures, Media Foundation encode smoke (software H.264) +
in-house MP4 inspector + `MediaPlayer` playback check; `--capture` screenshots of every
screen for visual regression (pixel-diff tolerance) and for the phase report.
- Fixtures: tiny synthetic files checked in; CC0 RAW samples (one per major format, from a
public CC0 sample set) fetched by `Chronos.Tools fixtures` into `tests/fixtures/external`
(git-ignored; CI fetches them on every run, without a cache; amended 2026-10-23, R3).
### 20.3 Static rules
Warnings as errors; nullable enabled; `dotnet format`; XAML lint: every `Button`,
`ToggleButton`, `Slider`, `ComboBox`, `CheckBox`, `MenuItem` has a `ToolTip`; no literal
`Content="…"`/`Text="…"` outside resources; no `PackageReference`; no Windows APIs in
`Chronos.Core`/`Chronos.Data`/`Chronos.Protocol`/`Chronos.Server` (checked by building them on
Linux); public API of `Chronos.Protocol` versioned.
### 20.4 Quality gates carried over from the prototype (regression thresholds)
Deflicker: flicker reduction ≥ 60 % on the synthetic ramp sequence with the ramp preserved
within 0.05 EV; region deflicker: landscape residual ≤ 25 % of the global-curve residual;
phase correlation: sub-pixel error ≤ 0.10 px; stabilization on a textureless frame: shake
≤ 0.1 px (texture gating); holy grail: no step > 0.3 EV in the target curve; time remap
monotonic; star-trail luminance non-decreasing on ≥ 99 % of steps; memory: peak RSS
independent of sequence length for a fixed window; cancellation: no partial output, no
unobserved exceptions, spill file removed.
---
## 21. Monetization — absolute final step (Phase 9; do not start before every gate passed)
- In-house ad delivery, no SDK, no tracking by default: the client fetches a signed
campaign manifest (JSON: id, image URL, link, weight, languages, countries, start/end,
minimum version) from `ads/manifest.json`, a raw file of the releases repository on Gitea
(by default `https://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/ads/manifest.json`),
or from a URL set by the human (amended 2026-10-23, R2), caches creatives, renders them
natively in one slot — the Export section while a render runs (prototype rationale: the
only moment an ad takes nothing from anyone) — and optionally a small footer slot in
Library. Clicks open the browser. Manifest signature: ECDSA P-256 with an embedded public
key.
- No usage data (amended 2026-11-06, owner review 4 R2): Chronos sends nothing about its
use: no impression counting, no daily ping, no consent to ask, and an ad's impressions are
never reported anywhere. The diagnostics bundle (Settings › Advanced › Diagnostics, admin
panel › Logs › Diagnostics) is only saved locally; the user decides whether to share it.
Privacy policy link in About and EULA.
- Ad-free: "Chronos Pro" licence key (ECDSA-signed, offline validation, tied to a display
name and edition, no phone-home) entered in Settings › Licence; a server licence makes
all its connected clients ad-free (team scenario). Fallback content when the manifest
is empty: internal tips about the program.
- Everything above is a toggle in Settings for the human's own builds; the feature ships
disabled by default until the human flips a build property `ChronosAdsEnabled=true`.
---
## 22. Phased delivery plan
Each phase ends with the Definition of Done (§0.2 rule 9) and a phase report. Phases may be
split into sub-phases; order inside a phase is Claude Code's choice.
### Phase 0 — Bootstrap (repo, rules, shells)
Solution, `Directory.Build.*`, `global.json`, `CLAUDE.md`, `DECISIONS.md`, `CHANGELOG.md`;
`Chronos.Testing`; zero-package guard; `ci.yml`; i18n infrastructure with `en` + `it`;
WPF shell (rail, theme, job bar, status strip, settings skeleton, tooltip lint); server
skeleton (Kestrel, `/health`, `/server/info`, login page, admin shell); Dockerfile builds;
branding mark + ICO generator.
*Gate:* both apps start, server container answers `/health`, CI green on both OSes.
### Phase 1 — Metadata and imaging core
Parsers (§9), managed codecs (§8.3), WIC provider, decode tiers, thumbnails/proxies,
`ImageBuffer`/`FrameWindow` port, fixtures tool, fuzz tests, DNG full pipeline.
*Gate:* every fixture decodes at the expected tier on Windows and Linux; PSNR/round-trip
tests green; `Chronos.Tools diagnose <folder>` reports per-file tier and metadata.
### Phase 2 — Data layer and archive
SQLite binding, PostgreSQL wire client, migrations, repositories, archive layout, sidecars,
scanner, rebuild, verify, duplicates, orphans, adopt folder, naming templates.
*Gate:* import synthetic 100k-frame archive; rebuild equals original; verify detects
corruption; PG tests green against 16 and 17.
### Phase 3 — Client Library and Archive manager
Virtualized grid/list/timeline, filters, saved views, mass operations, jobs screen, stats
charts, maintenance, settings screens, `--capture` screenshots.
*Gate:* 500k-photo synthetic library meets §1.1 timings.
### Phase 4 — Card import
Device detection, card pool and profiles, plan preview, sessions, hash-verified copy,
post-actions (delete/format/eject), auto-import, direct-to-server destination stub.
*Gate:* end-to-end import from a simulated card folder; destructive actions gated by
verification; screenshots.
### Phase 5 — Analysis advisor
Light + deep analysis, reports, charts, recommendations with reasons, auto presets,
Auto/manual controls, Optimise.
*Gate:* golden recommendations for synthetic sequences; every recommendation has a
localised reason; deep analysis of 10k frames completes unattended.
### Phase 6 — Engine, encoding and Sequence editor
6a modules port with regression thresholds (§20.4); 6b Media Foundation encoder, MP4 muxer
(H.264/HEVC/AV1), managed encoders (AVI/GIF/APNG/sequences), presets; 6c preview tools,
section charts, spline editor, export UI, batch render.
*Gate:* self-test suite green; renders play in Windows Media Player and the in-house
inspector validates containers; hardware MFT used when present (logged).
### Phase 7 — Server, sync, uploader
Full API, auth, uploads/ingest, sync, jobs, render nodes, admin panel, Docker + compose,
client server mode, Uploader app, LAN discovery.
*Gate:* two clients + uploader against a Docker server: upload, sync, render via node and
via server; crash-restart resumes jobs; audit log complete.
### Phase 8 — Worldwide release readiness
All languages (§16), RTL pass, installer, `release.yml`, releases repository content
(README, EULA draft, template; a separate public repository optional since 2026-10-23, R2),
Unraid template, update check, diagnostics bundle,
accessibility pass, performance pass, docs.
*Gate:* tagged pre-release published end-to-end from CI; install/uninstall/upgrade tested;
Unraid template validated.
### Phase 9 — Monetization (§21)
*Gate:* human explicitly approves start; feature behind build property; privacy text done.
---
## 23. Assumptions and open decisions (for the human; do not block on these)
1. Product name **Chronos**, given by the owner on 2026-10-23 in place of the name kept
from the prototype (amended 2026-10-23, R1); settled.
2. Linux server MP4 output relies on render nodes (and P2 intra-only encoder). If an
FFmpeg subprocess were ever allowed as an *optional, opt-in* backend, it would be a
single `IVideoEncoderProvider`; not planned unless the human approves.
3. HEIC pixels are only decodable on Windows (WIC); server-side rendering of HEIC-only
sequences requires proxies from a client/node.
4. Native RAW decoders beyond DNG are phased (CR2, NEF, ARW, PEF, ORF, RW2, RAF
uncompressed first); until then those formats render from full-size embedded previews
on the server and via WIC + Raw Image Extension on Windows.
5. Windows 10 21H2+/Windows 11, x64 only (ARM64 later); `winsqlite3.dll` presence assumed.
6. Tests use the in-house runner to keep the zero-package rule absolute; xUnit would be
acceptable only if the human relaxes the rule for test projects.
7. Installer is in-house; Inno Setup/MSIX acceptable if the human allows build-time tools.
8. Ads and licence keys are designed but disabled by build property until Phase 9.
---
## 24. Amendments
The product owner's change requests amend this brief in place; each amended paragraph says
"(amended <date>, R<n>)". The request files in `docs/requests/` keep the owner's words, the
questions asked and the answers; DECISIONS rows give the reasons.
| Date | Request | Sections | What changed |
|---|---|---|---|
| 2026-10-16 | Owner review 1, R4 | §8.1, §8.2 | DNG decodes through the managed decoder (WIC only through the Raw Image Extension, never DNG); a GoPro DNG is GPR only when VC-5; analyses and previews take an adequate embedded preview by choice, renders decode natively. |
| 2026-10-16 | Owner review 1, R2 | §12.8, §14.6, §14.8, §14.9 | Jobs run one at a time; the parallelism is photos the running job processes at once; an optional priority queue by job kind pauses lower jobs and resumes them by itself; `CHRONOS_PARALLELISM` (former `CHRONOS_WORKERS`) and `CHRONOS_PRIORITY_QUEUE`. |
| 2026-10-16 | Owner review 1, R1 | §12.1, §14.8 | The rail is 200 px and collapses to 48 px of icons with ≡ or Ctrl+B, their tooltips naming the sections, saved at once; the admin panel's sidebar is 256 px and collapses the same way, kept in the browser. |
| 2026-10-16 | Owner review 1, R7 | §4.1, §10.2, §12.1, §12.3 | The Sequence section is now Edit: one sequence at a time, chosen in a picker inside the section (Change sequence, Ctrl+O); the editor's tabs are the steps of a guided, freely navigable path that starts with a new Analysis step, each step showing where it stands, with Previous and Next. |
| 2026-10-23 | Chronos on Gitea, R1 | whole brief, §23 | The product and its programs are named Chronos (Chronos, Chronos Server, Chronos Uploader) everywhere: projects and namespaces, files, settings, `CHRONOS_*` variables, `%LOCALAPPDATA%\Chronos`, `.chronos` project bundles and folders, the image `chronos-server`; the product name is no longer an open decision. |
| 2026-10-23 | Chronos on Gitea, R2 | §3, §16, §18, §19.4, §19.6, §21, §22 | The repository is `BalboSoft/Chronos` on the self-hosted Gitea (`https://gitea.encke-hake.ts.net`): the update check reads the Gitea releases API of `ChronosReleasesUrl`; licence, issue and support links, the Unraid template and the ads manifest point to that repository; images go to the Gitea container registry; releases are published in the repository itself, a separate public releases repository is optional (`RELEASES_REPO`); `EULA.md` and `SECURITY.md` at the root, issue forms in `.gitea/ISSUE_TEMPLATE`. |
| 2026-10-23 | Chronos on Gitea, R3 | §0.2, §18, §19.1, §19.2, §19.3, §19.5, §20.2, Appendix A | Gitea Actions on a Linux act_runner in Docker mode: CI jobs build, postgres, docker and yaml, plus a windows job once a Windows runner is registered; shell steps only, no artifacts, caches, job summaries or annotations; the release cross-compiles the Windows programs on Linux, checks them with `pe-check`, signs them with `osslsigncode` when secrets exist, publishes them with `gitea-release` and pushes a `linux/amd64` image with `REGISTRY_TOKEN`; Definition of Done is green on Gitea Actions, the Windows-only tests on a Windows runner or a Windows PC. |
| 2026-10-26 | Owner review 2, R1 | §19.3, §19.5, §19.6 | `:latest` follows the highest stable release, or the highest pre-release while none is stable, as decided by `Chronos.Tools release-channels` by SemVer 2.0 precedence; the releases repository's content and the update check still follow stable releases only; `:nightly` is the nightly build of `main`, never a release. |
| 2026-10-26 | Owner review 2, R2 | §14.4, §14.8, §14.9, §19.6 | `CHRONOS_SPACE_PATH` (`SpacePath`) names the volume whose free space the admin panel shows, the Unraid template mapping the share's array view `/mnt/user0/<share>` read-only to `/space`; the archive's own volume shows apart as *Write volume* when it differs; the figures' tooltip names the file system (`fuse.shfs` from mountinfo); completing an upload checks the archive's own volume first (507, resumable). |
| 2026-10-26 | Owner review 2, R4 | §12.1, §14.8 | The Settings icon is a toothed gear in Chronos, the Uploader and the admin panel; the admin panel docks Settings at the foot of its sidebar (the end of the top bar on narrow screens). |
| 2026-10-26 | Owner review 2, R5 | §12.1, §12.8, §12.9, §14.8 | About is the last page of the desktop Settings and the last group of the admin panel's Settings, no longer a rail or sidebar entry; nothing is offered twice (update check and releases on Updates, data folder and diagnostics on Advanced); `#/about` opens the admin Settings on About. |
| 2026-10-26 | Owner review 2, R9 | §12.4, §13 | Import › Folder… can group the folder as *Whole folder*: one sequence per file format whatever the cameras and pauses, titled after the folder, with a session key per PC, folder and format so a repeated import adds to the same sequence; desktop only. |
| 2026-10-26 | Owner review 2, R10 | §5, §6.2, §7, §12.5, §12.6, §12.8, §14.3, §14.6, §14.8, §14.9, §19.6 | Scheduled jobs: a Schedule entity (migration 0007, `jobs.schedule_id`) with an in-house recurrence form, a scheduler per host that claims runs by compare-and-set, with catch-up and DST rules; every timer that queued work is a visible system schedule (server: archive scan, upload clean-up every 6 h, index backup at 03:00, job history and audit log clean-ups; desktop: archive scan, daily index backup, housekeeping with cache trim), seeded once and kept as the user edits it; new Backup and Cleanup job kinds and duplicates/orphans report jobs; Jobs has Queue and Scheduled tabs on the desktop and the admin panel; `/api/v1/schedules` and the `scheduleChanged` event; one backup retention; the audit retention is the audit clean-up schedule's; Settings › Archive › Rescan every and the admin Settings' job history are gone; the trash is only reported, never emptied. |
| 2026-10-26 | Owner review 2, R11 | §12.8, §14.1, §14.3, §14.8, §14.9, §19.6 | Log settings: file and console levels apart on the server (`CHRONOS_LOG_LEVEL` locks both, `CHRONOS_LOG_CONSOLE_LEVEL` the console), retention, a file size limit with numbered parts, a total size limit, daily or hourly rotation, audit retention and the diagnostics share, in the admin panel's Settings › Logs (applied at once, `lockedBy` naming the variable) and the desktop's Settings › Advanced (from the first log line); the server's files take Debug and Trace when asked; logging never fails a job. |
| 2026-10-26 | Owner review 2, R6 | §5, §7, §12.2, §12.5, §14.3, §14.4, §14.5, §14.8 | The admin panel manages, never edits: a Library page (filters from facets, cards or list, keyboard selection, mass Analyse, Proxies, Thumbnails, Verify, Tags, Export CSV and Delete), a sequence's page with a photo viewer, cover, downloads and photo deletion, and the trash view with Restore and Empty; photos deleted into `trash/photos` under journals, a photo never hashed hashed as it goes, tombstones in the sidecar (`removed`) and the index (`frame_removals`, migration 0008) that keep sync and uploads from bringing a deleted photo back unless the user restores it or uploads it again on purpose; trash kinds, restore reasons, and Empty as the `empty-trash` job behind a dry run, a typed confirmation and a fingerprint, never scheduled; the library, trash and bulk endpoints; the panel's files revalidated (`no-cache`, ETag). |
| 2026-10-26 | Owner review 2, R3 | §14.3, §14.4, §14.8 | Upload from the admin panel into an existing or a new sequence (file picker, drag and drop, no folders), hashed in the browser by a self-tested in-house SHA-256 in a module worker, the capture time read from Exif, sent in resumable chunks through the upload API and verified by the server; `server/info` lists the photo extensions; hidden dot files are refused for every client. |
| 2026-10-26 | Owner review 2, R7 (Reorganize) | §5, §7, §12.2, §12.5, §12.8, §14.3, §14.5, §14.8 | Reorganize on the desktop (Archive manager, Library, the toast of Settings › Archive) and the admin panel (Library, the toast of Archive): folder, file and title templates applied to sequences already filed, behind a dry run that lists each sequence's changes, the photos that keep their names and why (in place outside `originals/`, never hashed, missing) and the sequences that stay whole (unreadable sidecar); applied by the `move` job of exactly the confirmed plan (fingerprint), which holds the rest when paused, cancelled or failed and lets a sequence still receiving photos keep its file names; crash-safe plan and file journals (two-phase renames through hidden temporary names, recovery by the next writer); a sequence of the plan left as it was inside a moving folder goes with it; the index, frames and exports follow a moved folder in one transaction, on this index and at another index's next scan; writers take the folder under the lease, never create a left one again and never write into a folder another sequence took; `POST /api/v1/archive/reorganize` with a kept, bounded plan cache and `sequenceChanged` `reorganized`; Rename… and Move… replaced. |
| 2026-10-26 | Owner review 2, R7 (naming) | §7.1, §13, §14.3 | One naming rule for import, upload and Reorganize: the sequence's camera and lens, `{n}` its place, a frame without a time at the sequence's start; template rules everywhere a template is typed or sent (no folder level scans skip, one a value such as a title gives escaped with `_`; a file template keeps the extension, tells photos apart, holds no slash; long names shortened before `.{ext}`; titles as text), held to a template only when it is given anew; `invalid_template` names the rule. |
| 2026-10-26 | Owner review 2, R7 (conversion) | §5, §7, §8.1, §8.3, §8.7, §9, §12.2, §12.4, §12.5, §13, §14.3, §14.4, §14.5, §14.8, §14.9 | Convert after import on the desktop (the Archive manager's set, the Library's selection) and the admin panel (the Library's selection): JPEG with a quality, TIFF-16 or linear DNG (the archival choice, scene-referred so a RAW's highlights above white and colours outside sRGB survive), Replace or New sequence chosen at every run and never remembered, behind a dry run that lists each sequence's photos, sizes and the photos that stay as they are with why, and the free space where the conversion writes; Replace confirmed by typing; the `convert` job (stored as 19) converts exactly the photos confirmed, one sequence at a time and all or nothing, resumable through its journals and staging, never twice at once; full-resolution decodes only (the managed decoders first, never a 16-bit file from an 8-bit RAW development; the server leaves what it cannot read to a PC), what Chronos reads from a photo never changed (profiles carried, a linear DNG of sRGB values only), Exif carried, every file verified by the server's decoders; Replace swaps the files of the frames in place under a crash-safe journal, the originals going into a replaced trash entry that Undo or Restore swaps back and that Empty erases only while the archive on disk shows each conversion intact, or deleted on its own word (a tombstone, the trash, an erasure record); import still copies byte for byte and the card keeps a converted photo's copy; sync and the ingest count every encoding of a photo as one; `POST /api/v1/archive/convert` with the plan cache it shares with Reorganize, `sequenceChanged` `converted` and `created`, the audit `archive_converted`. |
| 2026-10-26 | Owner review 2, R8 (phase 5a: workspace and projects, local home) | §4.4, §5, §7, §12.2, §12.3, §12.6, §12.8, §14.5, §14.6 | A sequence's home (this PC's archive) keeps its projects: Main, mirrored both ways with the sequence's settings so older clients and sync keep working, and other named projects, each a linear history of immutable versions in the portable form (positions parked by photo, SHA-256 of canonical text), stored as sidecars in `.chronos/projects/` and indexed by migration 0009 (`projects`, `project_versions`, `renders.project_id`/`project_version_id`); deletions only on the archive's word, the trash read first; Edit opens only workspace projects: *Open in workspace* (project, proxies), the `workspace-copy` job (stored as 20, desktop only, hash-verified, resumable, space checked), the working state in a folder outside the library, the project button with its state chip and menu (Save version, Sync, History with Compare and Restore, Open, New, Rename, Delete, Remove local copy), push and pull with replay and field-level merge, conflicts only when both sides changed a setting (Keep mine, Take library's, Save both, Later), renders at the home with the settings embedded; Settings › Workspace (folder, sync, kept versions). The server home is phase 5b; originals, local render, clean-up and the rest of Settings › Workspace are phase 5c. |
| 2026-10-26 | Owner review 2, R8 (phase 5b: server home) | §4.4, §7, §12.2, §12.3, §12.7, §14.3, §14.5, §14.7, §14.8 | A Chronos Server keeps its sequences' projects as a PC's archive does: `/api/v1/sequences/{sid}/projects` (list with Main made at the first read, create, rename, delete with the owner's, maker's or an admin's right, head, versions in size-capped pages, stored check, push with its outcome, frames and their stamp), the `projects` capability and `projectChanged`; settings written outside the projects become Main's version soon after, and a settings `PATCH` writes `project.json` under the lease; a sequence without photos keeps no projects; renders and render nodes take a project version's settings and record it; the admin panel's sequence page lists the projects (versions, Rename, Delete). The desktop opens a server sequence as a workspace project through its sign-in: *Open in workspace* on the Server screen and in Edit, proxies downloaded into the workspace (hash-checked, resumable), push and pull, conflicts, history and live state against the server, texts naming the server, renders and analyses on the server of the version it holds; an account without Edit and an older server keep *Open with proxies*. |
| 2026-10-26 | Owner review 2, R8 (phase 5c: originals, local render, clean-up, Workspace settings) | §4.4, §5, §12.3, §12.7, §12.8, §14.3, §14.5, §14.6 | Originals in the workspace on request (*Open in workspace* › Originals, *Copy originals…*, *Proxies only…* behind a plan), copied from either home hash-checked and resumable, a frame whose original is missing keeping its proxy; media index format 2 and project file format 3 while originals are held; a project with originals renders on this PC (`workspace-render`, stored as 21) into `exports/` with the ledger `renders.json`, *Version on render* saving a version first, and sends its renders home (`workspace-send`, 22) with their project and version, idempotent by render id, refusals per render; render uploads take optional `projectId` and `projectVersionId`, checked against the sequence (422 `project_mismatch`); *Pause metered transfers* holds every transfer with a server, downloads and workspace copies and sends included; originals judged by their bytes against the home's frames, those it lacks kept in the workspace's trash; the clean-up of media in step with their home (*Clean after*, *Size limit*, the `workspace-cleanup` schedule) and the workspace's trash emptied only by *Empty…* (typed count, fingerprint); Remove local copy weighs unsent renders and originals; moving the workspace folder (`workspace-move`, 23) behind a plan, renamed on one drive or copied and verified across drives, journaled, resumable, the source kept until the switch, with *Resume*; Settings › Workspace complete (Folder with Move…, Size limit, Default media, Sync, Version on render, Kept versions, Clean after, Open project, Trash). |
| 2026-11-04 | Owner review 3 (ports) | §12.7, §14.8, §14.9, §15, §19.6 | The public HTTP/HTTPS ports are server settings as well as variables (a variable locks them), applied at once; in a container the listening ports are locked to the template's; the admin panel's Network and TLS shows the container's ports, the public ports and the client address with Copy; clients read an address without scheme or port as port 8443 and report an address that answers as something else, never offering its certificate for trust; the Unraid template and compose gain *Public HTTP port*. |
| 2026-11-04 | Owner review 1, R5/R6 (phase 4: visual crop, transforms, looks) | §10.3, §11.2, §11.4, §12.3, §14.3, §14.7 | The crop is edited on the preview with handles, always locked to the output aspect, in the view frame (turned, straightened); the chosen proportions win: a fixed-size preset is a box the aspect is fitted in (4K at 9:16 = 2160×3840), "source" keeps the preset, the preset name stays and *Output size* shows the result; the Camera step gains Rotation (quarter turns), Mirror, Flip, Straighten (±15°, automatic cover zoom), Crop size/X/Y and Reset framing, the crop-margin and offset rows go; a turn or mirror keeps the content (crop, keyframes, a transposed aspect); the Exposure step ends with a Look (eight built-in colour looks with a strength), applied after stacking and before the knee; one Core path for render, server, nodes and preview; settings format 2 written only when a transform or look is used, read-only in older builds; `server/info` and node registrations announce the settings format, and nothing an older server or node would get wrong is sent to it; the advisor works on the view as shown. |
| 2026-11-05 | Owner review 1, R3/R8/R9 (phase 5: export panel and Render menu, export options, videos library) | §5, §7, §11.1, §11.3, §11.4, §11.5, §12.1, §12.3, §12.5, §12.8, §12.10, §14.3, §14.6, §14.7, §14.8, §14.9, §19.6 | The header's *Render ▾* reads "Render" at a fixed width, its tooltip giving the details, its menu the recommended, batch and recent presets, *Other presets ›* by group with a details line, *Render batch*, *Add to queue*, *Save frame ›* and *Videos*; the Export step's cards become a grouped preset table and its Output panel four collapsible groups (Output, Encoding, Playback, File) with summaries, open state kept by the app, and a fixed footer; advanced encoding (rate control, bit rate or quality, keyframes in seconds, B-frames, profile) and standard resolutions over the existing overrides, no format raise; playback (reverse, boomerang, loops, fades to black, hold at the end) as an output program, settings format 3 written only when used, read-only in older builds and never sent to an older server or node; *Save frame* saves one corrected frame as PNG, JPEG or TIFF 16-bit (kind `still`, format-3 jobs); renders record their SHA-256 and kind, copies are recorded (migration 0010); one Videos library on the desktop (a rail section on Ctrl+4, Archive, Jobs and Server moving to Ctrl+5…7; this PC's, the server's and unsent workspace renders merged; an in-process player) and on the admin panel (a Videos page with a browser player); a hash-verified `video-copy` job (stored as 24) into a flat videos folder (Settings › Archive, the server's `videosPath`, `CHRONOS_VIDEOS_PATH`, the optional `/videos` volume); delete into `trash/videos/` behind a dry run and fingerprint, restore with the same id after a hash check; `/api/v1/videos`, the `videos` capability, `RenderDto` `sha256` and `kind`. |
| 2026-11-06 | Owner review 1, phase 6 (deploy guide) | §14.9, §19.6 | The deploy guide `docs/deploy/` (Docker, Unraid, desktop) documents every `CHRONOS_*` variable with its default, the volumes, ports and public ports (host 8087/8444 → container 8080/8443 with Public HTTPS port 8444), TLS modes and the fingerprint, upgrades and migrations, backup and restore, PostgreSQL and troubleshooting, kept in step with the compose file, the Unraid template and the release's user guide; `CHRONOS_TRUSTED_PROXIES`, which the server already read, is listed in §14.9. |
| 2026-11-06 | Owner review 4, R1 (work board) | §12.10, §14.8 | Every video made or published in one board, the published ones apart from the work in a workspace: a third Videos layout *Board* (kept as the cards/list choice is) on the desktop and on the admin panel's Videos page, two lanes *Published* and *Workspace*, newest first, each with its count and the list's filters; a sent workspace render is in both lanes, its ledger row marked *Sent*; cards start with the preset; sizes keep number and unit together (issue #29). |
| 2026-11-06 | Owner review 4, R2 | §21 | Chronos sends nothing about its use: the usage counts consent is gone from the first run and from Settings › General (and its setting, an old settings file still loading), monetization counts no impressions; the diagnostics bundle is only saved locally. |
| 2026-11-06 | Owner review 4, R3 (archive structure) | §7, §12.8, §14.8, §14.9 | The archive's root-level folder tree (`.chronos` with `locks`, `journal`, `staging`, `trash`, `trash/photos`, `trash/videos`) is created inside the chosen archive path when an archive is created, adopted or opened, on the desktop and on the server, in Docker and on Windows; existing folders and files are never touched; a create whose tree cannot be made fails with the reason, an open logs and shows it (the dashboard's *Archive incomplete*, `/health` archive "incomplete"); Settings › Archive folder creates the archive in a folder that has none (issue #31). |
## Appendix A — `CLAUDE.md` content (create verbatim in Phase 0, keep updated)
```markdown
# Chronos — working rules
Read docs/BRIEF.md when in doubt; it wins over these notes.
- Zero <PackageReference>. Anything not in the .NET BCL / Microsoft shared frameworks / OS APIs is written here.
- No external processes at runtime (no ffmpeg, exiftool, powershell). Only OS dialogs listed in BRIEF §8.6.
- Chronos.Core / Data / Protocol / Server target net10.0 and build on Linux; Windows-only code lives in *.Windows or the desktop apps.
- English identifiers, comments, commits (Conventional Commits). Prototype in docs/reference is Italian: port algorithms, not language.
- Every UI string is a resource (en source, it translation). Labels ≤ 3 words; explanations only in tooltips; every actionable control has a tooltip; no helper paragraphs.
- Destructive operations: dry-run plan first, hash verification, explicit user action.
- When the brief is silent: choose the simplest safe option, log it in docs/DECISIONS.md, continue. Ask only at phase gates or before irreversible choices.
- Definition of Done per phase: CI green on Gitea Actions (the Linux jobs; the windows job once a Windows runner is registered, until then the Windows-only tests run on a Windows PC), tests green, no new warnings, DECISIONS + CHANGELOG updated, i18n check green, phase report with "how to try it".
- Build: dotnet build -c Release; tests: dotnet run --project tests/<X> -- --junit out.xml; tools: dotnet run --project src/Chronos.Tools -- <command>.
- Current phase and next steps: see docs/STATUS.md (update at every gate).
```
## Appendix B — Prototype module map (grep targets in `docs/reference/chronos-prototype.md`)
| Prototype (Italian) | New home | Notes |
|---|---|---|
| `Metadata/TiffDirectory, TiffPrimitives, MetadataReader, XmpScanner, FrameMetadata` | `Core/Metadata` | extend with BMFF/RIFF/RAF walkers, MakerNotes |
| `Imaging/WicInterop, ImageDecoder` | `Core.Windows/Wic` | keep pull-based scaling chain |
| `Imaging/ImageBuffer, ColorSpace, GeometryStage, RasterWriter, OrientationDetector` | `Core/Imaging` | RasterWriter → `Codecs/TiffWriter`, `LinearDngWriter` |
| `Analysis/*` (LuminanceAnalyzer, DeflickerEngine, RegionSegmenter, HolyGrailEngine, ExposureProcessor, ColorScience) | `Core/Analysis` | keep validated behaviour + tests |
| `Motion/*` (Fourier, PhaseCorrelator, GrayPyramid, OpticalFlowEngine, MotionField, MotionBlurRenderer, Stabilizer, VirtualCamera, TemporalStacker, FrameInterpolator) | `Core/Motion` | |
| `Core/Spline, LocalRegression, TimelapseSequence, FrameRecord` | `Core/Math`, `Core/Sequences` | |
| `Pipeline/RenderPlan, RenderPipeline, FrameWindow, AutoDirector, AutoOptimizer, SequenceWarnings` | `Core/Render`, `Core/Advisor` | AutoDirector/Optimizer → advisor rules with reasons |
| `Pipeline/MediaImporter, PathTemplate` | `Core/Import`, `Core/Naming` | tokens translated to English |
| `Video/MediaFoundationInterop, VideoEncoderSession, Nv12Converter, CodecLimits` | `Core.Windows/MediaFoundation` | add P010, AV1, capability enumeration |
| `Video/Mp4Muxer, BoxWriter, AnnexBParser, ExportPresets, ExportSettings` | `Core/Video`, `Core/Export` | add `av1C`, new presets |
| `Diagnostics/SelfTest, SyntheticSequence, SequenceDiagnostics, Mp4Inspector, Mp4Playback, AdvancedModuleTests, ExifWriter, IconGenerator, CrashGuard` | `tests/*`, `Chronos.Tools`, `Core/Diagnostics` | 63 checks → tests |
| `UI/*` (WinForms) | not ported | reuse only the interaction ideas (rail, preview tools, Auto indicator, presets) |
| `UI/SponsorPanel` | Phase 9 only | |
## Appendix C — Glossary
Sequence (a shoot: one folder of frames = one project) · Frame (one photo) · Hero frame
(thumbnail of the sequence) · Light/Deep analysis · Advisor (rule engine producing
recommendations with reasons) · Tier (how a frame's pixels are obtained) · Proxy (JPEG
stand-in) · Sidecar (`sequence.json` manifest) · Render (an exported video) · Preset
(bundle of export values) · Sequence preset (project settings + export preset produced by
the advisor) · Render node (client lending its GPU to the server) · Job (any long
operation, resumable) · Card profile (import rules for a memory card).