diff --git a/docs/reference/original/README.md b/docs/reference/original/README.md new file mode 100644 index 00000000..1e233c19 --- /dev/null +++ b/docs/reference/original/README.md @@ -0,0 +1,13 @@ +# Original documentation + +The documentation the project started from, kept as it was delivered. The product was then called **Titano**; it became **Chronos** later (see DECISIONS). + +These files are frozen history. The current rules are in `docs/BRIEF.md`, `docs/ui/DESIGN.md` and `docs/ui/mockups/`, and they win where they differ from what is here. + +| Path | What it is | +|---|---| +| `titano-ui-kit/BRIEF.md` | The original build brief | +| `titano-ui-kit/DESIGN.md` | The original design tokens and controls | +| `titano-ui-kit/mockups/*.html` | The original screen mockups (open them in a browser) | +| `titano-ui-kit/branding/` | The original app, server and uploader icons | +| `titano-icon-sheet.png` | The original icon sheet | diff --git a/docs/reference/original/titano-icon-sheet.png b/docs/reference/original/titano-icon-sheet.png new file mode 100644 index 00000000..f2b2743c Binary files /dev/null and b/docs/reference/original/titano-icon-sheet.png differ diff --git a/docs/reference/original/titano-ui-kit/BRIEF.md b/docs/reference/original/titano-ui-kit/BRIEF.md new file mode 100644 index 00000000..6a5f2d75 --- /dev/null +++ b/docs/reference/original/titano-ui-kit/BRIEF.md @@ -0,0 +1,1346 @@ +# 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 `` 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`, `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 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 OpenAsync(CancellationToken ct); // connection from pool +} +public interface IDbSession : IAsyncDisposable { + Task ExecuteAsync(string sql, params DbParam[] p); + IAsyncEnumerable QueryAsync(string sql, params DbParam[] p); + Task BeginAsync(); + Task BulkInsertAsync(string table, IReadOnlyList columns, IAsyncEnumerable 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. + +``` +/ +├── .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-.exe`, `Titano-Uploader-Setup-.exe`, `Titano-Server-win-x64-.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//titano-server:` 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//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//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://.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 ` 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 . 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/ -- --junit out.xml; tools: dotnet run --project src/Titano.Tools -- . +- 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). diff --git a/docs/reference/original/titano-ui-kit/DESIGN.md b/docs/reference/original/titano-ui-kit/DESIGN.md new file mode 100644 index 00000000..6bcfbea5 --- /dev/null +++ b/docs/reference/original/titano-ui-kit/DESIGN.md @@ -0,0 +1,119 @@ +# Titano — Design reference for Claude Code + +Companion to `docs/BRIEF.md` §12 (UI spec). Suggested repo placement: +`docs/ui/DESIGN.md` (this file), `docs/ui/mockups/*.html` (open in any browser; +each file is one screen at its natural size, links between screens work), `branding/` +(icon sources). The mockups are the visual target; where a mockup and the brief disagree +on behaviour, the brief wins; where they disagree on looks, the mockup wins. + +## 1. Tokens → WPF resource dictionary (`Titano.App/Themes/Dark.xaml`, `Light.xaml`) + +| Key (SolidColorBrush) | Dark | Light | Use | +|---|---|---|---| +| `Brush.Bg` | #1F1F23 | #F3F3F3 | window background | +| `Brush.Chrome` | #1A1A1E | #FFFFFF | title bar, rail, status bar, web sidebar | +| `Brush.Surface` | #26262C | #FFFFFF | panels, toolbars, dialogs | +| `Brush.Card` | #2F3038 | #FFFFFF | cards, inputs, buttons, hovered rows | +| `Brush.Stroke` | #3E404A | #E5E5E5 | 1 px borders and dividers | +| `Brush.Text` | #F2F3F5 | #1A1A1A | primary text | +| `Brush.TextMuted` | #A9AEB9 | #616161 | secondary text, labels | +| `Brush.TextFaint` | #7B818E | #9E9E9E | hints, column headers, disabled | +| `Brush.Accent` | #4CC2FF | #0067C0 | primary button, active rail edge, links, Auto | +| `Brush.OnAccent` | #0B1B24 | #FFFFFF | text on accent | +| `Brush.AccentSelected` | rgba(76,194,255,.25) | #E8F1FA | selection glow / selected nav | +| `Brush.Sun` | #F5A524 | #E08A1E | manual slider track, uploader accent, icon sun | +| `Brush.Success` | #35C48F | #0F7B4F | analysed, in sync, done | +| `Brush.Warning` | #E8B339 | #9A6700 | warnings, destructive outline | +| `Brush.Error` | #F0625D | #C42B1C | errors, failed | +| `Brush.Region` | #5AD1C8 | #1A9E95 | sky/landscape region masks only | + +Dark is the client default; Light follows the OS setting; the web admin is Light-only. +Never use colour alone to carry state: pair it with a glyph (● ○ ◐ ▲ ✕ ▶) or a word. + +## 2. Type (Segoe UI Variable, fallback Segoe UI; `FontSize` keys) + +`Text.PageTitle` 18/600 · `Text.Title` 16/600 · `Text.Section` 14/600 · `Text.Body` 13/400 +· `Text.Secondary` 12/400 muted · `Text.Chip` 11/400. Line heights 24/22/20/18/16/14. +Numbers in tables use tabular figures (`Typography.NumeralAlignment="Tabular"`). +Layout must survive +40 % text width (de, fi): no fixed-width labels, `MinWidth` only. + +## 3. Spacing, radii, sizes + +Spacing scale 4 · 8 · 12 · 16 · 20 (`Thickness` keys `Space.1`…`Space.5`). +Radii: 6 controls · 8 cards/panels · 12 pills · 12 modal dialogs. +Controls 32 px tall, 44 px minimum width, 12 px horizontal padding; compact row buttons 26–28 px. +Rail 128 px (collapses to 48 px icons); title bar 34; job bar 40; toolbar 56; status bar 30; +table rows 36–40 (52 in the web admin); side panels 320 px; settings section list 200 px. +Label column left of controls: 116 px in panels, 180 px in Settings. + +## 4. Controls and states (see `Components.html`) + +- **Button**: Card fill, Stroke border. Hover +6 % lightness, pressed −6 %, focus = 2 px + Accent ring outside. **Primary** (Accent fill, OnAccent text, 600) — one per screen. + **Destructive** = Warning outline, transparent fill, never a primary. **Subtle** = no border + until hover. **Toggled** = Accent text + Accent border. **Disabled** = 40 % opacity and the + tooltip says why. Icon-only buttons carry `AutomationProperties.Name` and a tooltip. +- **Inputs**: Card fill, Stroke border, Accent border on focus, Error border when invalid with + the message in the tooltip (never a line of text under the field). Enter commits, Esc reverts. +- **Slider — Auto/manual** (brief §10.4): Auto state = Accent track, dimmed thumb, an `Auto · 41` + pill at the right whose tooltip gives the advisor's reason; touching it turns the track Sun + (manual), shows the value, and a `⟲` reset button returns to Auto. Not applicable = greyed + value "n/a" with the reason in its tooltip. +- **Status glyphs**: `●` green Analysed · `○` faint Not analysed · `●` Proxies · `▶ n` rendered + · `●` accent Synced/Remote · `◐` amber Analysing · `▲ n` warnings · `✕ n` errors. +- **Chips**: 24 px pills, Card fill, Stroke border; selected/recommended = Accent border and text. +- **Progress**: 6 px bar, Accent fill, text to the right; indeterminate = sliding highlight. +- **Tooltip**: light on dark (#F2F3F5 on dark, #1A1A1A text), 12 px, one line: action + cost + + shortcut ("Read every frame again · about 6 min · Ctrl+Shift+A"); 400 ms delay; ≤ 200 chars. + Every interactive element has one. There is no other explanatory text in the UI. +- **Dialog**: Surface fill, Stroke border, radius 12, 24 px shadow, two buttons maximum, safe + action left and default, destructive on the right with typed confirmation for formatting. +- **Toast**: bottom-right, 420 px, Card fill with a 3 px Accent left edge, one action button, + 8 s, hover pauses. Used for card insertion, render done, server messages. +- **Job bar**: 40 px strip under the title bar in every client screen: current job, progress, + time left, pause; hidden when idle only in the editor (it shows "Ready" elsewhere). +- **Rail item**: 36 px; active = Card fill + 3 px Accent left edge; badge = Accent pill with + the count of things needing attention. +- **Cards** (Library): 236 px wide, thumbnail 16:9, count badge top-right, checkbox top-left on + hover/selection, selected = Accent border + `AccentSelected` glow; hover scrubs the thumbnail. +- **Tables**: header 11 px faint, sortable; rows Card fill on hover; numbers right-aligned, + tabular; virtualised beyond 200 rows; row actions are 26 px buttons revealed on the row. + +## 5. Icons + +16 px, 1.5 px strokes, round caps and joins, `currentColor`, drawn as `PathGeometry` / +`DrawingImage` resources in `Titano.App/Icons/Icons.xaml` (source SVGs in `branding/ui-icons/` +if generated by a tool). No icon fonts, no emoji in shipped UI (the mockups use a few glyphs +only as placeholders: replace ⟳ ▾ ✕ ■ ❚❚ ≡ with drawn icons). Directional icons mirror in RTL. + +## 6. App icon (`branding/`) + +`titano.svg` is the master: 256 plate radius 56 #1A1A1E, ring r 92, 12 ticks of 12° with 18° +gaps, stroke 20 round caps, opacity 0.14 → 1.0 clockwise from 12 o'clock, sun disc at +(152,104) r 30 #F5A524. Variants: `titano-server.svg` (rack badge), `titano-uploader.svg` +(up-arrow badge), `titano-mono.svg` (white, no plate, for the tray). PNG renders at +16/32/48/64/128/256 are reference output; `Titano.Tools make-icon` must regenerate ICO/PNG +from the SVG geometry (no raster assets checked in as sources). Badges only at ≥ 48 px. + +## 7. Screen-by-screen notes (mockup → brief section) + +| Mockup | Brief | Notes | +|---|---|---| +| `Main.html` | §12.2 Library | grid/list, year·camera·status filters, selection panel | +| `Editor.html` | §12.3 Sequence editor | Exposure tab, wipe compare, curves, advisor Auto pills | +| `Export.html` | §12.3 / §11.4 | preset cards with size/time estimate, Output panel, batch | +| `Import.html` | §12.4 / §13 | card profile, sessions, plan, verification, after-import actions | +| `Archive.html` | §12.5 | tree, mass operations, stats, verify/rebuild, maintenance | +| `Jobs.html` | §12.6 | filters, queue order, expandable log, retry/open/folder | +| `Server.html` | §12.7 / §14 | connection with TOFU fingerprint, account and quota, render node, sync table, conflicts | +| `Settings.html` | §12.8 | section list, Rendering section, encoder table, self-test | +| `Welcome.html` | §12.1 | first run: local archive / adopt folder / connect; consent line; card toast | +| `Admin.html` | §14.7 | dashboard | +| `AdminUsers.html` | §14.7 | users table, roles, quotas, temporary password, render-node right | +| `Uploader.html` | §15 | single window, watch folder, queue, tray | +| `Components.html` | §12.1 | the control kit above, with hex values and state rules | +| `Icon.html` | §17 | construction, sizes, variants, wordmark | + +Missing on purpose (build from the brief and this kit): About, Login dialog, the other editor +tabs (Frames, Motion, Camera, Time, Stack), Import "Show plan", Archive rebuild dialog, the +admin Archive/Jobs/Settings/Logs pages. Reuse the shell and the kit; do not invent new colours. diff --git a/docs/reference/original/titano-ui-kit/branding/titano-128.png b/docs/reference/original/titano-ui-kit/branding/titano-128.png new file mode 100644 index 00000000..b5ee30fb Binary files /dev/null and b/docs/reference/original/titano-ui-kit/branding/titano-128.png differ diff --git a/docs/reference/original/titano-ui-kit/branding/titano-16.png b/docs/reference/original/titano-ui-kit/branding/titano-16.png new file mode 100644 index 00000000..bcedc8e1 Binary files /dev/null and b/docs/reference/original/titano-ui-kit/branding/titano-16.png differ diff --git a/docs/reference/original/titano-ui-kit/branding/titano-256.png b/docs/reference/original/titano-ui-kit/branding/titano-256.png new file mode 100644 index 00000000..67133730 Binary files /dev/null and b/docs/reference/original/titano-ui-kit/branding/titano-256.png differ diff --git a/docs/reference/original/titano-ui-kit/branding/titano-32.png b/docs/reference/original/titano-ui-kit/branding/titano-32.png new file mode 100644 index 00000000..76e45193 Binary files /dev/null and b/docs/reference/original/titano-ui-kit/branding/titano-32.png differ diff --git a/docs/reference/original/titano-ui-kit/branding/titano-48.png b/docs/reference/original/titano-ui-kit/branding/titano-48.png new file mode 100644 index 00000000..cdc1dc43 Binary files /dev/null and b/docs/reference/original/titano-ui-kit/branding/titano-48.png differ diff --git a/docs/reference/original/titano-ui-kit/branding/titano-64.png b/docs/reference/original/titano-ui-kit/branding/titano-64.png new file mode 100644 index 00000000..8f431728 Binary files /dev/null and b/docs/reference/original/titano-ui-kit/branding/titano-64.png differ diff --git a/docs/reference/original/titano-ui-kit/branding/titano-icon-sheet.png b/docs/reference/original/titano-ui-kit/branding/titano-icon-sheet.png new file mode 100644 index 00000000..71fecbf1 Binary files /dev/null and b/docs/reference/original/titano-ui-kit/branding/titano-icon-sheet.png differ diff --git a/docs/reference/original/titano-ui-kit/branding/titano-mono-256.png b/docs/reference/original/titano-ui-kit/branding/titano-mono-256.png new file mode 100644 index 00000000..e40e00bf Binary files /dev/null and b/docs/reference/original/titano-ui-kit/branding/titano-mono-256.png differ diff --git a/docs/reference/original/titano-ui-kit/branding/titano-mono.svg b/docs/reference/original/titano-ui-kit/branding/titano-mono.svg new file mode 100644 index 00000000..58642c70 --- /dev/null +++ b/docs/reference/original/titano-ui-kit/branding/titano-mono.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/reference/original/titano-ui-kit/branding/titano-server-256.png b/docs/reference/original/titano-ui-kit/branding/titano-server-256.png new file mode 100644 index 00000000..4da363c8 Binary files /dev/null and b/docs/reference/original/titano-ui-kit/branding/titano-server-256.png differ diff --git a/docs/reference/original/titano-ui-kit/branding/titano-server.svg b/docs/reference/original/titano-ui-kit/branding/titano-server.svg new file mode 100644 index 00000000..7cd565b2 --- /dev/null +++ b/docs/reference/original/titano-ui-kit/branding/titano-server.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/reference/original/titano-ui-kit/branding/titano-uploader-256.png b/docs/reference/original/titano-ui-kit/branding/titano-uploader-256.png new file mode 100644 index 00000000..fd1844ac Binary files /dev/null and b/docs/reference/original/titano-ui-kit/branding/titano-uploader-256.png differ diff --git a/docs/reference/original/titano-ui-kit/branding/titano-uploader.svg b/docs/reference/original/titano-ui-kit/branding/titano-uploader.svg new file mode 100644 index 00000000..31fd2675 --- /dev/null +++ b/docs/reference/original/titano-ui-kit/branding/titano-uploader.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/reference/original/titano-ui-kit/branding/titano.svg b/docs/reference/original/titano-ui-kit/branding/titano.svg new file mode 100644 index 00000000..fb2f35ed --- /dev/null +++ b/docs/reference/original/titano-ui-kit/branding/titano.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/reference/original/titano-ui-kit/mockups/Admin.html b/docs/reference/original/titano-ui-kit/mockups/Admin.html new file mode 100644 index 00000000..fe0ac6f5 --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Admin.html @@ -0,0 +1,118 @@ + + + + +Titano Server — Admin dashboard + + + +
+ +
+
+ Dashboard + up 12 d 4 h · PostgreSQL 17 · TLS auto · discovery on + + + + +
+
+
+
+ Storage + 9.4 TBof 16 TB +
+ 6.6 TB free · exports 210 GB · proxies 610 GB +
+
+ Archive + 412sequences + 618,204 photos · 14 cameras · last scan 07:12 + 3 sequences without proxies +
+
+ Jobs + 3running + 12 queued · 41 done today · 0 failed + workers 4 of 4 busy +
+
+ Render nodes + 2online + studio-pc · NVENC HEVC/H.264/AV1 · busy + laptop-alb · QSV HEVC/H.264 · idle +
+
+
+
+ Storage by year + +
+
+
Uploads · last 30 daysframes per day · 96,410 total · peak 12,400
+ +
+
+
+
+
Recent activityAll logs
+
+ 09:41alberto uploaded 1,020 frames to Construction cam · week 38 + 09:12studio-pc rendered Milan skyline dusk · 4K HEVC · 2 min 41 s + 08:55uploader roof-cam signed in from 192.168.1.44 + 08:30admin set export retention to 180 days + 07:12scheduled scan finished · 412 sequences · 0 changes + 06:00database backup · /data/backups/2026-09-30.sql.gz · 190 MB + 23:04admin created user giulia · Editor · quota 2 TB +
+
+
+ +
+ KindTargetNodeProgressState + RenderHarbour sunset → 4K 10-bit HEVCstudio-pc
62 %
running + Deep analysisConstruction cam · week 38server
28 %
running + ProxiesComet over the ridgeserver
91 %
running + VerifyArchive · 2024server
—
queued + RenderAurora, Tromsø → 1080p share H.264laptop-alb
—
queued +
+
+
+
+
+
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/AdminUsers.html b/docs/reference/original/titano-ui-kit/mockups/AdminUsers.html new file mode 100644 index 00000000..faffd14d --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/AdminUsers.html @@ -0,0 +1,76 @@ + + + + +Titano Server — Users + + + +
+ +
+
+ Users + 6 accounts · 5 active · roles: admin, editor, uploader, viewer + + + + +
+
+
+
UserRoleQuotaLast seenUploads 30 dStatus
+
AadminAdministrator · created at first startAdmin—now · 192.168.1.100● Active
+
AalbertoAlberto · render node studio-pcEditor
2.1 of 5 TB
10:15 · client 1.3.014,208● Active
+
GgiuliaGiulia · must change passwordEditor
0.1 of 2 TB
09:20 · client 1.3.0640● Active
+
Rroof-camUploader on the roof PC · watch folderUploader
0.6 of 1 TB
08:55 · uploader 1.3.081,320● Active
+
MmarcoMarco · clientViewer—2026-09-140● Active
+
SsimoneSimone · disabled 2026-08-30Editor
0.4 of 2 TB
2026-08-290○ Disabled
+ +
Passwords: PBKDF2-SHA512, 12 characters minimum · tokens expire after 30 days idleSign-in log
+
+ +
+
+
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/Archive.html b/docs/reference/original/titano-ui-kit/mockups/Archive.html new file mode 100644 index 00000000..8837fc49 --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Archive.html @@ -0,0 +1,142 @@ + + + + +Titano — Archive manager + + + +
+
+ + Titano — Archive + + —▢✕ +
+
+ +
+
+
+ Verify · 6.7 of 9.4 TB · 410 MB/s · 1 h 52 min left · 0 errors + +
+
+
+ + + + + + + + + + + Last scan 2026-09-29 07:12 · 14 min +
+
+
618,204photos
+
412sequences · 1,309 loose photos
+
9.4 TBoriginals · 610 GB proxies · 1.8 GB thumbnails
+
14cameras · 9 formats
+
2019 – 2026316 rendered · 84 never rendered · 12 not analysed
+
+
+
+
Photos per month021k
+ +
+
+ Storage by year + +
+
+ By camera + +
+
+ By format + +
+
+
+
+ Index health +
Sidecars 412 / 412 · database matches the disk
+
3 sequences without proxies
+
1 sequence not verified in 90 days
+
Database 214 MB · thumbnail pack 1.8 GB · 0 orphans · 0 duplicates
+
Network root reachable · SMB · 118 MB/s read
+
+
+
Recent maintenance
+
+ 2026-09-29Verify · running71 % + 2026-09-20Verify · 9.4 TB0 errors + 2026-09-01Vacuum · 231 → 214 MBdone + 2026-08-14Rebuild index · 412 sidecarsdone + 2026-08-02Backup · D:\Backups\titano-2026-08-02.dbdone +
+
+
+
+ Filtered set + + + + + + + + + + + +
+
+
+ 412 sequences618,204 photos9.4 TBConnected to "Studio NAS"1 job +
+
+
+
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/Components.html b/docs/reference/original/titano-ui-kit/mockups/Components.html new file mode 100644 index 00000000..7dfa392c --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Components.html @@ -0,0 +1,193 @@ + + + + +Titano — UI kit + + + +
+
+ COLOURS · CLIENT (DARK, DEFAULT) +
+
Bg #1F1F23
+
Chrome #1A1A1E
+
Surface #26262C
+
Card #2F3038
+
Stroke #3E404A
+
Text #F2F3F5
+
Muted #A9AEB9
+
Faint #7B818E
+
Accent #4CC2FF
+
On accent #0B1B24
+
Sun #F5A524
+
Success #35C48F
+
Warning #E8B339
+
Error #F0625D
+
+ Region teal #5AD1C8 only for sky/landscape masks · one accent per screen · never colour alone: pair with a shape or a word +
+
+ COLOURS · LIGHT THEME & WEB ADMIN +
+
Bg #F3F3F3
+
Card #FFFFFF
+
Stroke #E5E5E5
+
Text #1A1A1A
+
Muted #616161
+
Accent #0067C0
+
+ Selected nav #E8F1FA · sun #E08A1E · success #0F7B4F · warning #9A6700 · error #C42B1C +
+
+ TYPE · SPACING · RADII + Page title 18 / 600 + Sequence title 16 / 600 + Section 14 / 600 + Body and controls 13 / 400 + Secondary 12 / 400 muted + Chips and axis labels 11 / 400 +
+ + 4 · 8 · 12 · 16 · 20 px + + 6 control · 8 card · 12 pill +
+
+
+ BUTTONS · 32 PX · MIN WIDTH 44 +
+ + + +
+
+ + + + +
+
+ + +
+ Hover +6 % lightness · pressed −6 % · focus ring 2 px accent outside · every button has a tooltip +
+
+ INPUTS · SELECTION + +
+ + + +
+ +
+ + + + + +
+ Labels left of the control, 116 px column · placeholder never replaces a label · Enter commits, Esc reverts +
+
+ SLIDERS · AUTO / MANUAL +
+
+ +
+
+
0.80
+ +
+
Colour temperaturen/a
+ Accent track = Auto · sun track = manual · greyed with reason = not applicable · values edit on double-click +
+
+ STATUS · PROGRESS · TOOLTIP +
+ ● Analysed○ Not analysed● Proxies▶ 2 rendered● Synced● Remote◐ Analysing▲ 1 warning✕ 2 errors +
+
+ sunset ✕ + holy grail ✕ + Recommended +
+
Determinate 6 px · text to the right, never inside
+
Indeterminate: sliding highlight
+
+ +
Read every frame again and refresh the analysis · about 6 min · Ctrl+Shift+A
+
+ Tooltip: one line, action + cost + shortcut · shows after 400 ms · light on dark +
+
+ DIALOG · DESTRUCTIVE CONFIRM +
+ Format EOS R5 · card A? + 4,812 photos were copied and verified. Formatting removes everything on the card. + +
+ + +
+
+ Two buttons max · safe action left and default · destructive never primary · Esc = safe +
+
+ TOAST · JOB BAR · RAIL +
+ + EOS R5 · card A inserted4,812 photos · 96.2 GB · 3 sessions + + +
+
+
+ Building proxies · 1,240 / 3,600 · 3 min left + +
+
+
+ Library + Import + Jobs2 +
+ Rail 128 px, collapses to 48 px icons · active = card fill + 3 px accent edge · badge = count needing attention · toast bottom-right, 8 s, hover pauses +
+
+
+ EMPTY STATE · SEQUENCE CARD · TABLE ROW +
+
+ + No sequences yet +
+ + + +
+
+
+
+
3,600
+
Harbour sunsetCanon EOS R5 · 2 h 00 m
● Analysed● Proxies▶ 2
+
+ Selected card: accent border + glow · thumbnail is the first analysed keyframe, hover scrubs +
+
+
SequenceCameraFramesState
+
Harbour sunsetCanon EOS R53,600● ok
+
Comet over the ridgeGoPro HERO81,005▲ 1
+
Aurora, TromsøNikon Z 81,860● sync
+ Rows 36 px · hover = card fill · numbers right-aligned in real tables · sortable headers · virtualised past 200 rows +
+
+
+
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/Editor.html b/docs/reference/original/titano-ui-kit/mockups/Editor.html new file mode 100644 index 00000000..3e013a8f --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Editor.html @@ -0,0 +1,114 @@ + + + + +Titano — Sequence editor + + + +
+
+ + Titano — Harbour sunset + + —▢✕ +
+
+ +
+
+ ← + Harbour sunset + 3,600 frames · Canon EOS R5 · 2 s interval · 2 h 00 m · 3 warnings + + + + +
+
+
+
+
+
+
+
original | corrected
+
+ + + + + + +
+
0413 / 3,600 · 18:02:11 · 1/8 s · f/8 · ISO 400 · 24 mm
+
+
+
▼▼▼▼
+
+
+
+
+
+ + + + + + + +
+
+
— measured luminance— target curve- - sky region▼ exposure steps as receivedflicker −67 % · max step 0.21 EV
+ +
+
+ +
+
+
+
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/Export.html b/docs/reference/original/titano-ui-kit/mockups/Export.html new file mode 100644 index 00000000..16814484 --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Export.html @@ -0,0 +1,102 @@ + + + + +Titano — Sequence editor · Export + + + +
+
+ + Titano — Harbour sunset + + —▢✕ +
+
+ +
+
+ ← + Harbour sunset + 3,600 frames · 24 fps · 2 min 30 s · 3840×2160 source 8192×5464 + + + + +
+
+
+
+
+
+ + + +
+
0413 / 3,600 · 00:17.2 of 02:30 · output 3840×2160
+
+
+
+
+
+ + + + + + + +
+
+ + + + + + + + +
+
+ +
+
+
+
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/Icon.html b/docs/reference/original/titano-ui-kit/mockups/Icon.html new file mode 100644 index 00000000..b45593f5 --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Icon.html @@ -0,0 +1,80 @@ + + + + +Titano — Icon + + + +
+ + + + + + + + + + + + + + + + + + + + + + plate 256 · radius 56 · ring r 92 · stroke 20 · sun (152,104) r 30 + + 12 ticks of 12°, 18° gaps, round caps — a clock face and an intervalometer at once. + Opacity 0.14 → 1.0 clockwise from 12 o'clock: time accumulating, exposure ramping. + The sun sits off-centre, north-east, the way it does in every sunset shot. + Two colours only: accent #4CC2FF on plate #1A1A1E, sun #F5A524. No gradients, no text. + Generated by `Titano.Tools make-icon` into ICO (16–256), PNG, and the WPF DrawingImage. + + + ON DARK + + + + + + 12864483216 + + + ON LIGHT + + + + + + + VARIANTS + + + + Titano ServerTitano UploaderTray · monochrome · no plate + + WORDMARK · Segoe UI Variable Display Semibold, tracking −1 %, cap height aligned to the ring + + Titano + + Titano Server + + Titano Uploader + + Clear space around the mark: one tick length (40/256) on every side. Never rotate, recolour or add a drop shadow. + Badges only at 48 px and above; below that the Server and Uploader use the plain mark and their window title. + Installer, Store listing, GitHub social preview and the Unraid template icon all use the 256 px PNG. + + +
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/Import.html b/docs/reference/original/titano-ui-kit/mockups/Import.html new file mode 100644 index 00000000..3f1f14da --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Import.html @@ -0,0 +1,154 @@ + + + + +Titano — Import + + + +
+
+ + Titano — Import + + —▢✕ +
+
+ +
+
+
+ Ready · 0 jobs queued +
+
+ +
+
+ EOS R5 · card A + SD 128 GB · serial 3F2A-9C11 · Canon EOS R5 #0431 · last import 2026-09-21 + + + +
+
+ Destination +
+ + + + + + Studio NAS +
+ Scan +
+ + + gap min + min frames + +
+ Names +
+
+ + / + + +
+ → 2026/2026-09-28 Canon EOS R5/2026-09-28_18-02-11_0001.CR2 +
+ On existing +
+ + + +
+ Convert +
+ + + + +
+ After import +
+ + + + + + +
+
+
+
+ Plan + 3 sessions · 4,812 photos · 96.2 GB · about 12 min + + 0 duplicates + 2.1 TB free after import +
+
+ SessionFrames · intervalSizeCameraSequence + 2026-09-28 · 18:02 → 20:043,600 · 2 s72.4 GBEOS R5new · 2026-09-28 Canon EOS R5 + 2026-09-27 · 05:41 → 06:571,140 · 4 s22.6 GBEOS R5new · 2026-09-27 Canon EOS R5 + 2026-09-26 · 21:10 → 23:3472 · 120 s1.2 GBEOS R5loose photos +
+ +
+ + + +
+
+
+
+
+ 412 sequences618,204 photos9.4 TBConnected to "Studio NAS"0 jobs +
+
+
+
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/Jobs.html b/docs/reference/original/titano-ui-kit/mockups/Jobs.html new file mode 100644 index 00000000..9a391d65 --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Jobs.html @@ -0,0 +1,80 @@ + + + + +Titano — Jobs + + + +
+
+ + Titano — Jobs + + —▢✕ +
+
+ +
+
+
+ Render · Harbour sunset · 2,232 / 3,600 · 11.3 fps · 2 min left + +
+
+ + + + + + + + + + Workers 4 / 4 · GPU NVENC busy + + +
+
+
KindTargetProgressSpeedLeftWhereState
+
RenderHarbour sunset → 4K 10-bit HEVC · 24 fps
62 %
11.3 fps2 minthis PC · NVENCrunning
+
+
10:14:02 window 41 · deflicker −67 % · 3 exposure steps redistributed over 18 frames
+
10:14:03 stabilisation on · mean shake 0.42 px · crop 1.8 %
+
10:14:03 encoder NVENC HEVC Main10 · 3840×2160 · 120 Mb/s · 24 fps · GOP 48
+
10:15:41 frame 2232 / 3600 · 11.3 fps · spill 0 · memory 6.1 GB of 8 GB budget
+
+
Deep analysisConstruction cam · week 38
28 %
41 fps6 minthis PCrunning
+
UploadComet over the ridge → Studio NAS
46 %
38 MB/s4 minnetworkrunning
+
ProxiesComet over the ridge
91 %
118 fps8 sthis PCrunning
+
RenderAurora, Tromsø → 1080p share H.264
—
—after 1this PCqueued
+
VerifyArchive · 2024
—
—after 2this PCqueued
+
VerifyStar trails, Colle del Nivolet
100 %
—09:58this PCfailed · 2
+
RenderMilan skyline dusk → 4K HEVC
100 %
14.8 fps09:12studio-pcdone · 2:41
+
ImportEOS R5 · card A → Archive · 4,812 photos
100 %
410 MB/s08:41this PCdone · 11:52
+
Thumbnails2026-09-27 Sony ILCE-7M4
100 %
2,300 fps08:42this PCdone · 0:01
+ +
History keeps 90 days · 1,412 jobsFailed jobs retry automatically 3× with backoff, then wait for youRendering settings
+
+
+ 412 sequences618,204 photos9.4 TBConnected to "Studio NAS"4 jobs +
+
+
+
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/Main.html b/docs/reference/original/titano-ui-kit/mockups/Main.html new file mode 100644 index 00000000..ba11bd8a --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Main.html @@ -0,0 +1,101 @@ + + + + +Titano — Library + + + +
+
+ + Titano + + —▢✕ +
+
+ +
+
+
+ Building proxies · Harbour sunset · 1,240 / 3,600 · 12 fps · 3 min left + +
+
+ + + + + + + + + + + + +
+
+
+
+
Harbour sunset3,600 · Canon EOS R5 · 2 h 00 m
● Analysed● Proxies▶ 2● Synced
+
+
+
+
Comet over the ridge1,005 · GoPro HERO8 · 5 h 34 m
● Analysed● Proxies▲ 1
+
+
+
+
2026-09-27 Sony ILCE-7M42,140 · Sony A7 IV · 1 h 11 m
● Analysed○ Proxies
+
+
+
+
Aurora, Tromsø1,860 · Nikon Z 8 · 4 h 08 m
● Analysed● Proxies● Synced
+
+
+
+
Construction cam · week 388,920 · Brinno · 7 d
◐ Analysing● Remote
+
+
+
+
Milan skyline dusk2,400 · iPhone 16 Pro · 1 h 20 m
● Analysed● Proxies▶ 1
+
+
+
+
Clouds over the Langhe1,320 · Canon EOS R5 · 44 m
○ Analysed○ Proxies
+
+
+
+
Star trails, Colle del Nivolet640 · Sony A7 IV · 5 h 20 m
● Analysed● Proxies▶ 3
+
+
+
+
Fog lifting, Asti980 · DJI Osmo Action 5 · 1 h 38 m
● Analysed○ Proxies
+
+
+
+
Holy grail · Monviso1,720 · Nikon Z 8 · 3 h 02 m
● Analysed● Proxies▶ 1● Synced
+
+
+
+ 412 sequences618,204 photos9.4 TBConnected to "Studio NAS"3 jobs +
+
+
+
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/Server.html b/docs/reference/original/titano-ui-kit/mockups/Server.html new file mode 100644 index 00000000..f865587e --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Server.html @@ -0,0 +1,112 @@ + + + + +Titano — Server + + + +
+
+ + Titano — Server + + —▢✕ +
+
+ +
+
+
+ Upload · Comet over the ridge · 46 % · 38 MB/s · 4 min left + +
+
+
+
+
+ + + + +
+
+ Status + Connected + ·Studio NAS · v1.3.0 · 14 ms + ·TLS 9A:3C:71:E0:… trusted 2026-09-01 + +
+
+ Account + A + alberto·Editor· +
2.1 TB of 5 TB + + + +
+
+ + NVENC HEVC · H.264 · AV1 + + + +
+
+
+
Render nodeBusy
+ Rendering Harbour sunset → 4K 10-bit HEVC for the server · 62 % · 11.3 fps +
+
Today3 jobs · 41 min GPU timeQueue1 waiting on the serverAvailabilitywhen idle for 2 min · never on battery
+ +
Node settings
+
+
+
+
+ Sequences + + + + + + + + +
+
SequenceThis PCServerState
+
Holy grail · Monvisooriginals · proxiesoriginals · proxies▲ settings differ
+
Harbour sunsetoriginals · proxiesoriginals · proxies● in sync
rendering on this PC as a node
+
Comet over the ridgeoriginals · proxies46 % received● uploading
+
Clouds over the Langheoriginals—local only
+
Construction cam · week 38proxiesoriginals · proxies● remote
+
Aurora, Tromsøoriginals · proxiesoriginals · proxies● in sync
+
Star trails, Colle del Nivoletoriginals · proxiesoriginals · proxies · 3 exports● in sync
+
Milan skyline dusk—originals · proxies · 1 export● remote
+ +
Last sync 10:15 · manifest diff 0.4 sServer archive 9.4 TB · 412 sequences · 6 usersOpen admin panel
+
+
+
+ 418 sequences640,118 photos9.4 TBConnected to "Studio NAS"2 jobs +
+
+
+
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/Settings.html b/docs/reference/original/titano-ui-kit/mockups/Settings.html new file mode 100644 index 00000000..6991a8d5 --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Settings.html @@ -0,0 +1,83 @@ + + + + +Titano — Settings + + + +
+
+ + Titano — Settings + + —▢✕ +
+
+ +
+
+ + + General + Archive + Import + Analysis + Rendering + Formats + Server + Updates + Licence + Advanced + + + +
+
+
RenderingChanges apply to the next job
+
+ Quality profile +
Best · Balanced · Fast
+ +
8 GBof 32 GB installed
+ Cache folder +
1.4 GB used · SSD · 612 GB free
+ Parallelism +
of 16 logical cores
+ Hardware encoding +
+
+
+
Encoders on this PCNVIDIA GeForce RTX 4070 · driver 560.94 · Media Foundation 10.0.26100
+
+
CodecEncoder10-bitMaxSelf-testUsed for
+
HEVCNVIDIA NVENC (hardware)Main108192×8192✓ 142 fps · ok4K archive · 4K HEVC · 1440p · cinema
+
H.264NVIDIA NVENC (hardware)—4096×4096✓ 188 fps · ok1080p share · social · square · 720p
+
AV1NVIDIA NVENC (hardware)10-bit8192×8192✓ 96 fps · oknot in any preset · available in Custom
+
H.264Microsoft (software)—4096×2304✓ 21 fps · okfallback for every H.264 preset
+
MJPEG · AVITitano (built in)—no limit✓ 64 fps · oklossless-ish intermediate
+
GIF · APNGTitano (built in)—1080p✓ okpreviews, social loops
+
+ Intel QSV and AMD AMF appear here on PCs that have them. HEVC and AV1 exist only as hardware encoders: without one, those presets fall back to H.264 and say so in the preset list. +
+
+
+
+
+
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/Uploader.html b/docs/reference/original/titano-ui-kit/mockups/Uploader.html new file mode 100644 index 00000000..653dc74e --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Uploader.html @@ -0,0 +1,70 @@ + + + + +Titano Uploader + + + +
+
+ + Titano Uploader + + —✕ +
+
+ + https://nas.local:8443 + · + alberto + · + Connected + + 1.9 TB free of 5 TB + +
+
+
+ + Drop photos, folders or a card here + +
+
+ Target + + + + +
+
+ Queue + 4,812 files · 96.2 GB · 38 MB/s · 41 min left + + + + Limit MB/s +
+
+
+
2026-09-28_18-02-11_0413.CR22,214 of 4,812 sent · 2,201 verified by the server · 0 retries
+
+
+ Watch folders + D:\Cam\Roof · every 60 s + \\garage-pi\cam · every 5 min + +
+ +
+ + + +
+
+
+ + diff --git a/docs/reference/original/titano-ui-kit/mockups/Welcome.html b/docs/reference/original/titano-ui-kit/mockups/Welcome.html new file mode 100644 index 00000000..83c9d379 --- /dev/null +++ b/docs/reference/original/titano-ui-kit/mockups/Welcome.html @@ -0,0 +1,81 @@ + + + + +Titano — First run + + + +
+
+ + Titano + + —▢✕ +
+
+ +
+
Ready
+
+ + Year ▾ + Camera ▾ + Status ▾ +
+
No sequences yet
+
0 sequences0 photosNo archiveNot connected
+
+
+
+
+
+ + Welcome to TitanoWhere should your time-lapses live? + +
+
+ + + +
+
+ + + +
+
+
+ + New card inserted · SD 128 GBCanon EOS R5 · 4,812 photos · not yet known to Titano + + +
+
+ +