Features

Audio playback

• Multiple formats: MP3 / WAV / OGG / M4A / FLAC / AAC
• Playback controls: Play / pause, previous / next track
• Progress and time: Progress bar with current / total duration
• Playback speed: Adjustable from 0.5x to 2.0x
• Volume: Mute, 25%, 50%, 75%, 100%
• Queue: View the current queue and switch tracks quickly

Playback modes

• Sequential: Play in list order; stop when the list ends
• Loop list: Restart from the beginning when the list ends
• Loop one: Repeat the current track
• Shuffle: Play tracks in random order

Library management

• All tracks: Every scanned music file
• Favorites: One-tap favorites for quick access
• Playlists: Create / edit / delete custom playlists
• Artists: Tracks grouped by artist
• Albums: Tracks grouped by album
• Search: Search tracks, artists, and albums

Lyrics

• Source: Lyrics are read only from embedded metadata in audio files. The plugin does not read external lyric files from disk and does not fetch lyrics online.
  • Standard lyrics: Standard LRC-style lyrics in tags
  • Word-by-word lyrics: Timestamped syllable/word lyrics (karaoke style)
• Display:
  • Three-line view: Previous line, current line, next line
  • Full-screen lyrics: Full list with auto-scroll and highlight
• Sync: Lyrics follow playback position automatically

For detailed lyric formats, see Lyrics format below.

UI and interaction

• Album art: Embedded or folder-based art with optional spinning disc animation
  • Cover resolution order:
    1. An image file named cover in the same folder as the track (e.g. cover.jpg, cover.png, case-insensitive)
    2. An image in the same folder with the same basename as the track (e.g. song.mp3 → song.jpg)
    3. Embedded cover art from the audio file’s metadata
• Disc transition animation: When using previous/next or shortcuts, the disc shows a sliding transition
• Disc view: Full-screen disc-style playback UI
• Lyrics view: Focused lyrics screen
• Responsive layout: Works on desktop and mobile
• Keyboard shortcuts: See Keyboard shortcuts below

Settings

• Music folder:
  • Search and pick a music folder;
  • Click the input to browse the folder list;
  • If left empty, the whole vault is scanned (for large vaults, a dedicated music folder is recommended).
• Autoplay on open: Whether to auto-play the first track when opening the player
• Default playback mode: Initial mode configurable in settings

Auto-sync and indexing

• File watching: Watches for create, delete, rename, and move of music files
• Library updates: Updates library data when files move in or out of the music folder
• Consistency check: On startup, checks index vs. the file system
• Rebuild hint:
  • When a rebuild is suggested, a small dot appears on the rebuild control;
  • You can tap rebuild manually to re-index.

---

Installation

Manual install

For local development builds or when the plugin is not yet in the community catalog:

1. Go to Releases and download the latest plugin archive or files.
2. Extract / place the plugin folder under your Obsidian plugins directory (typically:

• <Your vault>/.obsidian/plugins/music-player/).

3. In Obsidian, open Settings → Community plugins → Installed plugins and enable this plugin.

Install with BRAT (recommended for testers)

For beta / latest dev builds:

1. Install the BRAT plugin.
2. In BRAT settings, choose Add beta plugin.
3. Enter the repo: TracingOrigins/obsidian-music-player-plugin.
4. After install, enable the plugin under Settings → Community plugins → Installed plugins.

---

Usage

Quick start

1. Enable the plugin (Settings → Community plugins → Installed plugins).
2. Click the music icon in the left ribbon, or use the command palette and run Open music player.
3. On first use, set a dedicated music folder in plugin settings (recommended):

• Optional: leave empty to scan the entire vault for audio files.

4. Click any track in the list to start playback.

Lyrics format

The plugin reads these lyric formats from embedded tags in audio files:

Note: The plugin does not read standalone .lrc files next to tracks and does not download lyrics; only embedded lyric tags are parsed.

