Files
Chronos/docs/BRIEF.md
T
Claude 83a54fb57b chore: bootstrap repository foundation
Solution layout, build rules with zero-package guard, in-house test
framework, localization runtime, brand mark rasteriser with ICO/PNG
generation, Core contracts (imaging, video, domain model, TIFF reader),
Titano.Tools (make-icon, i18n, xaml-lint, package-guard) and docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
2026-10-02 08:59:40 +00:00

1347 lines
87 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Titano — Build Brief for Claude Code
> This document is the complete specification and standing instruction set for building the
> Titano 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: **Titano**. Three shipped programs — **Titano** (Windows desktop client),
> **Titano Server** (Linux/Docker and Windows), **Titano 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/titano-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/titano-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.** `Titano.Core`, `Titano.Data`,
`Titano.Protocol` and `Titano.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:** builds green on `windows-latest` and
`ubuntu-latest`; 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/titano-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
Titano 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 Titano 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** — Titano 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 (`Titano.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
```
titano/ (private GitHub repo)
├── 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
├── Titano.slnx
├── global.json pins .NET 10 SDK
├── src/
│ ├── Titano.Core/ net10.0 — engine: Metadata, Imaging, Codecs, Analysis, Motion, Video (container/muxers), Archive model, Naming, Localization runtime
│ ├── Titano.Core.Windows/ net10.0-windows — WIC decoder, Media Foundation encoder, DXGI, device APIs, winsqlite3 binding
│ ├── Titano.Data/ net10.0 — IDatabase abstraction, SQL dialects, migrations, repositories, Postgres wire client (Titano.Data.Postgres), SQLite driver surface (implemented by Core.Windows binding)
│ ├── Titano.Protocol/ net10.0 — API DTOs, JSON contexts (source-generated), chunked upload protocol, sync manifests, WebSocket event schema, version negotiation
│ ├── Titano.Server/ net10.0 — ASP.NET Core minimal API, auth, job engine, storage service, admin web UI (embedded static files), Docker entrypoint
│ ├── Titano.App/ net10.0-windows — WPF desktop client
│ ├── Titano.Uploader/ net10.0-windows — WPF uploader (tray-capable)
│ ├── Titano.Setup/ net10.0-windows — in-house installer/uninstaller (self-extracting, Add/Remove Programs, shortcuts, file associations)
│ └── Titano.Tools/ net10.0 — CLI: selftest, diagnose, make-icon, i18n export/check, fixtures fetch, changelog
├── tests/
│ ├── Titano.Testing/ in-house test framework + runner (attributes, asserts, fixtures, JUnit XML)
│ ├── Titano.Core.Tests/
│ ├── Titano.Data.Tests/ includes PostgreSQL integration tests (skipped without TITANO_TEST_PG)
│ ├── Titano.Server.Tests/ in-process Kestrel on a random port
│ ├── Titano.App.Tests/ view-model tests + XAML lint (tooltip/resource rules) + screenshot smoke (`--capture`)
│ └── fixtures/ tiny checked-in samples; larger CC0 RAW samples fetched by `Titano.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/titano.xml
├── .github/workflows/ ci.yml, release.yml, docker.yml
└── docs/ BRIEF.md (this), DECISIONS.md, CHANGELOG.md, ARCHITECTURE.md (generated per phase), reference/titano-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
```
┌────────────────────────────────────────────────────────────────┐
│ Titano (WPF client) │
│ Library · Sequence editor · 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)
▼ ▼
┌───────────────────────────────────┐ ┌──────────────────────────┐
│ Titano Server │ │ Titano 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
`Titano.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), target ids, state (queued, running,
paused, done, failed, cancelled), progress (done/total, fps, eta), log tail, created by,
node id, attempts, error.
- **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.
Paging everywhere (keyset pagination on `(first_capture, id)`).
---
## 6. Data layer
### 6.1 `Titano.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 `Titano.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: `Titano.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%\Titano\titano.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` nightly copy kept ×3; restore from Settings › Advanced.
### 6.3 PostgreSQL client (`Titano.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=titano-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>/
├── .titano/
│ ├── 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)
├── 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 …
│ └── .titano/
│ ├── 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)
```
`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 }],
tags, rating, notes, status, versions, createdBy, updatedAt }`.
Rules: originals are immutable (never rewritten; edits are settings); every write of a
sidecar goes to a temp file, `fsync`, rename; the folder name is derived from templates at
import time and never auto-renamed afterwards (renaming is a user mass-operation that
updates sidecars and DB together). Network drives: UNC or mapped paths; long-path aware
(`\\?\` prefix); no `FileSystemWatcher` reliance — periodic polling by mtime/size 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.
---
## 8. Image pipeline
### 8.1 Supported input formats
| Family | Extensions | Metadata (in-house) | Pixels on Windows | Pixels on server (Linux) |
|---|---|---|---|---|
| JPEG | jpg jpeg jpe jfif | APP1 Exif/XMP, MPF | WIC or managed | managed (baseline + progressive) |
| PNG | png | eXIf, iTXt XMP | WIC or managed | managed |
| TIFF | tif tiff | IFDs | WIC or managed | managed (strips/tiles; none/PackBits/LZW/Deflate/JPEG) |
| DNG (smartphones: Apple ProRAW, Android, Samsung; DJI; Insta360; Leica; Pentax; Ricoh) | dng | IFDs, MakerNote | WIC (if Raw ext.) or managed full decode | 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) + 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 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 `Titano.Core/Codecs`, pure C#, SIMD where it pays)
- `JpegDecoder` (baseline, progressive, restart intervals, 4:4:4/4:2:2/4:2:0/4:1:1/gray,
12-bit optional, ICC ignored), `JpegEncoder` (baseline, quality 1–100, subsampling
choice, optimised Huffman tables optional, Exif/XMP APP1 embedding).
- `PngDecoder`/`PngEncoder` (all colour types, 8/16-bit, Adam7 decode, filters, zlib via
`System.IO.Compression.ZLibStream`).
- `TiffReader`/`TiffWriter` (as prototype: 16-bit TIFF, linear DNG writer with
`PhotometricInterpretation=34892`).
- `GifEncoder` (animated; median-cut palette + Floyd–Steinberg; frame differencing).
- `ApngEncoder`.
- `AviMjpegWriter` (RIFF AVI with `MJPG`, OpenDML index for > 2 GB).
- `Mp4Muxer` (port of prototype: streaming `ftyp`/`mdat`/`moov`, 90 kHz timescale,
variable durations, `avcC`/`hvcC`; add `av1C` + OBU handling in P1), `AnnexBParser`.
- `Bmff` reader (HEIF/CR3/AVIF boxes), `Riff` reader (WebP/AVI), `Raf` reader.
### 8.4 Image buffers
Port the prototype's `ImageBuffer`/`FrameBufferPool` (pooled float planes, linear light),
`FrameWindow` (sliding window, disk spill under a memory budget, read-ahead), and
`GeometryStage` (crop/aspect/affine with Catmull-Rom). Memory is governed by the window
size and budget, never by sequence length; the self-tests assert this.
### 8.5 Thumbnails and proxies
- Thumbnail: 320 px long edge JPEG q80, packed per sequence in `thumbs.pack` (header,
index table, entries), with an LRU in-memory cache and async loading for the UI.
- Proxy: JPEG at policy long edge (default 1920; options 1280/1920/2560/full), q92, Exif
orientation applied, capture time copied into Exif. Proxies are optional and regenerable;
they enable remote editing, server-side rendering of formats the server cannot decode,
and fast scrubbing.
### 8.6 The only OS executables/dialogs the product may invoke
`SHFormatDrive` (format card), `ShellExecute("open", url)` (links, Store pages),
`ShellExecute("explore", folder)` (reveal in Explorer). Nothing else.
---
## 9. Metadata model and parsers (`Titano.Core/Metadata`)
Port and extend the prototype's binary parsers: container detection by signature; JPEG
segment scan (APP1 Exif, APP1 XMP + extended XMP, APP2 MPF); TIFF/IFD walker with on-demand
window reads (never load a whole RAW to read tags), SubIFD selection of the main image,
`0x02BC` XMP; ISO-BMFF walker (`meta/iinf/iloc` Exif item, CR3 `CMT` boxes, `PRVW`/`THMB`,
track sample tables for the CR3 JPEG); RIFF; RAF; PNG chunks. MakerNote parsing only where
it adds value: Canon/Nikon/Sony/Fuji/Olympus/Panasonic body serial, shutter count, lens
name, exposure mode, image stabilisation flag, intervalometer hints, sRaw flags.
Fields extracted per frame: DateTimeOriginal + SubSecTimeOriginal + OffsetTimeOriginal
(fallback: CreateDate, GPS time, file mtime — recorded with `TimestampSource`), ExposureTime,
FNumber, ISO, FocalLength (+35 mm equiv), ExposureBias, ExposureProgram, MeteringMode,
WhiteBalance mode + Kelvin if present, Flash, Orientation, dimensions, Make/Model/BodySerial,
Lens, GPS (lat/lon/alt), Artist/Copyright, Rating/Label from XMP, `Software`. All parsers
are fuzz-safe (no exception escapes; malformed input yields partial metadata + a warning).
`ExifWriter` (prototype) is kept for proxies/exports: writes a minimal, valid Exif block.
---
## 10. Analysis advisor
Two passes; both deterministic, both explainable (every finding and every recommendation
carries a resource key + parameters that render as a localised reason in tooltips).
### 10.1 Light analysis (at import/scan, metadata only, seconds per 10k frames)
Cadence (median interval, jitter, gaps → session boundaries; `SessionGapMinutes` default
45, `MinimumSessionFrames` 8), total capture span, exposure series (EV =
log2(N²/t) − log2(ISO/100)), exposure step detection (ISO/shutter/aperture changes and
their EV amplitude), camera/lens identity, orientation consistency, resolution
consistency, timestamp sanity (clock resets, duplicates, non-monotonic), format tiers,
GPS → sunrise/sunset/civil twilight via an in-house solar-position calculation (NOAA
algorithm) → day/night/transition labelling.
### 10.2 Deep analysis (background job after import; "speed is not an issue")
Every frame decoded at analysis width (default half native, capped 2048): per-frame
trimmed log-luminance mean, histogram, clip fractions, per-channel means (WB drift), colour
temperature where applicable (McCamy with Planckian-locus validity check), sharpness
(Laplacian variance), noise estimate, phase-correlation shift vs previous frame (shake
magnitude, drift → panning), region mask (horizon by strongest row-luminance step, refined
per column; fallback by luminance), flicker spectrum (autocorrelation of luminance
residuals → deflicker window), exposure steps *as actually received* by the pixels,
star-field detection (small bright point density on night frames), cloud coverage estimate
(sky-region texture), scene-change detection (histogram distance), duplicate/black/white
frames, motion magnitude histogram (for motion-blur recommendation), suggested hero frame.
Results → `analysis.json` + compact summary in DB; charts in the Sequence editor.
### 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. Titano 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 │
│Seq │ 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): full names, collapsible to icons (state saved),
badge counts (warnings, running jobs), hover tooltip with section description.
- 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, Move,
Upload, Download, Delete, Export list as CSV).
- Filters are chips; saved views (e.g. "Night, 4K, not rendered"); search is instant
(indexed columns); everything virtualized (in-house `VirtualizingWrapPanel`).
### 12.3 Sequence editor
```
│ ← Harbour sunset · 3,600 frames · Canon EOS R5 · 2 s interval · 2 h 00 m [Analyse] [Optimise all] [Render ▾] │
├──────────────────────────────────────────────────────────────────┬──────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────┐ │ Exposure │
│ │ │ │ Deflicker [●] Auto 41 ⓘ │
│ │ PREVIEW │ │ Strength ───●──── 0.8 │
│ │ │ │ Regions [●] Auto horizon │
│ │ [◧ compare] [⊹ vectors] [▭ regions] [▦ crop mask] [1:1] [⛶] │ │ Transitions [●] Auto 18 ⓘ │
│ └──────────────────────────────────────────────────────────────┘ │ WB smoothing [●] Auto │
│ ▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏▏ filmstrip + markers │ │
│ [Frames] [Exposure] [Motion] [Camera] [Time] [Stack] [Export] │ [Optimise section] [Reset] │
│ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ measured (amber) vs target (accent) luminance chart, │ │ │
│ │ exposure-step markers, region curves; click = seek preview │ │ │
│ └──────────────────────────────────────────────────────────────┘ │ │
```
- 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.
- Sections (tabs inside the editor; each with its measuring tool below the filmstrip and
its settings column on the right): **Frames** (virtualized table: index, time, exposure,
ISO, f, size, tier, flags; exclude/include; set hero; warnings list), **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), **Export**
(preset, values, output name, batch list, render history, sponsor slot — Phase 9 only).
- Every deducible control shows Auto/manual state (§10.4); every control has a tooltip
with the reason and the effect of moving it the wrong way.
- While a job runs on this sequence, settings that would change the rules mid-render are
disabled; viewing tools stay live.
### 12.4 Import (cards)
```
│ Devices │ Profile "EOS R5 · card A" (SD 128 GB · serial 3F2A-9C11 · Canon EOS R5 #0431) [Edit ▾] [New] │
│ ● SD 128 GB EOS R5 card A ▲ │ Destination (•) Archive ( ) Folder [D:\Shoots …] ( ) Server ☁ "Studio NAS" │
│ ● microSD 64 GB GoPro 12 │ Scan [✓] Subfolders Sessions [✓] gap [45] min · min [8] frames [✓] Verify hashes │
│ ○ E:\ no DCIM │ Names {year}/{date} {camera} / {date}_{time}_{n:0000} → 2026/2026-09-28 Canon EOS R5/2026-09-28_18-02-11_0001.CR2 │
│ ○ Folder… │ On existing (•) Skip ( ) Rename ( ) Overwrite Convert (•) Copy ( ) TIFF-16 ( ) Linear DNG ( ) JPEG │
│ │ After import (•) Keep card ( ) Delete imported ( ) Format card [✓] Eject [✓] Deep analysis │
│ [✓] Import automatically when │ Plan 3 sessions · 4,812 photos · 96.2 GB · 12 min [Show plan] [ Import ▶ ] │
│ a known card is inserted │ │
```
- Devices list: removable volumes and any volume with `DCIM`; identity = volume serial +
label + capacity, camera identity from the first file; known cards show their nickname
and profile; unknown cards prompt for a nickname (one field).
- Plan before touching disk: sessions, folders to be created, first three file names,
duplicates already in the archive (by hash), disk space check.
- Copy with hash while streaming; verify by re-reading destination; only then delete or
format (OS dialog); eject via `IOCTL_STORAGE_EJECT_MEDIA` after `FSCTL_LOCK_VOLUME`.
- Destination "Server" streams frames through the client to the server (§14.4); the
server confirms each hash before the client counts it as imported.
- Auto-import on insertion (per card), with the OS toast "Card X detected — Import".
### 12.5 Archive manager
```
│ [Archive: D:\TitanoArchive ▾] [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] [Move] [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).
### 12.6 Jobs
Queue + history table: kind, target, progress, fps, ETA, node, state; pause/resume/cancel/
retry; log tail on expand; filters. 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, network polling), Import (defaults, session rules, verify, post-actions),
Analysis (widths, thresholds, deep analysis auto-run), Rendering (quality profile, memory
budget, spill folder, parallelism, encoders detected, hardware preference), Formats (per
format tier on this PC, codec install links), Server (last servers, trusted fingerprints,
render node), Updates (check on start), Advanced (portable mode, logs, database backup/
restore, reset). Import/export settings as JSON.
### 12.9 About
Version, build, licence/EULA link, third-party notice (none), diagnostics bundle button
(zips logs + environment report), update check.
---
## 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.
- 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.
- Post-actions: keep / delete imported files (only those verified) / format card (OS
dialog) / eject; run deep analysis automatically (default on, background, low priority).
- Failure handling: card removed mid-copy → partial files deleted, plan resumable on
re-insert; errors listed per file, never a modal per error.
---
## 14. Titano 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 `Titano.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).
### 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-Titano-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
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&tag&q&cursor&limit
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 (sync)
GET /api/v1/sequences/{id}/analysis · GET /stats · GET /renders
GET /api/v1/sequences/{id}/frames?cursor&limit
GET /api/v1/frames/{id}/original · /proxy · /thumb (streamed, Range supported)
POST /api/v1/uploads {sequenceId|null, fileName, size, sha256, capturedAt?} → {uploadId, chunkSize, received[]} | 200 {alreadyExists}
PUT /api/v1/uploads/{id}/chunks/{n} body bytes (idempotent) → {received}
POST /api/v1/uploads/{id}/complete → 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
WS /api/v1/events {type: jobProgress|jobState|sequenceChanged|cardEvent|nodeState, …}
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)
GET /api/v1/i18n/{culture} strings for the web admin
```
### 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.
### 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.
### 14.6 Job engine
Persistent queue in the DB; N worker threads (configurable, default = cores/2); job kinds
in §5; checkpoints every 5 s (progress + resumable cursor); crash-safe restart; priorities
(user-initiated > background analysis); cancellation cooperative; logs per job; retention
of history 90 days.
### 14.7 Render nodes
A Titano 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)
```
┌─────────────┬────────────────────────────────────────────────────────────────────────────┐
│ Titano │ Dashboard │
│ ● Dashboard │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ Users │ │ 9.4 TB │ │ 412 seq │ │ 3 jobs │ │ 2 nodes │ │
│ Archive │ │ of 16 TB │ │ 618k pho │ │ running │ │ online │ │
│ Jobs │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ Settings │ Storage by year ▁▂▃▅▇█ Uploads last 30 days ▂▁▃▆▇▅▂ │
│ Logs │ Recent: alberto uploaded 1,020 frames · node "studio-pc" rendered 4K HEVC │
│ About │ │
└─────────────┴────────────────────────────────────────────────────────────────────────────┘
```
Pages: Login · Dashboard · Users (table; create/edit/disable/reset/roles/quota) · Archive
(path, templates, proxy policy, scan/rebuild/verify, stats) · Jobs (queue/history/nodes,
cancel/retry) · Settings (server name, ports, TLS mode + fingerprint, discovery, limits,
language, retention) · Logs (tail, download) · About. Same UI rules: tooltips only, light/
dark, localised via `/api/v1/i18n`, keyboard accessible.
### 14.9 Configuration and Docker
Environment variables (also readable from `/data/server.json`):
`TITANO_ADMIN_USER`, `TITANO_ADMIN_PASSWORD` (used only when no admin exists; forced change
at first login), `TITANO_ARCHIVE_PATH=/archive`, `TITANO_DATA_PATH=/data`,
`TITANO_DB=postgres|sqlite` (Linux: postgres only), `TITANO_DB_HOST`, `TITANO_DB_PORT=5432`,
`TITANO_DB_NAME`, `TITANO_DB_USER`, `TITANO_DB_PASSWORD`, `TITANO_DB_SSLMODE=prefer`,
`TITANO_HTTP_PORT=8080`, `TITANO_HTTPS_PORT=8443`, `TITANO_TLS_MODE=auto|pem|proxy`,
`TITANO_TLS_CERT`, `TITANO_TLS_KEY`, `TITANO_SERVER_NAME`, `TITANO_LANG=en`,
`TITANO_WORKERS`, `TITANO_DISCOVERY=true` (LAN UDP beacon), `PUID`, `PGID`, `TZ`.
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`, `HEALTHCHECK` on
`/health`, `linux/amd64` + `linux/arm64`. `docker-compose.yml` with a PostgreSQL 17 service.
Windows: `Titano.Server.exe` runs as console or Windows Service (`sc create`), SQLite or
PostgreSQL.
---
## 15. Titano 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.
```
│ Titano 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
`Titano.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 `Titano.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 public releases repo): `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.
- `Titano.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 (`Titano.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.)
- `Titano.Setup` (in-house, WPF, ~one screen): choose components (Titano, Uploader,
Server for Windows), folder, shortcuts, file associations (`.titano` project bundles),
installs to `%LOCALAPPDATA%\Programs\Titano` 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 (`signtool` from the Windows SDK) using
secrets when present; unsigned builds are still produced.
- Updates: on start (opt-out) the client calls the GitHub Releases API of the **public
releases repository** (§19.4) and shows a one-line notice with "Download" (P1: download
installer, verify SHA-256 from `SHA256SUMS`, run it).
- Distribution: installers and `SHA256SUMS` on the public releases repo; Docker images on
GHCR (public package); Unraid template in the public repo.
---
## 19. CI/CD, Docker, Unraid
### 19.1 `ci.yml` (push, PR)
Matrix `windows-latest` / `ubuntu-latest`: `dotnet --info`, restore (no packages → fast),
build with warnings as errors, run `Titano.Testing` for all test projects (JUnit XML
uploaded and annotated), `dotnet format --verify-no-changes`, `Titano.Tools i18n check`,
XAML lint (App.Tests), zero-package guard, Docker build (no push) on ubuntu; PostgreSQL 16
and 17 service containers for `Titano.Data.Tests`; CC0 RAW fixtures fetched by
`Titano.Tools fixtures` and cached (`actions/cache`).
### 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. Only `actions/*` and `docker/*` GitHub
Actions are used in workflows.
### 19.3 `release.yml` (tag `v*`)
Version from the tag → `Directory.Build.props`; publish self-contained binaries; build
`Titano-Setup-<ver>.exe`, `Titano-Uploader-Setup-<ver>.exe`, `Titano-Server-win-x64-<ver>.zip`;
sign if secrets present; generate `SHA256SUMS` and the changelog (`Titano.Tools changelog`
from Conventional Commits); build and push multi-arch Docker image to
`ghcr.io/<org>/titano-server:<ver>` and `:latest`; create the GitHub Release **in the
public releases repository** with `gh release create` (the `gh` CLI is preinstalled on
runners) using a fine-grained PAT stored as `RELEASES_TOKEN`; copy `deploy/unraid/
titano.xml` and EULA there.
### 19.4 Public releases repository
Because release assets of a private repository are not publicly downloadable, a second,
public repository (`titano-releases`) holds only: README (what it is, screenshots,
requirements), EULA/LICENSE, release assets, `SHA256SUMS`, Unraid template, `i18n/`
translations for community review, and issues. The private repo publishes into it; nothing
is developed there. The GHCR package is set to public visibility.
### 19.5 `docker.yml`
Nightly build of `main` to `ghcr.io/<org>/titano-server:nightly`; `deploy/docker/
docker-compose.yml` for users (server + PostgreSQL + volumes).
### 19.6 Unraid template (`deploy/unraid/titano.xml`)
Community Applications XML: repository `ghcr.io/<org>/titano-server:latest`, WebUI
`http://[IP]:[PORT:8080]/admin`, ports 8080/8443, paths `/archive` → `/mnt/user/Timelapse`,
`/data` → `/mnt/user/appdata/titano`, variables from §14.9 (admin user/password, DB
host/port/name/user/password, TLS mode, PUID/PGID, TZ), icon URL from the public repo,
support/project links, description ≤ 2 sentences. Document (in the public README) how to
add the template repository URL in Unraid and to pair with the official PostgreSQL
template.
---
## 20. Testing and quality
### 20.1 `Titano.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 `Titano.Tools fixtures` into `tests/fixtures/external`
(git-ignored, CI-cached).
### 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
`Titano.Core`/`Titano.Data`/`Titano.Protocol`/`Titano.Server` (checked by building them on
Linux); public API of `Titano.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 `https://<org>.github.io/titano-releases/ads/manifest.json`
(or a URL set by the human), 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: "Titano 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 `TitanoAdsEnabled=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`;
`Titano.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; `Titano.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`, public releases repo bootstrap
(README, EULA draft, template), 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 **Titano** kept from the prototype — rename before Phase 0 if desired
(repo-wide rename later is costly).
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.
---
## Appendix A — `CLAUDE.md` content (create verbatim in Phase 0, keep updated)
```markdown
# Titano — 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.
- Titano.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: green on windows-latest + ubuntu-latest, 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/Titano.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/titano-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/*`, `Titano.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).