Skip to content

armgit / nota

Public Imported from GitHub
0

Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.

6.0 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.

namespace Nota.Application;

/// <summary>A track renamed between two versions.</summary>
public sealed record TrackRename(string From, string To);

/// <summary>What a version changed against its parent, worked out from the two manifests
/// when it is recorded. Track names stand for tracks; "Master" for the master bus. The
/// History tab turns it into a one-line description ("Added Bass · Tempo 120.00 → 124.00").</summary>
public sealed record VersionChanges
{
    /// <summary>The first version: no parent to compare with.</summary>
    public bool First { get; init; }
    public int TrackCount { get; init; }
    public IReadOnlyList<string> TracksAdded { get; init; } = [];
    public IReadOnlyList<string> TracksRemoved { get; init; } = [];
    public IReadOnlyList<TrackRename> TracksRenamed { get; init; } = [];
    public double? TempoFrom { get; init; }
    public double? TempoTo { get; init; }
    /// <summary>Time signature before / after ("4/4").</summary>
    public string? MeterFrom { get; init; }
    public string? MeterTo { get; init; }
    /// <summary>Tracks whose clips, notes, session slots or automation changed.</summary>
    public IReadOnlyList<string> Edited { get; init; } = [];
    /// <summary>Tracks whose instrument, devices or modulation changed.</summary>
    public IReadOnlyList<string> Sound { get; init; } = [];
    /// <summary>Tracks whose volume, pan, mute, solo or sends changed.</summary>
    public IReadOnlyList<string> Mix { get; init; } = [];
    /// <summary>Audio files no earlier version of this branch had (recordings, imports, bounces).</summary>
    public int NewAudio { get; init; }
    /// <summary>Other parts of the project that changed: "sections", "midi map", "layout", "freeze".</summary>
    public IReadOnlyList<string> Other { get; init; } = [];

    public bool IsEmpty => !First && TracksAdded.Count == 0 && TracksRemoved.Count == 0 && TracksRenamed.Count == 0
                           && TempoTo is null && MeterTo is null && Edited.Count == 0 && Sound.Count == 0
                           && Mix.Count == 0 && NewAudio == 0 && Other.Count == 0;
}

/// <summary>One saved version of a project — a node of the history tree.</summary>
/// <param name="Parent">The version this one was saved on top of (null for the root).</param>
/// <param name="AddedBytes">Disk space this version added when it was saved (new audio,
/// plugin states and manifests no earlier version had).</param>
/// <param name="CanOpen">False when the version was saved by a newer Nota whose project
/// format this build can't read.</param>
public sealed record ProjectVersion(
    string Id, string? Parent, DateTimeOffset CreatedAt,
    string? Label, string? Note, bool Starred,
    string AppVersion, int ProjectFormat, long AddedBytes, bool CanOpen)
{
    /// <summary>What changed against the parent; null when it couldn't be worked out.</summary>
    public VersionChanges? Changes { get; init; }
}

/// <summary>A project's history: every version (oldest first) and the one the working
/// copy was last saved as or switched to.</summary>
public sealed record ProjectHistoryState(IReadOnlyList<ProjectVersion> Versions, string? Head)
{
    public static readonly ProjectHistoryState Empty = new([], null);
    public ProjectVersion? HeadVersion => Versions.FirstOrDefault(v => v.Id == Head);
}

/// <summary>Disk use of a project: <see cref="Total"/> is the whole bundle's audio, states
/// and history; <see cref="HistoryOnly"/> is what only older versions need (freed by
/// erasing the history).</summary>
public readonly record struct ProjectHistorySize(long Total, long HistoryOnly);

/// <summary>History is unreadable (damaged, or from a newer Nota) or a version can't be
/// restored (its files are missing). The working copy is never touched when this is thrown.</summary>
public sealed class ProjectHistoryException(string message, Exception? inner = null) : Exception(message, inner);

/// <summary>Version history of a <c>.nota</c> bundle, kept inside the bundle. A version is
/// recorded on each explicit save; switching restores a version's files into the bundle
/// (the caller then reopens the project). Saving on top of an older version branches.</summary>
public interface IProjectHistory
{
    /// <summary>Does the bundle keep a version history (even a damaged one)?</summary>
    bool Exists(string bundleDir);

    /// <summary>All versions and the head. Empty when the bundle has no history yet.</summary>
    ProjectHistoryState Read(string bundleDir);

    /// <summary>Records the bundle's current (just saved) state as a child of the head.
    /// Returns null when nothing changed since the head.</summary>
    ProjectVersion? Commit(string bundleDir, string? note = null);

    /// <summary>Restores <paramref name="versionId"/>'s files into the bundle and makes it
    /// the head. The caller reloads the project afterwards.</summary>
    void Checkout(string bundleDir, string versionId);

    void SetLabel(string bundleDir, string versionId, string? label);
    void SetNote(string bundleDir, string versionId, string? note);
    void SetStarred(string bundleDir, string versionId, bool starred);

    /// <summary>Deletes a version (not the head); its children move up to its parent.
    /// Returns the bytes freed.</summary>
    long Delete(string bundleDir, string versionId);

    /// <summary>Deletes several versions at once (none of them the head). Returns the bytes freed.</summary>
    long DeleteMany(string bundleDir, IReadOnlyCollection<string> versionIds);

    /// <summary>Deletes the whole history and every file only it needed.</summary>
    long Erase(string bundleDir);

    /// <summary>Carries the history, with every file its versions need, from one bundle to
    /// another (Save As). No-op when <paramref name="fromBundle"/> has no history.</summary>
    void CopyTo(string fromBundle, string toBundle);

    ProjectHistorySize Size(string bundleDir);
}