config-central/docs/desktop-app-configs.md

217 lines
11 KiB
Markdown

# Desktop application configuration
The `desktop-apps` profile installs XnView MP, Zoom, Nextcloud Desktop, Notepad++,
HandBrake, GIMP, Krita, LibreOffice, Waterfox, Shotcut, and MPC-HC. Ontime
configuration is also managed when Ontime is installed separately.
Close an application before applying its config so it
does not immediately overwrite the result.
Review the checked-in declarations before sharing them across machines; they
include application preferences and Windows defaults.
Run `cc capture` to collect the current machine's configuration without applying
repository content. Captures are written beneath
`Documents\ConfigCentral\captures` and split between repository-shaped
`configs/` files and raw `review/` files that require curation. Nextcloud's full
configuration is excluded; only keys already declared in its safe overlay are
captured. Close applications first so their files reflect the latest saved
preferences.
## MPC-HC
MPC-HC normally stores preferences below
`HKCU\Software\MPC-HC\MPC-HC`. Config Central applies only values listed in
`configs/mpc-hc/settings.json`; it does not delete other values or registry keys.
The standard x86 and x64 builds use this same settings key for the same Windows
user: applying once configures both. This HKCU location is shared across registry
views; do not add a speculative Wow6432Node or "MPC-HC x64" target.
See [MPC-HC's settings store](https://github.com/clsid2/mpc-hc/blob/develop/src/mpc-hc/Profile.cpp)
and [Windows registry sharing rules](https://learn.microsoft.com/en-us/windows/win32/winprog64/shared-registry-keys).
Apply attempts to create missing registry keys and writes each declared value
independently. If some writes fail, the summary is a yellow warning listing only
the keys that could not be written; other values continue to apply. If every
write fails, the config fails. The existing running-player and backup checks
still apply. Full Windows errors are saved alongside the registry backup in a
`*.write-results.json` file. Partial deployments track the observed registry
state, so a later update retries the missing values instead of claiming that
all desired settings are current. Capture still explains how to initialize
settings when no registry profile exists.
Close **both** `mpc-hc.exe` and `mpc-hc64.exe` before applying. The adapter refuses
writes while either process is running, to prevent an open player from saving
stale settings over the new values. If the two players still differ, check each
one's settings-storage option and Windows account: separate INI files are not
managed by this registry adapter.
This adapter supports **registry mode only**. MPC-HC also supports an INI file
next to its executable (`mpc-hc.ini` or `mpc-hc64.ini`). Check the player's
settings-storage option before capture or apply: an old registry key can remain
even when the active player uses INI storage. A successful registry write does
not prove the player reads that registry key.
See [MPC-HC's storage implementation](https://github.com/clsid2/mpc-hc/blob/develop/src/mpc-hc/mplayerc.cpp).
Capture is deliberately filtered, not a complete player backup: monitor/device
selection and other machine-specific or private values are excluded. Apply only
updates declared values for the current Windows user. Close MPC-HC before
capture or deployment, then reopen it afterward.
On the machine whose settings should be the baseline, close MPC-HC and run:
```powershell
pwsh -File .\tools\Export-MpcHcSettings.ps1
```
The exporter omits history, favorites, recent files, URLs, and common path-like
values by default. Review the generated JSON anyway before committing it. Remove
any value that is machine-specific. `-IncludePrivateValues` exists for deliberate
local export work, but its output should almost never be committed.
## Ontime
The profile manages Ontime's supported CSS override at
`%APPDATA%\Ontime\user\styles\override.css`. Edit
`configs/ontime/override.css` to define the shared presentation. The event timer
hides current/next event cards, uses the same enlarged font size for the countdown
and bottom message, and flashes the background red when Blink is active. Text
stays visible. Fullscreen messages are bottom-aligned, share the countdown font
size, and use the same background blink effect. The upper-right clock is enlarged and shows hours/minutes without seconds.
Blink uses a gradual three-second cycle; reduced-motion browsers show steady red
instead. Slower flashing is not a guarantee of photosensitive safety.
Keep bottom messages short to fit at countdown size. The background trigger uses
CSS `:has()`, so use a current browser for the timer display.
The shared size is `--cc-timer-size`, the clock size is `--cc-clock-size`, and
the flash color is `--cc-blink-red` at the
top of the stylesheet. After deploying, reload the timer browser view.
Ontime stores projects, uploads, logs, crash data, its database, and volatile
`app-state.json` beneath `%APPDATA%\Ontime`. Config Central leaves those files
alone. In particular, `app-state.json` contains the active project, rundown,
server port, and session health, so copying it between machines would be wrong.
## XnView MP
The profile overlays keys from `configs/xnviewmp/xnview.ini` onto
`%APPDATA%\XnViewMP\xnview.ini`. Unlisted sections and keys remain untouched,
including the catalog and thumbnail databases.
Use **Settings > Integration > Paths > Open Config Files Location** in XnView MP
to locate the active INI file. Copy only portable sections and keys into the
repository overlay. Some XnView installations use an additional `settings`
subdirectory or portable mode; override the `xnviewmp-settings` target in that
machine's manifest when its displayed path differs.
Avoid sharing catalog paths, recent folders, database locations, or other values
that name a local drive.
## Nextcloud Desktop
Nextcloud's Windows configuration file is
`%APPDATA%\Nextcloud\nextcloud.cfg`. The profile uses an INI overlay from
`configs/nextcloud/managed.ini`, so account sections and other unlisted keys stay
untouched.
Never commit the full `nextcloud.cfg`: it contains account and authentication
material. Add only documented, non-secret preferences to `managed.ini`. Account
setup should remain interactive. To prefill a first-run wizard without storing a
password, Nextcloud supports commands such as:
```powershell
& 'C:\Program Files\Nextcloud\nextcloud.exe' `
--overrideserverurl 'https://cloud.example.com' `
--overridelocaldir 'D:/Nextcloud'
```
The local folder is commonly machine-specific, so this command is not run by the
shared profile.
## Windows hosts file
Add entries to `configs/windows/hosts.entries`:
```text
192.0.2.10 service.example.test
2001:db8::10 service-v6.example.test alias.example.test
```
Config Central validates every active line, requests elevation, backs up the
hosts file, and owns only this marked section:
```text
# BEGIN CONFIG CENTRAL: windows-hosts
...
# END CONFIG CENTRAL: windows-hosts
```
Lines outside that block are preserved. A comment-only declaration is a no-op.
## Applying changes
Run `cc plan` first. Existing unmanaged values are reported as conflicts rather
than overwritten. Once the repository version is correct, use:
```powershell
cc apply -ForceConfigs
```
Forced file and hosts updates are backed up under
`%LOCALAPPDATA%\ConfigCentral\backups`. Registry backups contain only the values
managed by the declaration, including each value's original type and whether it
existed. Failed individual writes are restored from that backup; successful
writes remain applied when the result is a warning. If the registry operation
fails, all its managed values are restored, including removal of values that
were originally absent. Unrelated values and key containers are left alone.
Rollback errors are reported explicitly with the retained backup path.
This automatic failure recovery is separate from the manual `cc restore`
command, which still does not support registry backups.
Inspect and commit each source file separately so no
history, credentials, tokens, or machine-specific paths enter Git.
## Windows sounds and battery display timeout
The `desktop-apps` profile includes `windows-sounds` and `windows-power`.
They participate in normal setup, config-only updates, conflict detection,
backups, and `cc capture`. Capture just these settings with:
```powershell
cc capture -Config windows-sounds
cc capture -Config windows-power
```
Each capture writes under Documents, with repository-relative
`configs/windows/sounds.json` or `configs/windows/power.json`. Review and copy
these files into the repository, commit and push, then run the usual config
update on each computer. Capture never changes the live settings.
**Sounds:** the checked-in `{"schemaVersion":1,"disabled":true}` preset clears
all registered current sound-event assignments for the desktop user and selects
“No Sounds”. It applies to events present on each receiving machine, including
events absent on the capture machine. If capture finds any assigned sounds, it
instead exports current event assignments and the selected scheme. Review
custom WAV paths before sharing; WAV files themselves are not copied.
This controls the user's Windows sound scheme, not master volume, audio devices,
the separate startup-sound setting, or applications that play their own audio.
Windows stores these assignments under
[AppEvents sound-event registry keys](https://devblogs.microsoft.com/scripting/hey-scripting-guy-how-can-i-randomly-assign-a-sound-to-a-sound-event/).
Close the Sound control panel before updating; applications that cache sounds
may need restarting.
**Power:** `batteryDisplayTimeoutSeconds` sets only the active plan's display
idle timeout on battery; `0` means never, as specified in
[Microsoft's display idle timeout documentation](https://learn.microsoft.com/en-us/windows-hardware/customize/power-settings/display-settings-display-idle-timeout).
Capture saves seconds, not a machine-specific plan GUID. Apply targets the
receiving machine's active plan. AC timeouts, sleep, hibernation, lid actions,
and lock-screen display timeout are unchanged; sleep can still switch off the
display. Switching plans later can select a different timeout, so rerun the
update after switching if needed. A managed Windows policy may block writes;
the result reports that failure instead of bypassing policy.
Before applying, both adapters save backups under Config Central's backup
directory. Any sound-write failure restores the managed sound assignments;
power failures restore the previous timeout on the original plan. Restoration
errors retain the backup and are reported explicitly. These adapters run as the
desktop user and never redirect sound settings into an administrator profile.
Manual `cc restore` remains limited to file configs.