refactor!: rename Titano to Chronos and move CI and releases to Gitea (#6)
CI / Build and test (push) Successful in 8m14s
CI / Windows tests and installer (push) Skipped
CI / YAML check (push) Successful in 7s
Release / Build, test and publish (push) Successful in 13m19s
CI / PostgreSQL 16 integration (push) Successful in 4m49s
CI / PostgreSQL 17 integration (push) Successful in 5m28s
CI / Docker image (push) Successful in 53s
Release / Server image (push) Failing after 10s

The owner renamed the product and moved the repository to the self-hosted
Gitea (https://gitea.encke-hake.ts.net/BalboSoft/Chronos) for more control,
and asked for Actions and a first automatic release with the server package
and the Windows exe (docs/requests/2026-10-23-chronos-gitea.md).

- Chronos everywhere: a byte-exact rename of contents and paths, then a
  per-language review of the forms the old name's ending had dictated.
- Gitea instead of GitHub: the update check, licence, issue and support
  links read ChronosReleasesUrl; the update check takes the highest stable
  version, offers a pre-release build its final release and reports a
  repository it cannot see as a failed check. EULA, security policy and
  Gitea issue forms live at the repository root.
- Gitea Actions for the Linux act_runner (.gitea/workflows): CI, release,
  nightly image and performance gates in the .NET SDK container with git
  checkout and the system SQLite. The release cross-compiles the Windows
  programs, checks their icon, version and DPI manifest, packs installers
  and zips, publishes the Gitea release and pushes the server image
  (REGISTRY_TOKEN). Windows-only tests run in an opt-in job on a Windows
  runner (WINDOWS_RUNNER).
- New Chronos.Tools commands: zip, gitea-release, postgres-ci (replaces the
  docker-exec script, which Gitea's service containers do not allow; the
  throw-away server runs without durability) and pe-check.
- Timed tests take their budget from TestTiming (CHRONOS_TEST_TIME_FACTOR,
  3 on the shared runner; the weekly performance gates keep theirs).

BREAKING CHANGE: programs, settings, data folders, file types, environment
variables and the Docker image use the new name; nothing is migrated from
Titano, which never had a release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Alberto Balbo <alberto.balbo.96@gmail.com>
This commit was merged in pull request #6.
This commit is contained in:
Alby96andClaude Opus 5.5 authored and Alby96 committed 2026-10-23 12:45:18 +02:00
1 parent c99842cc86
commit f2b58522b9
1801 files changed
+11804 -10676

No files matched your search

@@ -0,0 +1,61 @@
using Chronos.Core.Model;
using Chronos.Data.Jobs;
using Chronos.Data.Repositories;
namespace Chronos.Data.Processing;
/// <summary>
/// Light analysis queued after work that brings sequences or frames into the index (card import, adoption, scan), so the
/// advisor's Auto values and recommended preset exist without any user action (BRIEF §1.1, §4.3); a background deep
/// analysis too when the host asks for it. Nothing is queued when the engine cannot run the analysis, and a sequence
/// already waiting in a queued analysis of the same kind is not queued again (that job runs after the changes that led
/// here).
/// </summary>
internal static class AnalysisFollowUp
{
/// <summary>Queues one light analysis of <paramref name="sequenceIds"/>, labelled <paramref name="label"/> (by default like the job that found them).</summary>
public static async Task QueueAsync(ChronosDatabase db, JobContext context, IReadOnlyCollection<Guid> sequenceIds, string? label = null)
{
if (sequenceIds.Count == 0) return;
var waiting = (await db.Jobs.ListQueuedAsync([JobKind.LightAnalyse], 1000, context.Cancellation).ConfigureAwait(false))
.SelectMany(j => j.TargetIds).ToHashSet();
var targets = sequenceIds.Where(id => !waiting.Contains(id)).Distinct().ToList();
if (targets.Count == 0) return;
var request = ProcessingJobs.LightAnalysis(targets, label ?? context.Job.TargetLabel);
await context.EnqueueFollowUpAsync(request.Kind, request.Targets, request.Label, request.ParametersJson, request.Priority).ConfigureAwait(false);
}
/// <summary>
/// Queues one background deep analysis of <paramref name="sequenceIds"/> (BRIEF §10.2: background, low priority),
/// leaving out the sequences a queued deep analysis already covers.
/// </summary>
public static async Task QueueDeepAsync(ChronosDatabase db, JobContext context, IReadOnlyCollection<Guid> sequenceIds)
{
if (sequenceIds.Count == 0) return;
var waiting = (await db.Jobs.ListQueuedAsync([JobKind.DeepAnalyse], 1000, context.Cancellation).ConfigureAwait(false))
.SelectMany(j => j.TargetIds).ToHashSet();
var targets = sequenceIds.Where(id => !waiting.Contains(id)).Distinct().ToList();
if (targets.Count == 0) return;
var request = ProcessingJobs.DeepAnalysis(targets, context.Job.TargetLabel) with { Priority = JobPriority.Background };
await context.EnqueueFollowUpAsync(request.Kind, request.Targets, request.Label, request.ParametersJson, request.Priority).ConfigureAwait(false);
}
/// <summary>
/// Sequences of <paramref name="archiveId"/> without a current light analysis (new, adopted, or with frames a scan added),
/// and those with frames stored as GPR that are DNGs: the light analysis probes them again and records the DNG format
/// and its native tier (R4, owner review 1).
/// </summary>
public static async Task<List<Guid>> UnanalysedAsync(ChronosDatabase db, Guid archiveId, CancellationToken cancellationToken)
{
var ids = new List<Guid>(await db.Frames.ListSequencesWithStaleGprAsync(archiveId, cancellationToken).ConfigureAwait(false));
var query = new SequenceQuery { ArchiveId = archiveId, WithoutStatus = SequenceStatus.AnalyzedLight, Sort = SequenceSort.Oldest, Limit = 1000 };
do
{
var page = await db.Sequences.ListAsync(query, cancellationToken).ConfigureAwait(false);
ids.AddRange(page.Items.Select(s => s.Id));
query = query with { Cursor = page.NextCursor };
}
while (query.Cursor is not null);
return [.. ids.Distinct()];
}
}
@@ -0,0 +1,28 @@
using Chronos.Core.Analysis.Deep;
using Chronos.Core.Archiving;
using Chronos.Core.Imaging;
using Chronos.Core.Model;
namespace Chronos.Data.Processing;
/// <summary>
/// Saved deep-analysis reports (<c>.chronos/analysis.json</c>, BRIEF §10.2) for hosts that hand them on: a server serves
/// one to the editors of its clients only while it still describes the sequence (§14.5).
/// </summary>
public static class DeepReports
{
/// <summary>
/// The saved report of <paramref name="sequence"/> when it describes its frames as a host with
/// <paramref name="decoder"/> reads them now; null when there is none, it covers another number of frames, or it
/// found unreadable a frame that has been read from its proxy since (an original that host cannot decode, whose proxy
/// arrived after the analysis): its verdict and its advice to exclude that frame no longer hold.
/// </summary>
public static async Task<DeepAnalysisReport?> ReadCurrentAsync(ChronosDatabase db, Archive archive, Sequence sequence, ImageDecoder decoder,
CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(archive);
ArgumentNullException.ThrowIfNull(sequence);
var frames = await SequenceFrames.LoadAsync(db, archive, sequence, useProxies: false, decoder, cancellationToken).ConfigureAwait(false);
return SequenceAnalyser.ReadReport(new ArchivePaths(archive.RootPath).Sequence(sequence.Folder), frames);
}
}
+26
View File
@@ -0,0 +1,26 @@
using Chronos.Core.Model;
using Chronos.Core.Project;
using Chronos.Data.Repositories;
namespace Chronos.Data.Processing;
/// <summary>
/// The index's hero frame (<see cref="Sequence.HeroFrameId"/>, the frame the Library shows) follows the project's hero
/// (<see cref="ProjectSettings.HeroFrame"/>, a frame index; frame indices are positions).
/// </summary>
public static class HeroFrame
{
/// <summary>
/// The <see cref="SequenceEdit.HeroFrameId"/> of a project whose hero went from <paramref name="before"/> to
/// <paramref name="after"/>: null when it did not change, else the frame at the new index, or <see cref="Guid.Empty"/>
/// (the first frame shows) when there is none.
/// </summary>
public static async Task<Guid?> EditAsync(ChronosDatabase db, Guid sequenceId, int? before, int? after, CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(db);
if (before == after) return null;
if (after is not >= 0) return Guid.Empty;
var frames = await db.Frames.ListBySequenceAsync(sequenceId, after.Value - 1, 1, cancellationToken).ConfigureAwait(false);
return frames is [{ } frame] && frame.Index == after ? frame.Id : Guid.Empty;
}
}
@@ -0,0 +1,115 @@
using System.Globalization;
using Chronos.Core.Analysis.Deep;
using Chronos.Core.Archiving;
using Chronos.Core.Localization;
using Chronos.Core.Model;
using Chronos.Data.Jobs;
namespace Chronos.Data.Processing.Jobs;
/// <summary>
/// <see cref="JobKind.LightAnalyse"/> and <see cref="JobKind.DeepAnalyse"/> over the target sequences, one after the
/// other. Progress counts sequences (light) or frames (deep). A sequence that cannot be analysed is logged and the
/// others still run; the job then fails, and a retry analyses only the failed ones. An offline archive stops the job at
/// once. Checkpoint: the next target and the failed ones (<c>next[;i,j…]</c>). A deep pass interrupted inside a
/// sequence resumes from that sequence's <c>analysis.partial</c>.
/// </summary>
internal sealed class AnalyseJobHandler(ChronosDatabase db, SequenceAnalyser analyser, JobKind kind) : IJobHandler
{
public JobKind Kind => kind;
public async Task RunAsync(JobContext context)
{
var deep = kind == JobKind.DeepAnalyse;
var targets = context.Job.TargetIds;
var (next, retry) = Parse(context.Checkpoint, targets.Count);
// Deep progress is in frames across all targets, so the bar and the ETA cover the whole job.
var units = new long[targets.Count];
for (var i = 0; i < targets.Count; i++)
units[i] = deep ? (await db.Sequences.GetAsync(targets[i], context.Cancellation).ConfigureAwait(false))?.FrameCount ?? 0 : 1;
var total = units.Sum();
var done = Enumerable.Range(0, next).Where(i => !retry.Contains(i)).Sum(i => units[i]);
var failed = new List<int>();
string? failure = null;
int[] order = [.. retry, .. Enumerable.Range(next, targets.Count - next)];
for (var k = 0; k < order.Length; k++)
{
context.Cancellation.ThrowIfCancellationRequested();
var i = order[k];
var before = done;
var chain = new ProgressChain(context.ReportAsync);
var progress = deep ? chain.For<AnalysisProgress>(p => (before + p.Done, total, null)) : null;
try
{
var outcome = await analyser.AnalyseAsync(targets[i], deep, progress, context.Cancellation).ConfigureAwait(false);
await chain.FlushAsync().ConfigureAwait(false);
if (outcome is null) context.Log(Loc.L("Archive.Log.SequenceMissing", targets[i]));
else if (outcome.FramesChanged != FramesChange.None) await NotRecordedAsync(context, outcome).ConfigureAwait(false);
else Report(context, outcome, deep);
}
catch (Exception ex) when (ex is not (OperationCanceledException or ArchiveOfflineException))
{
await chain.FlushAsync().ConfigureAwait(false);
Core.Diagnostics.Log.Warning("processing", $"Analysis of sequence {targets[i]} failed", ex);
failure = Loc.L("Advisor.Log.Failed", await TitleAsync(targets[i], context.Cancellation).ConfigureAwait(false), ex.Message);
context.Log(failure);
failed.Add(i);
}
done += units[i];
next = int.Max(next, i + 1);
// Failed targets of an earlier attempt not retried yet stay listed.
await context.CheckpointAsync(Format(next, [.. failed, .. retry.Skip(k + 1)]), done, total).ConfigureAwait(false);
}
// One failure is the job's error as it was logged; several are counted (the log names each).
if (failed.Count > 0) throw new InvalidOperationException(failed.Count == 1 ? failure : Loc.L("Errors.Analysis.Failed", failed.Count, targets.Count));
}
/// <summary>
/// A sequence whose frames changed while it was analysed: nothing was recorded from the frames the analysis read (the
/// deep report it saved counts only for the frames it describes). When this index holds the frames as they are, and no
/// light analysis is queued for it, one is queued; frames another process changed are analysed by that process, and
/// indexed here by the next scan (<see cref="FramesChange.NotIndexed"/>).
/// </summary>
private async Task NotRecordedAsync(JobContext context, AnalysisOutcome outcome)
{
var sequence = outcome.Sequence;
if (outcome.FramesChanged == FramesChange.NotIndexed)
{
context.Log(Loc.L("Advisor.Log.FramesChangedElsewhere", sequence.DisplayTitle));
return;
}
context.Log(Loc.L("Advisor.Log.FramesChanged", sequence.DisplayTitle));
await AnalysisFollowUp.QueueAsync(db, context, [sequence.Id], sequence.DisplayTitle).ConfigureAwait(false);
}
private async Task<string> TitleAsync(Guid sequenceId, CancellationToken cancellationToken) =>
(await db.Sequences.GetAsync(sequenceId, cancellationToken).ConfigureAwait(false))?.DisplayTitle ?? sequenceId.ToString();
private static void Report(JobContext context, AnalysisOutcome outcome, bool deep)
{
var title = outcome.Sequence.DisplayTitle;
context.Log(Loc.L(deep ? "Advisor.Log.DeepDone" : "Advisor.Log.LightDone", title, outcome.Frames, outcome.Warnings));
if (outcome.SettingsChanged) context.Log(Loc.L("Advisor.Log.AutoUpdated", title));
if (outcome.SettingsUnreadable) context.Log(Loc.L("Advisor.Log.ProjectUnreadable", title));
if (outcome.Presets.Count > 0) context.Log(Loc.L("Advisor.Log.Presets", string.Join(" · ", outcome.Presets.Select(p => p.DisplayName()))));
}
/// <summary>Next target and the failed targets to retry first; a missing or unreadable checkpoint starts over.</summary>
internal static (int Next, IReadOnlyList<int> Retry) Parse(string? checkpoint, int count)
{
var parts = checkpoint?.Split(';');
if (parts is not ([_] or [_, _]) || !int.TryParse(parts[0], NumberStyles.None, CultureInfo.InvariantCulture, out var next) || next > count) return (0, []);
var retry = new List<int>();
foreach (var item in parts.Length == 2 ? parts[1].Split(',') : [])
{
if (!int.TryParse(item, NumberStyles.None, CultureInfo.InvariantCulture, out var index) || index >= next) return (0, []);
if (!retry.Contains(index)) retry.Add(index);
}
return (next, retry);
}
internal static string Format(int next, IReadOnlyCollection<int> failed) =>
failed.Count == 0
? next.ToString(CultureInfo.InvariantCulture)
: string.Create(CultureInfo.InvariantCulture, $"{next};{string.Join(',', failed.Order())}");
}
@@ -0,0 +1,88 @@
using Chronos.Core.Diagnostics;
using Chronos.Core.Export;
using Chronos.Core.Localization;
using Chronos.Core.Model;
using Chronos.Core.Video;
using Chronos.Data.Jobs;
using Chronos.Protocol;
namespace Chronos.Data.Processing.Jobs;
/// <summary>
/// <see cref="JobKind.Render"/> on the server (BRIEF §4.4, §14.5, §14.7): it takes the jobs whose every output (the preset
/// and each batch preset) its managed encoders produce, and runs them like a client does. Jobs that need a platform
/// encoder (MP4) wait for render nodes while <see cref="ProcessingOptions.AwaitsRenderNode"/> says one may take them;
/// after that the server takes them too, writes each output it cannot encode as MJPEG in AVI at the same size and frame
/// rate, and says so in the job log. A job it started (it left a checkpoint) resumes here, and jobs whose parameters
/// cannot be read are taken, so they fail with their reason instead of waiting for a claimer that never comes.
/// </summary>
internal sealed class ManagedRenderJobHandler(RenderJobHandler render, ProcessingOptions options) : ISelectiveJobHandler
{
/// <summary>The managed preset whose values stand in for an output only a render node could make.</summary>
private const string FallbackPresetId = "mjpeg-avi";
private readonly EncoderCapability[] _capabilities = [.. options.Encoders.SelectMany(e => e.Capabilities)];
public JobKind Kind => JobKind.Render;
public async ValueTask<bool> AcceptsAsync(Job job, CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(job);
RenderJobParameters parameters;
try
{
parameters = ProcessingJobs.ReadParameters(job.ParametersJson);
// Most jobs are decided by the main codec, before the export is read.
if (Produces(parameters.Codec) && RenderJobHandler.Targets(ProcessingJobs.ReadExport(parameters.PresetJson), parameters.PresetName).All(t => Produces(t.Export)))
return true;
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
return true;
}
if (job.Checkpoint is not null) return true;
if (options.AwaitsRenderNode is not { } awaits) return false;
try
{
return !await awaits(job, parameters, cancellationToken).ConfigureAwait(false);
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
// Unknown whether a node could take it: the job keeps waiting rather than losing its format.
Log.Warning("processing", $"Render job {job.Id}: render node availability unknown", ex);
return false;
}
}
public Task RunAsync(JobContext context) =>
render.RunAsync(context, target => Produces(target.Export) ? target : Fallback(context, target));
/// <summary>The output as MJPEG in AVI with the managed preset's quality, at the size and frame rate asked for.</summary>
private static ExportTarget Fallback(JobContext context, ExportTarget target)
{
var mjpeg = ExportResolver.FromPreset(ExportPresets.Find(FallbackPresetId)!);
context.Log(Loc.L("Export.Log.NoRenderNode", target.PresetName, ExportNaming.CodecLabel(target.Export.Codec), ExportNaming.CodecLabel(mjpeg.Codec)));
return target with
{
Export = target.Export with
{
PresetId = ExportResolver.CustomId,
NameKey = null,
Codec = mjpeg.Codec,
Profile = mjpeg.Profile,
BitDepth = mjpeg.BitDepth,
BitRate = 0,
BitsPerPixel = 0,
Quality = mjpeg.Quality,
RateControl = mjpeg.RateControl,
Encoder = null,
},
};
}
private bool Produces(string codec) =>
_capabilities.Any(c => string.Equals(ProcessingJobs.CodecName(c.Codec), codec, StringComparison.OrdinalIgnoreCase));
private bool Produces(ResolvedExport export) =>
_capabilities.Any(c => c.Codec == export.Codec && export.Width <= c.MaxWidth && export.Height <= c.MaxHeight);
}
@@ -0,0 +1,162 @@
using System.Buffers.Binary;
using System.Security.Cryptography;
using Chronos.Core.Archiving;
using Chronos.Core.Export;
using Chronos.Core.Localization;
using Chronos.Core.Model;
using Chronos.Core.Project;
using Chronos.Core.Render;
using Chronos.Data.Archiving;
using Chronos.Data.Jobs;
namespace Chronos.Data.Processing.Jobs;
/// <summary>
/// <see cref="JobKind.Render"/> on this machine (BRIEF §11.5): target = the sequence; parameters = Protocol
/// <c>RenderJobParameters</c> whose preset JSON is the export section of a project (preset, overrides, name template,
/// folder, batch). The project is the embedded one or the sequence's own; frames flagged missing, corrupt, excluded or
/// undecodable are left out, and a frame found undecodable while rendering is shown as its nearest neighbour, logged
/// and (when the originals were read) flagged so later renders leave it out (BRIEF §8.2). The preset and every batch
/// preset render after one preparation pass into the sequence's <c>exports/</c> (or the export folder, never on a
/// server), named by the template without taking a name another render of this process is writing, and each finished
/// output is recorded at once (its row id derives from the job and the entry, so every attempt knows what is recorded).
/// Checkpoint: the entries recorded and the output being written, so a crashed attempt's leftovers are removed and only
/// unfinished entries render again. A failed entry fails the job after the others ran; retrying renders it alone.
/// </summary>
internal sealed class RenderJobHandler(ChronosDatabase db, ProcessingOptions options, FrameTiers tiers) : IJobHandler
{
public JobKind Kind => JobKind.Render;
public Task RunAsync(JobContext context) => RunAsync(context, target => target);
/// <summary>Runs the job with each output still to render passed through <paramref name="adapt"/> (the server's managed stand-ins).</summary>
internal async Task RunAsync(JobContext context, Func<ExportTarget, ExportTarget> adapt)
{
var cancellation = context.Cancellation;
var (parameters, export) = ProcessingJobs.ReadRender(context.Job.ParametersJson);
if (context.Job.TargetIds is not [var sequenceId] || await db.Sequences.GetAsync(sequenceId, cancellation).ConfigureAwait(false) is not { } sequence
|| await db.Archives.GetAsync(sequence.ArchiveId, cancellation).ConfigureAwait(false) is not { } archive)
throw new InvalidOperationException(Loc.L("Errors.Render.Sequence"));
var paths = new ArchivePaths(archive.RootPath);
ArchiveVolume.EnsureWritable(paths);
var folder = paths.Sequence(sequence.Folder);
// A server writes only inside its archive (BRIEF §14.2): an export folder chosen on a client means nothing there.
if (options.Host == EncoderHost.Server) export = export with { Folder = null };
var project = (parameters.SettingsJson is { } embedded ? ProjectStore.Parse(embedded) : ProjectStore.Read(sequence, folder)) with { Export = export };
var settingsJson = project.ToJson();
using var names = new OutputNames();
var all = Targets(export, parameters.PresetName);
var resume = RenderCheckpoint.Parse(context.Checkpoint);
var done = resume.Done.ToList();
// A crash after a render row was written but before the checkpoint: that entry is finished.
for (var i = 0; i < all.Count; i++)
{
if (!done.Contains(i) && await db.Renders.GetAsync(RenderId(context.Job.Id, i), cancellation).ConfigureAwait(false) is not null) done.Add(i);
}
if (resume is { Pending: { } pending, PendingOutput: { } output } && !done.Contains(pending) && names.TryReserve(output))
{
// Unless another render recorded that name since (the output did not exist yet when it chose it).
var recorded = await db.Renders.ListBySequenceAsync(sequence.Id, cancellation).ConfigureAwait(false);
Discard(output, keepOutput: recorded.Any(r => r.OutputPath == Stored(paths, output)));
names.Release(output); // free again for the entry's new attempt
}
var targets = all.Select((t, i) => (i, t)).Where(t => !done.Contains(t.i)).Select(t => (t.i, adapt(t.t))).ToList();
if (targets.Count == 0) return;
var frames = await SequenceFrames.LoadAsync(db, archive, sequence, parameters.UseProxies, options.Archive.Decoder, cancellation).ConfigureAwait(false);
var companions = await GprCompanions.FindAsync(db, archive, frames.Frames, cancellation).ConfigureAwait(false);
IReadOnlyList<TargetOutcome> outcomes;
await using (var render = new SequenceRender(frames, project, SequenceAnalyser.ReadReport(folder, frames), options, originals: !parameters.UseProxies,
companions))
{
outcomes = await render.RenderAllAsync(
targets,
(target, setup) => names.Reserve(taken => ExportNaming.OutputPath(project.Export, folder.Exports, SequenceRender.NameContext(sequence, target, setup), taken)),
(index, path) => context.CheckpointAsync(new RenderCheckpoint(done, index, path).ToJson(), context.Done, context.Total),
async (index, target, result) =>
{
// The output is complete: record it even if the job is being cancelled, so it is never orphaned.
var entity = result.ToEntity(sequence.Id, target.PresetName, settingsJson, options.ProducedBy) with
{
Id = RenderId(context.Job.Id, index),
OutputPath = Stored(paths, result.OutputPath),
};
await db.Renders.InsertAsync(entity, CancellationToken.None).ConfigureAwait(false);
done.Add(index);
await context.CheckpointAsync(new RenderCheckpoint(done, null, null).ToJson(), context.Done, context.Total).ConfigureAwait(false);
context.Log(Loc.L("Export.Log.Rendered", target.PresetName, Path.GetFileName(result.OutputPath)));
foreach (var remark in SequenceRender.Remarks(result)) context.Log(remark);
await options.NotifyAsync(sequence.Id, ProcessingOptions.RenderedChange, CancellationToken.None).ConfigureAwait(false);
},
context.ReportAsync,
cancellation).ConfigureAwait(false);
if (render.StandIns.Count > 0)
context.Log(Loc.L("Export.Log.StandIns", string.Join(", ", render.StandIns.Select(i => (i + 1).ToString(Loc.Culture)))));
// Recorded without the job's token: what decoding found holds even if the job is cancelled meanwhile, and a
// sidecar that cannot be written now only leaves it to the next analysis or render. A frame decoded from its
// preview whose proxy arrived during the render is not preview-only: FrameTiers looks for the proxy as it records.
try
{
var decoded = render.Decoded.ToDictionary(kv => frames.Frames[kv.Key].Id, kv => kv.Value);
await tiers.RecordAsync(archive, sequence, decoded, proxies: false, CancellationToken.None).ConfigureAwait(false);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or InvalidDataException or LeaseUnavailableException
or ArchiveOfflineException)
{
Core.Diagnostics.Log.Warning("processing", $"The decode tiers of {sequence.DisplayTitle} could not be recorded", ex);
}
}
var failed = outcomes.Where(o => o.Error is not null).ToList();
foreach (var outcome in failed) context.Log(Loc.L("Export.Log.Failed", outcome.Target.PresetName, outcome.Error));
if (failed.Count > 0)
throw new InvalidOperationException(failed.Count == 1 ? failed[0].Error : Loc.L("Errors.Render.Failed", failed.Count, outcomes.Count));
}
/// <summary>The job's preset, then every other preset of the batch with its own values.</summary>
internal static List<ExportTarget> Targets(ExportSettings export, string presetName) =>
[
new(ExportResolver.Resolve(export), presetName),
.. ProcessingJobs.BatchPresets(export).Select(id => ExportResolver.Resolve(ProcessingJobs.BatchExport(export, id)))
.Select(resolved => new ExportTarget(resolved, ProcessingJobs.PresetName(resolved))),
];
/// <summary>Archive-relative for outputs inside the archive (like the server's renders), absolute otherwise.</summary>
private static string Stored(ArchivePaths paths, string output)
{
var relative = paths.ToRelative(output);
return relative.StartsWith("..", StringComparison.Ordinal) || Path.IsPathRooted(relative) ? output : relative;
}
/// <summary>
/// The id of the render row of entry <paramref name="index"/> of a job: the same in every attempt, so a resumed job
/// finds what it recorded (a name-based UUID, version 8).
/// </summary>
internal static Guid RenderId(Guid jobId, int index)
{
Span<byte> name = stackalloc byte[20];
jobId.TryWriteBytes(name, bigEndian: true, out _);
BinaryPrimitives.WriteInt32BigEndian(name[16..], index);
Span<byte> hash = stackalloc byte[SHA256.HashSizeInBytes];
SHA256.HashData(name, hash);
hash[6] = (byte)((hash[6] & 0x0F) | 0x80);
hash[8] = (byte)((hash[8] & 0x3F) | 0x80);
return new Guid(hash[..16], bigEndian: true);
}
/// <summary>
/// Removes what an interrupted attempt left of <paramref name="output"/>: the encoder's hidden temporary file or
/// folder, and an output that was completed but never recorded (it renders again under the same name).
/// </summary>
private static void Discard(string output, bool keepOutput)
{
var parent = Path.GetDirectoryName(output);
if (parent is null || !Directory.Exists(parent)) return;
var leftovers = Directory.EnumerateFileSystemEntries(parent, "." + Path.GetFileName(output) + ".*.tmp");
foreach (var leftover in keepOutput ? leftovers : leftovers.Append(output))
{
if (Directory.Exists(leftover)) Directory.Delete(leftover, recursive: true);
else if (File.Exists(leftover)) File.Delete(leftover);
}
}
}
@@ -0,0 +1,55 @@
using System.Collections.Concurrent;
namespace Chronos.Data.Processing;
/// <summary>
/// The output paths the renders of this process are writing. Encoders write to a hidden temporary file and rename it over
/// the output when they finish, so two renders that picked the same free name (the same preset queued twice) would
/// overwrite each other: a render reserves each name it picks until it ends.
/// </summary>
internal sealed class OutputNames : IDisposable
{
private static readonly ConcurrentDictionary<string, byte> Writing = new(StringComparer.OrdinalIgnoreCase);
private readonly List<string> _mine = [];
/// <summary>A path from <paramref name="pick"/>, given the test for paths other renders are writing, reserved for this render.</summary>
public string Reserve(Func<Func<string, bool>, string> pick)
{
while (true)
{
var path = pick(p => Writing.ContainsKey(Key(p)));
// Another render may have taken the same name since: pick again.
if (TryReserve(path)) return path;
}
}
/// <summary>Reserves <paramref name="path"/> for this render; false when another render is writing it.</summary>
public bool TryReserve(string path)
{
var key = Key(path);
if (!Writing.TryAdd(key, 0)) return false;
lock (_mine) _mine.Add(key);
return true;
}
/// <summary>Gives back a path this render reserved, so it can be picked again.</summary>
public void Release(string path)
{
var key = Key(path);
lock (_mine)
{
if (_mine.Remove(key)) Writing.TryRemove(key, out _);
}
}
public void Dispose()
{
lock (_mine)
{
foreach (var key in _mine) Writing.TryRemove(key, out _);
_mine.Clear();
}
}
private static string Key(string path) => Path.GetFullPath(path);
}
@@ -0,0 +1,189 @@
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Text.Json.Serialization;
using Chronos.Core.Export;
using Chronos.Core.Localization;
using Chronos.Core.Model;
using Chronos.Core.Project;
using Chronos.Core.Video;
using Chronos.Data.Archiving.Jobs;
using Chronos.Protocol;
namespace Chronos.Data.Processing;
/// <summary>
/// Builds the analysis and render jobs; enqueue them with <see cref="Archiving.ArchiveJobs.EnqueueAsync"/> (local
/// engine) or post the same kind, targets and parameters to <c>/api/v1/jobs</c> (server).
/// </summary>
public static class ProcessingJobs
{
/// <summary><see cref="JobKind.LightAnalyse"/>: targets = sequences; no parameters.</summary>
public static ArchiveJobRequest LightAnalysis(IReadOnlyList<Guid> sequenceIds, string? label = null) =>
new(JobKind.LightAnalyse, sequenceIds, label, null, JobPriority.Background);
/// <summary><see cref="JobKind.DeepAnalyse"/>: targets = sequences; no parameters.</summary>
public static ArchiveJobRequest DeepAnalysis(IReadOnlyList<Guid> sequenceIds, string? label = null) =>
new(JobKind.DeepAnalyse, sequenceIds, label, null, JobPriority.User);
/// <summary>
/// <see cref="JobKind.Render"/> of one sequence. <paramref name="export"/> (preset, overrides, name template,
/// folder, batch) replaces the project's export section; <paramref name="project"/> embeds the settings to render,
/// null renders the sequence's current project. <paramref name="sourceWidth"/>×<paramref name="sourceHeight"/>
/// stands in for a preset without a fixed size, so render nodes can match the job by resolution.
/// </summary>
public static ArchiveJobRequest Render(Sequence sequence, ExportSettings export, int sourceWidth, int sourceHeight, ProjectSettings? project = null,
bool useProxies = false)
{
ArgumentNullException.ThrowIfNull(sequence);
ArgumentNullException.ThrowIfNull(export);
var parameters = Parameters(export, sourceWidth, sourceHeight, project?.ToJson(), useProxies);
return new ArchiveJobRequest(JobKind.Render, [sequence.Id], RenderLabel(sequence.DisplayTitle, parameters.PresetName),
JsonSerializer.Serialize(parameters, ProtocolJson.Default.RenderJobParameters), JobPriority.User);
}
/// <summary>
/// The label of a render job, "Harbour sunset → 4K HEVC". It is stored as written, in the language of the moment like
/// the preset name: its arrow points from the sequence to the preset in that language's reading direction.
/// </summary>
public static string RenderLabel(string title, string presetName) =>
Loc.L(Loc.IsRightToLeft ? "Jobs.Target.RenderRtl" : "Jobs.Target.Render", title, presetName);
/// <summary>
/// A posted render job as one job per preset, as <see cref="RenderEach"/> makes them (a render node uploads one file
/// per job): the job itself when it has no batch; otherwise its own preset, then each batch preset with its own values,
/// all with the job's project and proxy choice. <paramref name="sourceWidth"/>×<paramref name="sourceHeight"/> stands in
/// for a batch preset without a fixed size.
/// </summary>
/// <exception cref="InvalidDataException">The preset JSON is not an export section.</exception>
public static IReadOnlyList<RenderJobParameters> Split(RenderJobParameters parameters, int sourceWidth, int sourceHeight)
{
ArgumentNullException.ThrowIfNull(parameters);
var export = ReadExport(parameters.PresetJson);
var batch = BatchPresets(export).ToList();
if (batch.Count == 0) return [parameters];
return
[
parameters with { PresetJson = JsonSerializer.Serialize(export with { Batch = [] }, ProcessingJson.Default.ExportSettings) },
.. batch.Select(id => Parameters(BatchExport(export, id), sourceWidth, sourceHeight, parameters.SettingsJson, parameters.UseProxies)),
];
}
/// <summary>
/// One <see cref="Render"/> job per preset of <paramref name="export"/>: its preset, then each batch preset with its
/// own values. For a server: a render node uploads one file per job, so a batch must not travel as one job.
/// </summary>
public static IReadOnlyList<ArchiveJobRequest> RenderEach(Sequence sequence, ExportSettings export, int sourceWidth, int sourceHeight,
ProjectSettings? project = null, bool useProxies = false)
{
ArgumentNullException.ThrowIfNull(export);
return
[
Render(sequence, export with { Batch = [] }, sourceWidth, sourceHeight, project, useProxies),
.. BatchPresets(export).Select(id => Render(sequence, BatchExport(export, id), sourceWidth, sourceHeight, project, useProxies)),
];
}
/// <summary>The batch presets of an export besides its own, each once (blank entries of a hand-written batch are skipped).</summary>
internal static IEnumerable<string> BatchPresets(ExportSettings export)
{
var main = ExportResolver.Resolve(export).BasePresetId;
return export.Batch.Where(id => !string.IsNullOrWhiteSpace(id)).Distinct(StringComparer.OrdinalIgnoreCase)
.Where(id => !id.Equals(main, StringComparison.OrdinalIgnoreCase));
}
/// <summary>A batch preset rendered with its own values, named and placed like the export it belongs to.</summary>
internal static ExportSettings BatchExport(ExportSettings export, string presetId) =>
new() { Preset = new Auto<string>().WithManual(presetId), NameTemplate = export.NameTemplate, Folder = export.Folder };
private static RenderJobParameters Parameters(ExportSettings export, int sourceWidth, int sourceHeight, string? settingsJson, bool useProxies)
{
var resolved = ExportResolver.Resolve(export);
return new RenderJobParameters(PresetName(resolved), JsonSerializer.Serialize(export, ProcessingJson.Default.ExportSettings), CodecName(resolved.Codec),
resolved.Width > 0 ? resolved.Width : sourceWidth, resolved.Height > 0 ? resolved.Height : sourceHeight, useProxies, settingsJson);
}
/// <summary>Codec name in job parameters and render-node capabilities ("h264", "hevc", "mjpeg", "pngsequence"…).</summary>
public static string CodecName(VideoCodec codec) => codec.ToString().ToLowerInvariant();
/// <summary>Display name of an export's preset in the current language ("Custom" when the values match none).</summary>
public static string PresetName(ResolvedExport export)
{
ArgumentNullException.ThrowIfNull(export);
return Loc.L(export.NameKey ?? "Export.Preset.Custom");
}
/// <summary>The parameters of a render job and the export they select.</summary>
/// <exception cref="InvalidDataException">The job has no valid render parameters.</exception>
public static (RenderJobParameters Parameters, ExportSettings Export) ReadRender(string? parametersJson)
{
var parameters = ReadParameters(parametersJson);
return (parameters, ReadExport(parameters.PresetJson));
}
/// <summary>The protocol record of a render job, without reading its export.</summary>
/// <exception cref="InvalidDataException">The job has no valid render parameters.</exception>
internal static RenderJobParameters ReadParameters(string? parametersJson)
{
try
{
if (parametersJson is { Length: > 0 } && JsonSerializer.Deserialize(parametersJson, ProtocolJson.Default.RenderJobParameters)
is { PresetName.Length: > 0, PresetJson.Length: > 0, Codec.Length: > 0 } parameters)
return parameters;
}
catch (JsonException ex)
{
throw new InvalidDataException(Loc.L("Errors.Render.Parameters"), ex);
}
throw new InvalidDataException(Loc.L("Errors.Render.Parameters"));
}
/// <summary>The export section in a render job's preset JSON; values it leaves out take their defaults.</summary>
/// <exception cref="InvalidDataException">The JSON is not an export section.</exception>
internal static ExportSettings ReadExport(string? presetJson)
{
try
{
// Read as the export section of a project, so missing values keep their defaults (ProjectSettings.FromJson).
var project = new JsonObject { ["export"] = JsonNode.Parse(presetJson ?? string.Empty) };
return ProjectSettings.FromJson(project.ToJsonString()).Export;
}
catch (JsonException ex)
{
throw new InvalidDataException(Loc.L("Errors.Render.Parameters"), ex);
}
}
}
/// <summary>
/// Resume point of a render job: the batch targets already recorded, and the output a crashed attempt was writing
/// (its leftovers are removed before that target renders again).
/// </summary>
internal sealed record RenderCheckpoint(IReadOnlyList<int> Done, int? Pending, string? PendingOutput)
{
public static RenderCheckpoint Empty { get; } = new([], null, null);
public static RenderCheckpoint Parse(string? json)
{
if (string.IsNullOrEmpty(json)) return Empty;
try
{
return JsonSerializer.Deserialize(json, ProcessingJson.Default.RenderCheckpoint) ?? Empty;
}
catch (JsonException)
{
return Empty;
}
}
public string ToJson() => JsonSerializer.Serialize(this, ProcessingJson.Default.RenderCheckpoint);
}
/// <summary>JSON written into render jobs: presets (the export section of <c>project.json</c>) and checkpoints.</summary>
[JsonSourceGenerationOptions(
PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
UseStringEnumConverter = true,
PropertyNameCaseInsensitive = true)]
[JsonSerializable(typeof(ExportSettings))]
[JsonSerializable(typeof(RenderCheckpoint))]
internal sealed partial class ProcessingJson : JsonSerializerContext;
@@ -0,0 +1,115 @@
using Chronos.Core.Analysis.Deep;
using Chronos.Core.Export;
using Chronos.Core.Imaging;
using Chronos.Core.Model;
using Chronos.Core.Render;
using Chronos.Core.Video;
using Chronos.Core.Video.Managed;
using Chronos.Data.Archiving;
using Chronos.Protocol;
namespace Chronos.Data.Processing;
/// <summary>
/// What differs between the hosts that analyse and render (BRIEF §4.2): decoders (inside <see cref="Archive"/>),
/// encoders and where the work runs. Client: WIC then managed decoders, Media Foundation then managed encoders;
/// server: managed only.
/// </summary>
public sealed record ProcessingOptions
{
/// <summary><see cref="SequenceChanged"/> after a render was recorded.</summary>
public const string RenderedChange = "renders";
/// <summary><see cref="SequenceChanged"/> after the advisor changed the project.</summary>
public const string SettingsChange = "settings";
/// <summary>Decoders, lease owner and lease timing for the sidecar and project writes.</summary>
public ArchiveServiceOptions Archive { get; init; } = new();
/// <summary>Encoder providers in priority order.</summary>
public IReadOnlyList<IVideoEncoderProvider> Encoders { get; init; } = [new ManagedEncoderProvider()];
/// <summary>
/// Whether a render of the given preset (its base preset id) may use hardware encoders (Settings › Rendering); when
/// not, it gets only the software ones. Asked at every render, so a changed preference applies to the next one.
/// </summary>
public Func<string, bool> AllowsHardware { get; init; } = _ => true;
/// <summary>
/// Told after a job changed a sequence: <see cref="RenderedChange"/> (a render was recorded) or
/// <see cref="SettingsChange"/> (the advisor changed Auto values). A server tells its connected clients (BRIEF §14.3).
/// A failure is logged and never fails the job.
/// </summary>
public Func<Guid, string, CancellationToken, Task>? SequenceChanged { get; init; }
/// <summary>The server delegates platform codecs to render nodes (<see cref="AwaitsRenderNode"/>).</summary>
public EncoderHost Host { get; init; } = EncoderHost.Client;
/// <summary>
/// Server: whether a queued render job that needs a platform encoder still waits for a render node (BRIEF §14.7). Once
/// it does not, the server renders it itself, every output only a node could make as MJPEG in AVI at the same size and
/// frame rate, and says so in the job log. Null: such jobs always wait for a node.
/// </summary>
public Func<Job, RenderJobParameters, CancellationToken, Task<bool>>? AwaitsRenderNode { get; init; }
/// <summary>Recorded with every render this host produces (client or server name).</summary>
public string ProducedBy { get; init; } = Environment.MachineName;
public DeepAnalysisOptions DeepAnalysis { get; init; } = DeepAnalysisOptions.Default;
/// <summary>Read-ahead and memory budget of the render decode window.</summary>
public FrameWindowOptions FrameWindow { get; init; } = new();
public RenderOptions Render { get; init; } = RenderOptions.Default;
/// <summary>
/// The host's current tuning, asked at the start of every analysis and render: it returns these options with the
/// values the user may change at any time (on the desktop Settings › Rendering and Analysis: memory budget, quality
/// profile, parallelism, analysis width and thresholds), so a change applies to the next job. Null: these options as
/// they are.
/// </summary>
public Func<ProcessingOptions, ProcessingOptions>? Tune { get; init; }
/// <summary>These options with the host's current tuning (<see cref="Tune"/>).</summary>
internal ProcessingOptions Current => Tune?.Invoke(this) ?? this;
/// <summary>
/// These options with <paramref name="parallelism"/> photos processed at once (owner review 1, R2: one job runs at a
/// time and the host's parallelism decides how many photos it processes at once): the deep analysis measures that many
/// frames together and the render's decode window loads that many ahead, within its memory budget.
/// </summary>
public ProcessingOptions WithParallelism(int parallelism)
{
var n = Math.Max(1, parallelism);
return this with
{
DeepAnalysis = DeepAnalysis with { MaxDegreeOfParallelism = n },
FrameWindow = FrameWindow with { MaxConcurrentLoads = n, Ahead = Math.Max(FrameWindow.Ahead, n) },
};
}
/// <summary>Tells <see cref="SequenceChanged"/>; a failure is logged, never passed on to the job.</summary>
internal async Task NotifyAsync(Guid sequenceId, string change, CancellationToken cancellationToken)
{
if (SequenceChanged is null) return;
try
{
await SequenceChanged(sequenceId, change, cancellationToken).ConfigureAwait(false);
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
Core.Diagnostics.Log.Warning("processing", $"The {change} change of sequence {sequenceId} could not be announced", ex);
}
}
/// <summary><see cref="Encoders"/> without their hardware encoders, for renders <see cref="AllowsHardware"/> keeps off them.</summary>
internal IReadOnlyList<IVideoEncoderProvider> SoftwareEncoders =>
[.. Encoders.Select(e => e.Capabilities.Any(c => c.Hardware) ? new SoftwareEncoderProvider(e) : e)];
/// <summary>
/// Encoders the advisor may count on: this machine's on a client; none listed on the server (render nodes can
/// produce any codec, so the advisor rules none out).
/// </summary>
internal IReadOnlyList<EncoderCapability> AdvisorCodecs =>
Host == EncoderHost.Server ? [] : [.. Encoders.SelectMany(e => e.Capabilities)];
}
@@ -0,0 +1,46 @@
using Chronos.Core.Export;
using Chronos.Core.Model;
using Chronos.Data.Archiving;
using Chronos.Data.Jobs;
using Chronos.Data.Processing.Jobs;
namespace Chronos.Data.Processing;
/// <summary>
/// The analysis and render engine of a host (BRIEF §4.3, §10, §11): job handlers for light analysis, deep analysis and
/// renders over the archive in the index, built with the host's decoders and encoders (<see cref="ProcessingOptions"/>).
/// Register it on the <see cref="JobEngine"/> next to the archive engine. A client renders every job it is given; a
/// server takes the renders its managed encoders produce and leaves the others to render nodes until none can take them
/// (<see cref="ProcessingOptions.AwaitsRenderNode"/>). Create jobs with <see cref="ProcessingJobs"/>.
/// </summary>
public sealed class ProcessingService : IJobHandlerProvider
{
private readonly ChronosDatabase _db;
private readonly SequenceAnalyser _analyser;
private readonly FrameTiers _tiers;
public ProcessingService(ChronosDatabase db, ProcessingOptions? options = null)
{
_db = db;
Options = options ?? new ProcessingOptions();
// Sidecar and project writes coordinate with the archive engine through the archive's lease files.
var writer = new SequenceWriter(Options.Archive);
var indexer = new ArchiveIndexer(db, writer);
_tiers = new FrameTiers(db, writer, indexer);
_analyser = new SequenceAnalyser(db, Options, writer, indexer, new ProjectStore(db, writer));
}
public ProcessingOptions Options { get; }
/// <summary>Handlers for <see cref="JobKind.LightAnalyse"/>, <see cref="JobKind.DeepAnalyse"/> and <see cref="JobKind.Render"/>.</summary>
public IReadOnlyList<IJobHandler> CreateJobHandlers()
{
var render = new RenderJobHandler(_db, Options, _tiers);
return
[
new AnalyseJobHandler(_db, _analyser, JobKind.LightAnalyse),
new AnalyseJobHandler(_db, _analyser, JobKind.DeepAnalyse),
Options.Host == EncoderHost.Server ? new ManagedRenderJobHandler(render, Options) : render,
];
}
}
@@ -0,0 +1,40 @@
namespace Chronos.Data.Processing;
/// <summary>
/// Delivers the synchronous progress reports of the engine (analysis, render stages) to an asynchronous sink (job
/// context, render-node protocol) one after the other, in report order. Await <see cref="FlushAsync"/> before a
/// checkpoint or the end of the work to observe the deliveries.
/// </summary>
internal sealed class ProgressChain(Func<long, long, string?, ValueTask> sink)
{
private readonly Lock _gate = new();
private Task _pending = Task.CompletedTask;
/// <summary>A progress receiver mapping its reports to done, total and message.</summary>
public IProgress<T> For<T>(Func<T, (long Done, long Total, string? Message)> map) => new Forward<T>(this, map);
public Task FlushAsync()
{
lock (_gate) return _pending;
}
private void Post(long done, long total, string? message)
{
lock (_gate) _pending = AfterAsync(_pending, done, total, message);
}
private async Task AfterAsync(Task previous, long done, long total, string? message)
{
await previous.ConfigureAwait(false);
await sink(done, total, message).ConfigureAwait(false);
}
private sealed class Forward<T>(ProgressChain chain, Func<T, (long Done, long Total, string? Message)> map) : IProgress<T>
{
public void Report(T value)
{
var (done, total, message) = map(value);
chain.Post(done, total, message);
}
}
}
@@ -0,0 +1,42 @@
using Chronos.Core.Model;
using Chronos.Core.Project;
namespace Chronos.Data.Processing;
/// <summary>
/// <c>.chronos</c> project files (BRIEF §18) against this index: the file for a sequence of one of its archives, and
/// the sequence a file names.
/// </summary>
public static class ProjectBundles
{
/// <summary>
/// The project file of <paramref name="sequenceId"/> with <paramref name="project"/> (the editor's current
/// settings), whose frame positions refer to <paramref name="frames"/> frames.
/// </summary>
/// <exception cref="InvalidOperationException">The sequence is not in the index.</exception>
public static async Task<ProjectBundle> CreateAsync(ChronosDatabase db, Guid sequenceId, ProjectSettings project, int frames,
CancellationToken cancellationToken = default)
{
var sequence = await db.Sequences.GetAsync(sequenceId, cancellationToken).ConfigureAwait(false)
?? throw new InvalidOperationException($"Sequence {sequenceId} is not in the index.");
var archive = await db.Archives.GetAsync(sequence.ArchiveId, cancellationToken).ConfigureAwait(false);
return new ProjectBundle(
new BundleArchive(sequence.ArchiveId, archive?.Name ?? string.Empty, archive?.RootPath),
new BundleSequence(sequence.Id, sequence.Folder, sequence.DisplayTitle, frames),
project,
DateTimeOffset.UtcNow);
}
/// <summary>
/// The sequence <paramref name="bundle"/> names: by its id, else the sequence in the same folder of the same
/// archive (an index rebuilt elsewhere, or a folder adopted again, gives it a new id). Null when this index has
/// neither: the archive is not added here, or the sequence was deleted.
/// </summary>
public static async Task<Sequence?> ResolveAsync(ChronosDatabase db, ProjectBundle bundle, CancellationToken cancellationToken = default)
{
if (await db.Sequences.GetAsync(bundle.Sequence.Id, cancellationToken).ConfigureAwait(false) is { } byId) return byId;
var locations = await db.Sequences.ListLocationsAsync(bundle.Archive.Id, cancellationToken).ConfigureAwait(false);
var match = locations.FirstOrDefault(l => string.Equals(l.Folder, bundle.Sequence.Folder, StringComparison.OrdinalIgnoreCase));
return match is null ? null : await db.Sequences.GetAsync(match.Id, cancellationToken).ConfigureAwait(false);
}
}
@@ -0,0 +1,69 @@
using System.Text.Json;
using Chronos.Core.Archiving;
using Chronos.Core.IO;
using Chronos.Core.Model;
using Chronos.Core.Project;
using Chronos.Data.Archiving;
using Chronos.Data.Repositories;
namespace Chronos.Data.Processing;
/// <summary>
/// The project of a sequence (BRIEF §7 <c>project.json</c>), mirrored in the index's settings column that the
/// server's API edits. The index copy is read first; writes go to both, under the sequence lock and with the index's
/// settings version as an optimistic check, so a concurrent edit is applied on top of, never overwritten.
/// </summary>
internal sealed class ProjectStore(ChronosDatabase db, SequenceWriter writer)
{
private const int Attempts = 3;
/// <summary>The settings in force: the index copy, else <c>project.json</c>, else defaults.</summary>
/// <exception cref="InvalidDataException">The settings are not valid JSON or come from a newer Chronos.</exception>
public static ProjectSettings Read(Sequence sequence, SequencePaths folder) =>
Parse(sequence.SettingsJson ?? (File.Exists(folder.ProjectPath) ? AtomicFile.ReadAllText(folder.ProjectPath) : null));
/// <exception cref="InvalidDataException">The settings are not valid JSON or come from a newer Chronos.</exception>
public static ProjectSettings Parse(string? json)
{
if (string.IsNullOrWhiteSpace(json)) return new ProjectSettings();
try
{
return ProjectSettings.FromJson(json);
}
catch (JsonException ex)
{
throw new InvalidDataException(ex.Message, ex);
}
}
/// <summary>Applies <paramref name="edit"/> to the settings in force and stores the result when it differs; false when nothing changed.</summary>
/// <exception cref="InvalidDataException">The stored settings cannot be read; nothing is written.</exception>
public async Task<bool> UpdateAsync(ArchivePaths paths, Sequence sequence, Func<ProjectSettings, ProjectSettings> edit, CancellationToken cancellationToken)
{
await using (await writer.LockAsync(paths, sequence.Id, cancellationToken).ConfigureAwait(false))
return await UpdateLockedAsync(paths, sequence, edit, cancellationToken).ConfigureAwait(false);
}
/// <summary><see cref="UpdateAsync"/> for a caller that holds the sequence lock already.</summary>
/// <exception cref="InvalidDataException">The stored settings cannot be read; nothing is written.</exception>
public async Task<bool> UpdateLockedAsync(ArchivePaths paths, Sequence sequence, Func<ProjectSettings, ProjectSettings> edit, CancellationToken cancellationToken)
{
var folder = paths.Sequence(sequence.Folder);
for (var attempt = 1; ; attempt++)
{
var row = await db.Sequences.GetAsync(sequence.Id, cancellationToken).ConfigureAwait(false) ?? sequence;
var current = Read(row, folder);
var before = current.ToJson();
var edited = edit(current);
var after = edited.ToJson();
if (after == before) return false;
AtomicFile.WriteAllText(folder.ProjectPath, after);
// The Library shows the project's hero frame (advice fills it, a sync takes another PC's).
var hero = await HeroFrame.EditAsync(db, sequence.Id, current.HeroFrame, edited.HeroFrame, cancellationToken).ConfigureAwait(false);
var result = await db.Sequences.EditAsync(sequence.Id, new SequenceEdit { SettingsJson = after, HeroFrameId = hero }, row.SettingsVersion,
cancellationToken).ConfigureAwait(false);
// A conflict means the API changed the settings meanwhile: apply the edit again on top of them.
if (result.Outcome != SequenceEditOutcome.Conflict || attempt == Attempts) return true;
}
}
}
@@ -0,0 +1,636 @@
using System.Diagnostics;
using System.Net;
using System.Text.Json;
using Chronos.Core.Archiving;
using Chronos.Core.Diagnostics;
using Chronos.Core.Export;
using Chronos.Core.Imaging;
using Chronos.Core.Localization;
using Chronos.Core.Model;
using Chronos.Core.Render;
using Chronos.Core.Video;
using Chronos.Data.Archiving;
using Chronos.Protocol;
using Chronos.Protocol.Client;
namespace Chronos.Data.Processing;
/// <summary>Settings of a <see cref="RenderNodeClient"/>.</summary>
public sealed record RenderNodeOptions
{
/// <summary>Name the server lists the node under; one node per user and name.</summary>
public required string ClientName { get; init; }
/// <summary>Folder for downloaded originals and for outputs until they are uploaded (inside the client's cache).</summary>
public required string CacheDirectory { get; init; }
/// <summary>Downloaded originals beyond this size are deleted, least recently used first, after every job.</summary>
public long CacheLimitBytes { get; init; } = 20L << 30;
/// <summary>Wait between claims while the queue has nothing for this node.</summary>
public TimeSpan PollInterval { get; init; } = TimeSpan.FromSeconds(10);
/// <summary>Sign of life; the server gives the jobs of a node silent for 90 s to others.</summary>
public TimeSpan HeartbeatInterval { get; init; } = TimeSpan.FromSeconds(30);
/// <summary>Shortest interval between progress reports to the server.</summary>
public TimeSpan ProgressInterval { get; init; } = TimeSpan.FromSeconds(2);
/// <summary>Concurrent frame downloads.</summary>
public int Downloads { get; init; } = 4;
/// <summary>Retries of a frame download cut by the network or a busy server, each resuming the partial file.</summary>
public int DownloadRetries { get; init; } = 5;
/// <summary>Wait before the first retry; it doubles with each further one.</summary>
public TimeSpan RetryDelay { get; init; } = TimeSpan.FromSeconds(1);
}
/// <summary>
/// "Offer this PC as render node" (BRIEF §14.7): registers this machine's single-file encoders with the server,
/// heart-beats, claims one render job at a time that it can encode, downloads the frames it needs (originals
/// hash-verified into a content-addressed cache, or proxies when the job asks or this PC cannot decode the original; a
/// dropped download resumes; frames missing, corrupt or excluded on the server are left out), renders the job's preset
/// with the host's encoders and uploads the output, which the server files as a render of the sequence. Then it sends
/// the proxies the server asks for, made from the originals it fetched (BRIEF §2.3: the server cannot decode HEIF).
/// Progress and render remarks go to the server; a job cancelled or reassigned there stops here; a failure is reported
/// with its reason. Stopping abandons the job in flight without reporting it: the server requeues it when the node
/// registers again or its heartbeats stop. Image sequences are not offered and batches are refused: the protocol uploads
/// one file per job.
/// </summary>
public sealed class RenderNodeClient : IAsyncDisposable
{
private const string LogCategory = "render-node";
/// <summary>
/// Frames no node renders: absent on the server, not the archived file, or excluded. Undecodable is the server's
/// verdict on its own decoders, so this PC's decoders try those frames.
/// </summary>
internal const FrameFlags NotFetched = FrameFlags.Missing | FrameFlags.Corrupt | FrameFlags.Excluded;
private readonly ChronosClient _client;
private readonly ProcessingOptions _processing;
private readonly RenderNodeOptions _options;
private readonly CancellationTokenSource _stopping = new();
private Task _running = Task.CompletedTask;
private Guid? _nodeId;
public RenderNodeClient(ChronosClient client, ProcessingOptions processing, RenderNodeOptions options)
{
_client = client;
_processing = processing;
_options = options;
}
/// <summary>
/// The encoders this node offers, each with its largest output: every single-file capability of the host's
/// providers, hardware ones only when the user lets renders use them (<see cref="ProcessingOptions.AllowsHardware"/>).
/// </summary>
public IReadOnlyList<NodeEncoder> Encoders =>
[
.. _processing.Encoders.SelectMany(p => p.Capabilities)
.Where(c => VideoCodecInfo.DefaultContainer(c.Codec) != ContainerFormat.ImageSequence
&& (!c.Hardware || _processing.AllowsHardware(ExportResolver.CustomId)))
.Select(c => new NodeEncoder(ProcessingJobs.CodecName(c.Codec), c.Name, c.Hardware, c.SupportsTenBit, c.MaxWidth, c.MaxHeight)),
];
/// <summary>Completes when the node has stopped: asked to, or refused by the server (signed out, no render-node right,
/// changed certificate), which only the user can change.</summary>
public Task Completion => _running;
/// <summary>Starts registering, heart-beating and claiming in the background.</summary>
public void Start() => _running = Task.Run(() => RunAsync(_stopping.Token));
/// <summary>Stops claiming, abandons the job in flight and waits for the background work to end.</summary>
public async Task StopAsync()
{
await _stopping.CancelAsync().ConfigureAwait(false);
await _running.ConfigureAwait(false);
}
public async ValueTask DisposeAsync()
{
await StopAsync().ConfigureAwait(false);
_stopping.Dispose();
}
/// <summary>Registers this node (again) and returns its id.</summary>
public async Task<Guid> RegisterAsync(CancellationToken cancellationToken)
{
// Each encoder carries its own limit; the node-wide one (for servers that read only that) is the largest offered.
var encoders = Encoders;
var request = new RegisterNodeRequest(_options.ClientName, encoders, encoders.Select(e => e.MaxWidth).DefaultIfEmpty().Max(),
encoders.Select(e => e.MaxHeight).DefaultIfEmpty().Max());
var node = await _client.RegisterNodeAsync(request, cancellationToken).ConfigureAwait(false);
_nodeId = node.Id;
return node.Id;
}
/// <summary>Claims one job this node can encode and runs it to the end; false when the queue had none.</summary>
public async Task<bool> RunOnceAsync(CancellationToken cancellationToken)
{
var nodeId = _nodeId ?? await RegisterAsync(cancellationToken).ConfigureAwait(false);
if (await _client.ClaimAsync(nodeId, cancellationToken).ConfigureAwait(false) is not { } claimed) return false;
var work = Path.Combine(_options.CacheDirectory, "jobs", claimed.Job.Id.ToString("N"));
using var job = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
var reporter = new NodeReporter(_client, nodeId, claimed.Job.Id, _options.ProgressInterval, job);
try
{
Directory.CreateDirectory(work);
var input = await RenderAsync(claimed, work, reporter, job.Token).ConfigureAwait(false);
// The job is done on the server; the proxies it asked for follow, on the node's own time.
await SendProxiesAsync(claimed, input, cancellationToken).ConfigureAwait(false);
}
catch (Exception ex) when (job.IsCancellationRequested)
{
// Stopping, or the server cancelled or reassigned the job: either way it is no longer ours to report.
Log.Info(LogCategory, $"Render job {claimed.Job.Id} abandoned: {ex.Message}");
}
catch (Exception ex)
{
// Whatever went wrong belongs to this job: report it and stay available for the next one.
Log.Warning(LogCategory, $"Render job {claimed.Job.Id} failed", ex);
await ReportFailureAsync(nodeId, claimed.Job.Id, SequenceRender.Reason(ex), cancellationToken).ConfigureAwait(false);
}
finally
{
TryDelete(work);
TrimCache();
}
return true;
}
private async Task RunAsync(CancellationToken stopping)
{
using var heartbeat = CancellationTokenSource.CreateLinkedTokenSource(stopping);
Task? beating = null;
while (!stopping.IsCancellationRequested)
{
try
{
var nodeId = _nodeId ?? await RegisterAsync(stopping).ConfigureAwait(false);
beating ??= HeartbeatAsync(heartbeat.Token);
if (await RunOnceAsync(stopping).ConfigureAwait(false)) continue;
}
catch (OperationCanceledException) when (stopping.IsCancellationRequested)
{
break;
}
catch (Exception ex) when (ex is ChronosApiException { Status: HttpStatusCode.Unauthorized or HttpStatusCode.Forbidden } or UntrustedCertificateException)
{
// Signed out, no render-node right, or a changed certificate: nothing to retry until the user acts.
Log.Warning(LogCategory, "The server refused this render node", ex);
break;
}
catch (ChronosApiException ex) when (ex.Status == HttpStatusCode.NotFound && _nodeId is not null)
{
_nodeId = null; // removed on the server: register again at once
continue;
}
catch (Exception ex)
{
// Server unreachable, busy or without the render-node routes: the node keeps trying until it is stopped.
Log.Warning(LogCategory, "Render node cycle failed; retrying", ex);
}
try
{
await Task.Delay(_options.PollInterval, stopping).ConfigureAwait(false);
}
catch (OperationCanceledException)
{
break;
}
}
await heartbeat.CancelAsync().ConfigureAwait(false);
if (beating is not null) await beating.ConfigureAwait(false);
}
private async Task HeartbeatAsync(CancellationToken cancellationToken)
{
using var timer = new PeriodicTimer(_options.HeartbeatInterval);
try
{
while (await timer.WaitForNextTickAsync(cancellationToken).ConfigureAwait(false))
{
if (_nodeId is not { } nodeId) continue;
try
{
await _client.HeartbeatAsync(nodeId, cancellationToken).ConfigureAwait(false);
}
catch (ChronosApiException ex) when (ex.Status == HttpStatusCode.NotFound)
{
_nodeId = null;
}
catch (Exception ex) when (!cancellationToken.IsCancellationRequested)
{
// Unreachable or refusing: the claim loop decides whether to go on; beating must not stop the node.
Log.Warning(LogCategory, "Heartbeat failed", ex);
}
}
}
catch (OperationCanceledException)
{
}
}
/// <summary>Renders the job and uploads its output; returns the frames it read.</summary>
private async Task<SequenceFrames> RenderAsync(ClaimedJob claimed, string work, NodeReporter reporter, CancellationToken cancellationToken)
{
var export = ProcessingJobs.ReadExport(claimed.PresetJson);
var resolved = ExportResolver.Resolve(export);
var target = new ExportTarget(resolved, ProcessingJobs.PresetName(resolved));
if (target.Export.Container == ContainerFormat.ImageSequence) throw new InvalidOperationException(Loc.L("Errors.Render.NodeSequence"));
// One output per job: a server splits batches into one job per preset when they are posted.
if (ProcessingJobs.BatchPresets(export).Any()) throw new InvalidOperationException(Loc.L("Errors.Render.NodeBatch"));
var project = ProjectStore.Parse(claimed.SettingsJson) with { Export = export };
var sequence = ToSequence(await _client.GetSequenceAsync(claimed.SequenceId, cancellationToken).ConfigureAwait(false));
// The server's Undecodable stands, as in its own render, except for a format only its decoders lack (HEIF) that
// this PC's read: such a frame renders here from its original. One read from its proxy renders either way.
var decoder = _processing.Archive.Decoder;
var frames = (await ListFramesAsync(claimed.SequenceId, cancellationToken).ConfigureAwait(false))
.ConvertAll(f => ArchiveImages.ServerNeedsProxy(f.Format) && !ArchiveImages.NeedsProxy(decoder, f.Format)
? f with { Flags = f.Flags & ~FrameFlags.Undecodable }
: f);
var files = await DownloadAsync(claimed, frames, work, reporter, cancellationToken).ConfigureAwait(false);
var input = new SequenceFrames(sequence, frames, [.. frames.Select(f => files.GetValueOrDefault(f.Id).Path)])
{
Proxied = [.. frames.Select(f => files.GetValueOrDefault(f.Id).Proxy)],
};
IReadOnlyList<TargetOutcome> outcomes;
await using (var render = new SequenceRender(input, project, null, _processing))
{
outcomes = await render.RenderAllAsync(
[(0, target)],
(t, setup) => ExportNaming.OutputPath(work, project.Export.NameTemplate, SequenceRender.NameContext(sequence, t, setup)),
(_, _) => ValueTask.CompletedTask,
async (_, t, result) =>
{
// Remarks first: completing the upload ends the job on the server.
foreach (var remark in SequenceRender.Remarks(result)) await reporter.LogAsync(remark).ConfigureAwait(false);
await UploadAsync(reporter.NodeId, claimed.Job.Id, t, result, cancellationToken).ConfigureAwait(false);
},
reporter.ReportAsync,
cancellationToken).ConfigureAwait(false);
}
if (outcomes[0].Error is { } error) throw new InvalidOperationException(error);
return input;
}
/// <summary>
/// Sends the proxies the server asks for (<see cref="ManifestFrame.WantsProxy"/>) that this PC can make from the
/// originals it fetched, as the server's proxy policy says; a failure is logged and never fails the finished job.
/// </summary>
private async Task SendProxiesAsync(ClaimedJob claimed, SequenceFrames input, CancellationToken cancellationToken)
{
if (claimed.Proxies is not { } spec) return;
var wanted = claimed.Frames.Where(f => f.WantsProxy).Select(f => f.Id).ToHashSet();
if (wanted.Count == 0) return;
var camera = new SidecarCamera { Make = input.Sequence.CameraMake, Model = input.Sequence.CameraModel };
int sent = 0, unsent = 0;
for (var i = 0; i < input.Count; i++)
{
var frame = input.Frames[i];
if (!wanted.Remove(frame.Id)) continue;
if (input.Proxied?[i] == true || input.Files[i] is not { } original)
{
unsent++;
continue;
}
try
{
var jpeg = await Task.Run(async () =>
{
await Task.Yield();
return ArchiveImages.MakeProxy(_processing.Archive.Decoder, original, frame, camera, spec.LongEdge, spec.Quality, cancellationToken);
}, cancellationToken).ConfigureAwait(false);
if (jpeg is null)
{
unsent++;
continue;
}
await _client.UploadProxyAsync(frame.Id, jpeg, cancellationToken).ConfigureAwait(false);
sent++;
}
catch (ChronosApiException ex) when (ex.Status is HttpStatusCode.Conflict or HttpStatusCode.Forbidden)
{
// Proxies turned off on the server, or this account may no longer send them: none of the rest would go either.
Log.Warning(LogCategory, $"The server refused the proxies of job {claimed.Job.Id}", ex);
return;
}
catch (Exception ex) when (!cancellationToken.IsCancellationRequested)
{
// Best effort (a timed-out upload included): the job is done, and a proxy the server still lacks is asked for
// again with the next job.
Log.Warning(LogCategory, $"The proxy of {frame.FileName} could not be sent", ex);
unsent++;
}
}
Log.Info(LogCategory, $"Proxies of job {claimed.Job.Id}: {sent} sent, {unsent + wanted.Count} not");
}
private async Task UploadAsync(Guid nodeId, Guid jobId, ExportTarget target, RenderResult result, CancellationToken cancellationToken)
{
var size = new FileInfo(result.OutputPath).Length;
var sha = await ChronosClient.HashFileAsync(result.OutputPath, cancellationToken).ConfigureAwait(false);
var request = new RenderResultRequest(Path.GetFileName(result.OutputPath), size, sha, target.PresetName, ProcessingJobs.CodecName(result.Codec),
result.Width, result.Height, result.FrameRate.Value, result.DurationSeconds);
await _client.UploadRenderResultAsync(nodeId, jobId, result.OutputPath, request, null, cancellationToken).ConfigureAwait(false);
}
private async Task<List<Frame>> ListFramesAsync(Guid sequenceId, CancellationToken cancellationToken)
{
var frames = new List<Frame>();
string? cursor = null;
do
{
var page = await _client.ListFramesAsync(sequenceId, cursor, 1000, cancellationToken).ConfigureAwait(false);
frames.AddRange(page.Items.Select(ToFrame));
cursor = page.NextCursor;
}
while (cursor is not null);
frames.Sort((a, b) => a.Index.CompareTo(b.Index));
return frames;
}
/// <summary>
/// The files of the job's frames (none for frames missing, corrupt or excluded on the server): originals verified
/// against their SHA-256 into the content-addressed cache (reused across jobs, fetched once per content), originals the
/// server has not hashed yet into the job folder, or proxies into the job folder when the job asks for them or this PC
/// cannot decode the original, and the server has them.
/// </summary>
private async Task<Dictionary<Guid, (string Path, bool Proxy)>> DownloadAsync(ClaimedJob claimed, IReadOnlyList<Frame> rows, string work,
NodeReporter reporter, CancellationToken cancellationToken)
{
var formats = rows.ToDictionary(f => f.Id, f => f.Format);
var undecodable = rows.Where(f => (f.Flags & FrameFlags.Undecodable) != 0).Select(f => f.Id).ToHashSet();
bool Proxy(ManifestFrame f) =>
f.HasProxy && (claimed.UseProxies || (formats.TryGetValue(f.Id, out var format) && ArchiveImages.NeedsProxy(_processing.Archive.Decoder, format)));
var files = new Dictionary<Guid, (string, bool)>();
// An original that stays undecodable would only be skipped by the render.
var fetched = claimed.Frames.Where(f => ((FrameFlags)f.Flags & NotFetched) == 0 && (Proxy(f) || !undecodable.Contains(f.Id))).ToList();
var done = 0;
var total = fetched.Count;
await reporter.ReportAsync(0, total, Loc.L("Export.Job.Downloading")).ConfigureAwait(false);
var downloads = fetched.GroupBy(f => Proxy(f) || f.Sha256.Length == 0 ? f.Id.ToString("N") : f.Sha256.ToLowerInvariant()).ToList();
await Parallel.ForEachAsync(downloads, new ParallelOptions { MaxDegreeOfParallelism = _options.Downloads, CancellationToken = cancellationToken },
async (frames, ct) =>
{
var frame = frames.First();
var file = Proxy(frame)
? await DownloadProxyAsync(frame, work, ct).ConfigureAwait(false)
: (await DownloadOriginalAsync(frame, work, ct).ConfigureAwait(false), false);
lock (files)
{
foreach (var f in frames) files[f.Id] = file;
}
await reporter.ReportAsync(Interlocked.Add(ref done, frames.Count()), total, null).ConfigureAwait(false);
}).ConfigureAwait(false);
return files;
}
/// <summary>
/// A proxy into the job folder (regenerable, so neither cached nor hashed: the server keeps no hash of it, and a retry
/// fetches it whole, since a proxy rebuilt meanwhile must not be resumed from the old one); the original when the server
/// has none for the frame.
/// </summary>
private async Task<(string Path, bool Proxy)> DownloadProxyAsync(ManifestFrame frame, string work, CancellationToken cancellationToken)
{
var path = Path.Combine(work, "proxies", frame.Id.ToString("N") + ".jpg");
Directory.CreateDirectory(Path.GetDirectoryName(path)!);
try
{
await FetchAsync(frame, "proxy", path, resume: false, cancellationToken).ConfigureAwait(false);
return (path, true);
}
catch (ChronosApiException ex) when (ex.Status == HttpStatusCode.NotFound)
{
File.Delete(path);
return (await DownloadOriginalAsync(frame, work, cancellationToken).ConfigureAwait(false), false);
}
}
/// <summary>
/// A cached copy, or a download (resumed from a partial one) that must hash to the manifest's SHA-256; an original the
/// server has not hashed yet goes into the job folder and must have the manifest's size.
/// </summary>
private async Task<string> DownloadOriginalAsync(ManifestFrame frame, string work, CancellationToken cancellationToken)
{
if (frame.Sha256.Length == 0) return await DownloadUnhashedAsync(frame, work, cancellationToken).ConfigureAwait(false);
var sha = frame.Sha256.ToLowerInvariant();
if (sha.Length != 64 || !sha.All(char.IsAsciiHexDigitLower)) throw new InvalidDataException(Loc.L("Errors.Render.Download", frame.FileName));
var path = Path.Combine(_options.CacheDirectory, "originals", sha[..2], sha + Path.GetExtension(frame.FileName).ToLowerInvariant());
if (File.Exists(path))
{
File.SetLastWriteTimeUtc(path, DateTime.UtcNow); // most recently used: kept by the cache trim
return path;
}
Directory.CreateDirectory(Path.GetDirectoryName(path)!);
var part = path + ".part";
for (var attempt = 1; ; attempt++)
{
// A part as long as the file was complete when the last attempt stopped: only its hash is left to check.
if (!File.Exists(part) || new FileInfo(part).Length < frame.Size) await FetchAsync(frame, "original", part, resume: true, cancellationToken).ConfigureAwait(false);
if (await ChronosClient.HashFileAsync(part, cancellationToken).ConfigureAwait(false) == sha)
{
File.Move(part, path, overwrite: true);
return path;
}
File.Delete(part);
if (attempt == 2) throw new InvalidDataException(Loc.L("Errors.Render.Download", frame.FileName));
}
}
/// <summary>
/// An original without a SHA-256 on the server (adopted, not verified yet): nothing to check it against but its size,
/// so it is neither cached nor shared with other frames; a copy of another size is fetched again once.
/// </summary>
private async Task<string> DownloadUnhashedAsync(ManifestFrame frame, string work, CancellationToken cancellationToken)
{
var path = Path.Combine(work, "originals", frame.Id.ToString("N") + Path.GetExtension(frame.FileName).ToLowerInvariant());
Directory.CreateDirectory(Path.GetDirectoryName(path)!);
for (var attempt = 1; ; attempt++)
{
if (!File.Exists(path) || new FileInfo(path).Length < frame.Size) await FetchAsync(frame, "original", path, resume: true, cancellationToken).ConfigureAwait(false);
if (new FileInfo(path).Length == frame.Size) return path;
File.Delete(path);
if (attempt == 2) throw new InvalidDataException(Loc.L("Errors.Render.Download", frame.FileName));
}
}
/// <summary>
/// Fetches a frame resource into <paramref name="path"/>. A dropped connection or a busy server is retried (up to
/// <see cref="RenderNodeOptions.DownloadRetries"/> times, the wait doubling from <see cref="RenderNodeOptions.RetryDelay"/>);
/// with <paramref name="resume"/> (a download its hash verifies) each attempt appends to what the last one left,
/// otherwise it starts over.
/// </summary>
private async Task FetchAsync(ManifestFrame frame, string kind, string path, bool resume, CancellationToken cancellationToken)
{
for (var attempt = 0; ; attempt++)
{
try
{
await using var file = new FileStream(path, resume ? FileMode.OpenOrCreate : FileMode.Create, FileAccess.ReadWrite, FileShare.None);
await _client.DownloadFrameAsync(frame.Id, kind, file, null, cancellationToken).ConfigureAwait(false);
return;
}
catch (Exception ex) when (attempt < _options.DownloadRetries && !cancellationToken.IsCancellationRequested && IsTransient(ex))
{
Log.Info(LogCategory, $"Download of {frame.FileName} ({kind}) interrupted, resuming: {ex.Message}");
await Task.Delay(_options.RetryDelay * (1 << attempt), cancellationToken).ConfigureAwait(false);
}
}
}
/// <summary>Failures a later attempt can get past: the network, a busy server, a timeout (not a cancellation of ours).</summary>
private static bool IsTransient(Exception ex) =>
ex is HttpRequestException or IOException or OperationCanceledException or ChronosApiException { IsTransient: true };
private async Task ReportFailureAsync(Guid nodeId, Guid jobId, string error, CancellationToken cancellationToken)
{
try
{
await _client.ReportNodeFailureAsync(nodeId, jobId, error, cancellationToken).ConfigureAwait(false);
}
catch (Exception ex) when (ex is ChronosApiException or HttpRequestException or IOException or OperationCanceledException)
{
// Cancelled or reassigned meanwhile, or the server is gone: it requeues the job when the heartbeats stop.
Log.Warning(LogCategory, $"The failure of job {jobId} could not be reported", ex);
}
}
/// <summary>Deletes the least recently used originals until the cache fits its limit.</summary>
private void TrimCache()
{
try
{
var root = new DirectoryInfo(Path.Combine(_options.CacheDirectory, "originals"));
if (!root.Exists) return;
var files = root.EnumerateFiles("*", SearchOption.AllDirectories).OrderBy(f => f.LastWriteTimeUtc).ToList();
var size = files.Sum(f => f.Length);
foreach (var file in files)
{
if (size <= _options.CacheLimitBytes) break;
size -= file.Length;
file.Delete();
}
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
Log.Warning(LogCategory, "The render node cache could not be trimmed", ex);
}
}
private static void TryDelete(string folder)
{
try
{
if (Directory.Exists(folder)) Directory.Delete(folder, recursive: true);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
Log.Warning(LogCategory, $"Could not remove {folder}", ex);
}
}
internal static Sequence ToSequence(SequenceDto s) => new()
{
Id = s.Id,
ArchiveId = Guid.Empty,
Folder = s.Folder,
Title = s.Title,
CameraMake = s.CameraMake,
CameraModel = s.CameraModel,
Lens = s.Lens,
FirstCapture = s.FirstCapture,
LastCapture = s.LastCapture,
FrameCount = s.FrameCount,
};
internal static Frame ToFrame(FrameDto f) => new()
{
Id = f.Id,
SequenceId = f.SequenceId,
Index = f.Index,
RelativePath = f.FileName,
FileName = f.FileName,
Size = f.Size,
Sha256 = f.Sha256,
CapturedAt = f.CapturedAt,
UtcOffsetMinutes = f.UtcOffsetMinutes,
ExposureTime = f.ExposureTime,
FNumber = f.FNumber,
Iso = f.Iso,
FocalLength = f.FocalLength,
Orientation = f.Orientation,
Width = f.Width,
Height = f.Height,
Format = Enum.TryParse<ImageFileFormat>(f.Format, ignoreCase: true, out var format) ? format : default,
Flags = (FrameFlags)f.Flags,
PreviewWidth = f.PreviewWidth,
PreviewHeight = f.PreviewHeight,
};
/// <summary>
/// Progress of the job in flight to the server, at most every interval (and at the end). A refusal (409) means the
/// job was cancelled or given to another node: the job's token is cancelled.
/// </summary>
private sealed class NodeReporter(ChronosClient client, Guid nodeId, Guid jobId, TimeSpan interval, CancellationTokenSource job)
{
private readonly Stopwatch _clock = Stopwatch.StartNew();
private readonly SemaphoreSlim _gate = new(1, 1);
private TimeSpan _last = TimeSpan.MinValue;
private long _lastDone;
private long _lastTotal;
private string? _lastMessage;
public Guid NodeId => nodeId;
/// <summary>Progress, sent at most every interval; a stage message is sent when it changes.</summary>
public ValueTask ReportAsync(long done, long total, string? message) => SendAsync(done, total, message, remark: false);
/// <summary>A line for the job's log on the server, sent with the progress last reported.</summary>
public ValueTask LogAsync(string line) => SendAsync(0, 0, line, remark: true);
private async ValueTask SendAsync(long done, long total, string? message, bool remark)
{
await _gate.WaitAsync(CancellationToken.None).ConfigureAwait(false);
try
{
NodeProgress progress;
if (remark)
{
progress = new NodeProgress(_lastDone, _lastTotal, null, message);
}
else
{
var now = _clock.Elapsed;
var line = message is not null && message != _lastMessage ? message : null;
if (line is null && done < total && now - _last < interval) return;
double? rate = _last == TimeSpan.MinValue || done < _lastDone ? null : (done - _lastDone) / double.Max((now - _last).TotalSeconds, 1e-3);
(_last, _lastDone, _lastTotal) = (now, done, total);
if (line is not null) _lastMessage = line;
progress = new NodeProgress(done, total, rate, line);
}
await client.ReportNodeProgressAsync(nodeId, jobId, progress, job.Token).ConfigureAwait(false);
}
catch (ChronosApiException ex) when (ex.Status == HttpStatusCode.Conflict)
{
await job.CancelAsync().ConfigureAwait(false);
}
catch (Exception ex) when (ex is ChronosApiException or HttpRequestException or IOException)
{
Log.Warning(LogCategory, "Progress could not be reported", ex);
}
catch (OperationCanceledException)
{
// The job is stopping; its outcome is handled by the caller.
}
finally
{
_gate.Release();
}
}
}
}
@@ -0,0 +1,351 @@
using System.Security.Cryptography;
using System.Text;
using Chronos.Core.Advice;
using Chronos.Core.Analysis;
using Chronos.Core.Analysis.Deep;
using Chronos.Core.Archiving;
using Chronos.Core.Imaging;
using Chronos.Core.Model;
using Chronos.Data.Archiving;
using Chronos.Data.Repositories;
namespace Chronos.Data.Processing;
/// <summary>What an analysis of one sequence found and changed.</summary>
/// <param name="Warnings">Findings of warning severity or worse (light and, when current, deep).</param>
/// <param name="SettingsChanged">The advisor changed Auto values of the project.</param>
/// <param name="SettingsUnreadable">The project could not be read, so its Auto values were left alone.</param>
/// <param name="Presets">Sequence presets that fit the content (deep analysis only).</param>
/// <param name="FramesChanged">How the frames it read were no longer the sequence's when it recorded: anything but
/// <see cref="FramesChange.None"/> means nothing was recorded from them.</param>
internal sealed record AnalysisOutcome(Sequence Sequence, int Frames, int Warnings, bool SettingsChanged, bool SettingsUnreadable,
IReadOnlyList<SequencePreset> Presets, FramesChange FramesChanged = FramesChange.None);
/// <summary>How the frames an analysis read had changed by the time it recorded, under the sequence lock.</summary>
internal enum FramesChange
{
/// <summary>Still the sequence's frames, or changed in this index with a light analysis queued to replace what it records.</summary>
None,
/// <summary>
/// Added, removed or renumbered in this index (an upload, an import, a scan), with no light analysis queued: one must
/// run here for the frames as they are.
/// </summary>
Indexed,
/// <summary>
/// Changed in the sidecar by another process (a desktop sharing a server's archive, or that server), which analyses
/// them; this index holds them only after its next scan, which on a server queues their analysis here too.
/// </summary>
NotIndexed,
}
/// <summary>
/// Light (BRIEF §10.1) and deep (§10.2) analysis of archived sequences, followed by the advisor (§10.3–10.4) filling the
/// Auto values of the project. The light pass reads the index, probes the decode tier (§8.2) of frames whose tier is not
/// known yet (headers only, once per frame) and reads one file for the GPS fix; the deep pass decodes every frame,
/// checkpointing into <c>.chronos/analysis.partial</c> so a cancelled, paused or crashed run resumes, records the tier
/// each frame decoded at (or that it did not decode) and saves <c>analysis.json</c> atomically under the sequence lock.
/// Results land in the sidecar (status, tiers), the index (status, warning count, compact summary, tier flags,
/// per-frame light statistics) and <c>project.json</c>.
/// </summary>
internal sealed class SequenceAnalyser(ChronosDatabase db, ProcessingOptions options, SequenceWriter writer, ArchiveIndexer indexer, ProjectStore projects)
{
/// <summary>Long edge of the decode that confirms a frame an interrupted earlier run found undecodable.</summary>
private const int ConfirmLongEdge = 64;
private readonly FrameTiers _tiers = new(db, writer, indexer);
/// <summary>Analyses one sequence; null when it is no longer in the index.</summary>
/// <exception cref="ArchiveOfflineException">The archive is offline or read-only.</exception>
public async Task<AnalysisOutcome?> AnalyseAsync(Guid sequenceId, bool deep, IProgress<AnalysisProgress>? progress, CancellationToken cancellationToken)
{
if (await db.Sequences.GetAsync(sequenceId, cancellationToken).ConfigureAwait(false) is not { } sequence
|| await db.Archives.GetAsync(sequence.ArchiveId, cancellationToken).ConfigureAwait(false) is not { } archive) return null;
var paths = new ArchivePaths(archive.RootPath);
ArchiveVolume.EnsureWritable(paths);
var folder = paths.Sequence(sequence.Folder);
var frames = await SequenceFrames.LoadAsync(db, archive, sequence, useProxies: false, options.Archive.Decoder, cancellationToken).ConfigureAwait(false);
// Format tiers (BRIEF §10.1): frames indexed since the last analysis are probed with this host's decoders. A frame
// read from its proxy is not preview-only whatever its original's tier, so it caps nothing (BRIEF §8.1, §8.2); the
// flags are taken as the sidecar has them once recorded, so ones another worker recorded meanwhile count too.
var probed = await _tiers.ProbeUnknownAsync(archive, folder, ManifestStore.ReadSequence(folder.ManifestPath), cancellationToken).ConfigureAwait(false);
frames = WithTiers(frames, await _tiers.RecordAsync(archive, sequence, probed, proxies: true, cancellationToken).ConfigureAwait(false));
var metadata = frames.LightFrames();
DeepAnalysisReport? report = null;
if (deep)
{
// Proxies may have arrived during the pass: the flags below follow the frames as they are at its end, and the
// report is checked against them under the lock.
(report, var decoded) = await AnalyseDeepAsync(archive, frames, metadata, folder, progress, cancellationToken).ConfigureAwait(false);
frames = WithTiers(frames, await _tiers.RecordAsync(archive, sequence, decoded, proxies: true, cancellationToken).ConfigureAwait(false));
metadata = [.. metadata.Select((m, i) => m with { Flags = frames.Frames[i].Flags })];
}
var light = LightAnalyzer.Analyze(metadata);
var context = SequenceContext.FromFrames(frames.Frames, options.AdvisorCodecs);
bool changed, unreadable = false;
int warnings;
// Under the sequence lock, which a deep pass of the same sequence also takes to record its report: a light pass
// then either sees that report or runs before it is recorded, and never clears what it recorded. The report counts
// only while it describes the frames as they are under the lock (ReadReport), so a deep pass loads them again: a
// proxy that arrived while it ran (for hours) makes its verdict on that frame's original stale. The light analysis
// the proxy queued then either ran before this, and the advice, status and warnings stay without the report as it
// left them, or runs after. A pass whose frames were added to, removed or renumbered since it read them records
// nothing (FramesChangeAsync), and a light analysis of the frames as they are runs instead, here or where they
// were changed; its report is saved only over none of the frames as they are (SaveReport). What a deep pass records
// then follows the report analysis.json holds: its own, or the one it left in place.
await using (await writer.LockAsync(paths, sequence.Id, cancellationToken).ConfigureAwait(false))
{
var manifest = SequenceWriter.ReadLocked(folder, sequence.Id);
var change = await FramesChangeAsync(sequence, manifest, cancellationToken).ConfigureAwait(false);
// The frames as this host reads them now: a proxy that arrived while the pass ran moves no frames version but
// makes the pass's verdict on that frame's original stale, so only a report that describes them is current.
var now = deep && change == FramesChange.None
? await SequenceFrames.LoadAsync(db, archive, sequence, useProxies: false, options.Archive.Decoder, cancellationToken).ConfigureAwait(false)
: null;
var saved = deep && SaveReport(folder, report!,
change == FramesChange.None && manifest.Versions.Frames == sequence.FramesVersion && Describes(report!, now!),
now, manifest.Frames.Count);
if (change != FramesChange.None)
return new AnalysisOutcome(sequence, frames.Count, 0, SettingsChanged: false, SettingsUnreadable: false, [], change);
if (deep)
{
// A report left in place is read as a light analysis reads it, so the deep status, summary, warnings and
// Auto values recorded here describe the file that readers and the report endpoint open.
if (!saved) report = ReadReport(folder, now!);
else if (!Describes(report!, now!)) report = null;
}
else
{
report = ReadReport(folder, frames);
}
try
{
// The frame rate follows the user's "fit to N seconds" when one is set (BRIEF §10.3).
changed = await projects.UpdateLockedAsync(paths, sequence,
settings => Advisor.Apply(settings, Advisor.Recommend(light, report, context with { TargetDurationSeconds = settings.Timing.FitToSeconds })),
cancellationToken).ConfigureAwait(false);
}
catch (InvalidDataException ex)
{
Core.Diagnostics.Log.Warning("processing", $"The project of {sequence.DisplayTitle} cannot be read", ex);
(changed, unreadable) = (false, true);
}
warnings = Advisor.Recommend(light, report, context).Findings.Count(f => f.Severity >= FindingSeverity.Warning);
var set = SequenceStatus.AnalyzedLight | (report is null ? SequenceStatus.None : SequenceStatus.AnalyzedDeep)
| (warnings > 0 ? SequenceStatus.HasWarnings : SequenceStatus.None);
// Without a current report (none, or made before frames were added) the deep status no longer holds.
var clear = (report is null ? SequenceStatus.AnalyzedDeep : SequenceStatus.None) | (warnings > 0 ? SequenceStatus.None : SequenceStatus.HasWarnings);
var inStep = await indexer.InStepAsync(archive, folder, manifest, cancellationToken).ConfigureAwait(false);
var status = (manifest.Status | set) & ~clear;
if (status != manifest.Status) ManifestStore.WriteSequence(folder.ManifestPath, manifest with { Status = status, UpdatedAt = DateTimeOffset.UtcNow });
var summary = deep && report is not null ? AnalysisSummary.From(report).ToJson() : null;
await db.Sequences.RecordAnalysisAsync(sequence.Id, set, clear, warnings, summary, cancellationToken).ConfigureAwait(false);
if (inStep) await indexer.RecordStampsAsync(archive, folder, sequence.Id, cancellationToken).ConfigureAwait(false);
}
if (changed) await options.NotifyAsync(sequence.Id, ProcessingOptions.SettingsChange, cancellationToken).ConfigureAwait(false);
var presets = deep ? SequencePresets.Generate(light, report, context) : [];
return new AnalysisOutcome(sequence, frames.Count, warnings, changed, unreadable, presets);
}
/// <summary>
/// How the frames this pass read had changed by now, under the sequence lock. Every writer of this index's frames bumps
/// the row's frames version with them under the same lock (an upload or import, a scan reconciling photos copied in by
/// hand or indexing frames another process listed in the sidecar), and every writer of the sidecar's frames bumps its
/// version (<paramref name="manifest"/>, read under the lock). What the pass found then describes other frames:
/// recorded, it would mark the new ones analysed, with Auto values and warnings counted on the old ones, over what an
/// analysis of the frames as they are may have recorded already, in the shared sidecar and <c>project.json</c> too.
/// A sidecar at another version than the row lists frames another process changed and this index does not hold yet
/// (<see cref="FramesChange.NotIndexed"/>): nothing is queued here, since a light analysis would read this index as
/// it is and find it behind the sidecar again until the next scan indexes them. A row whose version moved since the
/// pass read it holds the frames as they are, and a light analysis here covers them (<see cref="FramesChange.Indexed"/>).
/// One already queued for the sequence runs after this on the frames as they are then, so the pass still records
/// meanwhile, as an image pass keeps its flag (<see cref="ArchiveImages"/>): during an upload burst every pass is
/// overtaken, and a sequence being shot would otherwise show no analysis until uploads paused.
/// </summary>
private async Task<FramesChange> FramesChangeAsync(Sequence sequence, SequenceManifest manifest, CancellationToken cancellationToken)
{
if (await db.Sequences.GetAsync(sequence.Id, cancellationToken).ConfigureAwait(false) is not { } row) return FramesChange.None;
if (manifest.Versions.Frames != row.FramesVersion) return FramesChange.NotIndexed;
return row.FramesVersion == sequence.FramesVersion
|| await db.Jobs.IsQueuedAsync(JobKind.LightAnalyse, sequence.Id, cancellationToken).ConfigureAwait(false)
? FramesChange.None
: FramesChange.Indexed;
}
/// <summary>
/// The saved deep report when it describes <paramref name="frames"/> as this host reads them now: also stale when a
/// frame it found unreadable has been read from its proxy since (one sent for an original this host cannot decode,
/// BRIEF §2.3), so that verdict and the frame's missing measurements no longer hold.
/// </summary>
public static DeepAnalysisReport? ReadReport(SequencePaths folder, SequenceFrames frames) =>
ReadReport(folder, frames.Count) is { } report && Describes(report, frames) ? report : null;
/// <summary>Whether <paramref name="report"/> describes <paramref name="frames"/> as this host reads them now (<see cref="ReadReport(SequencePaths, SequenceFrames)"/>).</summary>
private static bool Describes(DeepAnalysisReport report, SequenceFrames frames)
{
if (report.FrameCount != frames.Count) return false;
if (frames.Proxied is not { } proxied) return true;
HashSet<int> measured = report.ProxyFrames is { } read ? [.. read] : [];
foreach (var index in report.Issues.Undecodable)
{
if (index < frames.Count && proxied[index] && !measured.Contains(index) && (frames.Frames[index].Flags & SequenceFrames.NotAnalysed) == 0)
return false;
}
return true;
}
/// <summary>The saved deep report when it covers <paramref name="frameCount"/> frames; null when absent, stale or unreadable.</summary>
public static DeepAnalysisReport? ReadReport(SequencePaths folder, int frameCount)
{
if (!File.Exists(folder.AnalysisPath)) return null;
try
{
var report = DeepAnalysisReport.Load(folder.AnalysisPath);
return report.FrameCount == frameCount ? report : null;
}
catch (Exception ex) when (ex is IOException or InvalidDataException or System.Text.Json.JsonException)
{
Core.Diagnostics.Log.Warning("processing", $"{folder.AnalysisPath} cannot be read", ex);
return null;
}
}
/// <summary>The frame rows with the flags and preview sizes of the <paramref name="current"/> sidecar frames.</summary>
private static SequenceFrames WithTiers(SequenceFrames frames, IReadOnlyList<SidecarFrame> current)
{
if (current.Count == 0) return frames;
var byId = current.ToDictionary(f => f.Id);
var rows = frames.Frames.Select(f => byId.TryGetValue(f.Id, out var s)
? f with { Flags = s.Flags, PreviewWidth = s.PreviewW ?? 0, PreviewHeight = s.PreviewH ?? 0 }
: f).ToList();
return frames with { Frames = rows };
}
/// <summary>
/// What the deep pass learnt about each frame's tier, by frame id: the tier this run decoded it at. A frame this run
/// tried to read and recorded nothing for vanished or could not be read, which says nothing about its content. A frame
/// only an interrupted earlier run analysed and found undecodable is decoded again (small) to confirm it: that run's
/// failure may have been a read error too. Missing and corrupt frames are not decoded at all.
/// </summary>
private Dictionary<Guid, FileTier> Decoded(SequenceFrames frames, DeepAnalysisReport report, SequenceFrameSource source,
IReadOnlyDictionary<Guid, string> companions, CancellationToken cancellationToken)
{
var tiers = new Dictionary<Guid, FileTier>();
foreach (var (index, tier) in source.Observed) tiers[frames.Frames[index].Id] = tier;
var read = source.Read.ToHashSet();
foreach (var index in report.Issues.Undecodable)
{
// A frame read from its proxy says nothing about its original's tier.
if (index >= frames.Count || read.Contains(index) || frames.Files[index] is not { } path
|| (frames.Frames[index].Flags & SequenceFrames.NotAnalysed) != 0 || frames.Proxied is { } proxied && proxied[index]) continue;
var frame = frames.Frames[index];
try
{
using var decoded = options.Archive.Decoder.Decode(
new DecodeRequest(path, ConfirmLongEdge, DecodePurpose.Analysis, Companion: companions.GetValueOrDefault(frame.Id)), cancellationToken);
if (decoded is not null) tiers[frame.Id] = new FileTier(frame.Format, decoded.Tier, decoded.Decoder, null, 0, 0);
else if (File.Exists(path)) tiers[frame.Id] = new FileTier(frame.Format, DecodeTier.Unavailable, null, "no decoder produced pixels", 0, 0);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
Core.Diagnostics.Log.Warning("processing", $"Frame {path} could not be read", ex);
}
}
return tiers;
}
/// <summary>
/// Saves a deep pass's report as <c>analysis.json</c>, under the sequence lock, then drops its checkpoint; returns
/// whether it saved it. The report replaces the saved one when it describes the frames as they are
/// (<paramref name="current"/>), or when the saved one describes them no better: none, unreadable, or not describing
/// <paramref name="now"/> (the frames as this host reads them, proxies included), or, when they were not read, of
/// another frame count than <paramref name="frameCount"/>, the sidecar's. A pass overtaken by an upload, by a proxy,
/// or by another process sharing the archive, would otherwise replace the report a later pass made of the frames as
/// they are, and the next light analysis would drop that one's deep status.
/// </summary>
private static bool SaveReport(SequencePaths folder, DeepAnalysisReport report, bool current, SequenceFrames? now, int frameCount)
{
var save = current || (now is not null ? ReadReport(folder, now) : ReadReport(folder, frameCount)) is null;
if (save) report.Save(folder.AnalysisPath);
Checkpoint(folder).Delete();
return save;
}
/// <summary>The deep pass's checkpoint, <c>.chronos/analysis.partial</c>: kept until the pass has saved its report.</summary>
private static DeepAnalysisCheckpointFile Checkpoint(SequencePaths folder) =>
new(Path.Combine(folder.MetaDirectory, DeepAnalysisCheckpointFile.FileName));
private async Task<(DeepAnalysisReport Report, Dictionary<Guid, FileTier> Decoded)> AnalyseDeepAsync(Archive archive, SequenceFrames frames,
IReadOnlyList<LightFrame> metadata, SequencePaths folder, IProgress<AnalysisProgress>? progress, CancellationToken cancellationToken)
{
var file = Checkpoint(folder);
// The host's analysis parameters as they are now (Settings › Analysis on the desktop). Those that change per-frame
// results are part of the checkpoint's fingerprint, so a partial run made with other values starts again.
var analysis = options.Current.DeepAnalysis;
analysis = analysis with { MaxDegreeOfParallelism = AnalysisParallelism(analysis, frames, options.Archive.MemoryBudget()) };
var companions = await GprCompanions.FindAsync(db, archive, frames.Frames, cancellationToken).ConfigureAwait(false);
DeepAnalysisReport report;
Dictionary<Guid, FileTier> decoded;
await using (var source = new SequenceFrameSource(frames, metadata, options.Archive.Decoder) { Originals = true, Companions = companions })
{
report = await DeepAnalyzer.AnalyzeAsync(source, analysis, new FramesCheckpoint(file, ContentKey(frames)), progress, cancellationToken)
.ConfigureAwait(false);
decoded = Decoded(frames, report, source, companions, cancellationToken);
}
// An unreadable verdict on a frame read from its original goes stale once the frame has a proxy (ReadReport). The
// report is saved under the sequence lock, once the frames it measured are known to be current (SaveReport).
int[] fromProxies = [.. Enumerable.Range(0, frames.Count).Where(i => frames.Proxied?[i] == true)];
report = report with { ProxyFrames = fromProxies.Length > 0 ? fromProxies : null };
var columns = report.Frames;
var stats = new FrameLightStats[frames.Count];
for (var i = 0; i < stats.Length; i++)
stats[i] = new FrameLightStats(frames.Frames[i].Id, columns.LogLuminance[i], columns.ClipLow[i], columns.ClipHigh[i]);
await db.Frames.UpdateLightStatsAsync(stats, cancellationToken).ConfigureAwait(false);
return (report, decoded);
}
/// <summary>
/// Frames a deep analysis measures at once (owner review 1): its parallelism, fewer when some frame is developed whole
/// at its analysis size and <paramref name="memoryBudget"/> cannot hold that many (<see cref="SequenceFrames.DevelopedPixels"/>).
/// A sequence of JPEGs, proxies or RAWs with large enough embedded previews keeps the whole parallelism.
/// </summary>
internal static int AnalysisParallelism(DeepAnalysisOptions analysis, SequenceFrames frames, long memoryBudget)
{
long largest = 0;
for (var i = 0; i < frames.Count; i++)
{
var frame = frames.Frames[i];
largest = Math.Max(largest, frames.DevelopedPixels(i, analysis.AnalysisLongEdge(Math.Max(frame.Width, frame.Height)), preferPreview: true));
}
return largest == 0 ? analysis.MaxDegreeOfParallelism : DecodeBudget.PhotosAtOnce(analysis.MaxDegreeOfParallelism, memoryBudget, largest);
}
/// <summary>Identity of the analysed content: frames replaced or renumbered since a checkpoint was written (with the
/// same count), or now read from their proxies where they were read from their originals (or the other way round),
/// make it stale, like changed options do. Only frames read from proxies are marked, so the key of a sequence read
/// from its originals is what it was before proxies counted, and checkpoints written then still resume.</summary>
internal static string ContentKey(SequenceFrames frames)
{
using var hash = IncrementalHash.CreateHash(HashAlgorithmName.SHA256);
for (var i = 0; i < frames.Count; i++)
{
var f = frames.Frames[i];
var source = frames.Proxied is { } proxied && proxied[i] ? "/proxy" : "";
hash.AppendData(Encoding.UTF8.GetBytes($"{f.Id:N}/{f.Sha256}/{f.Size}/{f.Flags & SequenceFrames.NotAnalysed}{source};"));
}
return Convert.ToHexStringLower(hash.GetHashAndReset())[..16];
}
private sealed class FramesCheckpoint(DeepAnalysisCheckpointFile file, string contentKey) : IDeepAnalysisCheckpoint
{
public ValueTask<IReadOnlyList<DeepFrame>> LoadAsync(string fingerprint, CancellationToken cancellationToken) =>
file.LoadAsync($"{fingerprint};content={contentKey}", cancellationToken);
public ValueTask AppendAsync(IReadOnlyList<DeepFrame> frames, CancellationToken cancellationToken) => file.AppendAsync(frames, cancellationToken);
}
}
@@ -0,0 +1,287 @@
using System.Collections.Concurrent;
using System.Globalization;
using Chronos.Core.Advice;
using Chronos.Core.Analysis;
using Chronos.Core.Analysis.Deep;
using Chronos.Core.Imaging;
using Chronos.Core.Render;
namespace Chronos.Data.Processing;
/// <summary>
/// The frames of a <see cref="SequenceFrames"/> decoded by the host's <see cref="ImageDecoder"/> (oriented, linear
/// light, embedded previews when nothing else decodes). For the deep analysis a frame that is missing, corrupt or
/// unreadable is null, as <see cref="IFrameSource"/> expects. Renders exclude flagged frames from the plan; a frame that
/// still cannot be decoded stops the render with <see cref="FrameUnreadableKey"/>, unless the render gave
/// <see cref="RenderExcluded"/>: then the nearest planned frame that decodes stands in for it (BRIEF §8.2 tier 3: one
/// unreadable frame never stops a render) and it is listed in <see cref="StandIns"/>. Render reads go through a
/// <see cref="FrameWindow"/> per decode size, which decodes ahead in index order and spills under memory pressure; only
/// frames the pipeline asks for get a stand-in, not those the read-ahead met on the way (a speed-up skips them).
/// </summary>
internal sealed class SequenceFrameSource : IFrameSource, IRenderFrameSource, IAsyncDisposable
{
/// <summary>Render failure reason: {0} frame number (from 1), {1} file name.</summary>
public const string FrameUnreadableKey = "Export.Render.FrameUnreadable";
private const int ProbeLongEdge = 64;
private readonly SequenceFrames _frames;
private readonly IReadOnlyList<LightFrame> _metadata;
private readonly ImageDecoder _decoder;
private readonly FrameWindowOptions _windowOptions;
private readonly Lazy<(int Width, int Height)> _size;
private readonly SemaphoreSlim _gate = new(1, 1);
private readonly ConcurrentDictionary<int, FileTier> _observed = new();
private readonly ConcurrentDictionary<int, byte> _standIns = new();
private readonly ConcurrentDictionary<int, byte> _failed = new();
private readonly ConcurrentDictionary<int, byte> _read = new();
private FrameWindow? _window;
private (int Edge, DecodePurpose Purpose) _windowKey;
public SequenceFrameSource(SequenceFrames frames, IReadOnlyList<LightFrame> metadata, ImageDecoder decoder, FrameWindowOptions? window = null)
{
if (metadata.Count != frames.Count) throw new ArgumentException("One metadata entry per frame is required.", nameof(metadata));
_frames = frames;
_metadata = metadata;
_decoder = decoder;
_windowOptions = window ?? new FrameWindowOptions();
_size = new Lazy<(int, int)>(MeasureSize);
}
/// <summary>The files are the archive's originals, so what decoding finds describes the frames (<see cref="Observed"/>).</summary>
public bool Originals { get; init; }
/// <summary>
/// Positions the render plan leaves out. When set, a render frame that does not decode is replaced by the nearest
/// planned frame that does, instead of failing the render.
/// </summary>
public IReadOnlySet<int>? RenderExcluded { get; init; }
/// <summary>
/// The JPEG a GoPro wrote with each GPR frame that is not beside it, by frame id (<see cref="DecodeRequest.Companion"/>).
/// </summary>
public IReadOnlyDictionary<Guid, string>? Companions { get; init; }
/// <summary>
/// Decode tier each frame decoded at, or <see cref="DecodeTier.Unavailable"/> when the decoders read its file and none
/// produced pixels; recorded only for <see cref="Originals"/>. Sizes are oriented and given only where they are the
/// full size the tier delivers: a size-limited decode of a preview picks the smallest one that reaches the limit, so
/// it reports none and the stored size of the largest preview stays.
/// </summary>
public IReadOnlyDictionary<int, FileTier> Observed => _observed;
/// <summary>
/// Positions whose file this source tried to decode, whatever came of it (a read error or a vanished file records no
/// tier in <see cref="Observed"/>).
/// </summary>
public IReadOnlyCollection<int> Read => [.. _read.Keys];
/// <summary>Positions a render showed a neighbour for because they did not decode, ascending.</summary>
public IReadOnlyList<int> StandIns => [.. _standIns.Keys.Order()];
public int Count => _frames.Count;
public int FrameCount => _frames.Count;
public int Width => _size.Value.Width;
public int Height => _size.Value.Height;
public LightFrame Metadata(int index) => _metadata[index];
public ValueTask<ImageBuffer?> LoadAsync(int index, int maxLongEdge, CancellationToken cancellationToken)
{
if ((_frames.Frames[index].Flags & SequenceFrames.NotAnalysed) != 0) return ValueTask.FromResult<ImageBuffer?>(null);
return ValueTask.FromResult(Decode(index, maxLongEdge, DecodePurpose.Analysis, cancellationToken)?.Pixels);
}
public async ValueTask<ImageBuffer> GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken)
{
// The pipeline reads one frame at a time; the gate keeps a window switch from disposing a window in use.
await _gate.WaitAsync(cancellationToken).ConfigureAwait(false);
try
{
if (_window is null || _windowKey != (maxLongEdge, purpose))
{
if (_window is not null) await _window.DisposeAsync().ConfigureAwait(false);
_windowKey = (maxLongEdge, purpose);
// The window caps only its read-ahead; a demand load runs beside it, so a window that develops originals takes
// one gate for every decode, read-ahead and demand alike (owner review 1).
var limit = DevelopingLimit(maxLongEdge, purpose);
var decodes = limit is { } n ? new SemaphoreSlim(n, n) : null;
_window = new FrameWindow(Count, (i, ct) => LoadAsync(i, maxLongEdge, purpose, decodes, ct),
limit is { } loads ? _windowOptions with { MaxConcurrentLoads = loads } : _windowOptions);
}
_window.MoveTo(index);
return await ReadAsync(_window, index, cancellationToken).ConfigureAwait(false)
?? await StandInAsync(_window, index, cancellationToken).ConfigureAwait(false);
}
finally
{
_gate.Release();
}
}
public async ValueTask DisposeAsync()
{
await _gate.WaitAsync().ConfigureAwait(false);
try
{
if (_window is not null) await _window.DisposeAsync().ConfigureAwait(false);
_window = null;
}
finally
{
_gate.Release();
}
}
/// <summary><see cref="Load"/> within <paramref name="decodes"/>, the gate of a window that develops originals (null: none).</summary>
private async ValueTask<ImageBuffer> LoadAsync(int index, int maxLongEdge, DecodePurpose purpose, SemaphoreSlim? decodes, CancellationToken cancellationToken)
{
if (decodes is null) return Load(index, maxLongEdge, purpose, cancellationToken);
await decodes.WaitAsync(cancellationToken).ConfigureAwait(false);
try
{
return Load(index, maxLongEdge, purpose, cancellationToken);
}
finally
{
decodes.Release();
}
}
/// <summary>
/// The window's loader, for the pipeline's reads and the read-ahead alike: the decoded frame, else
/// <see cref="NotDecodedException"/>, remembered so the read-ahead does not decode the file again.
/// </summary>
private ImageBuffer Load(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken)
{
if (!_failed.ContainsKey(index) && Decode(index, maxLongEdge, purpose, cancellationToken) is { } decoded) return decoded.Pixels;
_failed.TryAdd(index, 0);
throw new NotDecodedException();
}
/// <summary>
/// Decodes a window at <paramref name="edge"/> for <paramref name="purpose"/> may run at once when some of them develop
/// an original whole (<see cref="SequenceFrames.DevelopedPixels"/>: a render's TIFFs, PNGs and RAWs, or a preparation's
/// frames without a large enough RAW preview), which takes room beyond the decoded frame the window counts (owner
/// review 1); null when none does (scaled JPEGs, proxies, embedded previews), and the window runs as it is set.
/// </summary>
internal int? DevelopingLimit(int edge, DecodePurpose purpose)
{
long largest = 0;
for (var i = 0; i < _frames.Count; i++) largest = Math.Max(largest, _frames.DevelopedPixels(i, edge, preferPreview: purpose != DecodePurpose.Render));
return largest == 0 ? null : Archiving.DecodeBudget.PhotosAtOnce(_windowOptions.MaxConcurrentLoads, _windowOptions.MemoryBudget, largest);
}
/// <summary>The options of a window at <paramref name="edge"/> for <paramref name="purpose"/>: its read-ahead within <see cref="DevelopingLimit"/>.</summary>
internal FrameWindowOptions WindowOptions(int edge, DecodePurpose purpose) =>
DevelopingLimit(edge, purpose) is { } limit ? _windowOptions with { MaxConcurrentLoads = limit } : _windowOptions;
/// <summary>A copy of the window's frame, or null when it does not decode.</summary>
private static async ValueTask<ImageBuffer?> ReadAsync(FrameWindow window, int index, CancellationToken cancellationToken)
{
try
{
using var lease = await window.GetAsync(index, cancellationToken).ConfigureAwait(false);
return lease.Image.Clone();
}
catch (NotDecodedException)
{
return null;
}
}
/// <summary>
/// The pixels shown for a frame the pipeline asked for that does not decode. Flagged frames are not planned, so this
/// one became unreadable after it was last analysed (or is beyond this host's decoders): the nearest planned frame
/// that decodes stands in, earlier first, and the render job records what decoding found. Without
/// <see cref="RenderExcluded"/>, or when nothing decodes, the render stops.
/// </summary>
private async ValueTask<ImageBuffer> StandInAsync(FrameWindow window, int index, CancellationToken cancellationToken)
{
if (RenderExcluded is not { } excluded || excluded.Contains(index)) throw Unreadable(index);
for (var distance = 1; distance < Count; distance++)
{
for (var side = -1; side <= 1; side += 2)
{
var neighbour = index + side * distance;
if (neighbour < 0 || neighbour >= Count || excluded.Contains(neighbour) || _failed.ContainsKey(neighbour)) continue;
if (await ReadAsync(window, neighbour, cancellationToken).ConfigureAwait(false) is not { } standIn) continue;
_standIns.TryAdd(index, 0);
Core.Diagnostics.Log.Warning("processing", $"Frame {index + 1} ({_frames.Frames[index].FileName}) does not decode; frame {neighbour + 1} stands in");
return standIn;
}
}
throw Unreadable(index);
}
private DecodedImage? Decode(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken)
{
if (_frames.Files[index] is not { } file) return null;
_read.TryAdd(index, 0);
var frame = _frames.Frames[index];
// A frame read from its proxy (an original this host cannot decode) says nothing about its original.
var proxied = _frames.Proxied is { } proxies && proxies[index];
DecodedImage? decoded;
try
{
var companion = proxied ? null : Companions?.GetValueOrDefault(frame.Id);
// Analyses and previews take an adequate embedded preview of a RAW (fast); renders develop it (R4, owner review 1).
decoded = _decoder.Decode(new DecodeRequest(file, maxLongEdge, purpose, Companion: companion, PreferPreview: purpose != DecodePurpose.Render),
cancellationToken);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
// The file was not read (locked, vanished, a network read failed): that says nothing about its content.
Core.Diagnostics.Log.Warning("processing", $"Frame {file} could not be read", ex);
return null;
}
// A file that vanished is missing, not undecodable (a verify flags it); only what decoding found is recorded.
// A preview taken by choice says how these pixels were made, not what the file can give.
if (Originals && !proxied && decoded is not { ByChoice: true } && (decoded is not null || File.Exists(file)))
{
_observed[index] = decoded switch
{
null => new FileTier(frame.Format, DecodeTier.Unavailable, null, "no decoder produced pixels", 0, 0),
{ Tier: DecodeTier.EmbeddedPreview } when maxLongEdge > 0 => new FileTier(frame.Format, decoded.Tier, decoded.Decoder, null, 0, 0),
_ => new FileTier(frame.Format, decoded.Tier, decoded.Decoder, null, decoded.SourceWidth, decoded.SourceHeight),
};
}
return decoded;
}
/// <summary>
/// The dominant oriented size from the metadata, else the size the first renderable frame decodes to (frames that do
/// not decode are passed over while a render may stand in for them).
/// </summary>
private (int, int) MeasureSize()
{
var context = SequenceContext.FromFrames(_frames.Frames);
if (context.SourceWidth > 0 && context.SourceHeight > 0) return (context.SourceWidth, context.SourceHeight);
var skipped = _frames.NotRenderable().ToHashSet();
if (RenderExcluded is { } excluded) skipped.UnionWith(excluded);
int? first = null;
for (var i = 0; i < Count; i++)
{
if (skipped.Contains(i)) continue;
using var probe = Decode(i, ProbeLongEdge, DecodePurpose.Thumbnail, CancellationToken.None);
if (probe is not null) return (probe.SourceWidth, probe.SourceHeight);
first ??= i;
if (RenderExcluded is null) break;
}
if (first is { } unreadable) throw Unreadable(unreadable);
throw new RenderException("Export.Render.NoFrames", "Every frame is excluded.");
}
private RenderException Unreadable(int index)
{
var name = _frames.Frames[index].FileName;
return new RenderException(FrameUnreadableKey, $"Frame {index + 1} ({name}) could not be decoded.",
[(index + 1).ToString(CultureInfo.InvariantCulture), name]);
}
/// <summary>A frame of the window that does not decode; <see cref="GetFrameAsync"/> resolves it, nothing else sees it.</summary>
private sealed class NotDecodedException : Exception;
}
@@ -0,0 +1,145 @@
using Chronos.Core.Analysis;
using Chronos.Core.Archiving;
using Chronos.Core.Diagnostics;
using Chronos.Core.Imaging;
using Chronos.Core.Metadata;
using Chronos.Core.Model;
using Chronos.Data.Archiving;
namespace Chronos.Data.Processing;
/// <summary>
/// One sequence as the processing jobs read it: the frame rows in index order and the file to decode for each (an
/// archive original or proxy, or a render node's cached copy; null when there is none).
/// </summary>
internal sealed record SequenceFrames(Sequence Sequence, IReadOnlyList<Frame> Frames, IReadOnlyList<string?> Files)
{
/// <summary>
/// The pixels of frame <paramref name="index"/>'s original that a decode at <paramref name="edge"/> develops whole
/// (<see cref="DecodeBudget.Developed"/>), 0 when it takes a cheap path or the frame has no file. A frame read through
/// its proxy, or from a JPEG file (an archive proxy, a proxy cache's copy), decodes as a JPEG (owner review 1).
/// </summary>
internal long DevelopedPixels(int index, int edge, bool preferPreview)
{
if (Files[index] is not { } file) return 0;
var frame = Frames[index];
var jpeg = Proxied?[index] == true || Path.GetExtension(file) is var extension
&& (extension.Equals(".jpg", StringComparison.OrdinalIgnoreCase) || extension.Equals(".jpeg", StringComparison.OrdinalIgnoreCase));
return DecodeBudget.Developed(jpeg ? ImageFileFormat.Jpeg : frame.Format, frame.Width, frame.Height, Math.Max(frame.PreviewWidth, frame.PreviewHeight),
edge, preferPreview);
}
/// <summary>Flags of frames that never reach a render.</summary>
public const FrameFlags NotRendered = FrameFlags.Missing | FrameFlags.Corrupt | FrameFlags.Excluded | FrameFlags.Undecodable;
/// <summary>Flags of frames whose content is not analysed (absent, or not the file that was archived).</summary>
public const FrameFlags NotAnalysed = FrameFlags.Missing | FrameFlags.Corrupt;
public int Count => Frames.Count;
/// <summary>
/// Per frame, whether its file is its proxy. <see cref="FrameFlags.Undecodable"/> is this host's verdict on the
/// original, so it does not keep a frame read from its proxy out of a render. Null: none is.
/// </summary>
public IReadOnlyList<bool>? Proxied { get; init; }
/// <summary>The originals, for metadata (proxies carry no GPS); null when <see cref="Files"/> are the originals.</summary>
public IReadOnlyList<string?>? Originals { get; init; }
/// <summary>
/// Every frame row of <paramref name="sequence"/> with its archive file: the proxy when asked, and whenever the
/// original is one <paramref name="decoder"/> cannot decode (<see cref="ArchiveImages.NeedsProxy(ImageDecoder, ImageFileFormat)"/>:
/// HEIF on the server, BRIEF §2.3, §8.5), as long as the frame's own proxy is there (<see cref="ArchiveImages.IsProxyOf"/>:
/// not one left at its index by a frame renumbered since, nor, for an original this host cannot decode, one smaller
/// than the archive's policy); else the original.
/// </summary>
public static async Task<SequenceFrames> LoadAsync(ChronosDatabase db, Archive archive, Sequence sequence, bool useProxies, ImageDecoder decoder,
CancellationToken cancellationToken)
{
var frames = await ListAsync(db, sequence.Id, cancellationToken).ConfigureAwait(false);
var paths = new ArchivePaths(archive.RootPath);
var folder = paths.Sequence(sequence.Folder);
var files = new string?[frames.Count];
var originals = new string?[frames.Count];
var proxied = new bool[frames.Count];
ProxyPolicy? policy = null;
for (var i = 0; i < files.Length; i++)
{
var frame = frames[i];
if ((frame.Flags & FrameFlags.Missing) != 0) continue;
originals[i] = paths.FromRelative(frame.RelativePath);
var needs = ArchiveImages.NeedsProxy(decoder, frame.Format);
var proxy = useProxies || needs ? folder.Proxy(frame.Index) : null;
proxied[i] = proxy is not null && ArchiveImages.IsProxyOf(proxy, frame.CapturedAt, frame.Width, frame.Height,
needs ? policy ??= ManifestStore.ReadArchive(paths.ManifestPath).ProxyPolicy : null);
files[i] = proxied[i] ? proxy : originals[i];
}
return new SequenceFrames(sequence, frames, files) { Proxied = proxied, Originals = originals };
}
public static async Task<List<Frame>> ListAsync(ChronosDatabase db, Guid sequenceId, CancellationToken cancellationToken)
{
const int pageSize = 1000;
var frames = new List<Frame>();
while (true)
{
var after = frames.Count > 0 ? frames[^1].Index : -1;
var page = await db.Frames.ListBySequenceAsync(sequenceId, after, pageSize, cancellationToken).ConfigureAwait(false);
frames.AddRange(page);
if (page.Count < pageSize) return frames;
}
}
/// <summary>
/// Light-analysis input (BRIEF §10.1): every frame's metadata with the sequence's camera and lens. The index keeps
/// no GPS, so the first readable file's fix is read once: a time-lapse camera stays put, and the analysis applies
/// that position (and the clock offset it implies) to the whole sequence.
/// </summary>
public IReadOnlyList<LightFrame> LightFrames()
{
var s = Sequence;
var light = new LightFrame[Frames.Count];
for (var i = 0; i < light.Length; i++)
{
light[i] = LightFrame.From(Frames[i]) with
{
Index = i,
CameraMake = s.CameraMake,
CameraModel = s.CameraModel,
CameraSerial = s.CameraSerial,
Lens = s.Lens,
};
}
if (FirstGpsFix() is var (index, gps)) light[index] = light[index] with { Latitude = gps.Latitude, Longitude = gps.Longitude, GpsUtc = gps.UtcTimestamp };
return light;
}
/// <summary>Positions of the frames a render must skip besides the project's exclusions.</summary>
public IEnumerable<int> NotRenderable()
{
for (var i = 0; i < Frames.Count; i++)
{
var skip = Proxied is { } proxied && proxied[i] ? NotRendered & ~FrameFlags.Undecodable : NotRendered;
if (Files[i] is null || (Frames[i].Flags & skip) != 0) yield return i;
}
}
private (int Index, GpsPosition Gps)? FirstGpsFix()
{
var files = Originals ?? Files;
for (var i = 0; i < files.Count; i++)
{
if (files[i] is not { } file || (Frames[i].Flags & NotAnalysed) != 0) continue;
try
{
return MetadataReader.Read(file).Gps is { } gps ? (i, gps) : null;
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
Log.Warning("processing", $"Metadata of {file} could not be read", ex);
return null;
}
}
return null;
}
}
@@ -0,0 +1,179 @@
using Chronos.Core.Analysis;
using Chronos.Core.Analysis.Deep;
using Chronos.Core.Export;
using Chronos.Core.Imaging;
using Chronos.Core.Localization;
using Chronos.Core.Model;
using Chronos.Core.Project;
using Chronos.Core.Render;
namespace Chronos.Data.Processing;
/// <summary>One output of a render job: the resolved export values and the preset name recorded with the render.</summary>
internal sealed record ExportTarget(ResolvedExport Export, string PresetName);
/// <summary>How one target of <see cref="SequenceRender.RenderAllAsync"/> ended: a result, or the localised reason it failed.</summary>
internal sealed record TargetOutcome(ExportTarget Target, RenderResult? Result, string? Error);
/// <summary>
/// The render of one sequence (BRIEF §11): the frame source, the clock-corrected capture metadata, the project with the
/// frames that cannot be rendered excluded, and the pipeline with the host's encoders. Targets share one preparation
/// pass; each is named once its encoder (and so its codec and size) is known, and failures of one target do not stop
/// the others. Outputs are written by the encoder sessions to temporary names and renamed on completion, so a
/// cancelled or failed target leaves nothing behind. A target gets the hardware encoders only when the user allows them
/// for its preset (<see cref="ProcessingOptions.AllowsHardware"/>).
/// </summary>
internal sealed class SequenceRender : IAsyncDisposable
{
private readonly SequenceFrameSource _source;
private readonly ProcessingOptions _processing;
private readonly Dictionary<bool, RenderPipeline> _pipelines = [];
private readonly RenderOptions _options;
/// <param name="analysis">The sequence's deep report, when current: its luminance spares the preparation a decode pass.</param>
/// <param name="originals">The frames' files are the archive's originals (no proxies), so <see cref="Decoded"/> describes them.</param>
/// <param name="companions">The JPEG of each GPR frame kept in another sequence, by frame id (<see cref="Archiving.GprCompanions"/>).</param>
public SequenceRender(SequenceFrames frames, ProjectSettings project, DeepAnalysisReport? analysis, ProcessingOptions options, bool originals = false,
IReadOnlyDictionary<Guid, string>? companions = null)
{
// The host's tuning as it is now (memory budget, quality profile): a change applies from the next render.
options = options.Current;
var metadata = frames.LightFrames();
var planned = project with { ExcludedFrames = [.. project.ExcludedFrames.Union(frames.NotRenderable()).Order()] };
// A frame that turns out not to decode is shown as its nearest planned neighbour instead of failing the render.
_source = new SequenceFrameSource(frames, metadata, options.Archive.Decoder, options.FrameWindow)
{
Originals = originals,
RenderExcluded = planned.ExcludedFrames.ToHashSet(),
Companions = companions,
};
_processing = options;
_options = options.Render;
Input = new RenderInput
{
Source = _source,
Frames = SourceFrameInfo.From(frames.Frames, LightAnalyzer.Analyze(metadata).AdjustedTimes),
Project = planned,
Analysis = analysis?.FrameCount == frames.Count ? new PrecomputedAnalysis { LogLuminance = Luminance(analysis.Frames) } : null,
};
}
public RenderInput Input { get; }
/// <summary>Positions that did not decode during the render; a neighbour stood in for each (ascending).</summary>
public IReadOnlyList<int> StandIns => _source.StandIns;
/// <summary>The decode tier each frame was read at so far (unavailable when it did not decode); originals only.</summary>
public IReadOnlyDictionary<int, FileTier> Decoded => _source.Observed;
/// <summary>Encoder, geometry and plan of an export before its output is named.</summary>
public RenderSetup Setup(ResolvedExport export) => Pipeline(export).Setup(Input, new RenderTarget(export, ExportNaming.FallbackName), _options);
/// <summary>
/// Prepares the sequence once and renders every target. <paramref name="name"/> gives the output path of a target
/// from its setup; <paramref name="starting"/> runs before a target writes anything (checkpoints),
/// <paramref name="finished"/> after its output is complete (record it, upload it). Progress counts measured and
/// rendered frames over the whole call.
/// </summary>
public async Task<IReadOnlyList<TargetOutcome>> RenderAllAsync(
IReadOnlyList<(int Index, ExportTarget Target)> targets,
Func<ExportTarget, RenderSetup, string> name,
Func<int, string, ValueTask> starting,
Func<int, ExportTarget, RenderResult, ValueTask> finished,
Func<long, long, string?, ValueTask> progress,
CancellationToken cancellationToken)
{
var outcomes = new List<TargetOutcome>(targets.Count);
var ready = new List<(int Index, ExportTarget Target, RenderSetup Setup)>();
foreach (var (index, target) in targets)
{
RenderSetup setup;
try
{
setup = Setup(target.Export);
}
catch (RenderException ex)
{
// The source size could not be measured (no renderable frame decodes).
outcomes.Add(new TargetOutcome(target, null, Reason(ex)));
continue;
}
if (setup.Encoder.IsReady && setup.Plan.Frames.Count > 0) ready.Add((index, target, setup));
else outcomes.Add(new TargetOutcome(target, null, Reason(setup)));
}
if (ready.Count == 0) return outcomes;
var preparing = ready[0].Setup.NeedsPreparation ? ready[0].Setup.Plan.IncludedFrames.Count : 0;
var total = preparing + ready.Sum(r => (long)r.Setup.Plan.Frames.Count);
var stage = Loc.L("Export.Job.Preparing");
var chain = new ProgressChain(progress);
var corrections = await RenderPreparation.PrepareAsync(Input, _options, Stage(chain, 0, preparing, total, stage), cancellationToken).ConfigureAwait(false);
await chain.FlushAsync().ConfigureAwait(false);
long done = preparing;
foreach (var (index, target, setup) in ready)
{
cancellationToken.ThrowIfCancellationRequested();
var output = name(target, setup);
await starting(index, output).ConfigureAwait(false);
try
{
var result = await Pipeline(target.Export).RenderAsync(Input, corrections, new RenderTarget(target.Export, output), _options,
Stage(chain, done, setup.Plan.Frames.Count, total, target.PresetName), cancellationToken).ConfigureAwait(false);
await chain.FlushAsync().ConfigureAwait(false);
await finished(index, target, result).ConfigureAwait(false);
outcomes.Add(new TargetOutcome(target, result, null));
}
catch (Exception ex) when (!(ex is OperationCanceledException && cancellationToken.IsCancellationRequested))
{
Core.Diagnostics.Log.Warning("processing", $"Render of {target.PresetName} to {output} failed", ex);
outcomes.Add(new TargetOutcome(target, null, Reason(ex)));
}
done += setup.Plan.Frames.Count;
}
return outcomes;
}
/// <summary>Values of the output name tokens: the shoot date and title of the sequence, the codec and size the encoder will use.</summary>
public static ExportNameContext NameContext(Sequence sequence, ExportTarget target, RenderSetup setup) => new()
{
Date = sequence.FirstCapture ?? DateTime.Now,
Title = sequence.DisplayTitle,
PresetName = target.PresetName,
Width = setup.Encoder.Settings.Width,
Height = setup.Encoder.Settings.Height,
FrameRate = setup.Encoder.Settings.FrameRate,
Codec = setup.Encoder.Settings.Codec,
};
/// <summary>Localised text of a render failure.</summary>
public static string Reason(Exception exception) =>
exception is RenderException render ? Loc.L(render.ReasonKey, [.. render.Args]) : exception.Message;
/// <summary>Localised remarks of a finished render (encoder fallbacks, ignored settings…), without repeats.</summary>
public static IEnumerable<string> Remarks(RenderResult result) => result.Warnings.Select(w => Loc.L(w.Key, [.. w.Args])).Distinct();
public ValueTask DisposeAsync() => _source.DisposeAsync();
/// <summary>The pipeline with the encoders <paramref name="export"/> may use.</summary>
private RenderPipeline Pipeline(ResolvedExport export)
{
var hardware = _processing.AllowsHardware(export.BasePresetId);
if (!_pipelines.TryGetValue(hardware, out var pipeline))
_pipelines[hardware] = pipeline = new RenderPipeline(hardware ? _processing.Encoders : _processing.SoftwareEncoders, _processing.Host);
return pipeline;
}
private static string Reason(RenderSetup setup)
{
if (setup.Plan.Frames.Count == 0) return Loc.L("Export.Render.NoFrames");
var notice = setup.Encoder.Notices.LastOrDefault() ?? new EncoderNotice(EncoderNotices.NoEncoder, setup.Encoder.Settings.Codec.ToString());
return Loc.L(notice.Key, [.. notice.Args]);
}
private static double[] Luminance(DeepFrameColumns columns) => [.. columns.LogLuminance.Select(v => v ?? double.NaN)];
/// <summary>One stage's progress (frames measured, or rendered for one target) as frames of the whole call.</summary>
private static IProgress<RenderProgress> Stage(ProgressChain chain, long offset, long length, long total, string message) =>
chain.For<RenderProgress>(p => (offset + long.Min(length, p.Done), total, message));
}
@@ -0,0 +1,30 @@
using Chronos.Core.Video;
namespace Chronos.Data.Processing;
/// <summary>
/// The software encoders of a provider, for renders the user keeps off the GPU (Settings › Rendering): hardware
/// capabilities are hidden, so the encoder selector falls back as on a PC without them (HEVC → software H.264), and an
/// encode opens the software encoder by name, ignoring a hardware one named in the export.
/// </summary>
internal sealed class SoftwareEncoderProvider(IVideoEncoderProvider inner) : IVideoEncoderProvider
{
public string Name => inner.Name;
public IReadOnlyList<EncoderCapability> Capabilities { get; } = [.. inner.Capabilities.Where(c => !c.Hardware)];
public bool CanEncode(EncodeSettings settings) => Software(settings) is not null;
public IVideoEncoderSession Open(EncodeSettings settings) =>
inner.Open(Software(settings) ?? throw new NotSupportedException($"No software encoder of {inner.Name} accepts {settings.Codec} {settings.Width}×{settings.Height}"));
/// <summary>The settings naming the first software encoder that accepts them; null when none does.</summary>
private EncodeSettings? Software(EncodeSettings settings)
{
var named = settings.EncoderName is { } name && Capabilities.Any(c => c.Name == name);
return Capabilities
.Where(c => c.Codec == settings.Codec && (!named || c.Name == settings.EncoderName))
.Select(c => settings with { EncoderName = c.Name, PreferHardware = false })
.FirstOrDefault(inner.CanEncode);
}
}