DeepSeek Harness Plugin: Local Music Player

Preface¶

One of the design principles of DeepSeek Harness (DSH) is “everything is a plugin.” For developers or users who need to manage media resources locally, embedding a player directly in the conversation view is more efficient than opening an external app or file browser. The local music player plugin is designed for this purpose, integrating playback functionality into the session view tab ring of DSH.

Plugin Introduction¶

This plugin is maintained by developer heshuren371 and is a local music player implemented based on web technologies. It adds a “Music” tab to the session view tabs, provides a macOS Music-style UI, supports common audio formats, and includes advanced features such as metadata completion and an equalizer.

Core Features¶

The plugin manages the music library by recursively scanning local directories and supports the following features:

File Support: Supports common formats such as FLAC, MP3, M4A, AAC, OGG, Opus, WAV, MP4, MOV, WebM, MKV, and AVI.
Waveform and Progress: Decodes audio and extracts peaks using FFmpeg to display a real waveform progress bar.
Equalizer: Provides a 10-band equalizer with built-in preset curves including original, pop, rock, classical, jazz, bass boost, vocal, and electronic.
Playback Controls: Crossfade track switching is enabled by default with 300ms/700ms settings. Supports single-track loop and list loop.
Metadata Management: Supports online metadata completion (QQ Music, iTunes, NetEase Cloud, MusicBrainz). Tag writing uses atomic operations and supports file renaming.
ReplayGain: Provides loudness normalization. Prioritizes reading embedded file tags and supports single-track/album modes.
System Integration: Integrates MediaSession and supports lock screen display and Control Center notifications.
Video Support: Supports MV three-tier classification (direct/remux/transcode) and invokes FFmpeg for cache processing.

Installation and Enablement¶

Before installation, ensure that Node.js (^22.19.0 || >=24.0.0) and pnpm are installed on the system, and that FFmpeg is installed.

Install the plugin:

    dsh plugin --profile web add github:heshuren371/dsh-music-player

Check installation:

    dsh plugin --profile web ls

Enable the plugin:
After installation, restart dsh web and refresh the page. Find the “Music” tab in the tab ring at the top of the session to use it.

Development and Debugging¶

The plugin source code is written in TypeScript, and build artifacts are committed to the repository. For development and debugging:

git clone https://github.com/heshuren371/dsh-music-player.git
cd dsh-music-player
pnpm install
cd .. && dsh plugin --profile web add link:./dsh-music-player
pnpm run dev

Network debugging: Confirm that the plugin API path is working properly:

curl -s -o /dev/null -w '%{http_code}\n' "http://127.0.0.1:<端口>/dsh-music/api/session"

Common Issues:
* Desktop limitations: The CLI refuses to write files. Installation must be performed through the app menu. After installation, restart the app or press F12 to refresh.
* Tab not displaying: Confirm that the plugin exists in dsh plugin --profile web ls and that the page has been refreshed.

Permissions and Dependencies¶

The plugin requires the following permissions and dependencies:

Permissions: fs.read (read music), fs.write (write tags), fs.delete (delete files), net.fetch (online metadata completion), transport.api (API interaction), and storage.local (caching).
Dependencies: Node.js (^22.19.0 || >=24.0.0), pnpm, and FFmpeg (for waveform extraction, MV processing, and metadata measurement).

Notes¶

Compatibility: The plugin supports DSH >=0.1.6-alpha.1 <0.2.0 || >=0.2.0-0 <0.3.0-0 (compatible with 0.1.7-rc.2).
Feature limitations: The plugin currently does not support shuffle playback or a lyrics page. Apple FairPlay-encrypted offline packages (.movpkg) cannot be played and are automatically skipped during scanning.
File safety: Tag writing and file renaming are atomic operations; if interrupted midway, the original files will not be corrupted.