Foreword

dsh-music-player-tui is a DeepSeek Harness (DSH) TUI plugin for dsh-tui. It puts a local music player into the terminal scene: input /music to open the full-screen scene, select a local music directory, scan common audio formats, and then call the local player process to play sound.

It mainly solves a specific problem: listening to local music while operating in dsh-tui, and ensuring the music does not stop after exiting the full-screen scene.

What is this

heshuren371/dsh-music-player-tui is an MIT licensed plugin maintained by heshuren371 for the dsh-tui host.

Its core idea is:

  • Provide a /music full-screen music scene within dsh-tui.
  • Scan audio files in local directories to generate a track list.
  • The host spawns the local player process (e.g., mpv, ffplay, afplay).
  • The playback process continues to exist after exiting the scene; music does not stop, and the scene can be re-entered at any time by inputting /music.

Core Features

Verified features include:

  • Recursive scan of local directories: flac / mp3 / m4a / aac / ogg / opus / wav.
  • Embedded tag parsing; defaults to the “Artist - Title” filename convention.
  • Track list displays Title, Artist, and Duration.
  • Use ↑/↓ or j/k to select tracks; the window adapts to terminal height.
  • Mouse support: Hover to move the cursor, click a list row to play directly.
  • Sorting: Title, Artist, Duration; toggle ascending/descending; playback order equals the visible list order.
  • Search filter: Title, Artist, Filename.
  • Loop mode: List loop, Single loop, Stop after end.
  • Seek: ←/→ adjusts ±5s, under Shift adjusts ±30s.
  • Volume adjustment: +/- adjusts 5% each time.
  • Music does not stop after exiting the scene.
  • Delete track: x inside the scene for 2nd confirmation, or /music delete <keyword>.
  • State persistence: Directory, Volume, Loop mode, Last played track and progress.
  • Direct access to /music subcommands: dir / play [keyword] / pause / next / prev / vol / refresh / delete.
  • Standard bundle plugin: Zero core changes, add to manifest, clean uninstall.
  • Automatic playback backend detection: mpv, ffplay (ffmpeg), afplay (macOS built-in).

Installation and Enablement

  1. Confirm prerequisites: dsh-tui installed and running, version ≥ 0.8; the first run will automatically initialize the profile.

  2. Add the plugin:

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

  1. Restart dsh-tui, enter /music and press Enter. The appearance of the full-screen scene indicates successful activation.

  2. It is recommended to install mpv for more complete playback control:

brew install mpv

The mpv backend supports seamless pause, instant volume/seek, and precise progress. If mpv is not present, the plugin will detect ffplay (ffmpeg) or afplay (macOS built-in). If none of the three backends are present, the plugin mounts as usual, but a prompt to install mpv/ffmpeg will appear upon starting playback.

Typical Usage

After installing and setting the directory, you can use the following /music subcommands within dsh-tui:

/music dir ~/Music
/music play
/music play keyword
/music pause
/music next
/music prev
/music vol 60
/music refresh
/music delete keyword

Corresponding meanings:

  • /music dir <path>: Set directory and scan, e.g., /music dir ~/Music.
  • /music play [keyword]: Play current/first track; with a keyword, play the first matching track.
  • /music pause: Pause or resume.
  • /music next / /music prev: Switch tracks.
  • /music vol <0-100>: Set volume.
  • /music refresh: Rescan current directory.
  • /music delete <keyword>: Delete track files; requires unique matching, not recoverable.

Inside the /music full-screen scene, you can also use:

  • Enter: Play the selected track.
  • Space: Pause or resume.
  • q / Esc: Exit scene, music continues playing.
  • x: Delete selected track, press x again to confirm; local files are deleted together, not recoverable.

Playback Backend

Sound is emitted by the local player process on the machine running the dsh-tui host. The plugin will automatically detect the following backends:

  • mpv: Recommended installation. Supports seamless pause, instant volume/seek, and precise progress.
  • ffplay (ffmpeg): Alternative backend. Pause relies on POSIX signals (SIGSTOP/SIGCONT); Windows users are advised to install mpv directly.
  • afplay: macOS built-in fallback backend. Does not support seeking, and volume takes effect upon the next playback start.

If none of the three backends are present, the plugin mounts as usual, but a prompt to install mpv/ffmpeg will appear upon starting playback.

Applicable Scenarios and Notes

Suitable for:

  • Listening to local music while operating in dsh-tui.
  • Wanting playback to continue without interruption after exiting the full-screen scene.
  • Using only local audio files and having the machine’s player process produce sound.
  • Needing simple track list, search, sorting, track switching, pause, and volume control.

Notes:

  • Deleting tracks deletes local files, which is not recoverable.
  • /music delete <keyword> requires a unique match.
  • x deletion inside the scene requires a second confirmation.
  • afplay is a fallback backend, does not support seeking, and volume takes effect upon the next playback start.
  • If none of the three playback backends are present, the plugin mounts as usual, but a prompt to install mpv/ffmpeg will appear upon starting playback.
  • The plugin runs in the dsh-tui host process via the “trusted-in-process” mode, not in a sandbox.
  • It actually does three things: reads the specified music directory, spawns the local player process, and deletes corresponding track files upon 2nd confirmation or command match; besides this, it does not read/write any files or access the network.
  • Dependencies closure is limited to music-metadata (pure JS, no native/build steps, no override/patch); state is written to the user directory by default, and the installed package directory remains read-only.
  • State file is located at ~/.dsh-music-player-tui/state.json. Uninstalling only removes the plugin package and does not touch audio files; the state file remains, and manually deleting this directory clears it completely.
  • Current specification is Draft/Experimental: this plugin declares experimental compatibility and does not represent official certification or a commitment to compatibility with all DSH hosts.
  • The plugin runs with the permissions of the current dsh-tui host process; source code and license should be reviewed before installation. The license is MIT.

Conclusion

The value of dsh-music-player-tui lies in putting local music playback into the dsh-tui scene: you can scan local directories, sort and search, play/pause/switch tracks, adjust volume, and music continues playing after exiting the scene.

Repository address: https://github.com/heshuren371/dsh-music-player-tui