The docs now describe mass conversion after import as the code at 48a0ce3e does it:
Replace or New sequence chosen at every run, the dry run and the convert job of
exactly the confirmed photos, the scene-referred linear DNG, the replaced trash
entries with their Undo and emptying, and sync and ingest counting every encoding
of a photo as one. Four earlier DECISIONS rows are marked superseded in part.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit c746fe689c7bf16a3b5c28ea7694d91cf423f4a9)
2525 lines
194 KiB
Markdown
2525 lines
194 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; convert,
|
||
stored as 19, a conversion of exactly the photos a confirmed plan lists, its targets the
|
||
sequences, each converted all or nothing into its own frames or a new sequence: amended
|
||
2026-10-26, R7), 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; convert-<job>.json, .staged, .pins: a conversion (below; amended 2026-10-26, R7)
|
||
│ ├── staging/ copies an import is filing; convert-<job>/<sequence>/: the files a conversion made, until they take their place (below; amended 2026-10-26, R7)
|
||
│ └── trash/ deleted sequences and photos, and originals a conversion replaced, kept until Empty (below; amended 2026-10-26, R6, R7)
|
||
├── 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, a frame replacement (replace.pending.json, a conversion or its undo; amended 2026-10-26, R7) 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: a conversion's Replace writes it, and its undo and a conversion job that resumes read it
|
||
(amended 2026-10-26, R7). A build that does not know either field keeps it and writes it back
|
||
unchanged.
|
||
|
||
Trash (amended 2026-10-26, R6). Nothing in it is erased except by *Empty* (§12.5, §14.8):
|
||
- `trash/<id>[-<time>[-n]]/` with `<name>.json` beside it: a deleted sequence folder, whole
|
||
(originals, proxies, exports, sidecars), and its record (the index row, renders and
|
||
tombstones the sidecar may lack).
|
||
- `trash/photos/<id>-<time>[-n]/originals/…` with `<name>.json` beside it: photos deleted
|
||
from sequence `<id>`, each original with its XMP companion when no photo that stays shares
|
||
it, and the record: each photo's frame record, each file's former place, size and SHA-256,
|
||
the sequence's title and folder, who deleted them, when, and the kind (photos, or replaced
|
||
for originals a conversion replaced, R7: such an entry also keeps each photo's replacement
|
||
SHA-256, a copy of the sequence's `analysis.json` and the job that made it). A photo never
|
||
hashed is hashed as it goes; one whose original was already missing goes with its record
|
||
alone.
|
||
- `trash/.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.
|
||
- A replaced entry (amended 2026-10-26, R7) goes back by a swap: while every converted frame
|
||
still holds its conversion (re-hashed) and names the original as its `source`, the originals
|
||
take their frames' place again as a Replace does (below), the converted files going into a
|
||
replaced entry in turn and the entry's `analysis.json` back into the sequence; otherwise the
|
||
originals come back as a new sequence. *Empty* erases it only while each conversion of its
|
||
originals still hashes to its SHA-256 where the archive shows it now; of a conversion deleted
|
||
since, every copy the trash still holds must hash to it, and with none left nothing keeps the
|
||
entry. The archive is asked, never this host's index alone: the sequence's sidecar where the
|
||
index or the entry says it is, in the trash, or found by walking the archive's folders,
|
||
followed through its replaced tombstones. A conversion counts as deleted only when the
|
||
sidecar shows it (a deleted tombstone, or its frame gone while every frame is hashed and no
|
||
photo of the folder is unlisted), when the sequence is in the trash, or when no sidecar of it
|
||
exists and the index has no row of it; whatever the archive cannot tell keeps the entry.
|
||
|
||
Deleting photos writes the sidecar without them (frames version + 1) and with a tombstone of
|
||
each SHA-256 no photo that stays holds, and clears what covered the frames (light and deep
|
||
analysis, thumbnails, proxies), which follow as jobs; proxies are renamed and `thumbs.pack`
|
||
is re-keyed so the frames that stay keep theirs (while a thumbnail pass holds the pack, that
|
||
pass draws them again). Filing a photo into the sequence again (an import, a restore, an
|
||
explicit upload again, §14.4) drops its tombstone; emptying the trash does not.
|
||
|
||
Reorganize (amended 2026-10-26, R7; §12.5, §14.8) applies a confirmed plan step by step, a
|
||
step being one sequence and the sequences nested in a folder that moves with it:
|
||
- `journal/rename-<plan>.json` holds the plan (its steps, templates and the sequences it was
|
||
made for), the steps completed and what they did; it is written before the first step and
|
||
deleted after the last. A plan whose job was paused, cancelled or failed is marked held and
|
||
waits for that job; any other is completed at the next archive open. A journal that cannot be
|
||
read is logged and left where it is: the archive opens, the plan is not resumed and its job
|
||
fails with the reason.
|
||
- Each step takes the leases of its sequences, then their thumbnail leases, and checks under
|
||
them, before anything of it moves, that the plan still fits: the sequences where the index
|
||
had them, nothing indexed since inside a folder that moves or at its new place, no sidecar of
|
||
a newer format to rewrite, the title the plan started from where it changes the title or
|
||
names the folder or files after it, the folder and title the templates give from the first
|
||
photo as it is now, and the file renames planned again from the sidecar (compared by digest).
|
||
What no longer fits refuses the rest of the plan, except photos changed since, whose
|
||
sequence keeps its names (§12.5).
|
||
- Then the folder moves (a change of case only through a temporary name, never onto another
|
||
folder of that exact name), and in one transaction the index follows: the sequence's folder
|
||
and title, its frames' paths and the paths of the exports that moved with the folder. Only
|
||
then are files renamed; once its folder moved, a step always goes to its end.
|
||
- A sequence of the plan that an earlier step left as it was inside a folder that moves later
|
||
(it changed after the plan, or the folder that was to carry it stayed) goes with that folder,
|
||
under the same leases, keeping its title and file names. Before a held plan resumes, a folder
|
||
that moves may hold only such sequences and those of the steps still to come; any other
|
||
refuses the plan, which is then given up.
|
||
- File renames run under `rename-files.json` in the sequence's `.chronos/`: every file first to
|
||
a hidden temporary name beside it (`.chronos-rename-<token>-<n>.tmp`), then every file to its
|
||
new name, so chains and swaps of names never meet a name another file holds and no file is
|
||
ever written over; then the sidecar names the new files (frame order and ids unchanged,
|
||
frames version + 1), then the index, then the journal goes. A failure while files move puts
|
||
every file back. After a crash the next writer of the sequence (any `ReadLocked`, the plan's
|
||
resume) completes the renames, safely run again from wherever it stopped: a new name taken
|
||
meanwhile sends that photo and its companions back together to their old names, or to the
|
||
first free `_2`, `_3`…, and the journal stays while a temporary file is left.
|
||
- Proxies (named by frame index), thumbnails (by index and content hash), tombstones and trash
|
||
records need nothing; a photo restored from the trash comes back under the name it had.
|
||
|
||
Conversion (amended 2026-10-26, R7; §8.7, §12.5, §14.8) writes over no original: Replace
|
||
moves each original into the trash, New sequence leaves it where it is.
|
||
- A `convert` job takes one sequence at a time. Under the sequence's lease, its sidecar settled
|
||
where the index has it then, it plans the sequence again and goes on only while the photos the
|
||
confirmed plan listed are there with the content confirmed; it pins them in
|
||
`journal/convert-<job>.pins` and from then on, a retry included, converts those alone, so
|
||
photos received or verified since stay as they are. A sequence another index moved away (its
|
||
folder gone, or holding another sequence) is left for the retry after this index's scan.
|
||
- Stage A, without the lease: each original is re-hashed against its record, converted and
|
||
verified (§8.7) into `staging/convert-<job>/<sequence>/`, several at once, and each staged file
|
||
is appended to `journal/convert-<job>.staged`; `journal/convert-<job>.json` records what each
|
||
sequence came to and whether the passes it needs were queued. A resumed or retried job keeps
|
||
the staged files whose SHA-256 still verifies, settles a replacement a crash left half-way,
|
||
and takes a sequence it had replaced already as converted.
|
||
- Stage B, under the lease and while every photo pinned still holds its content, all or
|
||
nothing: Replace swaps the files of the frames (next point); New sequence files the converted
|
||
copies into a new sequence through the archive ingest (§12.5).
|
||
- A Replace, and the undo of one, writes `replace.pending.json` in the sequence's `.chronos/`
|
||
first. Each swapped frame's original and its XMP companions go into one trash entry of kind
|
||
replaced; each converted file comes in under the name filing gives a photo of the sequence
|
||
(§7.1, with the target's extension), never onto a file there, those leaving included (`_2`…).
|
||
The frames keep their ids and indices; each record takes the converted file's size, SHA-256,
|
||
format, upright size and full-resolution tier, orientation 1, no preview, the flags of that
|
||
file and those the user set, and a `source` naming the original. The sidecar (its frames
|
||
version one higher, analyses, thumbnails and proxies cleared) gains a replaced tombstone per
|
||
original naming its replacement, and content that comes back loses its tombstone; then the
|
||
index follows, the proxies of the swapped frames are deleted and the passes the frames need
|
||
are queued. The journal records its phase (moving, written, undoing) and each frame's new
|
||
name: the next writer of the sequence completes a replacement whose sidecar lists a new name
|
||
and undoes any other, and an undo that fails stops that writer, as a deletion's recovery
|
||
does. Every writer that changes the frames (an ingest, a deletion, a restore, a Reorganize
|
||
step, a sequence deletion) settles it first, or waits while it cannot be settled yet (the
|
||
trash entry an undo takes its files from is busy); a scan settles it too, and reconciles
|
||
nothing in the folder while it stays.
|
||
- The job's journals and staging go once every sequence is final. Maintenance keeps a job's
|
||
staging while the job is queued, running or paused, removes it at once when the job is done
|
||
and otherwise once its files are a day idle, and removes the journal when the job is done. A
|
||
job this index does not know (another host's on a shared archive) keeps both while any of
|
||
their files was written within 90 days, then both go.
|
||
|
||
Rules: originals are immutable (never rewritten; edits are settings; a conversion takes an
|
||
original out of its sequence only into the trash, amended 2026-10-26, R7); every write of a
|
||
sidecar goes to a temp file, `fsync`, rename; the folder name is derived from templates at
|
||
import time and never auto-renamed afterwards: only Reorganize, an explicit user action
|
||
behind a dry run, moves and renames what is filed, updating sidecars and DB together
|
||
(amended 2026-10-26, R7). Network drives: UNC or mapped paths; long-path aware
|
||
(`\\?\` prefix); no `FileSystemWatcher` reliance — periodic polling by mtime/size (the
|
||
*Archive scan* system schedule of each host, §14.6; amended 2026-10-26, R10) plus manual
|
||
rescan; offline detection with graceful read-only state.
|
||
|
||
### 7.1 Naming templates
|
||
|
||
`FolderTemplate` default `{year}/{date} {camera}`; `FileTemplate` default
|
||
`{date}_{time}_{n:0000}`. Tokens (localised descriptions in resources): `year, month, day,
|
||
date, time, hm, session, sessionstart, camera, lens, iso, shutter, aperture, n, nsession,
|
||
name, ext, title`. `{token:format}` passes the format to the .NET formatter. Illegal
|
||
characters are replaced, never passed through; templates are validated live in the UI with a
|
||
preview of the first three names.
|
||
|
||
One naming rule for import, upload and Reorganize (amended 2026-10-26, R7):
|
||
- A photo is named in its sequence with the sequence's camera and lens (its first photo's, or
|
||
the camera hint its creator gave): a second body in a whole-folder import, or a lens changed
|
||
during a session, does not show in the names. `{n}` is its place in the sequence, `{name}`
|
||
its name on the card, `{ext}` its file's extension (the card name's when the file lost the
|
||
extension of a photo), and a frame recorded without a capture time takes the sequence's
|
||
start (its first frame's time, else when it was made; never today's date). A name already
|
||
given, or held by a file that stays, gets `_2`, `_3`… before the extension. Folder and title
|
||
templates see the sequence's first photo as filing saw it.
|
||
- So a Reorganize with the archive's own templates changes nothing filing named. It gives
|
||
other names, which its dry run lists, where filing could not know the sequence as it is now:
|
||
`{session}` of a card's second session on (an import numbers its sessions, a sequence is
|
||
one), `{n}` after photos skipped mid-session as duplicates or filed out of capture order, and
|
||
a folder or title from a photo that is no longer first.
|
||
- Rules every template meets wherever it is typed or sent (Settings › Archive, Import,
|
||
Reorganize, the admin panel's Archive): a folder template may not write a level scans never
|
||
enter (starting with `.`, or `originals`, `proxies`, `exports`, `.chronos`); a file template
|
||
must keep the photo's extension (appended, or after `.{ext}`: `{n}{ext}` is refused), tell
|
||
the photos of a session apart (three sample photos two seconds apart must get three names)
|
||
and hold no slash. A level a value such as a title would hide that way is written with a
|
||
leading `_`. A file name longer than 200 characters is shortened before its `.{ext}`, never
|
||
through it. A title template gives text, not a file name (`Paris: night` stays), at most 200
|
||
characters. A template `archive.json` already holds, saved before these rules, is kept
|
||
through edits of other settings; changing it holds it to them, and a new archive meets them all.
|
||
|
||
---
|
||
|
||
## 8. Image pipeline
|
||
|
||
### 8.1 Supported input formats
|
||
|
||
| Family | Extensions | Metadata (in-house) | Pixels on Windows | Pixels on server (Linux) |
|
||
|---|---|---|---|---|
|
||
| JPEG | jpg jpeg jpe jfif | APP1 Exif/XMP, MPF | WIC or managed | managed (baseline + progressive) |
|
||
| PNG | png | eXIf, iTXt XMP | WIC or managed | managed |
|
||
| TIFF | tif tiff | IFDs | WIC or managed | managed (strips/tiles; none/PackBits/LZW/Deflate/JPEG; gray, RGB and linear RAW samples only: a CMYK, CIELab or palette TIFF is unavailable, never read as gray; amended 2026-10-26, R7) |
|
||
| DNG (smartphones: Apple ProRAW, Android, Samsung; DJI; Insta360; Leica; Pentax; Ricoh; GoPro files converted by Adobe software) | dng | IFDs, MakerNote | managed full decode (amended 2026-10-16, R4) | managed full decode |
|
||
| Canon | cr2 cr3 | cr2: TIFF; cr3: ISO-BMFF `CMT1..4` | WIC (Raw ext.) → managed CR2 (P1) → embedded preview | managed CR2 (P1) → embedded full-size JPEG (CR3 track 1) |
|
||
| Nikon | nef nrw | TIFF | WIC → managed NEF (P1) → preview | managed NEF (P1) → preview |
|
||
| Sony | arw srf sr2 | TIFF | WIC → managed ARW (P1) → preview | idem |
|
||
| Fujifilm | raf | RAF header + TIFF | WIC → managed RAF uncompressed (P1) → preview | idem |
|
||
| Olympus/OM, Panasonic, Pentax, Samsung, Hasselblad, Phase One, Leica | orf rw2 raw pef srw 3fr fff iiq rwl | TIFF-like | WIC → managed (P1/P2) → preview | preview (P1: managed decoders as feasible) |
|
||
| GoPro | gpr (DNG+VC-5; a DNG is GPR only when its raw image is VC-5, amended 2026-10-16, R4) + jpg sidecar | IFDs | preview/sidecar JPEG; VC-5 out of scope | sidecar JPEG |
|
||
| HEIF/HEIC/AVIF (iPhone, Samsung, DJI) | heic heif hif avif | ISO-BMFF `Exif` item | WIC (HEIF + HEVC/AV1 extensions) | metadata only; pixels via client-made proxies |
|
||
| WebP | webp | RIFF `EXIF` chunk | WIC (WebP ext.) | metadata only (P2: managed VP8L) |
|
||
| JPEG XL, JPEG XR, BMP, GIF (single frame) | jxl jxr bmp gif | minimal | WIC if a codec exists | not supported |
|
||
|
||
Windows codec availability is enumerated at startup (`IWICImagingFactory::
|
||
CreateComponentEnumerator`). Missing codecs are surfaced as a one-line notice with an
|
||
"Install" button opening the Microsoft Store page (Raw Image Extension, HEIF Image
|
||
Extension, HEVC Video Extensions, AV1 Video Extension, WebP Image Extension; verify product
|
||
IDs at implementation time). The format table in Settings › Formats shows, per format,
|
||
which tier will be used on this machine.
|
||
|
||
### 8.2 Decode tiers (deterministic, logged per frame)
|
||
|
||
1. **Native full decode** (in-house or WIC) at working resolution, 16-bit linear light.
|
||
2. **Embedded preview** (largest JPEG found: TIFF `JPEGInterchangeFormat`/SubIFD strips,
|
||
RAF preview, CR3 full-size JPEG track, MPF). Marked `PreviewOnly` on the frame; the
|
||
sequence shows a chip with the count and the advisor caps output resolution to the
|
||
preview size unless the user overrides.
|
||
3. **Unavailable** → frame flagged `Undecodable`; excluded from render; listed in the
|
||
sequence warnings.
|
||
|
||
The tier is what the frame can give. Analyses, thumbnails, proxies and the editor's preview
|
||
take an embedded preview that is large enough when a RAW has one, by choice and without
|
||
changing the frame's tier; renders always decode natively. WIC counts as a native RAW
|
||
decoder only when the decoder it chose for the file is the Raw Image Extension (Windows'
|
||
in-box DNG decoder reads only the preview). (Amended 2026-10-16, R4.)
|
||
|
||
The in-house DNG pipeline (server and client): CFA/linear DNG, `Compression` 1/7 (lossless
|
||
JPEG SOF3)/8 (Deflate)/34892 (lossy JPEG), `LinearizationTable`, `BlackLevel` (+ repeat
|
||
dims, delta), `WhiteLevel`, `AsShotNeutral`/`AsShotWhiteXY`, `ColorMatrix1/2` +
|
||
`CameraCalibration`, `AnalogBalance`, Bradford adaptation to D65, demosaic **AHD** (default,
|
||
"perfect result" priority) with bilinear for Draft quality, highlight reconstruction (clip
|
||
+ desaturate), `ActiveArea`/`DefaultCrop*`, `Opcode` lists 1–3 (at least `GainMap`,
|
||
`WarpRectilinear`, `FixVignetteRadial`; unknown opcodes ignored with a warning),
|
||
`BaselineExposure`. Output: linear Rec.709/sRGB primaries float planes.
|
||
|
||
### 8.3 Managed codecs (all in `Chronos.Core/Codecs`, pure C#, SIMD where it pays)
|
||
|
||
- `JpegDecoder` (baseline, progressive, restart intervals, 4:4:4/4:2:2/4:2:0/4:1:1/gray,
|
||
12-bit optional, ICC ignored), `JpegEncoder` (baseline, quality 1–100, subsampling
|
||
choice, optimised Huffman tables optional, Exif/XMP APP1 embedding, an ICC profile in APP2
|
||
chunks: amended 2026-10-26, R7).
|
||
- `PngDecoder`/`PngEncoder` (all colour types, 8/16-bit, Adam7 decode, filters, zlib via
|
||
`System.IO.Compression.ZLibStream`).
|
||
- `TiffReader`/`TiffWriter` (as prototype: 16-bit TIFF, an ICC profile in tag 34675, linear DNG
|
||
writer with `PhotometricInterpretation=34892`, scene-referred for a conversion, §8.7: amended
|
||
2026-10-26, R7).
|
||
- `IccProfile` (amended 2026-10-26, R7): ICC profiles read and written (matrix/TRC and gray,
|
||
`curv`/`para` curves, `desc`/`mluc` text), an in-house Adobe RGB (1998)-compatible and a
|
||
Display P3 profile, and what a photo's headers say of its colour space (JPEG APP2, PNG
|
||
iCCP/sRGB, TIFF tag 34675, HEIF/AVIF `colr`, WebP ICCP, Exif ColorSpace and Interop).
|
||
- `GifEncoder` (animated; median-cut palette + Floyd–Steinberg; frame differencing).
|
||
- `ApngEncoder`.
|
||
- `AviMjpegWriter` (RIFF AVI with `MJPG`, OpenDML index for > 2 GB).
|
||
- `Mp4Muxer` (port of prototype: streaming `ftyp`/`mdat`/`moov`, 90 kHz timescale,
|
||
variable durations, `avcC`/`hvcC`; add `av1C` + OBU handling in P1), `AnnexBParser`.
|
||
- `Bmff` reader (HEIF/CR3/AVIF boxes), `Riff` reader (WebP/AVI), `Raf` reader.
|
||
|
||
### 8.4 Image buffers
|
||
|
||
Port the prototype's `ImageBuffer`/`FrameBufferPool` (pooled float planes, linear light),
|
||
`FrameWindow` (sliding window, disk spill under a memory budget, read-ahead), and
|
||
`GeometryStage` (crop/aspect/affine with Catmull-Rom). Memory is governed by the window
|
||
size and budget, never by sequence length; the self-tests assert this.
|
||
|
||
### 8.5 Thumbnails and proxies
|
||
|
||
- Thumbnail: 320 px long edge JPEG q80, packed per sequence in `thumbs.pack` (header,
|
||
index table, entries), with an LRU in-memory cache and async loading for the UI.
|
||
- Proxy: JPEG at policy long edge (default 1920; options 1280/1920/2560/full), q92, Exif
|
||
orientation applied, capture time copied into Exif. Proxies are optional and regenerable;
|
||
they enable remote editing, server-side rendering of formats the server cannot decode,
|
||
and fast scrubbing.
|
||
|
||
### 8.6 The only OS executables/dialogs the product may invoke
|
||
|
||
`SHFormatDrive` (format card), `ShellExecute("open", url)` (links, Store pages),
|
||
`ShellExecute("explore", folder)` (reveal in Explorer). Nothing else.
|
||
|
||
### 8.7 Conversion (amended 2026-10-26, R7; §7, §12.5)
|
||
|
||
A conversion makes each photo a JPEG (baseline, 4:4:4, optimised Huffman tables, 8-bit,
|
||
quality 1–100, default 95), a 16-bit TIFF (RGB, Deflate with the predictor) or a linear DNG
|
||
(16-bit LinearRaw, lossless JPEG tiles), the archival choice.
|
||
- Decoding: at full resolution only, never from an embedded preview, upright. The managed
|
||
decoders come first for every format they read natively (a RAW developed in-house at float
|
||
precision, the same on every host), WIC only for what they do not read. A 16-bit target never
|
||
takes a RAW through a decoder that develops it at 8 bits (WIC's Raw Image Extension): such a
|
||
RAW converts to JPEG only. The server decodes with the managed decoders alone, so it converts
|
||
no CR3, HEIC or RAW body its developer does not support, nor a CMYK, CIELab or palette TIFF,
|
||
an unsupported compression or a file past their size limits: its dry run says to convert
|
||
those photos on a PC, which reads them through WIC.
|
||
- A linear DNG keeps what a RAW develops: the values are stored in linear ProPhoto primaries
|
||
(colours outside sRGB stay positive), divided by the power of two, at most 2^4, that brings
|
||
their peak under white, which BaselineExposure gives back; ColorMatrix1 and ForwardMatrix1
|
||
describe that space (illuminant D65, AsShotNeutral 1/1/1). The as-shot white balance is baked
|
||
in and values below black are clipped. An export's DNG stays clipped linear sRGB (§11.3).
|
||
- Colour: the colour space the original's values are in is kept. A JPEG or TIFF carries the
|
||
original's ICC profile with its code values unchanged (a float TIFF's linear values are coded
|
||
with the profile's own curves); a DNG gets the values converted through a matrix/TRC profile
|
||
(an sRGB one, told by its numbers, needs nothing); a gray profile converts to sRGB. Exif Adobe
|
||
RGB (uncalibrated with Interop R03) and a HEIF nclx box with P3 primaries get the in-house
|
||
profiles. A space none of that keeps (CMYK, Lab, a lookup-table profile into a DNG, Exif
|
||
uncalibrated without R03, other nclx primaries or an HDR transfer, a profile that does not
|
||
parse) is not converted. A photo that records none is sRGB.
|
||
- Metadata: capture time (to the tick), offset, exposure, f-number, ISO, focal length, bias and
|
||
white balance from the sidecar; camera, serial, lens, 35 mm focal length, exposure program,
|
||
metering mode, flash, GPS, artist and copyright from the original, the sequence's camera and
|
||
lens where it names none. MakerNote and XMP are not carried; the orientation is 1.
|
||
- Size: a photo is not converted when the target cannot hold it (a JPEG side above 65535) or
|
||
the server's decoders could not read it back (a JPEG above 2^28 pixels; a TIFF-16 or DNG
|
||
above 2^29 samples, about 179 MP).
|
||
- Each converted file is hashed as it is made and written atomically, then read back (the same
|
||
size and SHA-256), its metadata read again (format, capture time and offset) and decoded by
|
||
the server's decoders at full resolution and size; a file that fails any of these is deleted
|
||
and its photo fails.
|
||
|
||
---
|
||
|
||
## 9. Metadata model and parsers (`Chronos.Core/Metadata`)
|
||
|
||
Port and extend the prototype's binary parsers: container detection by signature; JPEG
|
||
segment scan (APP1 Exif, APP1 XMP + extended XMP, APP2 MPF); TIFF/IFD walker with on-demand
|
||
window reads (never load a whole RAW to read tags), SubIFD selection of the main image,
|
||
`0x02BC` XMP; ISO-BMFF walker (`meta/iinf/iloc` Exif item, CR3 `CMT` boxes, `PRVW`/`THMB`,
|
||
track sample tables for the CR3 JPEG); RIFF; RAF; PNG chunks. MakerNote parsing only where
|
||
it adds value: Canon/Nikon/Sony/Fuji/Olympus/Panasonic body serial, shutter count, lens
|
||
name, exposure mode, image stabilisation flag, intervalometer hints, sRaw flags.
|
||
|
||
Fields extracted per frame: DateTimeOriginal + SubSecTimeOriginal + OffsetTimeOriginal
|
||
(fallback: CreateDate, GPS time, file mtime — recorded with `TimestampSource`), ExposureTime,
|
||
FNumber, ISO, FocalLength (+35 mm equiv), ExposureBias, ExposureProgram, MeteringMode,
|
||
WhiteBalance mode + Kelvin if present, Flash, Orientation, dimensions, Make/Model/BodySerial,
|
||
Lens, GPS (lat/lon/alt), Artist/Copyright, Rating/Label from XMP, `Software`. All parsers
|
||
are fuzz-safe (no exception escapes; malformed input yields partial metadata + a warning).
|
||
|
||
`ExifWriter` (prototype) is kept for proxies, exports and converted photos: writes a minimal,
|
||
valid Exif block, with the exposure program, metering mode, flash and white balance when known
|
||
(amended 2026-10-26, R7).
|
||
|
||
---
|
||
|
||
## 10. Analysis advisor
|
||
|
||
Two passes; both deterministic, both explainable (every finding and every recommendation
|
||
carries a resource key + parameters that render as a localised reason in tooltips).
|
||
|
||
### 10.1 Light analysis (at import/scan, metadata only, seconds per 10k frames)
|
||
|
||
Cadence (median interval, jitter, gaps → session boundaries; `SessionGapMinutes` default
|
||
45, `MinimumSessionFrames` 8), total capture span, exposure series (EV =
|
||
log2(N²/t) − log2(ISO/100)), exposure step detection (ISO/shutter/aperture changes and
|
||
their EV amplitude), camera/lens identity, orientation consistency, resolution
|
||
consistency, timestamp sanity (clock resets, duplicates, non-monotonic), format tiers,
|
||
GPS → sunrise/sunset/civil twilight via an in-house solar-position calculation (NOAA
|
||
algorithm) → day/night/transition labelling.
|
||
|
||
### 10.2 Deep analysis (background job after import; "speed is not an issue")
|
||
|
||
Every frame decoded at analysis width (default half native, capped 2048): per-frame
|
||
trimmed log-luminance mean, histogram, clip fractions, per-channel means (WB drift), colour
|
||
temperature where applicable (McCamy with Planckian-locus validity check), sharpness
|
||
(Laplacian variance), noise estimate, phase-correlation shift vs previous frame (shake
|
||
magnitude, drift → panning), region mask (horizon by strongest row-luminance step, refined
|
||
per column; fallback by luminance), flicker spectrum (autocorrelation of luminance
|
||
residuals → deflicker window), exposure steps *as actually received* by the pixels,
|
||
star-field detection (small bright point density on night frames), cloud coverage estimate
|
||
(sky-region texture), scene-change detection (histogram distance), duplicate/black/white
|
||
frames, motion magnitude histogram (for motion-blur recommendation), suggested hero frame.
|
||
Results → `analysis.json` + compact summary in DB; charts in the Edit section (§12.3; amended 2026-10-16, R7).
|
||
|
||
### 10.3 Recommendations (rules, each with reason and confidence)
|
||
|
||
- Frame timing mode: Constant when jitter < tolerance; Adaptive when the intervalometer
|
||
paused deliberately; Interpolated when gaps are sparse and motion is smooth.
|
||
- Frame rate and time compression: choose 24/25/30/60 fps and duration targets from cadence
|
||
and motion magnitude; offer "fit to N seconds".
|
||
- Motion blur target shutter angle: from measured shutter angle (360×exposure/interval) and
|
||
motion magnitude; skip flow when exposure already exceeds the target.
|
||
- Deflicker window (4× flicker period), region deflicker when horizon confidence is high,
|
||
holy-grail transition length (half the typical distance between exposure steps), WB
|
||
smoothing, stabilization on/off (measured shake > 0.3 px) with crop cost, crop/aspect
|
||
suggestions from subject placement, 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…, Convert…, Upload, Download, Delete, Export list as CSV). Reorganize… (amended
|
||
2026-10-26, R7; formerly Move) and Convert… (amended 2026-10-26, R7) take the selected
|
||
sequences of one archive, never a server-only one, into their dialogs of §12.5; a selection
|
||
of two archives is refused with the reason.
|
||
- Filters are chips; saved views (e.g. "Night, 4K, not rendered"); search is instant
|
||
(indexed columns); everything virtualized (in-house `VirtualizingWrapPanel`).
|
||
- Photos deleted from a sequence (amended 2026-10-26, R6; on the admin panel, §14.8, or by
|
||
another program sharing the archive) leave it at its next index sync: its count follows,
|
||
a cover whose photo went is cleared, the project's positions on those photos (exclusions,
|
||
hero, keyframes) wait as pending frames until a restore brings the photos back, and the
|
||
others follow their photos without a settings edit. *Delete…* still moves whole sequences
|
||
into the archive's trash, which lists photo entries too (§12.5).
|
||
|
||
### 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 │
|
||
│ │ After import (•) Keep card ( ) Delete imported ( ) Format card [✓] Eject [✓] Deep analysis │
|
||
│ [✓] Import automatically when │ Plan 3 sessions · 4,812 photos · 96.2 GB · 12 min [Show plan] [ Import ▶ ] │
|
||
│ a known card is inserted │ │
|
||
```
|
||
|
||
- Devices list: removable volumes and any volume with `DCIM`; identity = volume serial +
|
||
label + capacity, camera identity from the first file; known cards show their nickname
|
||
and profile; unknown cards prompt for a nickname (one field).
|
||
- Plan before touching disk: sessions, folders to be created, first three file names,
|
||
duplicates already in the archive (by hash), disk space check.
|
||
- A picked folder (`Folder…`, and Archive › Adopt folder › Copy into archive…) adds a
|
||
**Group** row: *Sessions* (as for a card) or *Whole folder* (amended 2026-10-26, R9).
|
||
Whole folder makes the folder (its subfolders too while Subfolders is on) one sequence
|
||
per file format: camera bodies and pauses are ignored, formats are not (RAW+JPEG of the
|
||
same shots stays two sequences, so no frame is doubled). Sessions, gap and minimum are
|
||
then disabled, their tooltips saying why. The title defaults to the folder's name (a
|
||
typed title wins; it also fills `{title}`); a repeated import gives the folder's name
|
||
only to a sequence without a title, so a rename made since survives. Each plan row shows
|
||
the camera, or "n cameras", and the format, and both dates when its photos span several
|
||
days; Split in Show plan cuts a part off, Merge joins it back. A folder
|
||
starts on Sessions every time (folders have no profile); cards, drives and the admin
|
||
panel have no Group choice.
|
||
- Copy with hash while streaming; verify by re-reading destination; only then delete or
|
||
format (OS dialog); eject via `IOCTL_STORAGE_EJECT_MEDIA` after `FSCTL_LOCK_VOLUME`.
|
||
- Import copies every photo byte for byte and converts nothing (amended 2026-10-26, R7; the
|
||
sketch's former *Convert* row is gone): deleting imported photos and formatting the card
|
||
need archived copies that re-hash to the card's files, which a converted file never does,
|
||
and originals are immutable. Converting is a separate, explicit step after import, behind a
|
||
dry run (*Convert…*, §12.5, §14.8); a photo converted since keeps its card copy (§13).
|
||
- Destination "Server" streams frames through the client to the server (§14.4); the
|
||
server confirms each hash before the client counts it as imported.
|
||
- Auto-import on insertion (per card), with the OS toast "Card X detected — Import".
|
||
|
||
### 12.5 Archive manager
|
||
|
||
```
|
||
│ [Archive: D:\ChronosArchive ▾] [Scan] [Rebuild index] [Verify] [Duplicates] [Orphans] [Adopt folder…] [Maintenance ▾] │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ 618,204 photos · 412 sequences · 9.4 TB · 14 cameras · 2019–2026 │
|
||
│ ▆▇█▅▂▁▃▆ photos per month (heatmap) ██████░░ storage by year ▉▉▉▍ by camera ▉▉▎ by format │
|
||
│ Index health: ✓ sidecars 412/412 · ⚠ 3 sequences without proxies · ⚠ 1 unverified since 90 days │
|
||
│ Recent maintenance: 2026-09-20 verify ✓ · 2026-09-01 vacuum ✓ │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Mass operations on filtered set (412): [Analyse] [Proxies] [Thumbnails] [Verify] [Reorganize…] [Convert…] [Retag] [Export CSV] [Delete] │
|
||
```
|
||
|
||
Operations: **Scan** (incremental, mtime/size), **Rebuild index** (from sidecars; falls
|
||
back to full metadata scan; never deletes originals), **Verify** (hashes; bit-rot report),
|
||
**Duplicates** (by hash across sequences), **Orphans** (files not indexed / rows without
|
||
files, with fix actions), **Adopt folder** (index an existing tree in place or copy into
|
||
the layout), **Merge/split sequences**, **Move archive** (relink), **Maintenance**
|
||
(SQLite vacuum/backup/restore, cache cleanup, proxy purge/rebuild, thumbnail pack
|
||
compaction, log rotation). Statistics drawn with in-house chart elements. Every operation
|
||
is a Job (resumable, cancellable, logged). Recurring scans, integrity checks, thumbnails,
|
||
proxies, analyses, maintenance, backups, clean-ups and reports are schedules in Jobs ›
|
||
Scheduled (§12.6, §14.6); the buttons here run them once (amended 2026-10-26, R10).
|
||
|
||
Maintenance › *Trash…* (amended 2026-10-26, R6) lists the archive's trash (§7), newest
|
||
first: deleted sequences and photos deleted from sequences, each with its kind, photos,
|
||
size, folder and when it went, and *Restore*. A sequence goes back as its folder is (into
|
||
its old place, or "folder (2)" when that is taken; its photos are not re-hashed, Verify does
|
||
that). Photos are re-hashed against their record and go back into their sequence with their
|
||
frame records (a name taken since gets `_2`, its companion following), or into a new
|
||
sequence when theirs is gone, every entry of that sequence joining the same new one. A photo
|
||
that stays in the trash says why (its files no longer match their record, they could not be
|
||
moved back, the sequence holds that content already, or its file was missing when it was
|
||
deleted): one sentence on the dialog's line, or how many stayed when the reasons differ, and
|
||
the tooltip with each reason and the first names. When no file of an entry matches, nothing
|
||
moves and the line says so. *Empty…* measures every entry (dry run), lists them, asks for the
|
||
number of entries to be typed, then queues the *Empty trash* job. The job erases exactly
|
||
those entries and nothing when the trash changed since; an entry that changes while it runs
|
||
is kept, and the job then fails after erasing the others. It is the only way the product
|
||
erases trash entries; no schedule runs it (§14.6).
|
||
|
||
Originals a conversion replaced (amended 2026-10-26, R7; §7) are listed as *Replaced
|
||
originals*. *Restore* swaps them back into their sequence while its converted frames are
|
||
unchanged, the conversions going to the trash in turn, and otherwise brings them back as a
|
||
new sequence. *Empty…*'s list names first, wherever the trash lists them, the entries whose
|
||
conversion was deleted since (*conversion deleted*: they may hold the last copy of their
|
||
photos), the others filling its six lines and the rest counted. The job keeps, each logged
|
||
with why, an entry changed since the plan, one whose sequence is busy, one whose conversion
|
||
no longer matches, and one whose conversion the archive cannot locate (a scan settles it).
|
||
|
||
*Reorganize…* (amended 2026-10-26, R7; it replaces Rename… and Move…) applies new templates
|
||
to sequences already filed: the set (online), the Library's selection (§12.2), or every
|
||
sequence of the archive from the toast of Settings › Archive (§12.8). The admin panel offers
|
||
the same (§14.8), through the same engine and job.
|
||
- An in-window dialog: Folders (`{title}` is the new title), File names (as filing names
|
||
them, §7.1) and Titles (`{title}` is the current title), each with its switch and field,
|
||
checked as it is typed against the rules of §7.1; a template switched off never blocks the
|
||
others. Folders and File names start on with the archive's templates, read again when the
|
||
dialog opens; Titles starts off, with `{title}`.
|
||
- The dry run (nothing touched) follows the typing (400 ms; Enter, or leaving a field, at
|
||
once) and lists, in the order the changes apply, each sequence with its folder, title and
|
||
first three file names before → after, *Follows its folder* for a sequence nested in a folder
|
||
that moves, how many files get a new name, and the photos that keep their names with why:
|
||
kept in place outside `originals/` (a tree someone else keeps), never verified (verify the
|
||
sequence first), missing; or that the sequence stays as it is, with every folder around it,
|
||
because its sequence file cannot be read (damaged, another sequence's, or from a newer
|
||
Chronos). The summary reads "12 of 36 change · 3,600 files renamed · 20 names kept".
|
||
- *Apply* (enabled only for the dry run of the templates on screen, when something changes)
|
||
queues the *Reorganize* job of exactly that plan at user priority; the dialog closes and a
|
||
toast links to Jobs. Cancel is the default button.
|
||
- The job (desktop and server) plans again and applies the plan only while it is the one
|
||
confirmed (its fingerprint, §14.3); otherwise it fails and nothing changes, a sequence
|
||
deleted since named in its log. It changes one step at a time. Pause or cancel stops
|
||
between two steps and holds the rest for the job's resume or retry; a failed job holds it too
|
||
(also when the archive's volume went away), and its retry completes it while it still fits.
|
||
A retry while the archive is still offline fails as offline and keeps the plan: a plan
|
||
journal it cannot reach is never taken for one completed.
|
||
An archive open completes a plan an interruption left (a crash, a yield to another job, the
|
||
program closing), not one its job holds.
|
||
- What changed after the dry run: a sequence moved or gone, one indexed inside a folder that
|
||
moves, a new folder taken, a title edited that the plan changes or names a folder or files
|
||
after, a sidecar of a newer Chronos it would rewrite: the rest of the plan is refused, the
|
||
steps done stay, and a new dry run is needed. Photos changed since (a sequence still
|
||
receiving them) refuse nothing: that sequence keeps its file names, and its folder and title
|
||
change while the templates still give them from its first photo as it is now, otherwise it
|
||
stays as it was, and so do the sequences its folder was to carry. A sequence left as it was
|
||
inside a folder that a later step moves goes with that folder, keeping its title and file
|
||
names, so the folder around it still moves. A photo in use or a new name taken keeps that
|
||
sequence's file names (every file back). These sequences are listed in the job's log, and
|
||
the job fails at the end, after the others changed, saying how many; its retry plans again.
|
||
- Deleting sequences of the archive is refused while a Reorganize job runs or is paused. The
|
||
Archive and Library screens read the archive again when it ends; an editor open on a
|
||
sequence it changed reloads where the sequence is now after that sequence's step.
|
||
|
||
*Convert…* (amended 2026-10-26, R7; §7, §8.7) converts the photos of sequences already filed
|
||
to JPEG, 16-bit TIFF or linear DNG: the set (online), or the Library's selection (§12.2). The
|
||
admin panel offers the same (§14.8), through the same engine and job.
|
||
- An in-window dialog: Format (JPEG, TIFF 16-bit, Linear DNG; Linear DNG, the archival choice,
|
||
chosen first), Quality (JPEG only, 1–100, 95) and Mode, *Replace* (the converted files take
|
||
the photos' place in their sequences; the originals go to the archive's trash, restorable
|
||
until it is emptied) or *New sequence* (converted copies in a new sequence beside each source;
|
||
the originals stay as they are). The mode is chosen at every run: it starts unchosen at every
|
||
open and is never remembered. Each choice's tooltip says what becomes of the originals.
|
||
- The dry run (nothing touched) follows the choices (400 ms after typing the quality; Enter at
|
||
once) and lists each sequence that converts, skips photos or stays whole: its photos and size
|
||
before → after (an estimate), the photos that stay as they are and why (already in that
|
||
format; a format this computer cannot read at full resolution; read only from an embedded
|
||
preview; a RAW developed here at 8 bits only, for a 16-bit format; a colour profile the format
|
||
can neither keep nor convert; larger than the format holds; unreadable; missing; never
|
||
verified; held open by another program or not openable), or why the whole sequence stays (a
|
||
job works on it, or a conversion of it waits; the archive offline or read-only; its sequence
|
||
file unreadable). With New sequence, the photos a copied sequence skips are *not copied* into
|
||
its new one. A summary ("12 of 36 change · 3,600 photos · 41 GB → 32 GB · 20 skipped") and the
|
||
space line follow ("Needs 12 GB, free 340 GB": the estimate with a 15 % margin and a 512 MiB
|
||
reserve, against the free space where the conversion writes); a volume without the space
|
||
blocks Apply. The mode does not change what converts, so choosing it plans nothing again.
|
||
- *Apply* (enabled for the dry run of the choices on screen when it converts something and the
|
||
space is there, once a mode is chosen, which is asked last) asks a Replace to type the number
|
||
of photos it replaces, and confirms a New sequence with how many photos the new sequences
|
||
lack; it then queues the *Convert* job of exactly that plan at user priority, and the dialog
|
||
closes. A conversion of one of its sequences already queued or running refuses it: the dry
|
||
run is made again and shows those sequences busy. Cancel is the default button.
|
||
- The job (desktop and server) converts one sequence at a time, all or nothing: the photos the
|
||
dry run listed alone, each only while it holds the content confirmed; photos received since
|
||
stay as they are. It checks the free space before it starts, before each sequence and before
|
||
each photo, and stops before the volume fills. Paused, resumed or retried in Jobs, it keeps
|
||
what it converted. A sequence whose confirmed photos changed is left as it is, and a retry
|
||
leaves it too (plan again); one busy, moved away by another program or with a photo held open
|
||
waits for the retry; one with a photo that cannot be converted is left as it was, what it
|
||
converted kept for the retry. The job's log says each, and the job fails at the end saying
|
||
how many.
|
||
- New sequence: titled "title (JPEG|TIFF|DNG)", in a folder from the archive's template, its
|
||
photos named as filing names them, owned as its source is, with its source's tags, rating,
|
||
notes and project (the positions on photos it lacks wait as pending frames). It holds the
|
||
converted copies alone; the job log says how many photos stayed in the source alone.
|
||
- When a Replace job ends, its toast offers *Undo* (once, never from the Windows notification):
|
||
the replaced entries that job made go back (swapped back, or as a new sequence for one that
|
||
changed since). Later, *Trash…* › *Restore* does the same, and the admin panel's trash view
|
||
for a conversion the server ran.
|
||
- A running or paused conversion makes its sequences busy. The Library and Archive screens read
|
||
the sequences again when it ends (a failed one converted the others); an editor open on a
|
||
converted sequence reloads.
|
||
|
||
### 12.6 Jobs
|
||
|
||
Two tabs, a *Queue | Scheduled* segmented control first in the toolbar (amended 2026-10-26,
|
||
R10; a tab, not a rail entry, so a schedule and the jobs it queued are side by side):
|
||
|
||
- **Queue**: queue + history table: kind, target, progress, fps, ETA, node, state;
|
||
pause/resume/cancel/retry; log tail on expand; filters. A job a schedule queued carries a
|
||
*Scheduled* pill. The history line gives the job-history days of the Housekeeping schedule
|
||
(*Full history kept* while it is off or at 0).
|
||
- **Scheduled**: every schedule of this PC, the system ones first: *Archive scan* (every 10
|
||
minutes, or the interval the former Settings › Archive › Rescan every had, no catch-up; a
|
||
scan follows Settings › Analysis › After a scan at every run; it also runs once after the
|
||
archive is reopened at start and when an unplugged archive is back), *Index backup*
|
||
(every day, catch-up, 3 copies kept) and *Housekeeping* (daily at 04:00, catch-up:
|
||
job history older than 90 days, the cache trimmed to Settings › Storage › Cache limit,
|
||
oldest files first, never files in use, synced proxies, the render node's cache or import
|
||
staging). Each row: an on/off switch, name (a system schedule by its key, in the UI
|
||
language), action, when (in the UI language), next run (Today, Tomorrow or a date, and a
|
||
time), last result (the state of the job it queued, else the outcome), Run now, Edit, and
|
||
Reset (system schedules) or Delete (the user's), both confirmed. Selecting a schedule
|
||
lists its last runs; *Show in queue* opens the job in the Queue tab with its log. Which
|
||
actions this PC runs is read again when the tab is shown and after a Run now that finds
|
||
one unavailable; without an index the tab says the schedules do not run.
|
||
- *New schedule* (the toolbar's end) and Edit open an in-window editor: name (a system
|
||
schedule keeps its name and action); action (those this PC cannot run disabled, the reason
|
||
in the tooltip); *Repeat* Every / Daily / Weekly / Monthly with their fields (interval 5
|
||
minutes to a day, 1–168 hours or 1–366 days; a time of this PC's clock; days of the week
|
||
in the UI language's order; day 1–28 of the month); the action's parameters (full scan,
|
||
rebuild all, deep analysis, unverified for or older than n days, at most a share of the
|
||
sequences, report only, copies kept, clean-up steps); priority; catch-up; on. Every field
|
||
is checked as it is typed.
|
||
- No work recurs out of sight: every timer that queues work is a schedule here (§14.6). A
|
||
schedule's background run raises a toast only when it fails, unless it is upkeep the next
|
||
run repeats (scan, thumbnails, proxies, light analysis, clean-up); Run now raises one only
|
||
when it queued nothing.
|
||
|
||
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).
|
||
A photo whose archived frame a conversion replaced since no longer matches its card file,
|
||
so a delete keeps it on the card and a format is refused while it is there (amended
|
||
2026-10-26, R7).
|
||
- Failure handling: card removed mid-copy → partial files deleted, plan resumable on
|
||
re-insert; errors listed per file, never a modal per error.
|
||
|
||
---
|
||
|
||
## 14. Chronos Server
|
||
|
||
### 14.1 Stack
|
||
|
||
ASP.NET Core minimal API on Kestrel (`Microsoft.AspNetCore.App` shared framework, no
|
||
packages), `System.Text.Json` source-generated contexts from `Chronos.Protocol`, WebSockets
|
||
for events, in-house structured file logging (`Microsoft.Extensions.Logging` abstractions
|
||
are part of the shared framework; the file provider is in-house), in-house rate limiting for
|
||
login and uploads, health endpoint, graceful shutdown (jobs checkpoint).
|
||
|
||
Logging (amended 2026-10-26, R11): files `/data/logs/server-yyyyMMdd.log`, or
|
||
`server-yyyyMMdd-HH.log` with hourly rotation (UTC). A file that reaches the size limit (50
|
||
MB by default, MB of 2²⁰ bytes; 0 = no limit) continues in `.1.log`, `.2.log`…, and a
|
||
restart continues the period's newest part. At every new file, and when the settings
|
||
change, files older than the retention (14 days) are deleted, then the oldest while all
|
||
the files exceed the total limit (1,024 MB; 0 = no limit; never below one file), never
|
||
the file being written and never a name the sink did not write. The console and the files
|
||
have their own levels (Information by default), which the logging filters read at every
|
||
line, so a change in the admin panel applies at once; ASP.NET Core's own categories never
|
||
write below Warning, the host's lifetime never below Information; the engine's level is
|
||
the lower of the console's and the files'. Logging never fails what logs: a line that
|
||
cannot be written (the folder removed, a full disk) is dropped and the next one tries the
|
||
file again (a removed folder is not created again), so a job still ends Failed and the job
|
||
engine and the scheduler go on. The desktop programs use the same sink (`chronos-`,
|
||
`uploader-`, `setup-` files, with the default limits; Chronos takes its own from Settings ›
|
||
Advanced, §12.8).
|
||
|
||
### 14.2 Security
|
||
|
||
- TLS: `auto` (self-signed cert generated at first start with `CertificateRequest`, stored
|
||
in `/data/tls`, fingerprint printed in logs and shown in admin), `pem` (cert + key
|
||
paths), `proxy` (HTTP behind a reverse proxy, `ForwardedHeaders` middleware, admin warns
|
||
if not local).
|
||
- Passwords: PBKDF2-SHA512, ≥ 210,000 iterations, 16-byte salt, versioned hash format;
|
||
minimum length 10; admin-created users get `mustChangePassword`.
|
||
- Tokens: 32 random bytes, stored as SHA-256, `Authorization: Bearer`; sliding expiry
|
||
(default 30 days), per-client name, revocation list; web admin uses an `HttpOnly; Secure;
|
||
SameSite=Strict` cookie session + double-submit CSRF token.
|
||
- Authorization: roles admin/editor/uploader/viewer + permission bits; sequence ownership;
|
||
admin-only management endpoints; path traversal impossible (ids → paths via DB only).
|
||
- Limits: max upload size, chunk size (default 8 MiB), per-user quota, request timeouts,
|
||
login rate limit (5/min/IP), audit log.
|
||
|
||
### 14.3 API v1 (JSON; errors as `{ code, message, details }`; `X-Chronos-Api: 1`)
|
||
|
||
```
|
||
POST /api/v1/auth/login {username,password,clientName} → {token,user,mustChangePassword}
|
||
POST /api/v1/auth/logout · POST /auth/password · GET /auth/me
|
||
GET /api/v1/server/info name, version, apiVersion, capabilities, tlsFingerprint, formats, limits, extensions
|
||
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)
|
||
POST /api/v1/archive/convert {sequenceIds|all, target, quality?, mode, dryRun, fingerprint?} → plan | 202 convert job (admin)
|
||
GET /api/v1/archive/trash · POST /archive/trash/{name}/restore · POST /archive/trash/empty {names?, dryRun, fingerprint} (admin)
|
||
GET /api/v1/i18n/{culture} strings for the web admin
|
||
```
|
||
|
||
Library and trash (amended 2026-10-26, R6):
|
||
- `frames/delete` needs the Delete permission and the sequence's owner or an admin, like
|
||
deleting the sequence. It takes 1–100,000 ids, under a body limit of its own (100,000 × 48
|
||
bytes + 4 KiB, about 4.8 MB; other JSON bodies stay at 1 MiB); a dry run answers the
|
||
photos, bytes and the frames version now, a deletion the frames version after it (the next
|
||
request's `expectedFramesVersion`), the frame count and the trash entry's name. Errors: 400
|
||
`bad_request` (`frameIds`); 404 `not_found` (`sequence`); 409 `frames_conflict` (the frames
|
||
changed since `expectedFramesVersion`, or an id is not the sequence's; details: the frames
|
||
version now), `sequence_busy` (a job works on it, as for deleting it), `would_empty` (every
|
||
photo would go: delete the sequence), `photo_unreadable` (a photo never hashed whose
|
||
original is on disk but cannot be read, so it could leave no tombstone; details: how many,
|
||
the message naming the first), `sidecar_mismatch`, `folder_in_use`; 413 `too_large`; 503
|
||
`archive_offline`. Audited `frames_deleted`; publishes `sequenceChanged` `frames`.
|
||
- The bulk routes take 1–1,000 distinct ids and answer `{items, ok, skipped, dryRun, photos,
|
||
bytes, job}`, one item per id in the request's order: `ok`, or `skipped` with the reason's
|
||
code and sentence. *delete* (Delete) moves each sequence as `DELETE /sequences/{id}` does,
|
||
whole or not at all, and skips `not_found`, `forbidden` (another user's, unless an admin),
|
||
`sequence_busy`, `archive_root`, `contains_sequences`, `sidecar_mismatch`, `folder_missing`,
|
||
`archive_offline`, `folder_in_use`. *retag* (Edit) is the PATCH tag edit (trimmed, at most
|
||
64 characters, at most 50 a sequence, case-insensitive, up to 3 attempts on a settings
|
||
conflict) and skips `not_found`, `bad_request`, `settings_conflict`. *jobs* (Edit; kind
|
||
`analyse`, `deep`, `proxies`, `thumbnails` or `verify`) queues one job at user priority over
|
||
the sequences found (202; 200 when none), a verify targeting their archive with the
|
||
sequences in its parameters, as `POST /jobs` with `verify` now does too; 400
|
||
`invalid_job_kind`, 409 `job_unavailable`. 400 `bad_request` (`ids`, `tags`).
|
||
- `GET /archive/trash` (ManageArchive, like the rest of the trash) answers the entries newest
|
||
first, `{name, kind: sequence|photos|replaced, sequenceId, title, folder, photos, files,
|
||
bytes, deletedBy, deletedAt}`, and their total bytes. A name is
|
||
`<32 hex>[-<14 digits>[-n]]` (a sequence) or `photos-<32 hex>-<14 digits>[-n]` (photos),
|
||
checked against that shape and never a path.
|
||
- Restore answers `{name, kind, sequenceId, photos, kept, newSequence, keptReasons,
|
||
message}`: the photos that stayed and, in the same order, why (`mismatch`, `not_moved`,
|
||
`in_sequence`, `no_file`), with one sentence per reason in the request's language. Errors:
|
||
404 `not_found` (`trash_entry`); 409 `sequence_in_library`, `sequence_busy`,
|
||
`sidecar_mismatch` (the sidecar of the sequence the photos return to is damaged or
|
||
another's), `folder_in_use`; 422 `trash_mismatch` (no file matches its record any more, or a
|
||
deleted sequence's own sidecar no longer names it); 503 `archive_offline`. Audited
|
||
`trash_restored`; publishes `sequenceChanged` `created` (a sequence, or a new one) or
|
||
`frames`. A replaced entry (amended 2026-10-26, R7) answers kind `replaced`, with
|
||
`newSequence` false once its originals swapped back in place of their conversions, true when
|
||
they came back as a new sequence.
|
||
- Empty: a dry run answers the entries measured on disk, their photos, files and bytes, the
|
||
plan's `fingerprint` and the names asked for that the trash does not hold (`unknown`); a
|
||
replaced entry whose conversion the archive shows deleted carries `conversionDeleted: true`,
|
||
which the fingerprint covers (amended 2026-10-26, R7). The erase sends the fingerprint back
|
||
and answers 202 with the `empty-trash` job. Errors: 400 `bad_request` (`names`,
|
||
`fingerprint`); 409 `trash_changed` (details: the fingerprint now), `job_unavailable`; 503
|
||
`archive_offline` (offline, and for the erase also read-only; the listing answers it too,
|
||
offline). The request is audited `trash_empty_requested`; what the job erased, and why it
|
||
kept an entry, is in its log.
|
||
- The manifest gains `removed: [{sha256, replacement, reason: deleted|replaced, at}]` (null
|
||
when there are none; covered by its ETag, since a deletion moves the frames version).
|
||
|
||
Reorganize (amended 2026-10-26, R7; ManageArchive; §7, §12.5, §14.8):
|
||
- The request names exactly one of `sequenceIds` (1–1,000) and `all`; a null template keeps
|
||
that part, at least one is given, each usable and within the rules of §7.1. A dry run
|
||
answers `{steps, sequences, files, kept, fingerprint}` and changes nothing: a step for each
|
||
sequence that changes, is carried or keeps photo names, in the order they apply,
|
||
`{sequenceId, fromFolder, toFolder, fromTitle, toTitle, carried, framesVersion, fileChanges,
|
||
fileSamples: [{from, to}] (at most 3, relative to the sequence folder), blocked: [{reason:
|
||
in_place|unhashed|missing|unreadable, photos, message}]}` (`unreadable`: the whole sequence
|
||
stays, 0 photos; the message in the request's language). The change sends the dry run's
|
||
fingerprint back and answers 202 with the `move` job. Errors: 400 `bad_request`
|
||
(`sequenceIds`, `templates`, `fingerprint`), `invalid_template` (below); 404 `not_found`
|
||
(`sequence`); 409 `nested_target` (details: the folder that would lie inside a sequence's
|
||
folder), `plan_changed` (details: the fingerprint now), `job_unavailable`; 503
|
||
`archive_offline`, `plan_dropped`. Audited `archive_reorganized` (sequences, files renamed,
|
||
templates). The job publishes `sequenceChanged` with the change `reorganized` for each
|
||
sequence once its step is journaled (at once for a step that failed after its folder moved
|
||
and its index rows followed); a plan the server completes as it starts tells no one, as no
|
||
client is connected yet.
|
||
- The fingerprint is a SHA-256 of the steps as the dry run shows them (folders, titles,
|
||
carried, file counts, samples, what stays and why), every file rename by its digest, and the
|
||
file template; not the frames version, so photos a sequence receives under the names the
|
||
plan leaves them keep it.
|
||
- The server keeps a dry run's plan, and a refusal (`nested_target`, `not_found`), for 5
|
||
minutes, keyed by the archive, the selection (all, or the ids in their order, which decides
|
||
which folder gets " (2)"), the templates, and a stamp of what the plan reads from the index:
|
||
every sequence's id and folder; the planned sequences' title, first capture, camera, lens,
|
||
photo count, frames version and how many of their photos are hashed; the title of the others
|
||
inside their folders. The same dry run again, and its confirmation, take the kept plan. A
|
||
plan is made apart from its request (one a proxy cuts off leaves it to be made, and asking
|
||
again waits for it), at most 2 at once and 8 kept or being made (Convert's dry runs counted,
|
||
R7); one still being made 15 minutes after it was asked, let go for newer ones, or when the
|
||
server stops is stopped, and its requests answer 503 `plan_dropped`. A change made on disk
|
||
alone is not in the stamp: the confirmation then answers 202, and the job, which plans again,
|
||
fails without changing anything.
|
||
- `invalid_template`, here and from `PUT /archive/settings`: the details name the field and,
|
||
after a colon, the rule a template that parses breaks (`folderTemplate:reserved_folder`,
|
||
`fileTemplate:file_separator`, `fileTemplate:extension`, `fileTemplate:not_unique`), the
|
||
message saying why in the request's language (`Errors.Template.<Rule>`); a blank, invalid or
|
||
unusable template keeps the bare field and the generic message. `PUT /archive/settings` holds
|
||
a template to the rules only when the save changes it; every template must still parse and
|
||
expand.
|
||
- Writers that file into a sequence's folder take it from the index row read under the
|
||
sequence's lease, so they write where a Reorganize put it. Completing a render upload or a
|
||
render node's result that cannot be filed for now answers 503 and keeps the upload
|
||
receiving, to be completed again: `sequence_busy` (the sequence held past the lease wait),
|
||
`archive_offline` (the archive offline or read-only) or `folder_moved` (the sequence's folder
|
||
not where the index has it, or holding another sequence, after another program moved them;
|
||
the server's next scan finds it). The node keeps its job while it retries. A proxy upload
|
||
answers 503 `sequence_busy` while the sequence is held, 404 `frame` when the sequence or its
|
||
folder is gone, or the folder is another sequence's.
|
||
|
||
Convert (amended 2026-10-26, R7; ManageArchive; §7, §8.7, §12.5, §14.8):
|
||
- The request names exactly one of `sequenceIds` (1–1,000) and `all`, a `target` (`jpeg`,
|
||
`tiff16`, `linear-dng`), a `quality` (1–100, default 95; it counts for a JPEG only) and a
|
||
`mode` (`replace` or `new-sequence`). A dry run answers `{target, quality, mode, steps,
|
||
sequences, photos, skipped, bytesBefore, bytesAfter, space, fingerprint}` and changes nothing:
|
||
a step per sequence asked, in order, `{sequenceId, title, folder, framesVersion, photos,
|
||
bytesBefore, bytesAfter (an estimate), skipped: [{reason: same_format|convert_on_pc|
|
||
undecodable|missing|unhashed|eight_bit|color_profile|too_large|inaccessible, photos,
|
||
message}], blocked: [{reason: busy|offline|unreadable, message}]}`, each message in the
|
||
request's language. `convert_on_pc` is a format or file the server cannot read at full
|
||
resolution ("convert these photos on a PC"); of a sequence `new-sequence` copies, a message
|
||
says the new sequence lacks those photos. `space` is `{required, free, enough, message}`:
|
||
the estimate × 1.15 plus 512 MiB, counted in both modes, against the free space where the
|
||
conversion writes (the tighter of the space path's volume and the archive's own, §14.9).
|
||
- The change sends the dry run's fingerprint back and answers 202 with the `convert` job, whose
|
||
parameters name each sequence's photos and their digest. Errors: 400 `bad_request`
|
||
(`sequenceIds`, `target`, `quality`, `mode`, `fingerprint`); 404 `not_found` (`sequence`);
|
||
409 `plan_changed` (details: the fingerprint now; none when a conversion of these sequences
|
||
was queued meanwhile), `nothing_to_convert`, `not_enough_space` (details: the bytes needed),
|
||
`job_unavailable`; 503 `archive_offline`, `plan_dropped`. Audited `archive_converted`
|
||
(sequences · photos · target · mode). The job publishes `sequenceChanged` `converted` for each
|
||
sequence whose frames it replaced and `created` for each new sequence, as each one completes.
|
||
- The fingerprint is a SHA-256 of the options, the mode, and each sequence with its frames
|
||
version, its photos' count and bytes, their digest (each frame id with the SHA-256 of its
|
||
content), what it skips and what blocks it.
|
||
- The server keeps a dry run as it keeps Reorganize's, in one cache for both (2 made at once,
|
||
8 kept, 5 minutes, stopped after 15 with `plan_dropped`), keyed by the archive, the selection,
|
||
the target with the quality that counts (none for a lossless target) and a stamp of the index:
|
||
Reorganize's, and of the planned sequences' photos their count, sizes, formats, pixel sizes
|
||
and how many are flagged missing, corrupt, preview-only or undecodable. Not the mode, which is
|
||
set on the kept plan, nor the busy sequences and the free space, measured again at every
|
||
request. A plan made while the archive was offline is not kept. A confirmation takes only the
|
||
plan kept for the index as it is now and never plans inside its own request: with none kept
|
||
it answers 503 `plan_dropped` (ask the dry run again), with a kept plan that differs 409
|
||
`plan_changed`. A change made on disk alone is found by the job, which converts the photos
|
||
confirmed only while each holds the content confirmed.
|
||
|
||
Uploads (amended 2026-10-26, R3, R6): `server/info` lists `extensions`, the photo file
|
||
extensions the archive files (lower case, no dot), which the admin panel's dialog keeps to. A
|
||
frame upload whose file name starts with `.` is 400 `invalid_file_name`. A start whose
|
||
SHA-256 the target sequence tombstoned (and none of its frames holds) answers 200
|
||
`alreadyExists` without a `frameId`, unless `restore` is true; the completion checks again
|
||
unless `?restore=true` and answers 409 `photo_removed`, the upload cancelled (§14.4). An
|
||
original a conversion replaced in the target sequence is tombstoned too; sent with `restore`,
|
||
it files nothing and its completion answers the frame that holds its conversion (amended
|
||
2026-10-26, R7).
|
||
|
||
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.
|
||
|
||
Replaced photos (amended 2026-10-26, R7): a photo a conversion replaced in a sequence is in it
|
||
as its conversion. The ingest answers its original (a card or a folder imported again, a
|
||
download, an upload sent with `restore`) as a duplicate of the frame that holds the conversion,
|
||
followed through later conversions, and keeps the tombstone that makes sync count both as one
|
||
photo; once no such frame is intact, the original is filed again. A batch files nothing into a
|
||
sequence while a restore from the trash or a frame replacement of it is not settled (its trash
|
||
entry busy): an upload's completion answers 503 and the client tries again.
|
||
|
||
The admin panel uploads through the same path (amended 2026-10-26, R3; the dialog, §14.8):
|
||
- It hashes each photo in the browser with an in-house incremental SHA-256 (FIPS 180-4,
|
||
`sha256.js`) in a same-origin module worker (`hash-worker.js`, under the panel's
|
||
`script-src 'self'`) that reads the file in 8 MiB blocks. Before its first hash the worker
|
||
runs the FIPS 180-4 known answers (the empty message, "abc", the 448- and 896-bit messages,
|
||
one million "a"), whole and fed in uneven pieces, and, where `crypto.subtle` exists,
|
||
compares a 1 MiB random buffer with it; on any mismatch it refuses every hash and the
|
||
dialog uploads nothing (fail closed). The server verifies every upload again.
|
||
- Each start carries the photo's capture time: the Exif DateTimeOriginal of a JPEG or a
|
||
TIFF-based file (TIFF, DNG, most RAW formats) read from its first 256 KiB, else the file's
|
||
modification time as local wall time without an offset; the ingest uses it only for a
|
||
photo that records no time of its own (a PNG, an export stripped of Exif).
|
||
- At most two photos and two chunks per photo travel at once (four requests, half the
|
||
server's eight per account). A call that got no answer, 429 or 503 is retried after 1, 2
|
||
and 4 s; a completion refused with 409 `upload_state` (another completion is filing that
|
||
upload) is read again after 1, 2, 4 and then every 8 s, about a minute in all. Two copies
|
||
of one photo in a run go one after the other, so the second finds the first.
|
||
- `alreadyExists` with a frame is *Already there*; without one, *Deleted before*, whose row
|
||
offers *Upload again* between runs (the `restore` above). A quota or permission refusal
|
||
(401, 403), no space (507), the target sequence gone (404 `sequence`) or a failed self-test
|
||
stops the remaining photos (*Not sent*) with the server's message. A new target sequence is
|
||
created once (`POST /sequences`, never retried) and stays the dialog's target.
|
||
- Cancel aborts, stops the worker and deletes the uploads the run started and did not
|
||
complete; a photo that failed otherwise keeps its upload receiving, so the next run resumes
|
||
it, and abandoned uploads expire after the upload retention. While photos are sent, leaving
|
||
the page asks first and Esc is held, so only Cancel stops the run.
|
||
- Only files whose extension `server/info` lists, not empty, not starting with `.` and no
|
||
larger than `limits.maxUploadBytes` are taken. Folders dropped on the dialog are counted
|
||
(*Folders skipped*) and left out, and it has no folder picker: importing a whole folder
|
||
stays a desktop feature (R9).
|
||
|
||
### 14.5 Sync
|
||
|
||
Manifest diff per sequence: originals are content-addressed (never conflict); settings and
|
||
tags carry version counters (last-writer-wins with an explicit conflict prompt in the
|
||
client when both changed); proxies/thumbs are regenerable and never synced upward; renders
|
||
are uploaded on request. "Edit with proxies, render where the originals are": a client can
|
||
open a remote sequence with proxies only and submit a render job to the server, which runs
|
||
it itself (managed formats) or hands it to a render node.
|
||
|
||
Removed photos (amended 2026-10-26, R6). A photo deleted on one side leaves a tombstone there
|
||
(sidecar `removed`, index `frame_removals`, manifest `removed`), and sync never offers it back:
|
||
no upload of a photo the server deleted, no download of one this PC deleted; sync never
|
||
deletes local files either way. A tombstone leaves a photo out only while its own side holds
|
||
no matching photo (by hash, or by size and capture time while unhashed), so a duplicate that
|
||
stays or a file put back by hand still syncs. A photo replaced by a converted file (R7) is
|
||
the same photo as its replacement on both sides, for the comparison, the transfers and the
|
||
frame positions (below). Content known only once hashed is checked then: a download skips an
|
||
unhashed server frame this PC deleted (or holds as its replacement), and an upload skips an
|
||
unhashed local frame the server deleted and then runs the archive verify, so the index gets
|
||
the hashes and the next comparison leaves it out.
|
||
Known limitations: until the server verifies such a frame, the sync table still counts it as
|
||
missing here and *Download* fetches and drops it each time; a photo never hashed whose
|
||
original was already missing when it was deleted leaves no tombstone, so a copy elsewhere
|
||
(another PC, a card) is not known to be deleted and can come back.
|
||
|
||
Converted photos (amended 2026-10-26, R7). Every replaced tombstone of either side links two
|
||
encodings of one photo, and the encodings these links join (a conversion, a conversion of it,
|
||
its undo, each side converting its own copy) compare, transfer and translate as one photo,
|
||
under the smallest of their SHA-256s; a deletion on either side covers every encoding. Linking
|
||
a local sequence to a server one by content and the proxies this PC sends follow them (a frame
|
||
this PC converted makes the proxy of the server's original). A download for a frame flagged
|
||
missing here whose photo the server holds only in another encoding puts that file in the
|
||
frame's place (the same id, nothing to the trash, a replaced tombstone linking the two), after
|
||
the transfers and only in the folder the index has for the sequence, and queues the passes the
|
||
swap cleared; a frame that changed meanwhile keeps its place and the copy is dropped.
|
||
|
||
Folders moved by another program (amended 2026-10-26, R7). When a desktop and a server share
|
||
an archive, a Reorganize by one index (or a folder moved by hand) is found by the other's next
|
||
scan, which moves the sequence's row, its frames and the paths of the exports that moved with
|
||
the folder (a file or, for an image sequence, a folder; an export written at the old place
|
||
after the move keeps its path there, and another sequence's export saved inside follows only
|
||
when it moved with the folder). The other program may also have moved another sequence into
|
||
the old folder (its sidecar names that sequence): the moving sequence's exports then follow to
|
||
its new folder, and an export of the sequence that took the old folder never follows, so no
|
||
row names another sequence's file. Until that scan nothing writes into the old place, which
|
||
would create it again, nor into another sequence that took it: *Save both* and *Take server*
|
||
answer that the folder is not where the index has it (try again after the next scan), and so
|
||
do a render job as it starts, exports fetched by sync, a proxy pass, and a thumbnail pass that
|
||
finds another sequence's sidecar there; the editor's save says the sequence is no longer in
|
||
the archive, and a deep analysis that loses its folder records nothing. A render of the other
|
||
program whose folder moves while it runs is not stopped. Known limitation: an export a
|
||
sequence saved into another sequence's folder (the Export folder picker), before the other
|
||
program moved that sequence away and the first one into its folder, keeps naming the old
|
||
path; the file is intact, moved with the other sequence.
|
||
|
||
### 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".
|
||
|
||
Convert (amended 2026-10-26, R7), the panel's way to the Convert of §12.5 through
|
||
`POST /archive/convert` (§14.3):
|
||
- The Library's selection bar has *Convert…*, after *Reorganize…*, for the same selection: up
|
||
to 1,000 sequences, or every sequence after *Select all* without a filter (one plan, one job).
|
||
- The dialog: Format (JPEG, TIFF-16, Linear DNG, the archival choice, chosen first), Quality
|
||
(JPEG only, 1–100, 95) and Mode (Replace or New sequence), never preselected; each choice's
|
||
tooltip says what becomes of the originals. Each change asks the server for a dry run, one at
|
||
a time (400 ms after typing the quality). Until a mode is chosen it is asked in Replace's
|
||
words; New sequence asks again, answered from the plan the server keeps. The table shows each
|
||
sequence, 200 at a time: photos converted, those left as they are with why (what blocks the
|
||
whole sequence first; *Not copied* with New sequence) and the size before → after; then the
|
||
totals and the server's space line. A dry run a proxy cut off is asked again every 2 s for up
|
||
to 16 minutes, the totals saying how long it takes.
|
||
- The dialog's *Convert…* (enabled while the table is the plan of the fields, converts
|
||
something, has the space and a mode is chosen; its tooltip says what is missing) asks a
|
||
Replace to type the word "replace" in the panel's language, and confirms a New sequence with
|
||
how many photos the new sequences lack, each sequence listed with its own count. It then
|
||
asks the dry run again (Close stays: nothing is sent yet) and sends that plan's fingerprint
|
||
only while it is the one confirmed; the toast offers *Open job*. `plan_changed`,
|
||
`plan_dropped`, `not_enough_space` and `nothing_to_convert` show the new plan and the button
|
||
waits; a request that got no answer is not sent again, as its job may be queued (the Jobs
|
||
page says).
|
||
- The trash view lists replaced originals as *Replaced*, whose *Restore* swaps the originals back
|
||
in place of their conversions while those are unchanged, else restores them into a new
|
||
sequence. *Empty…* lists first the entries whose conversion was deleted, each saying so.
|
||
- The audit log and the Dashboard read "… queued a conversion · N sequences · M photos ·
|
||
format · mode".
|
||
|
||
Upload (amended 2026-10-26, R3): Library › *Upload* (no sequence) and a sequence's *Add
|
||
photos* open the upload dialog (§14.4), a module the pages import only on demand.
|
||
- Target: the given sequence, or a choice between an existing sequence (a search box, then a
|
||
list) and a new one (title optional), fixed once the first run starts.
|
||
- Photos: the file picker (several files, the photo extensions only) or a drop on the dialog.
|
||
Folders, files that are not photos (hidden dot files among them) and files above the size
|
||
limit are counted in chips and left out.
|
||
- Each photo shows its state: waiting, hashing %, starting, uploading %, verifying, uploaded,
|
||
already there, deleted before (with *Upload again*), failed (the reason in the tooltip),
|
||
cancelled, not sent; a total bar shows photos and bytes.
|
||
- Buttons: *Upload*, which sends whatever is not on the server yet; *Cancel* while sending;
|
||
*Close* otherwise. Esc closes only while nothing is being sent.
|
||
|
||
The panel's files (amended 2026-10-26, R6) are served with `Cache-Control: no-cache` and an
|
||
ETag of their content: the browser asks again before each use and an unchanged file costs a
|
||
304 (`If-None-Match` lists, weak `W/` tags and `*` count), so after an upgrade it never runs
|
||
new modules next to old cached ones.
|
||
|
||
Storage (Dashboard and Archive) shows the space volume: the folder `CHRONOS_SPACE_PATH`
|
||
names (§14.9) when it can be measured, else the archive's own volume. When a space path is
|
||
in use and the archive's own volume (the write volume, where uploads land; on Unraid the
|
||
share's primary storage, often the cache) has other figures (another size, or free space
|
||
more than 64 MiB apart), a second line *Write volume* shows its free space. The figures'
|
||
tooltip names the volume and its file system (on Linux the mount's type from
|
||
`/proc/self/mountinfo`, so an Unraid share reads `fuse.shfs`); on such a share without a
|
||
space path it says the figures are the share's primary storage and to map the share's array
|
||
view (`/mnt/user0/<share>`) to `/space` and set `CHRONOS_SPACE_PATH=/space`. The server's
|
||
diagnostics report lists the archive, the space path and `/data`, each with free space,
|
||
file system and mount (amended 2026-10-26, R2).
|
||
|
||
### 14.9 Configuration and Docker
|
||
|
||
Environment variables (also readable from `/data/server.json`):
|
||
`CHRONOS_ADMIN_USER`, `CHRONOS_ADMIN_PASSWORD` (used only when no admin exists; forced change
|
||
at first login), `CHRONOS_ARCHIVE_PATH=/archive`, `CHRONOS_DATA_PATH=/data`,
|
||
`CHRONOS_SPACE_PATH` (`SpacePath` in `server.json`; optional: a folder, e.g. `/space`, whose
|
||
volume's free space the admin panel shows instead of the archive's; one that cannot be
|
||
measured falls back to the archive's with one warning, logged at start and again only once
|
||
it has worked in between; uploads always check the archive's own volume, §14.4, and a
|
||
conversion the tighter of the two, §14.3: amended 2026-10-26, R7),
|
||
`CHRONOS_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); a sequence of the plan left as it was inside a moving folder goes with it; the index, frames and exports follow a moved folder in one transaction, on this index and at another index's next scan; writers take the folder under the lease, never create a left one again and never write into a folder another sequence took; `POST /api/v1/archive/reorganize` with a kept, bounded plan cache and `sequenceChanged` `reorganized`; Rename… and Move… replaced. |
|
||
| 2026-10-26 | Owner review 2, R7 (naming) | §7.1, §13, §14.3 | One naming rule for import, upload and Reorganize: the sequence's camera and lens, `{n}` its place, a frame without a time at the sequence's start; template rules everywhere a template is typed or sent (no folder level scans skip, one a value such as a title gives escaped with `_`; a file template keeps the extension, tells photos apart, holds no slash; long names shortened before `.{ext}`; titles as text), held to a template only when it is given anew; `invalid_template` names the rule. |
|
||
| 2026-10-26 | Owner review 2, R7 (conversion) | §5, §7, §8.1, §8.3, §8.7, §9, §12.2, §12.4, §12.5, §13, §14.3, §14.4, §14.5, §14.8, §14.9 | Convert after import on the desktop (the Archive manager's set, the Library's selection) and the admin panel (the Library's selection): JPEG with a quality, TIFF-16 or linear DNG (the archival choice, scene-referred so a RAW's highlights above white and colours outside sRGB survive), Replace or New sequence chosen at every run and never remembered, behind a dry run that lists each sequence's photos, sizes and the photos that stay as they are with why, and the free space where the conversion writes; Replace confirmed by typing; the `convert` job (stored as 19) converts exactly the photos confirmed, one sequence at a time and all or nothing, resumable through its journals and staging, never twice at once; full-resolution decodes only (the managed decoders first, never a 16-bit file from an 8-bit RAW development; the server leaves what it cannot read to a PC), colour profiles kept, Exif carried, every file verified by the server's decoders; Replace swaps the files of the frames in place under a crash-safe journal, the originals going into a replaced trash entry that Undo or Restore swaps back and that Empty erases only while the archive on disk shows each conversion intact, or deleted; import still copies byte for byte and the card keeps a converted photo's copy; sync and the ingest count every encoding of a photo as one; `POST /api/v1/archive/convert` with the plan cache it shares with Reorganize, `sequenceChanged` `converted` and `created`, the audit `archive_converted`. |
|
||
|
||
## 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).
|