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.

20.0 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
//
// The sample library's analysis index (ISampleIndex). A background scan walks the Samples
// folder and has the engine measure every audio file it doesn't know yet — tempo, key,
// envelope, timbre — on a few below-normal-priority threads, a just-installed pack first.
// Results persist in <data>/sample-index/index.bin, keyed by path and invalidated by size or
// date, so a library of tens of thousands of files is analysed once, not on every launch.
// Only the raw analysis is stored: what it means (loop or one-shot, which tempo to trust)
// is worked out again from the name on load, so classifier fixes need no re-analysis.

using System.Collections.Concurrent;
using Nota.Application;
using Nota.Application.Samples;

namespace Nota.Infrastructure;

public sealed class SampleAnalyzer : ISampleAnalyzer
{
    public SampleAnalysis? Analyze(string path, double maxSeconds)
    {
        try
        {
            return NativeMethods.SampleAnalyzeFile(path, maxSeconds, out var a) == NativeMethods.NotaResult.Ok
                ? a.ToAnalysis() : null;
        }
        catch (DllNotFoundException) { return null; }
        catch (EntryPointNotFoundException) { return null; }
    }
}

public sealed class SampleLibraryIndex : ISampleIndex, IDisposable
{
    /// <summary>Seconds of a file the analysis decodes — a loop's worth and then some; a long
    /// recording's tempo and key show well before the end.</summary>
    public const double AnalyzeSeconds = 60;

    private static readonly string[] AudioExts = { ".wav", ".flac", ".mp3" };
    private const uint Magic = 0x3158534E;   // "NSX1"
    private const int FileVersion = 1;
    private static readonly TimeSpan SaveEvery = TimeSpan.FromSeconds(5);
    private static readonly TimeSpan NotifyEvery = TimeSpan.FromMilliseconds(750);

    // Timbre weights for "similar sounds": the band shape is the sound's colour; brightness,
    // noisiness and attack separate a clap from a rim; length keeps hits away from loops.
    private static readonly float[] TimbreWeights = { 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2.5f, 2f, 2f, 1.5f };

    private sealed class Entry
    {
        public long Size;
        public long Ticks;
        public SampleAnalysis? Analysis;   // null = couldn't be decoded
        public SampleInfo? Info;           // derived, cleared when the root changes
    }

    private readonly ISampleAnalyzer _analyzer;
    private readonly string _file;
    private readonly object _gate = new();
    private readonly Dictionary<string, Entry> _entries = new(PathComparer);
    private readonly List<string> _priority = new();
    private bool _loaded;
    private IReadOnlyList<string> _roots = Array.Empty<string>();   // the sample folders (spec 092)
    private CancellationTokenSource? _scanCts;
    private int _scanGen;
    private int _done, _total;
    private int _mutations;                 // bumps on every change; keys the stats cache
    private (int Mutations, float[] Mean, float[] Std)? _stats;
    private DateTime _lastNotify = DateTime.MinValue;
    private DateTime _lastSave = DateTime.UtcNow;
    private bool _dirty;

    public event Action? Changed;

    private static StringComparer PathComparer
        => OperatingSystem.IsLinux() ? StringComparer.Ordinal : StringComparer.OrdinalIgnoreCase;

    public SampleLibraryIndex(ISampleAnalyzer analyzer) : this(analyzer, Path.Combine(NotaPaths.SubDir("sample-index"), "index.bin")) { }

    /// <summary>Tests: an index persisted at <paramref name="file"/>.</summary>
    public SampleLibraryIndex(ISampleAnalyzer analyzer, string file)
    {
        _analyzer = analyzer;
        _file = file;
    }

    public (int Done, int Total) Progress { get { lock (_gate) return (_done, _total); } }

    public SampleInfo? Get(string path)
    {
        lock (_gate)
        {
            EnsureLoaded();
            return _entries.TryGetValue(path, out var e) ? InfoOf(path, e) : null;
        }
    }

