================
havMediaControls

VERSION 1.1.1.0
================

Copyright (c) 2026 René Nicolaus

Build: Windows (.NET 10, WPF, x64)
Source Code: https://github.com/Havoc7891/havMediaControls

========
Contents
========
1. What it does
2. Features
3. Requirements
4. How to run
5. Start with Windows (Optional)
6. Tray icons
7. Now-playing popup
8. Tray menu
9. Player support
10. Localization
11. Building and release
12. Notes
13. Uninstall
14. Troubleshooting
15. Changelog
16. License

===============
1. What it does
===============
havMediaControls is a WPF tray app that provides Windows media controls in
the notification area.

It creates separate tray icons for quick actions and a compact popup for the
active media session.

===========
2. Features
===========

- Separate tray icons for previous, play/pause/resume, next, repeat, and now playing
- Compact draggable now-playing popup
- Current media title, artist, album, source app, playback state, timeline, and cover art
- Previous, play/pause/resume, next, repeat, shuffle, seek, volume, mute, and speed controls
- Light theme, dark theme, and automatic system theme mode
- English and German localization, with additional language files discovered at startup
- Single-instance app behavior
- Configurable media-key command method
- Optional player-remote fallback for compatible external players
- Settings and logging under %APPDATA%\havMediaControls

===============
3. Requirements
===============
- Windows 10 version 1809 or later (Windows 11 recommended)
- .NET 10 Desktop Runtime (x64)

If you don't already have the .NET 10 Desktop Runtime, download and install it from:
https://dotnet.microsoft.com/en-us/download/dotnet/10.0/runtime

=============
4. How to run
=============
1) Extract the ZIP anywhere, for example C:\Apps\havMediaControls.
2) Run havMediaControls.exe. No admin rights are required.
3) Use the tray icons for quick media actions, or right-click a tray icon to open the menu.
4) Click the now-playing tray icon to open or close the popup.

================================
5. Start with Windows (Optional)
================================
Option A - Startup folder (Per-user)
- Press Win + R -> type: shell:startup -> OK
- Place a shortcut to havMediaControls.exe in that folder

Option B - Registry (Per-user)
Create a file named 'havMediaControls-Startup.reg' with the content below,
edit the path, then double-click to add:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run]
"havMediaControls"="\"C:\\Apps\\havMediaControls\\havMediaControls.exe\""

=============
6. Tray icons
=============
The app creates multiple notification-area icons:

- Previous: sends the previous-track command when supported
- Play/Pause/Resume: toggles playback when supported
- Next: sends the next-track command when supported
- Repeat: cycles repeat mode from off to list to track and back to off when supported
- Now playing: opens or closes the popup and shows current title/artist in the tooltip

Unsupported action icons are hidden instead of shown as disabled tray icons.
The optional action icons can also be hidden from the tray menu under Tray
buttons. The Now playing icon is always shown so the shared tray menu remains
reachable.
Windows controls notification-area icon order, pinning, and overflow visibility.

====================
7. Now-playing popup
====================
The popup shows:

- Source app and playback state
- Title, artist, album, and cover art
- Timeline and seek slider
- Previous, play/pause/resume, next, repeat, and shuffle buttons
- Default system output volume and mute button
- Playback speed slider with decrease, reset, and increase buttons

Repeat, shuffle, seek, and playback-speed controls are disabled when the active
media session does not report support for that command. Disabled controls show
the reason in their tooltip. Disabled speed stays displayed as 1.00x.

============
8. Tray menu
============
Find any tray icon and right-click it to open the shared settings menu.

Menu items:
- Open now playing: opens the popup
- Session: follow active media automatically, choose a specific media session, or choose the available transport fallback session
- Repeat: choose off, list, or track when repeat is supported
- Theme: choose auto, light, or dark
- Language: switch between available languages, including English and German
- Tray buttons: choose which optional action icons are shown in the notification area
- Advanced > Media key method: choose a compatibility method for play/pause, previous, and next
- Player remote: configure host/port endpoint and process name for the optional player-remote fallback
- Previous, Play/Pause, Next: execute media commands when supported
- Refresh: refresh session and player state manually
- About: shows product name, version, copyright, and description
- Exit: quits the app

