Configuration

Configuration files, settings locations, and format reference

CineWindows stores configuration in multiple locations depending on the installation type and the data being persisted.

QSettings JSON key bindings mpv.conf

Settings Location

./portable/
  └── settings.ini          # QSettings (INI format, all preferences)

When run from a portable ZIP, CineWindows creates a portable/ directory next to the executable and stores all settings in portable/settings.ini.

%APPDATA%\gyrolet\
  └── CineWindows\
        ├── settings.ini    # QSettings (INI format, all preferences)
        ├── session.json    # Session state (playlist + position)
        └── library.db      # Media library SQLite database

For installed versions, the config root is %APPDATA%/gyrolet/CineWindows/.

%APPDATA%\CineWindows\mpv\
  ├── mpv.conf              # Runtime mpv options (loaded via "include")
  ├── input.conf            # Additional key bindings in an app-owned input section
  ├── scripts\              # Lua/JS scripts and script packages
  ├── script-opts\          # Per-script .conf files
  ├── shaders\              # GLSL shaders
  ├── fonts\                # Subtitle and OSD fonts
  └── watch_later\          # Saved playback positions

CineWindows uses its own mpv folder, separate from application preferences and the standalone player’s %APPDATA%\mpv folder. An existing portable_config directory beside the executable takes precedence. Otherwise, setting CINEWINDOWS_DATA_DIR places the mpv folder under that directory. On other platforms the default is ~/.config/CineWindows/mpv.

Preferences provides commands to open this folder, edit either configuration file, reload configuration, and explicitly import standalone mpv files. Import leaves the source untouched and keeps existing destination files, except unmodified templates. CineWindows never automatically reads standalone mpv configuration.

Settings Reference

All application preferences are backed by QSettings and exposed through the SettingsManager QML singleton. Changes are persisted immediately.

General

Key	Type	Default	Description
`ui/openNewWindow`	bool	`true`	Open media in a new window
`ui/thumbnailPreview`	bool	`true`	Seek-bar thumbnail previews
`ui/showRemaining`	bool	`false`	Show remaining time
`ui/themeMode`	string	`"dark"`	`"dark"` or `"light"`
`ui/accentColor`	string	`"#10c7d1"`	Accent colour hex ARGB
`ui/reduceMotion`	bool	`false`	Reduce non-essential motion
`ui/locale`	string	(system)	UI language code
`input/leftClick`	int	`0`	Left-click action ID
`input/rightClick`	int	`1`	Right-click action ID

Playback

Key	Type	Default	Description
`playback/volume`	int	`100`	Volume (0–200)
`playback/muted`	bool	`false`	Mute state
`playback/hwdec`	string	`"auto-safe"`	Hardware decoding backend
`playback/normalizeVolume`	bool	`false`	Volume normalisation
`playback/savePosition`	bool	`false`	Save video position
`playback/saveSession`	bool	`false`	Save/restore session
`playback/equalizerEnabled`	bool	`false`	Equalizer toggle
`playback/visualization`	string	`"off"`	Audio visualisation mode
`playback/stereoInput`	string	`"off"`	Stereo upmix input
`playback/stereoOutput`	string	`"arcd"`	Stereo downmix layout
`playback/toneMapping`	string	`"auto"`	HDR tone mapping
`playback/targetPeak`	int	`203`	HDR peak brightness

Audio

Key	Type	Default	Description
`playback/audioLanguages`	string	(empty)	Preferred audio languages

Subtitles

Key	Type	Default	Description
`subtitles/font`	string	`"Adwaita Sans SemiBold"`	Subtitle font family
`subtitles/scale`	double	`1.0`	Subtitle scale (0.1–3.0)
`subtitles/color`	string	`"#ebebeb"`	Subtitle text colour
`subtitles/background`	bool	`false`	Subtitle background
`subtitles/backgroundColor`	string	`"#97000000"`	Subtitle background colour
`subtitles/languages`	string	(empty)	Preferred subtitle languages

Advanced

Key	Type	Default	Description
`updates/autoCheck`	bool	`true`	Auto-update check
`input/keyBindings`	string	(defaults)	Serialised key bindings JSON

Key Bindings Format

Key bindings are serialised as a JSON string stored in the input/keyBindings setting. The format is an object mapping normalized key sequence strings to action identifiers:

mpv.conf Support

CineWindows loads mpv.conf from its dedicated mpv folder after applying application preferences, so configured mpv options take precedence at startup. Since libmpv defaults to config=no and MpvQt initialises mpv immediately, configuration is applied at runtime using mpv’s include option.

Supported features include profiles, conditional profiles, nested include= files, ~~/ paths, hardware decoding options, shaders, script options, and BOM-marked UTF-8/UTF-16 configuration files. Nested includes are limited to eight levels. Relative include paths resolve against the CineWindows mpv folder.

Only runtime-settable options can apply. CineWindows owns the video output, graphics context, and native window, so options such as vo, gpu-api, gpu-context, fullscreen, geometry, border, and ontop are ignored in configuration files. Preferences lists ignored options. No embedded player can support every standalone mpv option or script unchanged.

Lua/JavaScript files and script packages containing main.lua or main.js are loaded from scripts. Per-script configuration comes from script-opts/<script-name>.conf; explicit script-opts values in mpv.conf take priority. Reload adds new scripts without loading existing scripts twice. Restart after changing or removing a running script, or when an option requires reinitialisation. Removed ordinary option assignments are not automatically reset to their defaults by Reload.

input.conf Support

CineWindows reads input.conf from its own mpv folder, or the path selected by input-conf= in mpv.conf, and registers default-section bindings in a dedicated mpv input section. Bindings take priority over application shortcuts while the player has keyboard focus; text fields retain normal editing behavior. Reload replaces the section so commands removed from the file no longer execute. Non-default named input sections and multi-key sequences are not handled by the application shortcut override lookup.

Wheel and mouse back/forward bindings are forwarded when configured. Left/right click actions remain application preferences. Commands that change mpv’s fullscreen state are mirrored to the native window, and mpv’s quit command closes CineWindows.

The MpvConfig class exposes isOverridden(qtSequence) and commandFor(qtSequence) to QML so the Shortcuts settings panel can display collision warnings when a key is also bound in input.conf.

Session Persistence

Session state (playlist items, current index, playback position) is saved to session.json in the config directory when the user selects Save Session and Close (Shift+Q). If saveSession is enabled, the session is restored automatically on the next launch.