Google Play Music Desktop Player: Complete Setup & Customization Guide

Troubleshooting Google Play Music Desktop Player — Fixes for Common Issues

1) App won’t launch / shows black screen

• Fix: Completely quit any running gpmdp process, then restart.
• Steps:
  1. Windows: open Task Manager → End Task for any “gpmdp” or “Google Play Music Desktop Player” processes.
  2. macOS: Activity Monitor → Force Quit gpmdp.
  3. Linux: pkill gpmdp or killall gpmdp.
  4. Relaunch app.
• If persists: reinstall latest release from the project repo, delete the app’s cache folder (Windows: %appdata%\gpm\ or %appdata%\Google Play Music Desktop Player; macOS: ~/Library/Application Support/gpmdp; Linux: ~/.config/gpmdp) then relaunch.

2) Playback stutters, no sound, or audio device not found

• Fix: Check system audio device and app audio output.
• Steps:
  1. Ensure correct output selected in system sound settings.
  2. In-app: open audio device selector (if available) and pick the correct device.
  3. Update audio drivers (Windows) or restart CoreAudio (macOS: sudo killall coreaudiod).
  4. If using external DAC/USB, unplug/replug and relaunch app.

3) Scrobbling to Last.fm not working

• Common causes: authentication issues, network/proxy, or Last.fm server problems.
• Fixes:
  1. Re-authenticate Last.fm inside the app (log out → log in).
  2. If behind a proxy, ensure proxy settings allow POST to audioscrobbler endpoints or configure system proxy so the app can reach Last.fm.
  3. Check Last.fm status; try scrobbling a few tracks and confirm on Last.fm web.
  4. Update to latest app; check open issues on the repo for known regressions.

4) Missing artwork or UI elements

• Fix: Clear cache and restart; ensure network access.
• Steps:
  1. Clear app cache (see paths in section 1).
  2. Disable any system or network-level content blockers/HTTPS interception that can break image requests.
  3. Reinstall if files remain missing.

5) Keyboard media keys or Fn keys not working

• Fix: Re-enable global media key handling or update OS permissions.
• Steps:
  1. Ensure no other media app has exclusive control. Quit competing apps (Spotify, iTunes, etc.).
  2. On macOS, allow input monitoring if requested.
  3. On Windows, update keyboard drivers and check manufacturer software (some override keys).

6) Proxy / network errors (app cannot load web content)

• Fix: Configure system or app proxy properly.
• Steps:
  1. Set system proxy explicitly rather than auto-detect.
  2. If using corporate/HTTPS-intercepting proxy, install/whitelist required certificates or bypass proxy for the app.
  3. Test network connectivity to Google/YouTube domains and to the project’s website.

7) App crashes or shows errors after update

• Fix: Roll back or reinstall, keep config if needed.
• Steps:
  1. Download previous stable release from the repo releases page.
  2. Uninstall current version (keep or remove user data per your preference), install older release.
  3. Report crash with logs to the GitHub issues page if reproducible.

8) How to collect useful logs before reporting

• Steps:
  1. Reproduce the issue.
  2. Locate logs:
     • Windows: %appdata%\gpm\logs or %appdata%\Google Play Music Desktop Player\logs
     • macOS: ~/Library/Logs/gpmdp or ~/Library/Logs/Google Play Music Desktop Player
     • Linux: ~/.config/gpmdp/logs
  3. Attach the most recent log file and a short description (OS, version, steps to reproduce) to a new GitHub issue.

Quick checklist (try this first)

• Restart the app and your computer.
• Update to latest release.
• Clear app cache.
• Re-authenticate any third-party services (Last.fm).
• Verify system audio device and drivers.
• Check proxy/firewall/antivirus blocking.
• Collect logs and search the repo issues before filing a new one.

If you want, I can produce the exact commands/paths for your OS (Windows/macOS/Linux) and provide a template for a GitHub issue.