=================
9. Player support
=================
havMediaControls controls normal media sessions through Windows Global System
Media Transport Controls (GSMTC). Support depends on what the active media app
exposes to Windows.

Transport commands (Previous, Play/Pause, Next) default to sending a targeted
app command to the player window because some apps report GSMTC success without
actually reacting. The Advanced > Media key method submenu lets you switch
command mode when a player behaves differently:

- Send to player window
- Global media keys
- Global media keys (SendInput)
- Global media keys (scancode)
- System media session

Repeat, shuffle, seek, and playback speed use GSMTC when available. There are
no universal Windows media keys for repeat or shuffle, so players that do not
expose those controls require player-specific support. If a player reports only
play/pause support, havMediaControls disables unsupported controls instead of
sending commands the player has already said it will ignore.

The optional player-remote fallback can provide transport, timeline, seek,
repeat, shuffle, cover-art, and metadata support for compatible external
players through a configured host/port endpoint. When a configured external
player is running without a usable Windows media session, the session menu can
show it as an External player (transport fallback) entry with play/pause,
previous, and next support. Playback speed is disabled for fallbacks that do not
provide dependable speed control and readback.

Player-remote cover art first uses remote metadata when available, then falls
back to image files near the current media file. Cover-style names win first,
track/album/title matches come next, and otherwise the newest usable image is
selected.

================
10. Localization
================
The app ships with:

- English (en)
- German (de)

Available languages are discovered from *.json files in the languages folder.
The file name is the language code, and the optional LanguageName value inside
the JSON file is used as the menu label.

Use languages/en.json as the template for additional languages. Adding a
translation file to the release languages folder is enough for the app to show
it in the language menu without rebuilding the EXE.

========================
11. Building and release
========================
Build the solution:

dotnet build havMediaControls.sln -c Release -p:Platform=x64

Create the release ZIP:

.\create-release-build.ps1

The script publishes a framework-dependent win-x64 release build and creates:

havMediaControls-1.1.1.0-win-x64.zip

Generate icon assets:

python scripts/GenerateIcons.py

This is only needed when changing generated icon assets. The script uses only
the Python standard library and a bundled font; the generated assets are
already committed for normal builds.

=========
12. Notes
=========
- Settings are stored in %APPDATA%\havMediaControls\config.json
- Logs are written to %APPDATA%\havMediaControls\havMediaControls.log; release builds keep errors and command results, while verbose polling diagnostics are DEBUG-only. The active log rotates at 1 MiB and keeps one previous log
- Volume controls the default system output endpoint
- The app intentionally avoids direct endpoint mute APIs and uses a media-key mute command instead
- Some media apps expose only play/pause. In that case next, previous, repeat, shuffle, seek, or speed can be disabled
- Cover art comes from the media session when available. The player-remote fallback can also look for image files near the current media file

=============
13. Uninstall
=============
- Exit from the tray menu
- Delete the app folder
- Delete %APPDATA%\havMediaControls if you want to remove settings and logs
- If you enabled auto-start: remove the shortcut from shell:startup or delete the 'havMediaControls' value from:
  HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run

===================
14. Troubleshooting
===================
- No tray icons: Check the Windows tray overflow and notification-area icon settings.
- Buttons do nothing: Switch Advanced > Media key method from the tray menu and try again.
- A control is disabled: The selected session did not report support for that command.
- Media information is stale: Use Refresh from the tray menu or restart the media app.
- Player-remote fallback does not appear: Configure the process name and make sure the external player is running.
- No cover art: The media session may not provide a thumbnail. For player-remote fallback, put a supported image file near the current media file.

=============
15. Changelog
=============
Version 1.1.1.0 - 2026-08-03
- Improved the Now playing tray icon tooltip when artist metadata is missing.

Version 1.1.0.0 - 2026-07-31
- Added a Tray buttons submenu for hiding optional tray action icons while keeping Now playing always visible.
- Added localization for the external-player fallback label.
- Improved volume slider behavior when clicking or dragging to a new level.

Version 1.0.0.0 - 2026-07-30
- First release.

===========
16. License
===========
Licensed under MIT - see LICENSE.txt

===========
End of file
===========
