277 lines
32 KiB
Markdown
277 lines
32 KiB
Markdown
# ModernZ User Options Guide
|
|
|
|
### Configuration File Location
|
|
|
|
Create `modernz.conf` in your mpv script-opts directory:
|
|
|
|
- Linux: `~/.config/mpv/script-opts/`
|
|
- Windows: `%APPDATA%/mpv/script-opts/`
|
|
- macOS: `~/Library/Application Support/mpv/script-opts/`
|
|
|
|
## Available Options
|
|
|
|
### Language and display
|
|
|
|
| Option | Value | Description |
|
|
| -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
| language | en | set language (for available options, see: [Translations](https://github.com/Samillion/ModernZ/blob/main/docs/TRANSLATIONS.md)) |
|
|
| icon_theme | fluent | set icon theme. accepts `fluent` or `material` |
|
|
| font | mpv-osd-symbols | font for the OSC (default: mpv-osd-symbols or the one set in mpv.conf) |
|
|
| idlescreen | yes | show mpv logo when idle |
|
|
| window_top_bar | auto | show OSC window top bar: `"auto"`, `"yes"`, or `"no"` (borderless/fullscreen) |
|
|
| showwindowed | yes | show OSC when windowed |
|
|
| showfullscreen | yes | show OSC when fullscreen |
|
|
| showonpause | yes | show OSC when paused |
|
|
| keeponpause | yes | disable OSC hide timeout when paused |
|
|
| greenandgrumpy | no | disable Santa hat in December |
|
|
|
|
### OSC behaviour and scaling
|
|
|
|
| Option | Value | Description |
|
|
| ----------------------- | ----- | ---------------------------------------------------------------------- |
|
|
| hidetimeout | 2000 | time (in ms) before OSC hides if no mouse movement |
|
|
| seek_resets_hidetimeout | yes | if seeking should reset the hidetimeout |
|
|
| fadeduration | 200 | fade-out duration (in ms), set to `"0"` for no fade |
|
|
| fadein | no | whether to enable fade-in effect |
|
|
| minmousemove | 0 | minimum mouse movement (in pixels) required to show OSC |
|
|
| bottomhover | yes | show OSC only when hovering at the bottom |
|
|
| bottomhover_zone | 130 | height of hover zone for bottomhover (in pixels) |
|
|
| osc_on_seek | no | show OSC when seeking |
|
|
| osc_on_start | no | show OSC on start of every file |
|
|
| mouse_seek_pause | yes | pause video while seeking with mouse move (on button hold) |
|
|
| force_seek_tooltip | no | force show seekbar tooltip on mouse drag, even if not hovering seekbar |
|
|
| vidscale | auto | scale osc with the video. (set to `"no"` to disable) |
|
|
| scalewindowed | 1.0 | osc scale factor when windowed |
|
|
| scalefullscreen | 1.0 | osc scale factor when fullscreen |
|
|
|
|
### Elements display
|
|
|
|
| Option | Value | Description |
|
|
| ----------------------- | ---------------- | -------------------------------------------------------------------------------- |
|
|
| show_title | yes | show title in the OSC (above seekbar) |
|
|
| title | `${media-title}` | title above seekbar format: `"${media-title}"` or `"${filename}"` |
|
|
| title_font_size | 24 | font size of the title text (above seekbar) |
|
|
| chapter_title_font_size | 14 | chapter title font size |
|
|
| show_chapter_title | yes | show chapter title (above seekbar) |
|
|
| chapter_fmt | %s | format for chapter display on seekbar hover (set to `"no"` to disable) |
|
|
| timetotal | yes | show total time instead of remaining time |
|
|
| timems | no | show timecodes with milliseconds |
|
|
| unicodeminus | no | use the Unicode minus sign in remaining time |
|
|
| time_format | dynamic | `"dynamic"` or `"fixed"`. shows MM:SS when possible, fixed always shows HH:MM:SS |
|
|
| time_font_size | 16 | font size of the time display |
|
|
| cache_info | no | show cached time information |
|
|
| cache_info_speed | no | show current cache speed per second |
|
|
| cache_info_font_size | 12 | font size of the time display |
|
|
| tooltip_font_size | 14 | tooltips font size |
|
|
|
|
### Title bar settings
|
|
|
|
| Option | Value | Description |
|
|
| -------------------- | ---------------- | ------------------------------------------------------------------------- |
|
|
| window_title | no | show window title in borderless/fullscreen mode |
|
|
| window_controls | yes | show window controls (close, minimize, maximize) in borderless/fullscreen |
|
|
| windowcontrols_title | `${media-title}` | same as title but for window_top_bar |
|
|
|
|
### Subtitle display settings
|
|
|
|
| Option | Value | Description |
|
|
| --------------------- | ----- | ---------------------------------------------------------------------- |
|
|
| raise_subtitles | yes | raise subtitles above the OSC when shown |
|
|
| raise_subtitle_amount | 125 | amount by which subtitles are raised when the OSC is shown (in pixels) |
|
|
|
|
### Buttons display and functionality
|
|
|
|
| Option | Value | Description |
|
|
| -------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| jump_buttons | yes | show "jump forward/backward 10 seconds" buttons |
|
|
| jump_amount | 10 | change the jump amount in seconds |
|
|
| jump_more_amount | 60 | change the jump amount in seconds when right-clicking jump buttons and shift-clicking chapter skip buttons |
|
|
| jump_icon_number | yes | show different icon for `5`, `10`, or `30` second jumps |
|
|
| jump_mode | relative | seek mode for jump buttons |
|
|
| jump_softrepeat | yes | enable continuous jumping when holding down seek buttons |
|
|
| chapter_skip_buttons | no | show the skip back and forward (chapter) buttons |
|
|
| chapter_softrepeat | yes | enable continuous skipping when holding down chapter skip buttons |
|
|
| track_nextprev_buttons | yes | show next/previous playlist track buttons |
|
|
| volume_control | yes | show mute button and volume slider |
|
|
| volume_control_type | linear | volume scale type: `"linear"` or `"logarithmic"` |
|
|
| playlist_button | yes | show playlist button: Left-click for simple playlist, Right-click for interactive playlist |
|
|
| hide_empty_playlist_button | yes | hide playlist button when no playlist exists |
|
|
| gray_empty_playlist_button | yes | gray out the playlist button when no playlist exists |
|
|
| download_button | yes | show download button on web videos (requires yt-dlp and ffmpeg) |
|
|
| download_path | ~~desktop/mpv | default download directory for videos. [Learn more about setting paths here](https://mpv.io/manual/master/#paths). |
|
|
| screenshot_button | no | show screenshot button |
|
|
| screenshot_flag | subtitles | Flag options for the screenshot button: `"subtitles"`, `"video"`, `"window"`, `"each-frame"`. [Find out more about these options](https://mpv.io/manual/master/#command-interface-screenshot-<flags>). |
|
|
| ontop_button | yes | show `window on top (pin)` button |
|
|
| loop_button | no | show `loop` button |
|
|
| speed_button | no | show speed control button |
|
|
| speed_button_click | 1 | speed change amount per click |
|
|
| speed_button_scroll | 0.25 | speed change amount on scroll |
|
|
| loop_in_pause | yes | enable looping by right-clicking pause |
|
|
| buttons_always_active | none | force buttons to always be active. can add: `playlist_prev`, `playlist_next` |
|
|
| info_button | yes | show `info (stats)` button |
|
|
| fullscreen_button | yes | show `fullscreen toggle` button |
|
|
| playpause_size | 28 | icon size for the play/pause button |
|
|
| midbuttons_size | 24 | icon size for the middle buttons |
|
|
| sidebuttons_size | 24 | icon size for the side buttons |
|
|
| zoom_control | yes | show zoom controls in image viewer mode |
|
|
| zoom_in_max | 4 | icon size for the side buttons |
|
|
| zoom_out_min | -1 | icon size for the side buttons |
|
|
|
|
|
|
### Colors and style
|
|
|
|
| Option | Value | Description |
|
|
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------- |
|
|
| osc_color | `#000000` | accent color of the OSC and title bar |
|
|
| window_title_color | `#FFFFFF` | color of the title in borderless/fullscreen mode |
|
|
| window_controls_color | `#FFFFFF` | color of the window controls (close, minimize, maximize) in borderless/fullscreen mode |
|
|
| windowcontrols_close_hover | `#E81123` | color of close window control on hover |
|
|
| windowcontrols_max_hover | `#F8BC3A` | color of maximize window controls on hover |
|
|
| windowcontrols_min_hover | `#43CB44` | color of minimize window controls on hover |
|
|
| title_color | `#FFFFFF` | color of the title (above seekbar) |
|
|
| seekbarfg_color | `#FB8C00` | color of the seekbar progress and handle |
|
|
| seekbarbg_color | `#94754F` | color of the remaining seekbar |
|
|
| seekbar_cache_color | `#918F8E` | color of the cache ranges on the seekbar |
|
|
| volumebar_match_seek_color | no | match volume bar color with seekbar color (ignores `side_buttons_color`) |
|
|
| time_color | `#FFFFFF` | color of the timestamps (below seekbar) |
|
|
| chapter_title_color | `#FFFFFF` | color of the chapter title (above seekbar) |
|
|
| cache_info_color | `#FFFFFF` | color of the cache information |
|
|
| side_buttons_color | `#FFFFFF` | color of the side buttons (audio, subtitles, playlist, etc.) |
|
|
| middle_buttons_color | `#FFFFFF` | color of the middle buttons (skip, jump, chapter, etc.) |
|
|
| playpause_color | `#FFFFFF` | color of the play/pause button |
|
|
| held_element_color | `#999999` | color of the element when held down (pressed) |
|
|
| hover_effect_color | `#FB8C00` | color of a hovered button when `hover_effect` includes `"color"` |
|
|
| thumbnail_border_color | `#111111` | color of the border for thumbnails (with thumbfast) |
|
|
| thumbnail_border_outline | `#404040` | color of the border outline for thumbnails |
|
|
| fade_alpha | 130 | alpha of the OSC background box (0 to disable) |
|
|
| fade_blur_strength | 100 | blur strength for the OSC alpha fade. caution: high values can take a lot of CPU time to render |
|
|
| fade_transparency_strength | 0 | use with "fade_blur_strength=0" to create a transparency box |
|
|
| window_fade_alpha | 100 | alpha of the window title bar (0 to disable) |
|
|
| window_fade_blur_strength | 100 | blur strength for the window title bar. caution: high values can take a lot of CPU time to render |
|
|
| window_fade_transparency_strength | 0 | use with "window_fade_blur_strength=0" to create a transparency box |
|
|
| thumbnail_border | 3 | width of the thumbnail border (for thumbfast) |
|
|
| thumbnail_border_radius | 3 | rounded corner radius for thumbnail border (0 to disable) |
|
|
|
|
### Button hover effects
|
|
|
|
| Option | Value | Description |
|
|
| ------------------------ | --------------- | ------------------------------------------------------------------------------------------------ |
|
|
| hover_effect | size,glow,color | active button hover effects: `"glow"`, `"size"`, `"color"`; can use multiple separated by commas |
|
|
| hover_button_size | 115 | relative size of a hovered button if "size" effect is active |
|
|
| button_glow_amount | 5 | glow intensity when `"glow"` hover effect is active |
|
|
| hover_effect_for_sliders | yes | apply hover size effect to slider handle |
|
|
|
|
### Tooltips and hints
|
|
|
|
| Option | Value | Description |
|
|
| ------------------------------ | ----- | --------------------------------------------------------------- |
|
|
| tooltips_for_disabled_elements | yes | enable tooltips for disabled buttons and elements |
|
|
| tooltip_hints | yes | enable text hints for info, loop, ontop, and screenshot buttons |
|
|
|
|
### Progress bar settings
|
|
|
|
| Option | Value | Description |
|
|
| ------------------------ | -------- | -------------------------------------------------------------------------- |
|
|
| seek_handle_size | 0.8 | size ratio of the seekbar handle (range: 0 ~ 1) |
|
|
| seekrange | yes | show seek range overlay |
|
|
| seekrangealpha | 150 | transparency of the seek range |
|
|
| livemarkers | yes | update chapter markers on the seekbar when duration changes |
|
|
| seekbarkeyframes | no | use keyframes when dragging the seekbar |
|
|
| nibbles_top | yes | top chapter nibbles above seekbar |
|
|
| nibbles_bottom | yes | bottom chapter nibbles below seekbar |
|
|
| nibbles_style | triangle | chapter nibble style. `triangle`, `bar` or `single-bar` |
|
|
| automatickeyframemode | yes | automatically set keyframes for the seekbar based on video length |
|
|
| automatickeyframelimit | 600 | videos longer than this (in seconds) will have keyframes on the seekbar |
|
|
| persistentprogress | no | always show a small progress line at the bottom of the screen |
|
|
| persistentprogressheight | 17 | height of the persistent progress bar |
|
|
| persistentbuffer | no | show buffer status on web videos in the persistent progress line |
|
|
|
|
### Miscellaneous settings
|
|
|
|
| Option | Value | Description |
|
|
| ----------------------------- | ----------------- | ------------------------------------------------------------- |
|
|
| visibility | auto | only used at init to set visibility_mode(...) |
|
|
| visibility_modes | never_auto_always | visibility modes to cycle through, modes are separated by `_` |
|
|
| tick_delay | 0.03 | minimum interval between OSC redraws (in seconds) |
|
|
| tick_delay_follow_display_fps | no | use display FPS as the minimum redraw interval |
|
|
|
|
### Elements Position
|
|
|
|
Useful when adjusting font size or type, this will help you change the affected elements position
|
|
|
|
| Option | Value | Description |
|
|
| ----------------------------- | ------ | ---------------------------------------------------------------------- |
|
|
| title_height | 96 | title height position above seekbar |
|
|
| title_with_chapter_height | 108 | title height position if a chapter title is below it |
|
|
| chapter_title_height | 91 | chapter title height position above seekbar |
|
|
| time_codes_height | 35 | time codes height position |
|
|
| time_codes_centered_height | 57 | time codes height position with portrait window |
|
|
| tooltip_height_offset | 2 | tooltip height position offset |
|
|
| tooltip_left_offset | 5 | if tooltip contains many characters, it is moved to the left by offset |
|
|
| portrait_window_trigger | 1000 | portrait window width trigger to move some elements |
|
|
| hide_volume_bar_trigger | 1150 | hide volume bar trigger window width |
|
|
| notitle_osc_h_offset | 25 | osc height offset if title above seekbar is disabled |
|
|
| nochapter_osc_h_offset | 10 | osc height offset if chapter title is disabled or doesn't exist |
|
|
| seek_hover_tooltip_h_offset | 0 | seek hover timecodes tooltip height position offset |
|
|
| osc_height | 132 | osc height without offsets |
|
|
|
|
### Mouse Commands (User Options)
|
|
|
|
Customize the button function based on mouse actions.
|
|
|
|
| Type | Option | Function |
|
|
| ----------------------------- | -------------------------------- | ------------------------------------------------------------------------------- |
|
|
| Title (above seekbar) | title_mbtn_left_command | `script-binding stats/display-page-5` |
|
|
| | title_mbtn_mid_command | `show-text ${path}` |
|
|
| | title_mbtn_right_command | `script-binding select/select-watch-history; script-message-to modernz osc-hide`|
|
|
| Playlist Button | playlist_mbtn_left_command | `script-binding select/select-playlist; script-message-to modernz osc-hide` |
|
|
| | playlist_mbtn_right_command | `show-text ${playlist} 3000` |
|
|
| Volume Control | vol_ctrl_mbtn_left_command | `no-osd cycle mute` |
|
|
| | vol_ctrl_mbtn_right_command | `script-binding select/select-audio-device; script-message-to modernz osc-hide` |
|
|
| | vol_ctrl_wheel_down_command | `no-osd add volume -5` |
|
|
| | vol_ctrl_wheel_up_command | `no-osd add volume 5` |
|
|
| Audio Button | audio_track_mbtn_left_command | `script-binding select/select-aid; script-message-to modernz osc-hide` |
|
|
| | audio_track_mbtn_mid_command | `cycle audio down` |
|
|
| | audio_track_mbtn_right_command | `cycle audio` |
|
|
| | audio_track_wheel_down_command | `cycle audio` |
|
|
| | audio_track_wheel_up_command | `cycle audio down` |
|
|
| Subtitle Button | sub_track_mbtn_left_command | `script-binding select/select-sid; script-message-to modernz osc-hide` |
|
|
| | sub_track_mbtn_mid_command | `cycle sub down` |
|
|
| | sub_track_mbtn_right_command | `cycle sub` |
|
|
| | sub_track_wheel_down_command | `cycle sub` |
|
|
| | sub_track_wheel_up_command | `cycle sub down` |
|
|
| Chapter Skip Buttons | chapter_prev_mbtn_left_command | `add chapter -1` |
|
|
| | chapter_prev_mbtn_mid_command | `show-text ${chapter-list} 3000` |
|
|
| | chapter_prev_mbtn_right_command | `script-binding select/select-chapter; script-message-to modernz osc-hide` |
|
|
| | chapter_next_mbtn_left_command | `add chapter 1` |
|
|
| | chapter_next_mbtn_mid_command | `show-text ${chapter-list} 3000` |
|
|
| | chapter_next_mbtn_right_command | `script-binding select/select-chapter; script-message-to modernz osc-hide` |
|
|
| Chapter Title (below seekbar) | chapter_title_mbtn_left_command | `script-binding select/select-chapter; script-message-to modernz osc-hide` |
|
|
| | chapter_title_mbtn_right_command | `show-text ${chapter-list} 3000` |
|
|
| Playlist Skip Buttons | playlist_prev_mbtn_left_command | `playlist-prev` |
|
|
| | playlist_prev_mbtn_mid_command | `show-text ${playlist} 3000` |
|
|
| | playlist_prev_mbtn_right_command | `script-binding select/select-playlist; script-message-to modernz osc-hide` |
|
|
| | playlist_next_mbtn_left_command | `playlist-next` |
|
|
| | playlist_next_mbtn_mid_command | `show-text ${playlist} 3000` |
|
|
| | playlist_next_mbtn_right_command | `script-binding select/select-playlist; script-message-to modernz osc-hide` |
|
|
| Fullscreen Button | fullscreen_mbtn_left_command | `cycle fullscreen` |
|
|
| | fullscreen_mbtn_right_command | `cycle window-maximized` |
|
|
| Info Button | info_mbtn_left_command | `script-binding stats/display-page-1-toggle` |
|
|
|
|
### Auto Profile
|
|
|
|
Below is an example of an auto-profile in `mpv.conf` you can use to set any of ModernZ options based on certain conditions, in this case `when window is pinned or fullscreen`.
|
|
|
|
```ini
|
|
[ModernZ-Custom]
|
|
profile-desc=Apply ModernZ options on pin or fullscreen
|
|
profile-cond=ontop and ontop == true or fullscreen
|
|
profile-restore=copy-equal
|
|
script-opts-append=modernz-persistentprogress=yes
|
|
script-opts-append=modernz-seekbarfg_color=#FF0000
|
|
script-opts-append=modernz-bottomhover=no
|
|
#...etc
|
|
```
|
|
|
|
More information about auto profiles available on [mpv's manual](https://mpv.io/manual/master/#conditional-auto-profiles).
|