An archive open lists the pending rename plans; one journal that was not valid JSON threw out of ArchiveService.OpenAsync, so the archive (and the server, at boot) did not open until the file was removed by hand. It is now logged and left in place; its own job fails with the reason instead of planning again over a half-applied plan. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2241 lines
168 KiB
Markdown
2241 lines
168 KiB
Markdown
# 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 |
|
||
|
||
---
|
||
|
||
## 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).
|
||
- **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), 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).
|
||
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 (below; amended 2026-10-26, R7)
|
||
│ └── trash/ deleted sequences and photos, kept until Empty (below; amended 2026-10-26, R6)
|
||
├── 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")
|
||
│ ├── 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 or a restore a crash interrupted (below)
|
||
```
|
||
|
||
`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, reserved for R7 (read and written, nothing acts on it yet). 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). A photo never hashed is hashed as it goes; one
|
||
whose original was already missing goes with its record alone.
|
||
- `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.
|
||
- 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.
|
||
|
||
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.
|
||
- 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.
|
||
|
||
Rules: originals are immutable (never rewritten; edits are settings); 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 | managed (strips/tiles; none/PackBits/LZW/Deflate/JPEG) |
|
||
| 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).
|
||
- `PngDecoder`/`PngEncoder` (all colour types, 8/16-bit, Adam7 decode, filters, zlib via
|
||
`System.IO.Compression.ZLibStream`).
|
||
- `TiffReader`/`TiffWriter` (as prototype: 16-bit TIFF, linear DNG writer with
|
||
`PhotometricInterpretation=34892`).
|
||
- `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.
|
||
|
||
---
|
||
|
||
## 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: writes a minimal, valid Exif block.
|
||
|
||
---
|
||
|
||
## 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, 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).
|
||
|
||
### 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.
|
||
|
||
### 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.
|
||
|
||
### 11.4 Presets
|
||
|
||
Presets bind resolution, aspect, 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.
|
||
|
||
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.
|
||
|
||
### 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.
|
||
|
||
### 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 │
|
||
│ ▣ │ │
|
||
│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, 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").
|
||
- 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…, Upload, Download, Delete, Export list as CSV). Reorganize… (amended
|
||
2026-10-26, R7; formerly Move) takes the selected sequences of one archive, never a
|
||
server-only one, into the dialog of §12.5.
|
||
- 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).
|
||
|
||
### 12.3 Edit (amended 2026-10-16, R7; formerly "Sequence editor")
|
||
|
||
```
|
||
│ ← Harbour sunset ▾ · 3,600 frames · Canon EOS R5 · 2 s interval · 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.
|
||
- 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) with
|
||
luminance/waveform charts, **Motion** (blur, flow quality, stabilization) with shake
|
||
path chart, **Camera** (crop, aspect, virtual camera keyframes with a spline editor),
|
||
**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).
|
||
- 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"), 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.
|
||
|
||
### 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 Convert (•) Copy ( ) TIFF-16 ( ) Linear DNG ( ) JPEG │
|
||
│ │ 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`.
|
||
- 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…] [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).
|
||
|
||
*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.
|
||
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, with any folder around it that was to move with it. 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.
|
||
|
||
### 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.
|
||
|
||
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).
|
||
|
||
### 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; 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),
|
||
Formats (per
|
||
format tier on this PC, codec install links), 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.
|
||
|
||
---
|
||
|
||
## 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).
|
||
- 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
|
||
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)
|
||
|
||
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, …}
|
||
|
||
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)
|
||
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`.
|
||
- 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`); 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 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; 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 (the sequence held past the lease wait, the
|
||
archive offline or read-only, or the sequence's folder not where the index has it after
|
||
another program moved it) answers 503 and keeps the upload receiving, to be completed again
|
||
(`sequence_busy` and `archive_offline` for the first two); the node keeps its job. A proxy
|
||
upload answers 503 `sequence_busy` while the sequence is held, 404 `frame` when the sequence
|
||
or its folder is gone.
|
||
|
||
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).
|
||
|
||
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).
|
||
|
||
### 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.
|
||
|
||
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)
|
||
counts as its replacement on both sides, an alias followed up to 8 steps, for the
|
||
comparison, the transfers and the frame positions. 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.
|
||
|
||
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). Until that scan nothing writes into the old place, which would
|
||
create it again: *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 the editor's saves, a render job as it
|
||
starts, exports fetched by sync and a proxy pass at each batch; a deep analysis that loses its
|
||
folder records nothing. A render of the other program whose folder moves while it runs is not
|
||
stopped.
|
||
|
||
### 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.)
|
||
|
||
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) and `housekeeping` (daily 04:00,
|
||
catch-up: `job-history` 90 days and `cache-trim`). 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.
|
||
|
||
### 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) · 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)). A field an environment
|
||
variable fixes is read-only, its tooltip naming that variable (`lockedBy`, §14.3; R11). 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).
|
||
- `#/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.
|
||
|
||
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".
|
||
|
||
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),
|
||
`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`, `CHRONOS_TLS_MODE=auto|pem|proxy`,
|
||
`CHRONOS_TLS_CERT`, `CHRONOS_TLS_KEY`, `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),
|
||
`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), `HEALTHCHECK` on
|
||
`/health`, `linux/amd64` + `linux/arm64`. `docker-compose.yml` with a PostgreSQL 17 service.
|
||
Windows: `Chronos.Server.exe` runs as console or Windows Service (`sc create`), SQLite or
|
||
PostgreSQL.
|
||
|
||
---
|
||
|
||
## 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), 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.
|
||
|
||
---
|
||
|
||
## 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.
|
||
- Consent: first-run one-line choice for anonymous impression counting (off by default);
|
||
when on, a daily aggregated ping (version, language, country from OS locale, counts) —
|
||
no identifiers. 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); 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 and never create a left one again; `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. |
|
||
|
||
## 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).
|