[CHORE:DOCS] add mpris docs + refactor code

the bullshit class name of song tree has been changed to
`SongLibrarySnapshot` (will remove the core namespace from it in future
commits.)

Author: nots1dd

CMakeLists.txt

@@ -202,7 +202,7 @@ include(${CMAKE_SOURCE_DIR}/cmake/Version.cmake)
 # Backend Shared Library
 # -----------------------------------------------------------
 set(INLIMBO_CORE_SOURCES
-    src/core/SongTree.cc
+    src/core/SongLibrarySnapshot.cc
     src/audio/backend/alsa/Impl.cc
     src/audio/backend/Interface.cc
     src/audio/Registry.cc

README.md

@@ -214,9 +214,15 @@ More *could* be added if that is required but these are the most used fields.
 
 Now each field has certain criteria upon which the map is reordered.
 
-1. Artist: `Lexicographically Ascending/Descending (ASCII only)`, `Albums Count Ascending/Descending`, `Track Count Ascending/Descending`
-2. Album: `Lexicographically Ascending/Descending (ASCII only)`, `Track Count Ascending/Descending`
-3. Track: `Track Number Ascending/Descending`
+1. Artist: 
+    - `Lexicographically Ascending/Descending (ASCII only)`
+    - `Albums Count Ascending/Descending`
+    - `Track Count Ascending/Descending`
+2. Album: 
+    - `Lexicographically Ascending/Descending (ASCII only)`
+    - `Track Count Ascending/Descending`
+3. Track: 
+    - `Track Number Ascending/Descending`
 
 These are self-explanatory and easy to understand what each sort does. You can check out [example config.toml](https://github.com/nots1dd/inLimbo/blob/main/examples/config/config.toml) for how to customize each sort.
 

include/inlimbo/audio/backend/Interface.hpp

@@ -61,7 +61,7 @@ class IAudioBackend
 
   [[nodiscard]] virtual auto getBackendInfo() const -> backend::BackendInfo = 0;
 
-  /* ---------------- Visualization support ---------------- */
+  /* ---------------- Audio buffer read ---------------- */
 
   [[nodiscard]] virtual auto copySequence() const noexcept -> ui64     = 0;
   [[nodiscard]] virtual auto copyBufferSize() const noexcept -> size_t = 0;

include/inlimbo/core/SongTree.hpp …ude/inlimbo/core/SongLibrarySnapshot.hppinclude/inlimbo/core/SongTree.hpp renamed to include/inlimbo/core/SongLibrarySnapshot.hpp include/inlimbo/core/SongTree.hpp renamed to include/inlimbo/core/SongLibrarySnapshot.hpp

@@ -18,14 +18,14 @@ namespace core
 {
 
 // ============================================================
-// SongTree Declaration (NOT THREAD SAFE)
+// SongLibrarySnapshot Declaration (NOT THREAD SAFE)
 // ============================================================
 //
 // Note that this structure is used ONLY for serialization and deserialization.
 // The in-memory representation used during runtime is a threads::SafeMap<SongMap>.
 //
 
-class SongTree
+class SongLibrarySnapshot
 {
 private:
   SongMap m_songMap;
@@ -36,30 +36,30 @@ class SongTree
   void addSong(const Song& song);
   void setMusicPath(const Path& path) { m_musicPath = path; }
 
-  ~SongTree() { clear(); }
+  ~SongLibrarySnapshot() { clear(); }
 
   void clear()
   {
-    RECORD_FUNC_TO_BACKTRACE("SongTree::clear");
+    RECORD_FUNC_TO_BACKTRACE("SongLibrarySnapshot::clear");
     m_songMap.clear();
     m_musicPath.clear();
   }
 
   // Query methods
   [[nodiscard]] auto returnSongMap() const -> const SongMap&
   {
-    RECORD_FUNC_TO_BACKTRACE("SongTree::returnSongMap");
+    RECORD_FUNC_TO_BACKTRACE("SongLibrarySnapshot::returnSongMap");
     return m_songMap;
   }
   [[nodiscard]] auto moveSongMap() noexcept -> SongMap
   {
-    RECORD_FUNC_TO_BACKTRACE("SongTree::moveSongMap");
+    RECORD_FUNC_TO_BACKTRACE("SongLibrarySnapshot::moveSongMap");
     return std::move(m_songMap);
   }
   // note that this replaces the entire song map and newMap is no longer valid after this call
   void newSongMap(const SongMap& newMap)
   {
-    RECORD_FUNC_TO_BACKTRACE("SongTree::replaceSongMap");
+    RECORD_FUNC_TO_BACKTRACE("SongLibrarySnapshot::replaceSongMap");
     m_songMap = std::move(newMap);
   }
   [[nodiscard]] auto returnMusicPath() const -> const Path { return m_musicPath; }

include/inlimbo/helpers/fs/Directory.hpp

@@ -1,13 +1,13 @@
 #pragma once
 
 #include "InLimbo-Types.hpp"
-#include "core/SongTree.hpp"
+#include "core/SongLibrarySnapshot.hpp"
 #include "taglib/Parser.hpp"
 
 namespace helpers::fs
 {
 
-void dirWalkProcessAll(const Directory& directory, taglib::Parser& parser,
-                       core::SongTree& songTree);
+void dirWalkProcessAll(const Directory& directory, taglib::Parser& tagParser,
+                       core::SongLibrarySnapshot& songLibrarySnapshot);
 
 } // namespace helpers::fs

include/inlimbo/mpris/Interface.hpp

@@ -1,7 +1,6 @@
 #pragma once
 
 #include "InLimbo-Types.hpp"
-#include <string>
 
 namespace mpris
 {
@@ -28,10 +27,10 @@ class IMprisBackend
   [[nodiscard]] virtual auto durationSeconds() const -> double = 0;
 
   /* Metadata */
-  [[nodiscard]] virtual auto title() const -> Title        = 0;
-  [[nodiscard]] virtual auto artist() const -> Artist      = 0;
-  [[nodiscard]] virtual auto album() const -> Album        = 0;
-  [[nodiscard]] virtual auto artUrl() const -> std::string = 0;
+  [[nodiscard]] virtual auto title() const -> Title    = 0;
+  [[nodiscard]] virtual auto artist() const -> Artist  = 0;
+  [[nodiscard]] virtual auto album() const -> Album    = 0;
+  [[nodiscard]] virtual auto artUrl() const -> PathStr = 0;
 
   /* Volume */
   [[nodiscard]] virtual auto volume() const -> double = 0; // 0.0 → 1.0

include/inlimbo/mpris/Service.hpp

@@ -3,13 +3,123 @@
 #include "Interface.hpp"
 #include "c/mpris.h"
 
+// MPRIS Service
+//
+// The structure of how we get to this service is:
+//
+// ┌──────────────────────────────┐
+// │          DBus / MPRIS        │
+// │  (org.mpris.MediaPlayer2)    │
+// └──────────────▲───────────────┘
+//                │
+//                │ calls / signals
+//                │
+// ┌──────────────┴───────────────┐
+// │        mpris_service (C)     │  ← opaque handle
+// │  - DBus glue                 │
+// │  - State cache               │
+// └──────────────▲───────────────┘
+//                │
+//                │ function pointers
+//                │
+// ┌──────────────┴───────────────┐
+// │      mpris_backend (C)       │  ← C ABI boundary
+// │  - userdata (IMprisBackend*) │
+// │  - play(), pause(), title()  │
+// └──────────────▲───────────────┘
+//                │
+//                │ dispatch
+//                │
+// ┌──────────────┴───────────────┐
+// │      mpris::Service (C++)    │  ← CPP boundary
+// │  - owns mpris_service*       │
+// │  - owns backend reference    │
+// └──────────────▲───────────────┘
+//                │
+//                │ virtual calls
+//                │
+// ┌──────────────┴───────────────┐
+// │    IMprisBackend (C++)       │  ← Strategy interface
+// │  - play(), seek(), metadata  │
+// └──────────────▲───────────────┘
+//                │
+//                │ concrete impl
+//                │
+// ┌──────────────┴───────────────┐
+// │     audio::Service calls     │
+// └──────────────────────────────┘
+//
+// Why was the C ABI made?
+//
+// Initially, the choice was made due to a simple reason.
+// I did not want to use gio or glib for this, it was too
+// tacky and felt too much for a simple DBus connection
+// and event poller/notifier.
+//
+// So i just wanted to write it in pure c using libdbus
+// API directly instead and statically compile it as a
+// separate library.
+//
+// An added benefit was that I can change the logic however
+// I want when these events are handled in cpp boundary,
+// without worrying about messing up the DBus core logic.
+//
+// But quite honestly, this isnt required still and I could
+// have just written externed C code over to cpp itself,
+// and had one core backend implementation (backend::Common)
+//
+// It currently is very stable and works pretty well, so
+// I do not have any intention of changing this however.
+// (unless some good points are made on why this is shitty)
+//
+// Also the frontend does not have to worry about all this,
+// which is another added benefit of just abstracting it all
+// behind an interface and language boundary.
+//
+// 1. How to create a MPRIS service?
+//
+// -> Create the backend implementation first
+// (or just use mpris::backend::Common)
+//
+// Note that the backend must inherit `IMprisBackend`
+// and ofc override all methods.
+//
+// -> Have an App name ready.
+//
+// Then simply invoke like so:
+//
+// ```cpp
+// mpris::backend::Common mprisBackend(audioService);
+// mpris::Service mprisService(mprisBackend, "test");
+// ```
+//
+// FAQ:
+//
+// - Will I need to create new mpris service objs in
+//   the frontend?
+//
+// NO. The inLimbo main context will handle it at compile
+// time. Frontend will ONLY receive that mpris service
+// as a pointer over the frontend C ABI.
+//
+// In short, you do not need to worry about creation
+// or deletion of this object. The lifetime is strictly
+// handled by the main context at all times.
+//
+// - Why would I ever need to create a custom MPRIS
+//   backend?
+//
+// Maybe to add some logging, connect to lastfm API,
+// idk. Possibilities with such a model is ofc quite
+// extensive and I will leave it upto you to decide.
+
 namespace mpris
 {
 
 class Service
 {
 public:
-  Service(IMprisBackend& backend, const std::string& name);
+  Service(IMprisBackend& backend, const std::string& appName);
   ~Service();
 
   void poll();

include/inlimbo/mpris/backends/Common.hpp

@@ -69,7 +69,7 @@ class Common final : public mpris::IMprisBackend
     return m ? m->album : "";
   }
 
-  [[nodiscard]] auto artUrl() const -> std::string override
+  [[nodiscard]] auto artUrl() const -> PathStr override
   {
     auto m = m_audioService.getCurrentMetadata();
     return m ? m->artUrl : "";

src/Context.cc

@@ -462,10 +462,10 @@ auto maybeHandleEditActions(AppContext& ctx) -> bool
   }
 
   // Persist updated SongMap to disk
-  SongTree tempSongTree;
-  tempSongTree.clear();
-  tempSongTree.newSongMap(g_songMap.snapshot());
-  tempSongTree.saveToFile(ctx.m_binPath);
+  SongLibrarySnapshot tempSongLib;
+  tempSongLib.clear();
+  tempSongLib.newSongMap(g_songMap.snapshot());
+  tempSongLib.saveToFile(ctx.m_binPath);
 
   LOG_DEBUG("Song object metadata updated successfully. Exiting app...");
   return true;
@@ -545,13 +545,13 @@ auto initializeContext(int argc, char** argv) -> AppContext
 
 void buildOrLoadLibrary(AppContext& ctx)
 {
-  SongTree tempSongTree;
-  bool     rebuild = ctx.args.rebuildLibrary;
+  SongLibrarySnapshot tempSongLib;
+  bool                rebuild = ctx.args.rebuildLibrary;
 
   try
   {
-    tempSongTree.loadFromFile(ctx.m_binPath);
-    if (tempSongTree.returnMusicPath() != ctx.m_musicDir)
+    tempSongLib.loadFromFile(ctx.m_binPath);
+    if (tempSongLib.returnMusicPath() != ctx.m_musicDir)
       rebuild = true;
   }
   catch (...)
@@ -562,26 +562,28 @@ void buildOrLoadLibrary(AppContext& ctx)
   if (!rebuild)
   {
     LOG_INFO("No song map rebuild. Loading song map and sorting...");
-    g_songMap.replace(tempSongTree.moveSongMap());
+    g_songMap.replace(tempSongLib.moveSongMap());
+    // loads any changes in sorting plan from config
     const auto plan = config::sort::loadRuntimeSortPlan();
     query::songmap::mut::sortSongMap(g_songMap, plan);
     return;
   }
 
   utils::Timer<> timer;
   timer.start();
-  tempSongTree.clear();
+  tempSongLib.clear();
 
-  helpers::fs::dirWalkProcessAll(ctx.m_musicDir, ctx.m_tagLibParser, tempSongTree);
+  helpers::fs::dirWalkProcessAll(ctx.m_musicDir, ctx.m_tagLibParser, tempSongLib);
 
-  tempSongTree.setMusicPath(ctx.m_musicDir);
-  g_songMap.replace(tempSongTree.moveSongMap());
-  // the song map is unordered so lets sort it
+  tempSongLib.setMusicPath(ctx.m_musicDir);
+  g_songMap.replace(tempSongLib.moveSongMap());
+  // the fresh song map is unordered so lets sort it
   //
   // note that by default, we are only sorting this following:
   //
   // -> artists in ascending order (lexicographically),
   // -> albums in ascending order (lexicographically),
+  // -> discs in ascending order (numerically),
   // -> tracks in ascending order (numerically)
   //
   // as that is most logical.
@@ -592,10 +594,10 @@ void buildOrLoadLibrary(AppContext& ctx)
   query::songmap::mut::sortSongMap(g_songMap, plan);
 
   // now let us save the newly sorted song map to disk
-  tempSongTree.newSongMap(g_songMap.snapshot());
-  tempSongTree.saveToFile(ctx.m_binPath);
+  tempSongLib.newSongMap(g_songMap.snapshot());
+  tempSongLib.saveToFile(ctx.m_binPath);
 
-  // SongTree has destructor so mem shud clear here
+  // SongLibrarySnapshot has destructor so mem shud clear here
   LOG_INFO("Library rebuilt in {:.3f} ms", timer.elapsed_ms());
 }
 
@@ -637,10 +639,13 @@ void runFrontend(AppContext& ctx)
     LOG_INFO("Fuzzy search song title query returned: '{}'", song->metadata.title);
 
     // ---------------------------------------------------------
-    // Create AudioService (owns AudioEngine)
+    // Create audio::Service
     // ---------------------------------------------------------
     audio::Service audio(g_songMap, ctx.m_audioBackendName);
 
+    // ---------------------------------------------------------
+    // Create mpris::Service (common backend logic)
+    // ---------------------------------------------------------
     mpris::backend::Common mprisBackend(audio);
     mpris::Service         mprisService(mprisBackend, APP_NAME);
 
@@ -707,15 +712,15 @@ void runFrontend(AppContext& ctx)
   }
   catch (const utils::unix::LockFileError& e)
   {
-    LOG_ERROR("Context threw LockFileError: {}", e.what());
+    LOG_ERROR("unix::LockFileError: {}", e.what());
   }
   catch (const frontend::PluginError& e)
   {
     LOG_ERROR("frontend::PluginError: Context threw Frontend error: {}", e.what());
   }
   catch (std::exception& e)
   {
-    LOG_ERROR("Context threw generic std::exception: '{}'", e.what());
+    LOG_ERROR("inlimbp::runFrontend threw std::exception: '{}'", e.what());
   }
 }
 

src/audio/Service.cc

@@ -16,9 +16,17 @@ Service::Service(threads::SafeMap<SongMap>& songMapTS, const std::string& backen
   {
     LOG_DEBUG("Found ALSA backend. Creating audio service...");
     m_backend = std::make_shared<backend::AlsaBackend>();
-    LOG_INFO("Audio Backend '{}' (ID: {}) created.", m_backend->backendString(),
-             (int)m_backend->backendID());
   }
+  else
+  {
+    // always default to ALSA for now
+    // (we will assume that inLimbo builds for ALSA at the bare minimum.)
+    LOG_WARN("audio::Service: Invalid audio backend name found, defaulting to ALSA...");
+    m_backend = std::make_shared<backend::AlsaBackend>();
+  }
+
+  LOG_INFO("Audio Backend '{}' (ID: {}) created.", m_backend->backendString(),
+           (int)m_backend->backendID());
 }
 
 Service::~Service() { shutdown(); }