    public SampleInfo? GetOrAnalyze(string path)
    {
        var fi = new FileInfo(path);
        if (!fi.Exists) return null;
        lock (_gate)
        {
            EnsureLoaded();
            if (_entries.TryGetValue(path, out var e) && Fresh(e, fi)) return e.Analysis is null ? null : InfoOf(path, e);
        }
        var a = _analyzer.Analyze(path, AnalyzeSeconds);
        return a is null ? null : Store(path, a);
    }

    public SampleInfo Store(string path, SampleAnalysis analysis)
    {
        var fi = new FileInfo(path);
        var e = new Entry { Size = fi.Exists ? fi.Length : -1, Ticks = fi.Exists ? fi.LastWriteTimeUtc.Ticks : 0, Analysis = analysis };
        SampleInfo info;
        lock (_gate)
        {
            EnsureLoaded();
            _entries[path] = e;
            info = InfoOf(path, e);
            _mutations++;
            _dirty = true;
        }
        Notify(force: true);
        return info;
    }

    public void Watch(string root) => Watch(new[] { root });

    public void Watch(IReadOnlyList<string> roots)
    {
        var list = roots.Where(r => !string.IsNullOrEmpty(r)).ToList();
        CancellationTokenSource cts;
        int gen;
        lock (_gate)
        {
            if (!list.SequenceEqual(_roots, PathComparer))
            {
                _roots = list;
                foreach (var e in _entries.Values) e.Info = null;   // folder hints are relative to the root
            }
            _scanCts?.Cancel();
            _scanCts = cts = new CancellationTokenSource();
            gen = ++_scanGen;
        }
        var thread = new Thread(() => Scan(list, gen, cts.Token)) { IsBackground = true, Name = "Sample index", Priority = ThreadPriority.BelowNormal };
        thread.Start();
    }

    public void Prioritize(string folder)
    {
        IReadOnlyList<string> roots;
        lock (_gate)
        {
            _priority.Remove(folder);
            _priority.Insert(0, folder);
            roots = _roots;
        }
        if (roots.Count > 0) Watch(roots);   // re-scan: the new files sort to the front
    }

    public IReadOnlyList<SimilarSample> Similar(string path, int count)
    {
        var anchor = GetOrAnalyze(path);
        if (anchor is null || anchor.Timbre.Length != SampleAnalysis.TimbreDims) return Array.Empty<SimilarSample>();
        lock (_gate)
        {
            var (mean, std) = Stats();
            var a = Normalize(anchor.Timbre, mean, std);
            var best = new List<SimilarSample>();
            foreach (var (p, e) in _entries)
            {
                if (e.Analysis is not { Timbre.Length: SampleAnalysis.TimbreDims } || PathComparer.Equals(p, path)) continue;
                var info = InfoOf(p, e);
                // A loop is never "like" a hit, however close their spectra.
                if (anchor.Kind != SampleKind.Unknown && info.Kind != SampleKind.Unknown && anchor.Kind != info.Kind) continue;
                double d = Distance(a, Normalize(info.Timbre, mean, std));
                best.Add(new SimilarSample(info, d));
            }
            best.Sort((x, y) => x.Distance.CompareTo(y.Distance));
            return best.Count > count ? best.GetRange(0, count) : best;
        }
    }

