Skip to main content

​
Installation issues

Error message: “Failed to find MPV on your system!”Cause: MUDE requires MPV to be installed and accessible from your system PATH.Solution:
1

Install MPV

Download and install MPV for your operating system:macOS:
brew install mpv
Ubuntu/Debian:
sudo apt install mpv
Windows:
  • Download from mpv.io
  • Extract to a permanent location (e.g., C:\Program Files\mpv)
  • Add the mpv directory to your system PATH
2

Verify installation

Open a new terminal and run:
mpv --version
You should see version information. If you get “command not found”, MPV is not in your PATH.
3

Restart VS Code

After installing MPV, completely restart VS Code (close all windows) to ensure the new PATH is recognized.
The extension checks for MPV during activation. If MPV is not found, the extension will not activate and you’ll see a modal error dialog.
Symptom: No headphone emoji appears in the status bar after installation.Possible causes:
  • MPV is not installed or not in PATH
  • Extension activation failed during startup
  • Global storage directory creation failed
Solution:
1

Check extension status

  • Open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
  • Type “Developer: Show Running Extensions”
  • Look for “MUDE music player” in the list
  • Check if it shows any errors
2

Check VS Code logs

  • Open Command Palette
  • Type “Developer: Open Extension Logs Folder”
  • Look for MUDE-related errors
3

Verify MPV installation

Follow the MPV installation steps in the accordion above.
4

Reinstall the extension

  • Uninstall MUDE from the Extensions view
  • Reload VS Code
  • Reinstall MUDE from the marketplace

​
Playback issues

Error message: “No media is currently playing” (when using play/pause)Cause: You’re trying to control playback before loading any media.Solution:Search for and select a track first:
  • Click the headphone emoji (🎧) in the status bar
  • Or use Command Palette: “MUDE: Search Music”
  • Select a track to load and play
The play/pause control only works when media is loaded into MPV. After state restoration, you may need to click play to resume.
Symptom: Status bar shows the track title but no playback controls appear.Possible causes:
  • MPV failed to load the downloaded file
  • The downloaded file is corrupted
  • MPV lost connection to the extension
Solution:
1

Check MPV process

Verify MPV is running:macOS/Linux:
ps aux | grep mpv
Windows:
tasklist | findstr mpv
2

Try a different track

Search for and select a different song to see if the issue persists.
3

Clear cached files

MUDE stores downloaded files in VS Code’s global storage:
  • Close VS Code completely
  • Navigate to the global storage directory:
    • macOS/Linux: ~/.config/Code/User/globalStorage/mayur1377.mude/
    • Windows: %APPDATA%\Code\User\globalStorage\mayur1377.mude\
  • Delete youtube_download.webm
  • Restart VS Code and try again
4

Restart the extension

  • Open Command Palette
  • Type “Developer: Reload Window”
  • This restarts all extensions including MUDE
Error indicator: $(error) Error loading [Track Name] in status barCause: Download failed or MPV couldn’t load the file.Common reasons:
  • Network connectivity issues
  • YouTube/YouTube Music blocking the download
  • Disk space issues
  • Invalid video ID or unavailable content
Solution:
1

Check internet connection

Ensure you have a stable internet connection and can access YouTube.
2

Try a different track

Some content may be region-restricted or unavailable. Search for a different song.
3

Check disk space

Ensure you have sufficient disk space in your user directory for downloaded audio files.
4

Check VS Code output

  • Open Command Palette
  • Type “Developer: Toggle Developer Tools”
  • Check the Console tab for detailed error messages
  • Look for download or playback errors
If you consistently see this error, youtube-dl-exec (the download library) may need updating, or YouTube may have changed their API. Check for MUDE extension updates.
Symptom: Playback is choppy or audio quality is poor.Possible causes:
  • High CPU usage in VS Code
  • Network issues during download
  • MPV configuration issues
Solution:
  1. Check system resources: Close unnecessary applications to free up CPU/memory
  2. Ensure complete download: Wait for the download to fully complete before playback starts
  3. Restart MPV: Reload VS Code to restart the MPV process
  4. Check MPV configuration: MUDE runs MPV in audio-only mode for optimal performance
