Liber Music Player

by Sudhanshu Chaudhary
5
4
3
2
1
Score: 50/100

Description

Reviews

No reviews yet.

Stats

0
stars
32
downloads
0
forks
2
days
2
days
2
days
9
total PRs
0
open PRs
0
closed PRs
9
merged PRs
0
total issues
0
open issues
0
closed issues
74
commits

Latest Version

3 days ago

Changelog

What's Changed in v3.0.2

This release ensures full compliance with the Obsidian Community Plugin Directory markdown specification.

📝 Documentation & AST Compatibility

  • Native CommonMark H1 Heading: Updated README.md to begin with a standard markdown # Liber Music Player heading on line 1, ensuring automated AST linters and directory crawlers correctly resolve the plugin name.
  • Alt Text Normalization: Normalized preview image attributes to match the manifest name.

🛡️ Verified Production Assets

  • main.js: Re-compiled production bundle with full Web Audio DSP, WASM Vorbis fallback, and React 18 view shell.
  • manifest.json: Version 3.0.2 with personal authorUrl (https://github.com/sudh29).
  • styles.css: Strict scoped styling with 0 !important declarations.
  • Cryptographic Provenance: Signed with GitHub SLSA build provenance attestations.

📦 Installation

Install directly via Obsidian Community Plugins or BRAT (sudh29/liber_music), or download the attached release assets below.

README file from

Github

Liber Music Player


📑 Table of Contents


✨ What's New in v3.0: Minimalist Material 3

Liber Music Player v3.0 introduces a comprehensive visual and architectural redesign:

  • 🎨 Dynamic Material 3 Color Extraction: Extracts dominant and secondary tones directly from the active song's album art, dynamically shading playing lyrics, active progress bars, and the hero FAB play/pause button with ambient mesh text glow.
  • 📐 Adaptive Fluid Layout & Zero Empty Voids: Proportional responsive sizing (clamp(140px, 28vh, 320px)) that eliminates empty black voids on tall screens while fitting comfortably into sidebars and mobile drawers without scrollbars.
  • 📱 Obsidian Mobile Drawer CSS Isolation: Scoped Navigation Bar styling (.music-player-nav-buttons) that prevents Obsidian core mobile drawer styles from forcibly pulling navigation icons over bottom playback controls.
  • 📱 Universal Cross-Platform Parity: Fully tested and optimized for 15.6" Laptop (Desktop Electron), Pixel 9a (Android Chromium), and iPad Air 13" (WebKit WKWebView).
  • 🎶 Expanded Triplet Lyrics Window: Generous vertical lyrics display (clamp(80px, 14vh, 200px)) with responsive fluid typography and word-by-word karaoke synchronization.

📱 Universal Device Showcase

Liber Music Player is engineered and visually calibrated for complete cross-platform parity across desktop, tablet, and mobile:

💻 Laptop / Desktop (Electron) 📱 Mobile / Pixel 9a (Android) 📲 Tablet / iPad Air 13" (WebKit)
Sidebar docked with synced lyrics & library Compact drawer layout with isolated controls Adaptive fluid canvas with touch controls

🚀 Quick Start

  1. Open the Player:
    • Click the 🎵 Liber Music ribbon icon on Obsidian's left sidebar, or
    • Press Ctrl/Cmd + P and run Liber Music Player: Open Liber Music Player.
  2. Configure Music Directory:
    • Open Settings $\rightarrow$ Liber Music Player.
    • Set Music folder to your audio directory (e.g. Music/ or Media/Audio), or leave empty to scan the entire vault.
  3. Enjoy Listening:
    • Click any track in your library to start playback.
    • Click the 🎛️ Equalizer icon in the player header to choose acoustic curves (Flat, Bass Boost, Harman Target).
    • Hover or tap any active lyric line and click 🔗 to copy an audio citation deep link directly into your notes.

📦 Installation

  1. Open Obsidian Settings $\rightarrow$ Community plugins.
  2. Turn off Restricted mode.
  3. Click Browse and search for Liber Music Player.
  4. Click Install, then Enable.

Option 2: Obsidian42 - BRAT (Beta Releases)

  1. Install the BRAT plugin from Community plugins.
  2. In BRAT settings, click Add Beta plugin.
  3. Enter repository path: sudh29/liber_music (or https://github.com/sudh29/liber_music).
  4. Click Add Plugin and enable Liber Music Player under Community Plugins.

Option 3: Manual Installation

  1. Download main.js, manifest.json, and styles.css from the Latest Release.
  2. Inside your Obsidian vault, navigate to .obsidian/plugins/ and create a folder named liber-music-player.
  3. Copy the three downloaded files into <YourVault>/.obsidian/plugins/liber-music-player/.
  4. In Obsidian, reload plugins under Settings $\rightarrow$ Community plugins and toggle Liber Music Player ON.

🌟 Key Features

🎚️ Audiophile Web Audio DSP Engine

  • 10-Band Graphic & Parametric Equalizer: Biquad filtering across 10 ISO standard octave frequencies (31Hz, 62Hz, 125Hz, 250Hz, 500Hz, 1kHz, 2kHz, 4kHz, 8kHz, 16kHz).
  • Master Bypass Switch: Bit-transparent, click-free unity audio passthrough when disabled without rebuilding graph nodes.
  • Preamp Gain Stage: Independent -12dB to +12dB preamp volume slider with dynamic headroom protection.
  • Acoustic Presets:
    • Flat: Bit-transparent standard reference.
    • Bass Boost: Deep low-end rumble and punch.
    • Vocal Clarity: Forward, articulate midrange for podcasts and vocals.
    • Acoustic: Natural instrument warmth for classical, folk, and strings.
    • Rock & Metal: Punchy V-shaped dynamic response.
    • Harman Target Curve: Scientifically calibrated listener preference target.
    • Electronic: Sub-bass extension and sparkling highs.
    • Custom: User-adjusted band gains.
  • Dual-Pipeline Gapless & Equal-Power Crossfading Engine:
    • Bit-Transparent Gapless (0s): Pre-buffers upcoming track binary headers to execute zero-latency seamless track transitions.
    • Acoustic Constant-Power Crossfade (1s–10s): Leverages a simultaneous dual-stream pipeline (outgoingAudioElement and incomingAudioElement), blending acoustic energy along equal-power curves (cos(t * π/2) / sin(t * π/2)) with zero volume drops or clicks.
    • Automatic fallback safety: immediately engages full volume if the outgoing stream is paused or unavailable.
  • ReplayGain & EBU R128 Volume Normalization:
    • Automatically reads embedded REPLAYGAIN_TRACK_GAIN and REPLAYGAIN_ALBUM_GAIN tags across ID3, Vorbis, and MP4 containers.
    • Track Gain Mode: Normalizes individual song loudness across mixed playlists.
    • Album Gain Mode: Preserves intentional acoustic dynamics between consecutive songs in an album release.
    • Off Mode: Bit-exact unadjusted raw audio volume.
  • Interactive Equalizer Modal & Commands:
    • Quick-access equalizer button (sliders-horizontal) directly in the player action bar.
    • Obsidian command palette: Open 10-Band Equalizer.
    • Settings tab toggles and default preset selection.

🚀 Universal iOS/iPadOS Codec Parity via WASM Vorbis

  • 100% Codec Parity Across All Apple Devices:
    • Bypasses Apple WebKit's native lack of Ogg Vorbis support on iPadOS, iOS, and Safari using an inlined WebAssembly decoder.
    • Automatically detects platform capability and decodes .ogg and .opus audio buffers into 16-bit PCM RIFF WAV Blob URLs in real time.
    • Retains full hardware acceleration, standard HTMLAudioElement event binding, media keys, lock screen widgets, equalizer filters, and crossfading without requiring users to convert or re-encode audio.
    • 100% offline-ready with zero external network requests or standalone .wasm file dependencies.
    • Configurable toggle (enableWasmVorbisDecoder) under audio settings with graceful native fallbacks.

⚡ Smart Library Automation & Dynamic Playlists

  • Rule-Based Smart Playlists:
    • Build dynamic playlists using composable boolean rules across rating, year, genre, duration, path, title, artist, or album.
    • Choose conjunction mode: match all rules (AND) or any rule (OR).
    • Configurable sort fields, sort directions (asc/desc), and custom track limit thresholds.
    • Interactive live preview modal with instant match counter and 1-click presets (High Rated, Classics, Epics & Jams, New Additions).
    • Full CRUD lifecycle with inline edit and delete actions and distinct ⚡ Smart badges in the sidebar.
  • Automated Vault Folder Sync:
    • Automatically mirror audio folder structures (e.g. 📁 Rock, 📁 Jazz, 📁 Ambient) as native playlists.
    • Configurable directory nesting depth (1–3 levels) with zero duplicate indexing.
    • Dynamic folder badges and real-time synchronization during library scan.
  • In-App ID3 / Vorbis Metadata & LRC Editor:
    • Inspect and modify Title, Artist, Album, Year, Genre, Track Number, and Star Rating directly within Obsidian.
    • Built-in companion .lrc lyrics editor with direct vault write-back.
    • Quick-access via turntable action bar button (file-pen), tracklist hover action, or Obsidian command palette (Edit Track Metadata).

🌈 Reactive Visuals & Dynamic Aesthetics

  • Dynamic Accent Palette Extraction:
    • Automatically samples and quantizes dominant swatches from active album art using an offscreen canvas.
    • Dynamically updates player CSS variables (--player-dynamic-accent, --player-dynamic-secondary, --player-dynamic-glow, --player-karaoke-highlight, --player-text-on-accent) with smooth 600ms transitions.
    • In-memory URL caching prevents redundant canvas quantization, falling back gracefully to the vault accent theme when art is unavailable.
  • Real-Time Audio Spectrum Visualizer:
    • Web Audio AnalyserNode (fftSize = 64) post-EQ frequency monitoring.
    • Sleek 16-bar frequency spectrum visualizer rendered via throttled requestAnimationFrame and direct DOM ref mutation to eliminate React re-render overhead.
    • Automatically hibernates during pause (0% idle CPU utilization).
    • Quick-toggle visualizer button (activity) directly in the turntable action bar.
  • Custom Turntable Materials & Dynamic Grooves:
    • Brushed Obsidian: Modern stealth dark matte aluminum with cyan indicator LEDs and brushed platter ring.
    • Vintage Walnut: Warm mahogany wood grain body with brass tonearm and gold platter accents.
    • Cyberpunk Acrylic: Semi-transparent frosted glass plinth with neon purple glow and underlighting.
    • Animated pulsing vinyl groove halo reactively illuminating playback state.
    • Quick-cycle style toggle button (sparkles) and persistent settings dropdown.

🎵 High-Fidelity Audio Playback

  • Broad Format Support: Plays .mp3, .wav, .ogg, .m4a, .flac, and .aac audio files directly from your Obsidian vault.
  • Granular Controls: Play/pause, track navigation (previous/next), scrubbable progress bar, elapsed and remaining time displays.
  • Interactive Progress Bar: Click to seek instantly; drag to scrub with visual-only updates until release; single-click/double-click elapsed time to rewind 5s/15s, and duration to skip forward 5s/15s.
  • Playback Speeds: Adjustable speeds from 0.5x to 2.0x.
  • Volume & Mute: Stepped volume presets and smooth slider popup controls.
  • Queue Management: Real-time interactive playback queue modal with instant track selection and search filtering.

🎛️ Playback Modes

  • Sequential: Plays tracks in listed order and stops when finished.
  • Repeat Queue: Cycles through the active playlist continuously.
  • Repeat One: Repeats the current track indefinitely.
  • Shuffle: Shuffles tracks randomly with zero-repeat queue tracking.

📚 Music Library & PKM Organization

  • All Tracks: Scans and displays all audio assets within your vault or dedicated folder.
  • Favorites: One-click track favoriting with persistent fast-access lists.
  • Custom Playlists: Full CRUD management—create, rename, reorder, and delete playlists.
  • Artist & Album Categorization: Automatic tag extraction and aggregation by artist and album.
  • Instant Search: Modal fuzzy-matching by title, artist, or album name with instant playback.

🎤 Synchronized Lyrics (LRC & Word-by-Word Karaoke)

  • Tag & Companion Parsing: Automatically extracts lyrics embedded within metadata tags (ID3/Vorbis) or adjacent companion .lrc files in the vault.
  • Standard LRC: Accurate line-level timestamp synchronization.
  • Karaoke Word-by-Word: Syllable-level highlight synchronization (<mm:ss.xx>) for karaoke sing-along experiences.
  • Dual Display Modes:
    • Three-Line Compact View: Shows previous, current, and upcoming lines below the turntable.
    • Full-Screen Scrolling View: Complete scrollable lyric script with active auto-centering and interactive timestamp jumping.

🎨 Skeuomorphic Vinyl Record Aesthetics

  • Animated Turntable: Realistic rotating vinyl record with tonearm needle placement animations on play/pause.
  • Disc Sliding Transitions: Smooth disc slide transitions when switching between tracks.
  • Hierarchical Cover Art Resolution:
    1. Image named cover.jpg / cover.png in the track's folder (case-insensitive).
    2. Companion image sharing the track's filename (e.g., song.mp3 → song.jpg).
    3. Embedded album artwork extracted from ID3/Vorbis metadata.
    4. Elegant vinyl grooved default placeholder.

🔄 Automatic Vault Sync & Cache Reindexing

  • File System Watchers: Listens to vault file creation, deletion, rename, and move events in real time.
  • Consistency Verification: Automatically compares the cached index against vault contents on startup.
  • Visual Reindex Indicator: An unobtrusive dot notification on the Rebuild button indicates index drift, enabling clean one-click cache reconstruction.

📦 Production Ops & Automated Distribution

  • Compact Tree-Shaken Distribution Bundle:
    • dist/main.js is ~761 KB (well under the strict 2.0 MB ceiling), containing zero dead code and zero external network dependencies.
    • dist/styles.css is ~93 KB with inlined high-DPI turntable assets, completely self-contained.
    • Automated bundle audit (scripts/check-bundle-size.mjs) guards against asset regressions during build.
  • Automated Tagged Release & CI/CD Pipeline:
    • GitHub Actions workflow (release.yml) triggers on tag pushes and release publications, compiling production bundles, verifying coverage, and attaching release assets (main.js, manifest.json, styles.css) with SLSA provenance attestations.
    • Full BRAT (Beta Reviewers Auto-update Tester) compatibility for seamless 1-click installation and updates.
    • Multi-node matrix CI workflow (lint.yml) validating Node.js 20.x & 22.x on every push and pull request.

📝 Markdown Codeblock Embeds & PKM Deep-Linking

Interactive Markdown Codeblock Player

Embed lightweight, self-contained music players directly inside notes using music codeblocks. Supports start/end timestamps, custom lyrics display, and compact or card layouts:

```music
track: "Music/Classical/Chopin - Nocturne Op. 9.mp3"
start: "01:23"
end: "03:45"
showLyrics: true
compact: false
autoplay: false
```

Timestamped Lyric Citations & URI Deep-Linking

  • Hover or tap any line in the full lyric view to reveal the Copy Timestamp Link button (🔗).
  • Generates markdown citation links: [01:23 — "Lyric text"](obsidian://music-player?track=...&t=83).
  • Clicking this link anywhere in Obsidian activates the sidebar player, loads the track, and jumps directly to that timestamp.

Daily Notes Listening History Scrobbler

  • Automatically records completed tracks (>70% listened) to your active Daily Note journal under a configurable heading (e.g. ## 🎧 Music Log).
  • Maintains an offline, persistent audit ledger in <configDir>/plugins/liber-music-player/history.json.
  • Single-Source Audio Coordination: Playing an in-note snippet automatically pauses sidebar playback and vice versa to eliminate conflicting audio streams.

⌨️ Global Commands & Hotkeys

Global Hotkey Commands (Settings → Hotkeys)

Control playback from anywhere in Obsidian without focusing the sidebar leaf:

  • Liber Music Player: Play or pause playback
  • Liber Music Player: Play next track
  • Liber Music Player: Play previous track
  • Liber Music Player: Increase volume (5% steps)
  • Liber Music Player: Decrease volume (5% steps)
  • Liber Music Player: Toggle shuffle
  • Liber Music Player: Toggle repeat mode
  • Liber Music Player: Open 10-band equalizer
  • Liber Music Player: Edit track metadata
  • Liber Music Player: Create smart playlist

In-Player View Shortcuts

When the player view is active, the following hotkeys are supported:

Key Binding Action
Space Toggle Play / Pause
↑ Previous Track
↓ Next Track
← Rewind 5 seconds
→ Fast-forward 5 seconds
Ctrl + ← Rewind 15 seconds
Ctrl + → Fast-forward 15 seconds

📖 Lyrics Format Specification

Liber Music Player supports standard timestamped LRC as well as word-by-word syllable karaoke timestamps.

1. Standard LRC

[00:12.50]Line 1 lyrics text
[00:15.80]Line 2 lyrics text
[00:20.10]Line 3 lyrics text

2. Syllable-Level Karaoke

Word timestamps are enclosed within <mm:ss.xx> tags following the line timestamp:

[02:23.43]<02:23.43>Here <02:23.65>comes <02:23.83>the <02:24.18>sun <02:24.71>and <02:24.90>it's <02:25.63>alright
[02:26.00]<02:26.00>Little <02:26.28>darling <02:26.68>it's <02:27.02>been <02:27.40>a <02:27.83>long <02:28.68>winter

⚙️ Settings Configuration

  • Music Folder Path: Specify a dedicated vault subfolder (e.g. Music/ or Media/Audio) to scan. Leaving this empty scans the entire vault.
  • Autoplay on Launch: Automatically resume or start the first track when the player view opens.
  • Autoplay Track: Pick a specific track to start on launch.
  • Record listening history to Daily Notes: Automatically logs completed listening sessions to your daily note journal via atomic Vault.process mutations.
  • Daily Notes Section Heading: Heading title under which song logs are appended (default: ## 🎧 Music Log).
  • Keep Screen Awake: Toggle Screen Wake Lock API to prevent device sleep during synchronized karaoke lyric tracking.
  • ReplayGain volume normalization: Choose between Track Gain (matches loudness per song), Album Gain (preserves dynamics across an album release), or Off.
  • Crossfade duration: Configure transition blending between tracks from 0s (strict gapless pre-buffering) to 10s (equal-power crossfade).
  • 10-Band Equalizer & Presets: Enable the DSP equalizer engine and select default acoustic curve (Flat, Harman Target, Bass Boost, etc.).
  • Turntable Visual Style: Select turntable aesthetics (Brushed Obsidian, Vintage Walnut, or Cyberpunk Acrylic).
  • WASM Vorbis Decoder: Toggle real-time inlined WebAssembly Vorbis/Opus decoding for iOS and iPadOS Safari WebViews.

⚡ Improvements Over Upstream (Fork Comparison)

Fork Lineage: Liber Music Player was forked from TracingOrigins/obsidian-music-player-plugin (v1.3.8).
While the original plugin offered a foundational sidebar vinyl player, Liber Music Player has undergone an end-to-end architectural overhaul, elevating it from a simple playback widget into a production-ready, audiophile-grade Personal Knowledge Management (PKM) audio engine.

📊 Comprehensive Comparison Matrix

Feature / Capability Upstream (TracingOrigins) Liber Music Player (v3.0.0) Architectural & User Impact
Automated Testing & CI ❌ 0 tests (0% coverage) ✅ 691 tests across 82 suites (98.32% lines, 85.37% branches) Strict quality regression gates; every parser, decoder, and state hook is verified in CI.
iOS / iPadOS OGG Playback ❌ Fails (Apple WebKit cannot decode OGG/Opus) ✅ 100% Codec Parity via inlined WASM Vorbis Bypasses WebKit limitations; decodes .ogg & .opus to WAV Blob URLs on iOS/iPadOS without user re-encoding.
Audio DSP & Equalizer ❌ None (raw browser output only) ✅ 10-Band Biquad EQ & Dual-Pipeline Crossfading ISO octave bands (31Hz–16kHz), ±12dB preamp, 7 tuned presets, and true simultaneous dual-stream sinusoidal crossfading.
Markdown Note Integration ❌ None (sidebar only) ✅ music Codeblock Player Embeds Embed interactive mini-players directly inside Obsidian markdown notes with custom start/end timestamps and lyrics.
Lyric Deep-Linking ❌ None ✅ 1-Click Timestamp URI Citation Links Click 🔗 on any lyric line to copy obsidian://music-player?track=...&t=... that jumps to exact moments across the vault.
Daily Notes Scrobbler ❌ None ✅ Automated Listening Journaling Logs completed listening sessions (>70%) to active Daily Notes with an offline audit ledger (history.json).
Smart Playlists ❌ None (static lists only) ✅ Dynamic Rule-Based Smart Playlists Composable boolean rules (rating, year, genre, duration, title, etc.), AND/OR logic, instant preview, and 1-click presets.
Vault Folder Sync ❌ None ✅ Automatic Folder-to-Playlist Mirroring Maps vault directories (e.g. 📁 Jazz, 📁 Classical) directly into playlists with configurable nesting (1–3 levels).
In-App Tag & LRC Editor ❌ None (metadata read-only) ✅ Full In-App Metadata & Lyric Editor Edit title, artist, album, year, genre, star rating, and companion .lrc text files directly inside Obsidian with vault write-back.
External Companion .lrc ❌ Ignored (embedded tags only) ✅ Full Companion .lrc Auto-Discovery Automatically finds and synchronizes standalone .lrc files located alongside audio files in the vault.
Visualizer & Theming ❌ Static CSS, 1 fixed vinyl look ✅ Real-Time Spectrum Visualizer & Dynamic Palette 16-bar Web Audio spectrum monitor; offscreen canvas quantizes album art colors into CSS variables; 3 turntable styles.
Mobile System Integration ❌ None (stops on lock) ✅ MediaSession API & Screen Wake Lock Lock screen player widget, Android notification controls, Bluetooth headphone keys, and screen keep-awake toggle.
Mobile Memory Safety ⚠️ High RAM (reads entire 50MB files) ✅ 512KB Header-Only Chunking & Streaming Streamed header reads eliminate mobile out-of-memory crashes; direct vault URL streaming for large tracks.
Shuffle Queue Correctness ⚠️ Flawed (repeats songs, button erasure) ✅ True Non-Repeating Fisher-Yates Shuffle Dedicated ShuffleManager guarantees 100% of tracks play before recycling; preserved icon rendering.
Loudness Normalization ❌ None ✅ ReplayGain (Track & Album Modes) & EBU R128 Automatic volume normalization preserving either per-song target loudness or inter-track album dynamics.
Build & Toolchain ⚠️ Basic legacy esbuild ✅ Vite+ (vp) & Rust Oxc Compiler / Linter Rust-powered transforms (oxc-transform-react), 0 lint warnings across 184 files, and automated bundle size audits.
Release & Distribution ⚠️ Manual file drops ✅ Automated GitHub Actions & BRAT Support Automated tagged releases with SLSA provenance attestations and 1-click beta updates via BRAT.
Localization & Repo Hygiene ⚠️ Chinese/English mix, Python .gitignore ✅ Clean English Architecture & Strict Hygiene 100% localized English docs/codebase, strict Node/Obsidian .gitignore, and zero untracked binaries in repository.

🏎️ Performance & Speed Benchmarks: Upstream vs Liber Music Player

Beyond new functional capabilities, Liber Music Player features deep architectural optimizations targeting render latency, disk I/O, battery life, and memory management.

Performance Metric / Operation Upstream (TracingOrigins) Liber Music Player (v3.0.0) Measured Speedup & Efficiency
Incremental Vault Rescan (2,000 tracks) ~18.5 seconds (full sequential binary disk reads) < 40 ms (mtime + size cache verification) 🚀 ~450x faster (0 redundant disk reads)
5,000-Track List Render / Mount Time ~1,200 ms initial mount lag & dropped frames < 16 ms instant frame budget (virtual windowing) 🚀 ~75x faster (rock-solid 60fps scrolling)
Active DOM Elements (5,000-track library) 5,000+ DOM nodes mounted simultaneously ~25–35 visible rows + overscan buffer 📉 99.5% fewer DOM elements
Idle / Paused CPU Utilization ~3%–5% CPU (unthrottled 60fps rAF loop) 0.0% CPU (rAF automatically halts when paused) 🔋 ~100% idle CPU reduction (battery preservation)
Background / Minimized App CPU Drain Continuous rendering & Web Audio sampling Pauses visualizer & throttles background polling 🔋 85%+ reduction in background energy consumption
Mobile Audio Header I/O Payload Reads entire 50MB audio files into RAM 512KB header-only chunk streaming 📉 99% reduction in I/O & peak RAM (zero OOM crashes)
In-Memory Cache Growth Unbounded maps (indefinite RAM accumulation) Bounded LRUMap (capped at 50 entries) 🛡️ Zero memory leaks over days of continuous listening
Distribution Stylesheet Size 538.72 KB (uncompressed base64 rasters) 85.92 KB (optimized WebP vector assets) 📉 84.1% smaller CSS footprint (6.3x lighter)
Lint & Static Analysis Execution No linter / legacy slow tooling ~340 ms via Vite+ & Rust Oxc (179 files / 12 threads) ⚡ Instantaneous developer feedback
Key Architectural Speed Multipliers:
  1. ~450x Faster Incremental Vault Rescanning: Upstream flushed all metadata and re-read binary headers for every audio file on disk on every rescan. Liber tracks file.stat.mtime and file.stat.size, verifying 2,000 tracks in under 40 milliseconds with zero redundant disk I/O.
  2. ~75x Faster DOM Rendering with Virtual Windowing: Upstream rendered a DOM node for every song in a playlist, freezing the interface on large libraries. Liber implements windowed virtualization that keeps only the visible ~25 rows mounted in the DOM, maintaining 60fps scrolling even with 10,000+ tracks.
  3. Zero Idle CPU Consumption: Upstream ran a continuous 60fps requestAnimationFrame loop on the root component at all times. Liber decouples the render loop, halting all animation frames the instant music is paused, saving laptop and mobile battery.
  4. 99% Lower Peak Memory on Mobile: Upstream read entire audio files into memory during metadata extraction, triggering frequent OS-level memory termination on mobile devices. Liber streams only the first 512KB header chunk, preventing out-of-memory crashes on iOS and Android.

🛠️ Development & Architecture

Prerequisites

  • Node.js (v18.0 or newer recommended, tested on Node 20 & Node 24)
  • npm package manager

Getting Started

# Clone the repository
git clone https://github.com/sudh29/liber_music.git
cd liber_music

# Install dependencies
npm install

# (Optional) Configure vault path for automatic local dev hot-reload deployment:
echo "VAULT_PATH=/path/to/your/obsidian/vault" > .env

# Start development build with live watch and vault deployment
npm run dev

# Run automated tests (via Vite+)
npm test

# Run Rust-powered linter (via Vite+ & Oxlint)
npm run lint

# Production bundle & typecheck
npm run build

Modernized Tech Stack

  • Language: TypeScript 5.8+ (Strict mode)
  • UI Framework: React 18 & Vanilla CSS Design System
  • Toolchain: Vite+ (vp) for next-generation developer tooling
  • Compiler & Linter: Oxc (oxc-transform-react & vp lint) for ultra-fast Rust-based parsing, transforms, and linting
  • Test Runner: Vitest via Vite+ (vp test run) with 691 passing unit and integration tests across 82 test suites (98.32% line coverage)
  • Bundler: esbuild with embedded image inlining and mobile Buffer polyfills
  • Metadata Parser: music-metadata (v12.x browser build)
  • Internationalization: English-only codebase and locale architecture

🤝 Contributing & Feedback

Contributions, feature suggestions, and bug reports are warmly welcome!

  • 🐛 Report a Bug: Open an issue on GitHub with reproduction steps, your OS, and Obsidian version.
  • 💡 Request a Feature: Submit a suggestion detailing the proposed enhancement or workflow.
  • 💻 Code Contributions: Review our Contributing Guide for local development setup, coding standards, and PR guidelines.
  • 💬 Discussions & Questions: Join community discussions in GitHub Discussions.

💖 Sponsoring & Donations

Liber Music Player is free and open-source software built with love for the Obsidian community. If this plugin enhances your daily workflow and listening enjoyment, consider supporting its ongoing maintenance and new features:


📄 License

This project is licensed under the MIT License.