217 lines
11 KiB
Markdown
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.
|