MUDE downloads audio in WebM format from YouTube, which is optimized for streaming quality. Audio quality depends on what’s available from YouTube Music.
Symptom: Track finishes but next recommendation doesn’t play automatically.Possible causes:
  • No recommendations were fetched
  • Reached the end of the recommendation queue
  • MPV ‘stopped’ event not firing correctly
Solution:
1

Check recommendations

Hover over the Next track button (▶) to see if there’s an “Up next” tooltip. If it says “Play next” with no track name, the recommendation queue is empty.
2

Start a new search

Starting a new search fetches fresh recommendations:
  • Click the headphone emoji (🎧)
  • Search for a track
  • Select and play
3

Manual navigation

Use the Next track button to manually trigger the next recommendation.
When the recommendation queue is exhausted, MUDE shows an information message: “Search for more songs to play!” Simply start a new search to continue listening.

​
State restoration issues

Symptom: After restarting VS Code, the previous track isn’t restored.Cause: The cached audio file may have been deleted, or global state wasn’t saved properly.Expected behavior:
  • MUDE saves the last played file path to VS Code’s global state
  • On activation, it checks if the file exists and loads it in paused state
  • If the file is missing, it gracefully shows stopped state
Solution:This is usually not an error. MUDE cleans up download files during playback:
  • Each new download overwrites the previous youtube_download.webm file
  • If the last file was overwritten, state restoration will show stopped state
  • Simply search for a new track to continue listening
State restoration is a convenience feature. It’s normal for it not to work if you’ve closed VS Code for an extended period or the cache was cleared.
Symptom: Status bar shows controls but nothing is playing, or vice versa.Cause: State synchronization issue between MPV and the extension.Solution:
1

Refresh the window

  • Open Command Palette
  • Type “Developer: Reload Window”
  • This resyncs all state
2

Check actual playback

Use Command Palette to check MPV properties:
  • Try “MUDE: Toggle Pause” to see if anything happens
  • If you get “No media is currently playing”, the state was incorrect
3

Reset state

If the issue persists:
  • Close all VS Code windows
  • Reopen VS Code
  • The extension will re-initialize with correct state
Symptom: Recommendation queue is empty after restarting VS Code.Cause: Recommendations are saved to global state but may not restore if:
  • The global state wasn’t saved before VS Code closed
  • There’s a timing issue during activation
Solution:This is expected behavior for the current implementation. Recommendations are tied to the current session:
  • Starting a new search fetches fresh recommendations
  • The queue is populated based on the track you select
If you want to continue with specific recommendations:
  • Use the Previous/Next buttons during your session
  • Avoid closing VS Code mid-playback if you want to maintain the queue
Future versions of MUDE may improve recommendation persistence. For now, treat each session as a fresh start for your music queue.

​
General troubleshooting steps

If you encounter an issue not covered above:
1

Check prerequisites

  • MPV is installed and in your PATH
  • VS Code is up to date (version 1.91.0 or higher)
  • Internet connection is stable
2

Gather diagnostic information

  • Open Developer Tools (Cmd+Shift+P > “Developer: Toggle Developer Tools”)
  • Check the Console tab for JavaScript errors
  • Look for MUDE-specific log messages (they include prefixes like [PLAYBACK], [SEARCH], [DOWNLOAD])
3

Try a clean restart

  • Close all VS Code windows
  • Kill any lingering MPV processes
  • Reopen VS Code
  • Test with a simple search
4

Report the issue

If the problem persists:
  • Visit the GitHub repository
  • Open an issue with:
    • Your OS and VS Code version
    • MPV version (mpv --version)
    • Steps to reproduce
    • Console logs from Developer Tools
Do not manually kill MPV processes while MUDE is active, as this can cause state synchronization issues. Always use VS Code’s reload or restart functions.

​
Getting help

If you need additional assistance: When reporting issues, always include:
  • Your operating system
  • VS Code version
  • MUDE extension version
  • MPV version
  • Detailed error messages or logs