# Windows Platform Guide MPV Manager v1.3 supports Windows 10/11 on amd64 (x86-64-v2) and arm64. The v1.3 artifact remains the current Go Web/TUI/CLI executable. The planned v1.4 primary Windows product is a Wails desktop application; there is no planned separate Windows terminal edition. ## Build ```bash make build-win-x86_64 make build-win-arm64 # or both make build-windows ``` Outputs: - `dist/mpv-manager-win-x86_64.exe` - `dist/mpv-manager-win-arm64.exe` The amd64 target always uses `GOAMD64=v2`. The Makefile uses pinned `go-winres` v0.3.3 to regenerate fail-closed amd64 and arm64 resources with the numeric release version. Tag CI additionally extracts both completed PE files and asserts their icon, Windows 10 minimum, and exact file/product versions. For a release identity smoke test on Windows: ```powershell .\mpv-manager-win-x86_64.exe --version --json ``` Confirm `product=mpv-manager`, `component=manager-portable`, the normalized release version, `goos=windows`, and the expected architecture. ## Run and diagnose ```powershell .\mpv-manager-win-x86_64.exe .\mpv-manager-win-x86_64.exe tui .\mpv-manager-win-x86_64.exe --debug ``` The default Web UI binds only to loopback. Windows Firewall should not need a public-network exception. If the browser does not open, navigate to the URL printed in the console. ## Install discovery and paths Existing Windows installations are checked in this order: 1. configured custom install location; 2. `%APPDATA%\mpv` and the user's `mpv` directory; 3. Scoop and Chocolatey locations; 4. executables available through `PATH`. Custom install paths must be absolute, creatable, not a filesystem root, and not inside `%WINDIR%`. The active MPV configuration, hotkeys, script options, UI discovery, and backups all resolve to `\portable_config`. Managed portable installs contain `.mpv-manager-owned.json`, an exact payload ownership manifest committed with the archive. Updates refuse populated trees without valid ownership proof. Uninstall removes only listed payload files and empty payload directories; `portable_config`, MPV Manager files, unrelated siblings, and user-added files remain. MPV Manager does not elevate or execute register/unregister batch files from a mutable install tree. Choose or remove MPV file-type defaults through **Windows Settings → Apps → Default apps**. Legacy desktop shortcuts that targeted those scripts are retired. ## Credentials and permissions Secrets use Windows Credential Manager. MPV Manager does not use a plaintext password fallback. Antivirus, Controlled Folder Access, an unwritable install directory, or a locked executable can prevent replacement; the updater must surface the error and retain or restore the previous binary. Package-owned installations must set `SelfUpdateDisabled=true` and delegate updates to their package owner. ## v1.3 native update gate Run the release artifact on `win-dev` and cover: - Windows 10 and 11 where available; - amd64 and arm64 artifacts as hardware permits; - update from N-2 and N-1; - writable and unwritable portable locations; - locked backup/replacement, antivirus interference, and insufficient rights; - wrong hash/product/component/version/architecture; - rollback and startup cleanup; - Web restart notice, backend-owned close, and exit status 0; - TUI relaunch and relaunch failure; - package-manager build refusing self-update. As of 2026-08-30, the development-only synthetic-version qualifier passes commit, forced partial rollback, lock contention, healthy relaunch, and failed health-check rollback on Windows 11 Pro amd64. That run found and fixed the staged payload's missing `.exe` suffix. The historical-version, ACL/antivirus, arm64, and signing cases above remain open release gates. A current v1.3 amd64 release binary also passes native identity/help, Web startup, authenticated API, System page, install-detection, CPU/GPU probe, and graceful shutdown checks on `win-dev`; the API-requested shutdown exits with status 0. The VM's Microsoft Basic Display Adapter safely produces the expected unknown-codec fallback. v1.1/v1.2 attempted to rename the running executable in-process. Those immutable Windows builds cannot be made to use the v1.3 post-exit helper, so upgrading to v1.3 is a one-time manual executable replacement. Subsequent portable updates originate from v1.3 and use the helper transaction. Microsoft Artifact Signing is planned for the desktop product. Authenticode validation is still a release gate for signed Windows artifacts; BLAKE3 alone does not establish publisher authenticity. ## v1.4 desktop direction The Windows Wails application will be distributed through a signed installer and an optional portable archive containing the same desktop app. It should reuse the current embedded frontend and the v1.3 signed manifest/transaction foundation. See [Self-update and Wails Review](../SELF_UPDATE_AND_WAILS_REVIEW_2026-08-28.md). --- See also: [Build and Deployment](../BUILD_DEPLOYMENT.md) · [Testing](../TESTING.md) · [Troubleshooting](../TROUBLESHOOTING.md) ## Legacy portable installations and ownership MPV Manager records installed payload files in `.mpv-manager-owned.json` and removes only those files during uninstall. A legacy managed record with the same install path can migrate automatically. For an externally detected portable installation, select that exact installation and use **Adopt** first. Migration validates the PE headers of `mpv.exe` and optional `mpv.com`, without executing them, and claims only those launchers. It does not claim the directory's DLLs, scripts, documents or configuration. Updates add files from the verified new payload to the inventory. Unclaimed files keep their current locations unless they collide with a new payload path; those originals are retained under `.mpv-manager-preserved-/` inside the installation. These preservation folders, other unclaimed files and `portable_config` survive uninstall. Review them manually when deciding what to keep; do not delete the ownership manifest to bypass checks. MPC-QT uninstall waits for the elevated native uninstaller and checks its exit status and the selected `mpc-qt.exe` path before reporting success. A failed or cancelled uninstaller, missing uninstaller, ambiguous legacy location, or an executable that remains installed leaves the app record available for reconciliation.