feat(QML): use waveform overview cache

Author: acolombier

res/qml/Library/TrackList.qml

@@ -329,13 +329,9 @@ Rectangle {
                     colorLow: Theme.green
                     colorMid: Theme.blue
                     renderer: Mixxx.WaveformOverview.Renderer.Filtered
-                    track: null // Lazy loaded
+                    trackUrl: file_url
                     implicitHeight: 30
                     implicitWidth: 30
-
-                    Component.onCompleted: {
-                        waveformOverview.track = TableView.view.model?.getTrackByRow(row)
-                    }
                 }
             }
             DelegateChoice {

src/coreservices.cpp

@@ -627,10 +627,19 @@ void CoreServices::initialize(QApplication* pApp) {
             m_pRecordingManager.get());
 
     OverviewCache* pOverviewCache = OverviewCache::createInstance(pConfig, m_pDbConnectionPool);
+    pOverviewCache->setTrackDAO(
+            &m_pTrackCollectionManager->internalCollection()->getTrackDAO());
     connect(&(m_pTrackCollectionManager->internalCollection()->getTrackDAO()),
             &TrackDAO::waveformSummaryUpdated,
             pOverviewCache,
             &OverviewCache::onTrackSummaryChanged);
+    // Forward per-track analyzer progress to OverviewCache so that
+    // OverviewCache clients (e.g. QmlWaveformOverview) can repaint
+    // the partial waveform during analysis.
+    connect(m_pPlayerManager.get(),
+            &PlayerManager::trackAnalyzerProgress,
+            pOverviewCache,
+            &OverviewCache::onTrackAnalysisProgress);
 
     // Binding the PlayManager to the Library may already trigger
     // loading of tracks which requires that the GlobalTrackCache has

src/library/dao/trackdao.h

@@ -143,6 +143,7 @@ class TrackDAO : public QObject, public virtual DAO, public virtual GlobalTrackC
     friend class LibraryScanner;
     friend class TrackCollection;
     friend class TrackAnalysisScheduler;
+    friend class OverviewCache;
 
     QList<TrackId> resolveTrackIds(
             const QStringList& pathList,

src/library/overviewcache.cpp

@@ -2,10 +2,12 @@
 
 #include <QFutureWatcher>
 #include <QPixmapCache>
+#include <QPointer>
 #include <QSqlDatabase>
 #include <QtConcurrentRun>
 
 #include "library/dao/analysisdao.h"
+#include "library/dao/trackdao.h"
 #include "moc_overviewcache.cpp"
 #include "util/db/dbconnectionpooled.h"
 #include "util/db/dbconnectionpooler.h"
@@ -40,8 +42,12 @@ OverviewCache::OverviewCache(UserSettingsPointer pConfig,
           m_pDbConnectionPool(std::move(pDbConnectionPool)) {
 }
 
-void OverviewCache::onTrackAnalysisProgress(TrackId trackId, AnalyzerProgress analyzerProgress) {
-    if (analyzerProgress < 1.0) {
+void OverviewCache::onTrackAnalysisProgress(TrackId trackId, AnalyzerProgress progress) {
+    // Always forward the raw progress so listeners that need to draw
+    // the partial waveform during analysis (e.g. QmlWaveformOverview)
+    // can repaint on every tick.
+    emit analyzerProgress(trackId, progress);
+    if (progress < 1.0) {
         return;
     }
     m_tracksWithoutOverview.remove(trackId);
@@ -238,6 +244,21 @@ void OverviewCache::requestWaveformSummary(TrackId trackId, const QObject* pRequ
 
     m_currentlyLoadingWaveform.insert(trackId);
 
+    // The async load carries `pRequester` verbatim and will eventually
+    // dispatch the result back to it. If `pRequester` is destroyed while
+    // the load is still in flight, its `slotWaveformSummaryReady` is
+    // auto-disconnected by Qt, no one adopts the loaded waveform, and
+    // `m_currentlyLoadingWaveform` would only be cleared when the
+    // background job finishes — meanwhile other requesters interested in
+    // the same track are silently blocked. Drop the pending entry as
+    // soon as the requester goes away so a new load can be started by
+    // any other listener still alive.
+    if (pRequester) {
+        QObject::connect(pRequester, &QObject::destroyed, this, [this, trackId] {
+            m_currentlyLoadingWaveform.remove(trackId);
+        });
+    }
+
     QFutureWatcher<FutureWaveformResult>* watcher =
             new QFutureWatcher<FutureWaveformResult>(this);
     QFuture<FutureWaveformResult> future = QtConcurrent::run(
@@ -253,6 +274,35 @@ void OverviewCache::requestWaveformSummary(TrackId trackId, const QObject* pRequ
     watcher->setFuture(future);
 }
 
+void OverviewCache::requestWaveformSummary(
+        const QString& trackLocation, const QObject* pRequester) {
+    if (trackLocation.isEmpty()) {
+        return;
+    }
+    if (!m_pTrackDAO) {
+        // Without a TrackDAO we cannot translate a file location into
+        // a TrackId. The TrackId-based overload is the only available
+        // path in that case.
+        return;
+    }
+
+    // Resolve the location into a TrackId on the GUI thread. The
+    // query is a single indexed lookup on `track_locations.location`,
+    // which is essentially instantaneous, so doing it on the GUI
+    // thread is preferable to introducing an extra round-trip through
+    // the worker pool and lets us reuse the existing TrackId-based
+    // dedup logic and async machinery. `TrackDAO` is owned by
+    // `TrackCollection` and lives on the GUI thread, so its
+    // pre-initialised `QSqlDatabase` connection is valid here.
+    const TrackId trackId = m_pTrackDAO->getTrackIdByLocation(trackLocation);
+    if (!trackId.isValid()) {
+        return;
+    }
+
+    // Delegate to the existing TrackId-based load path.
+    requestWaveformSummary(trackId, pRequester);
+}
+
 // static
 OverviewCache::FutureWaveformResult OverviewCache::prepareWaveformSummary(
         const UserSettingsPointer pConfig,
@@ -276,9 +326,18 @@ OverviewCache::FutureWaveformResult OverviewCache::prepareWaveformSummary(
             analysisDao.getAnalysesForTrackByType(
                     trackId, AnalysisDao::AnalysisType::TYPE_WAVESUMMARY);
 
-    if (!analyses.isEmpty()) {
-        result.pWaveform = ConstWaveformPointer(
-                WaveformFactory::loadWaveformFromAnalysis(analyses.first()));
+    // Only load analyses whose version is compatible with the current
+    // format, mirroring the logic in `AnalyzerWaveform::shouldAnalyze`.
+    // Loading an incompatible (e.g. `VC_REMOVE`) waveform would yield a
+    // `Waveform` with invalid data, producing a garbled overview.
+    for (const AnalysisDao::AnalysisInfo& analysis : std::as_const(analyses)) {
+        const WaveformFactory::VersionClass vc =
+                WaveformFactory::waveformSummaryVersionToVersionClass(analysis.version);
+        if (vc == WaveformFactory::VC_USE) {
+            result.pWaveform = ConstWaveformPointer(
+                    WaveformFactory::loadWaveformFromAnalysis(analysis));
+            break;
+        }
     }
 
     return result;
@@ -292,5 +351,15 @@ void OverviewCache::waveformSummaryPrepared() {
 
     m_currentlyLoadingWaveform.remove(res.trackId);
 
+    // The async job captured `pRequester` as a raw pointer; it may have
+    // been deleted on the GUI thread while the load was in flight.
+    // Re-check on the GUI thread before handing the (possibly dangling)
+    // pointer to listeners, so they don't compare against `this` with
+    // a dangling address.
+    QPointer<QObject> requesterGuard(const_cast<QObject*>(res.requester));
+    if (requesterGuard.isNull()) {
+        return;
+    }
+
     emit waveformSummaryReady(res.requester, res.trackId, res.pWaveform);
 }

src/library/overviewcache.h

@@ -3,20 +3,31 @@
 #include <QSqlDatabase>
 
 #include "analyzer/analyzerprogress.h"
+#include "analyzer/trackanalysisscheduler.h"
 #include "preferences/usersettings.h"
 #include "track/trackid.h"
 #include "util/db/dbconnectionpool.h"
 #include "util/singleton.h"
 #include "waveform/overviewtype.h"
 #include "waveform/waveform.h"
 
+class TrackDAO;
 class WaveformSignalColors;
 
 class OverviewCache : public QObject, public Singleton<OverviewCache> {
     Q_OBJECT
   public:
     void onTrackSummaryChanged(TrackId);
 
+    /// Inject the library's `TrackDAO`. Used by the
+    /// `requestWaveformSummary(QString)` overload to resolve a
+    /// track file location into a `TrackId` through the library
+    /// database. Must be called once after `createInstance`, before
+    /// any location-based request is made.
+    void setTrackDAO(TrackDAO* pTrackDAO) {
+        m_pTrackDAO = pTrackDAO;
+    }
+
     QPixmap requestCachedOverview(
             mixxx::OverviewType type,
             TrackId trackId,
@@ -37,6 +48,17 @@ class OverviewCache : public QObject, public Singleton<OverviewCache> {
     /// load for that track is already pending.
     void requestWaveformSummary(TrackId trackId, const QObject* pRequester);
 
+    /// Variant of `requestWaveformSummary` that resolves the track by
+    /// its file location rather than its `TrackId`. The location is
+    /// translated to a `TrackId` through the library database (a
+    /// single indexed query on the GUI thread) and then the existing
+    /// `TrackId`-based load path is reused. This is useful for tracks
+    /// that are not in the database (no valid `TrackId`) but whose
+    /// file URL is known, e.g. for tracks shown in browse/external
+    /// table views. If no track matches `trackLocation` the call is
+    /// a no-op.
+    void requestWaveformSummary(const QString& trackLocation, const QObject* pRequester);
+
     struct FutureResult {
         FutureResult()
                 : requester(nullptr) {
@@ -72,6 +94,15 @@ class OverviewCache : public QObject, public Singleton<OverviewCache> {
 
     void overviewChanged(TrackId);
 
+    /// Emitted on every analyzer progress update for `trackId`,
+    /// including partial progress while analysis is in flight.
+    /// Connect to this signal to repaint waveform overview
+    /// visualizations during analysis (the `Track` itself only emits
+    /// `waveformSummaryUpdated` once at the start and once at the
+    /// end of analysis, so it can't drive progressive drawing on its
+    /// own).
+    void analyzerProgress(TrackId trackId, AnalyzerProgress analyzerProgress);
+
     void waveformSummaryReady(
             const QObject* pRequester,
             TrackId trackId,
@@ -102,6 +133,11 @@ class OverviewCache : public QObject, public Singleton<OverviewCache> {
     UserSettingsPointer m_pConfig;
     mixxx::DbConnectionPoolPtr m_pDbConnectionPool;
 
+    /// Borrowed pointer to the library's `TrackDAO` (lives on the GUI
+    /// thread, owned by `TrackCollection`). Used to resolve track file
+    /// locations to `TrackId`s in `requestWaveformSummary(QString)`.
+    TrackDAO* m_pTrackDAO = nullptr;
+
     QSet<TrackId> m_currentlyLoading;
     QSet<TrackId> m_currentlyLoadingWaveform;
     QSet<TrackId> m_tracksWithoutOverview;