• Standard (LRC-style) lyrics Example:

  [02:22.94]外婆她的期待
  [02:26.14]慢慢变成无奈
  [02:29.08]大人们始终不明白
  [02:34.97]她要的是陪伴
  [02:37.97]而不是六百块
  [02:40.96]比你给的还简单
  

• Word-by-word (karaoke-style) lyrics After the line start timestamp, each character or word is wrapped with <time>. Example:

  [02:23.43]<02:23.43>外<02:23.65>婆<02:23.83>她<02:24.18>的<02:24.71>期<02:24.90>待<02:25.63>
  [02:26.00]<02:26.00>慢<02:26.28>慢<02:26.68>变<02:27.02>成<02:27.40>无<02:27.83>奈<02:28.68>
  [02:29.00]<02:29.00>大<02:29.30>人<02:29.69>们<02:30.03>始<02:30.28>终<02:30.61>不<02:30.83>明<02:31.18>白<02:34.00>
  [02:34.96]<02:34.96>她<02:35.25>要<02:35.65>的<02:36.02>是<02:36.34>陪<02:36.77>伴<02:37.62>
  [02:37.93]<02:37.93>而<02:38.22>不<02:38.53>是<02:38.88>六<02:39.19>百<02:39.63>块<02:40.61>
  [02:40.94]<02:40.94>比<02:41.21>你<02:41.55>给<02:41.96>的<02:42.31>还<02:42.68>简<02:43.03>单<02:44.84>
  

Playback queue

Use the queue / playlist button in the bottom control bar to:

• See all tracks in the current queue;
• Search within the queue;
• Tap any row to switch playback;
• See cover, title, artist, and album for each item;
• Highlight the currently playing track.

Keyboard shortcuts

When the music player view is focused:

• Space: Play / pause
• ↑: Previous track
• ↓: Next track
• ←: Seek back 5 seconds
• →: Seek forward 5 seconds
• Ctrl + ←: Seek back 15 seconds
• Ctrl + →: Seek forward 15 seconds

(Exact bindings may follow Obsidian’s shortcut UI; future versions may add or change shortcuts.)

---

FAQ

Q: What does the small dot on the rebuild control mean?

A: The index may be out of sync with the file system; a manual rebuild is recommended. Common causes:

• Music files deleted outside Obsidian (e.g. in File Explorer);
• Files moved or renamed without the index updating;
• Corrupt or incomplete index data.

What to do:

1. Tap Rebuild index (with the dot) to rebuild;
2. The dot disappears when rebuild finishes.

Note: Even without rebuilding, the library list reflects the file system in real time (removed files disappear from the list). Rebuild mainly cleans stale index entries and refreshes metadata.

---

Development

• Clone the repo:
  • git clone https://github.com/TracingOrigins/obsidian-music-player-plugin.git
• Node.js v16+ (current LTS recommended):
  • node --version
• Install dependencies:
  • npm install
• Dev (recommended):
  • npm run dev
  • Runs node scripts/deploy.mjs dev, symlinks dist into your vault, and runs the bundler in watch mode for local iteration.
• Production build and deploy to test vault:
  • npm run build
  • Runs TypeScript checks and production build, then node scripts/deploy.mjs build copies dist outputs into the vault plugin folder for testing or release.

The deploy script reads .env at the project root. Set:
VAULT_PATH=/path/to/your/Obsidian/vault.
Plugin id comes from manifest.json; files end up at <VAULT_PATH>/.obsidian/plugins/<pluginId>/.

---

Tech stack

• TypeScript
• React for UI
• Obsidian API for plugin integration
• HTML5 Audio for playback
• esbuild for bundling

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

---

🌟 Support & Help

If you find this plugin helpful, please consider:

• ⭐ Starring the repository.
• 🐛 Using the bug report template to submit bug reports.
• 💡 Using the feature request template to submit feature suggestions.
• ❓ Asking questions or sharing ideas in our Discussions.
• 📝 Referring to the Contributing Guide to contribute code or documentation.
• 💰 Providing sponsorship to the developer (if available).