    public IReadOnlyList<SampleInfo> Search(SampleFilter filter, string? text, int limit)
    {
        var words = (text ?? "").Split(' ', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
        var hits = new List<SampleInfo>();
        lock (_gate)
        {
            EnsureLoaded();
            foreach (var (p, e) in _entries)
            {
                if (e.Analysis is null) continue;
                if (words.Any(w => !p.Contains(w, StringComparison.OrdinalIgnoreCase))) continue;
                var info = InfoOf(p, e);
                if (filter.Matches(info)) hits.Add(info);
            }
        }
        hits.Sort((x, y) => string.Compare(x.Path, y.Path, StringComparison.OrdinalIgnoreCase));
        return hits.Count > limit ? hits.GetRange(0, limit) : hits;
    }

    public void Dispose()
    {
        lock (_gate) { _scanCts?.Cancel(); }
        Save();
    }

    // --- scan -----------------------------------------------------------------------------

    private void Scan(IReadOnlyList<string> roots, int gen, CancellationToken ct)
    {
        try
        {
            List<string> pending;
            lock (_gate) EnsureLoaded();
            WarmInfos(gen, ct);
            // Folders that are there now; one that is missing (an unplugged drive) keeps its
            // analyses for when it comes back.
            var live = roots.Where(r => { try { return Directory.Exists(r); } catch { return false; } }).ToList();
            var away = roots.Except(live, PathComparer).ToList();
            var found = new List<string>();
            foreach (var r in live) found.AddRange(Enumerate(r, ct));
            var present = new HashSet<string>(found, PathComparer);
            var stamps = new Dictionary<string, (long Size, long Ticks)>(found.Count, PathComparer);
            foreach (var p in found)
            {
                ct.ThrowIfCancellationRequested();
                var fi = new FileInfo(p);
                if (fi.Exists) stamps[p] = (fi.Length, fi.LastWriteTimeUtc.Ticks);
            }
            lock (_gate)
            {
                if (gen != _scanGen) return;
                // Forget files that left the library (anything outside it, dragged in from
                // elsewhere, stays until its file is gone).
                var gone = _entries.Keys.Where(p =>
                    away.Any(r => IsUnder(p, r)) ? false
                    : live.Any(r => IsUnder(p, r)) ? !present.Contains(p)
                    : !File.Exists(p)).ToList();
                foreach (var p in gone) _entries.Remove(p);
                if (gone.Count > 0) { _mutations++; _dirty = true; }

                pending = new List<string>();
                foreach (var (p, st) in stamps)
                    if (!_entries.TryGetValue(p, out var e) || e.Size != st.Size || e.Ticks != st.Ticks) pending.Add(p);
                var priority = _priority.ToList();
                pending.Sort((a, b) =>
                {
                    int pa = PriorityOf(a, priority), pb = PriorityOf(b, priority);
                    return pa != pb ? pa.CompareTo(pb) : string.Compare(a, b, StringComparison.OrdinalIgnoreCase);
                });
                _done = 0;
                _total = pending.Count;
            }
            if (pending.Count > 0) Notify(force: true);

            int next = -1;
            int workers = Math.Clamp(Environment.ProcessorCount / 2, 1, 4);
            var threads = new List<Thread>();
            for (int w = 0; w < workers; w++)
            {
                var t = new Thread(() =>
                {
                    while (!ct.IsCancellationRequested)
                    {
                        int i = Interlocked.Increment(ref next);
                        if (i >= pending.Count) break;
                        Analyze(pending[i], gen);
                    }
                }) { IsBackground = true, Name = "Sample analysis", Priority = ThreadPriority.BelowNormal };
                threads.Add(t);
                t.Start();
            }
            foreach (var t in threads) t.Join();
            if (ct.IsCancellationRequested) return;
            lock (_gate)
            {
                if (gen != _scanGen) return;
                _done = _total = 0;
                _priority.Clear();
            }
            Save();
            Notify(force: true);
        }
        catch (Exception) when (ct.IsCancellationRequested) { }
        catch (IOException) { }
        catch (UnauthorizedAccessException) { }
    }

    // Classify what loaded from disk here, a few hundred at a time, so the browser's first
    // pass over tens of thousands of rows is lookups, not name parsing on the UI thread.
    private void WarmInfos(int gen, CancellationToken ct)
    {
        string[] paths;
        lock (_gate) paths = _entries.Keys.ToArray();
        for (int i = 0; i < paths.Length; i += 500)
        {
            ct.ThrowIfCancellationRequested();
            lock (_gate)
            {
                if (gen != _scanGen) return;
                for (int k = i; k < Math.Min(paths.Length, i + 500); k++)
                    if (_entries.TryGetValue(paths[k], out var e)) InfoOf(paths[k], e);
            }
        }
        Notify(force: true);
    }

    private void Analyze(string path, int gen)
    {
        FileInfo fi;
        SampleAnalysis? a;
        try
        {
            fi = new FileInfo(path);
            if (!fi.Exists) return;
            a = _analyzer.Analyze(path, AnalyzeSeconds);
        }
        catch (IOException) { return; }
        lock (_gate)
        {
            _entries[path] = new Entry { Size = fi.Length, Ticks = fi.LastWriteTimeUtc.Ticks, Analysis = a };
            _mutations++;
            _dirty = true;
            if (gen == _scanGen) _done++;
        }
        if (DateTime.UtcNow - _lastSave > SaveEvery) Save();
        Notify(force: false);
    }

    private static int PriorityOf(string path, List<string> priority)
    {
        for (int i = 0; i < priority.Count; i++) if (IsUnder(path, priority[i])) return i;
        return priority.Count;
    }

    private static bool IsUnder(string path, string folder)
    {
        var rel = Path.GetRelativePath(folder, path);
        return rel != "." && !rel.StartsWith("..", StringComparison.Ordinal) && !Path.IsPathRooted(rel);
    }

    private static List<string> Enumerate(string root, CancellationToken ct)
    {
        var files = new List<string>();
        if (!Directory.Exists(root)) return files;
        var opts = new EnumerationOptions { RecurseSubdirectories = true, IgnoreInaccessible = true, AttributesToSkip = FileAttributes.Hidden | FileAttributes.System };
        foreach (var f in Directory.EnumerateFiles(root, "*", opts))
        {
            ct.ThrowIfCancellationRequested();
            if (AudioExts.Contains(Path.GetExtension(f).ToLowerInvariant())) files.Add(f);
        }
        return files;
    }

    private void Notify(bool force)
    {
        var now = DateTime.UtcNow;
        lock (_gate)
        {
            if (!force && now - _lastNotify < NotifyEvery) return;
            _lastNotify = now;
        }
        Changed?.Invoke();
    }

    // --- derived ----------------------------------------------------------------------------

    private static bool Fresh(Entry e, FileInfo fi) => e.Size == fi.Length && e.Ticks == fi.LastWriteTimeUtc.Ticks;

    private SampleInfo InfoOf(string path, Entry e)
        => e.Info ??= SampleClassifier.Classify(path, SampleNameHints.Parse(path, RootOf(path)), e.Analysis);

    // The sample folder holding `path` — folder-name hints are read below it.
    private string? RootOf(string path)
    {
        foreach (var r in _roots) if (IsUnder(path, r)) return r;
        return null;
    }

    // Per-dimension mean / spread over the library, so a dB band and a 0..1 flatness weigh alike.
    private (float[] Mean, float[] Std) Stats()
    {
        if (_stats is { } s && s.Mutations == _mutations) return (s.Mean, s.Std);
        int n = SampleAnalysis.TimbreDims;
        var mean = new double[n];
        var sq = new double[n];
        int count = 0;
        foreach (var e in _entries.Values)
        {
            if (e.Analysis is not { Timbre.Length: SampleAnalysis.TimbreDims } a) continue;
            for (int i = 0; i < n; i++) { mean[i] += a.Timbre[i]; sq[i] += a.Timbre[i] * (double)a.Timbre[i]; }
            count++;
        }
        var m = new float[n];
        var sd = new float[n];
        for (int i = 0; i < n; i++)
        {
            double mu = count > 0 ? mean[i] / count : 0;
            double v = count > 1 ? Math.Max(0, sq[i] / count - mu * mu) : 1;
            m[i] = (float)mu;
            sd[i] = (float)Math.Max(Math.Sqrt(v), 0.05);   // a dimension the library barely varies on can't dominate
        }
        _stats = (_mutations, m, sd);
        return (m, sd);
    }

    private static float[] Normalize(float[] t, float[] mean, float[] std)
    {
        var z = new float[t.Length];
        for (int i = 0; i < t.Length; i++) z[i] = (t[i] - mean[i]) / std[i];
        return z;
    }

    private static double Distance(float[] a, float[] b)
    {
        double sum = 0, wsum = 0;
        for (int i = 0; i < a.Length; i++)
        {
            double d = a[i] - b[i];
            sum += TimbreWeights[i] * d * d;
            wsum += TimbreWeights[i];
        }
        return Math.Sqrt(sum / wsum);
    }

    // --- persistence --------------------------------------------------------------------------
    // u32 magic, i32 file version, i32 analysis version, i32 count, then per entry:
    // string path, i64 size, i64 ticks, bool analysed, [f64 dur, f64 sr, i32 ch, f64 bpm,
    // i32 tonic, i32 mode, f32 conf, f32 tail, f32 peak, f32 rms, i32 n, f32[n] timbre].

    private void EnsureLoaded()
    {
        if (_loaded) return;
        _loaded = true;
        try
        {
            if (!File.Exists(_file)) return;
            using var r = new BinaryReader(File.OpenRead(_file));
            if (r.ReadUInt32() != Magic || r.ReadInt32() != FileVersion || r.ReadInt32() != SampleAnalysis.Version) return;
            int count = r.ReadInt32();
            for (int i = 0; i < count; i++)
            {
                string path = r.ReadString();
                var e = new Entry { Size = r.ReadInt64(), Ticks = r.ReadInt64() };
                if (r.ReadBoolean())
                {
                    double dur = r.ReadDouble(), sr = r.ReadDouble();
                    int ch = r.ReadInt32();
                    double bpm = r.ReadDouble();
                    int tonic = r.ReadInt32(), mode = r.ReadInt32();
                    float conf = r.ReadSingle(), tail = r.ReadSingle(), peak = r.ReadSingle(), rms = r.ReadSingle();
                    int n = r.ReadInt32();
                    if (n is < 0 or > 64) return;   // corrupt: keep what loaded, rescan the rest
                    var t = new float[n];
                    for (int k = 0; k < n; k++) t[k] = r.ReadSingle();
                    e.Analysis = new SampleAnalysis(dur, sr, ch, bpm, tonic, mode, conf, tail, peak, rms, t);
                }
                _entries[path] = e;
            }
        }
        catch (IOException) { }
        catch (UnauthorizedAccessException) { }
    }

    private void Save()
    {
        KeyValuePair<string, Entry>[] snapshot;
        lock (_gate)
        {
            if (!_dirty || !_loaded) return;
            _dirty = false;
            _lastSave = DateTime.UtcNow;
            snapshot = _entries.ToArray();
        }
        string tmp = _file + "." + Environment.CurrentManagedThreadId + ".tmp";
        try
        {
            Directory.CreateDirectory(Path.GetDirectoryName(_file)!);
            using (var w = new BinaryWriter(File.Create(tmp)))
            {
                w.Write(Magic);
                w.Write(FileVersion);
                w.Write(SampleAnalysis.Version);
                w.Write(snapshot.Length);
                foreach (var (path, e) in snapshot)
                {
                    w.Write(path);
                    w.Write(e.Size);
                    w.Write(e.Ticks);
                    w.Write(e.Analysis is not null);
                    if (e.Analysis is not { } a) continue;
                    w.Write(a.DurationSec); w.Write(a.SampleRate); w.Write(a.Channels); w.Write(a.Bpm);
                    w.Write(a.KeyTonic); w.Write(a.KeyMode);
                    w.Write(a.KeyConfidence); w.Write(a.TailRatio); w.Write(a.PeakDb); w.Write(a.RmsDb);
                    w.Write(a.Timbre.Length);
                    foreach (var v in a.Timbre) w.Write(v);
                }
            }
            File.Move(tmp, _file, overwrite: true);
        }
        catch (IOException) { lock (_gate) _dirty = true; TryDelete(tmp); }
        catch (UnauthorizedAccessException) { lock (_gate) _dirty = true; TryDelete(tmp); }
    }

    private static void TryDelete(string path)
    {
        try { File.Delete(path); } catch (IOException) { } catch (UnauthorizedAccessException) { }
    }
}