Giovanni Harting
613d28db90
- Add installation section with copy commands - Document each script with features, requirements, config examples - Add practical configuration examples for common use cases - Update CLAUDE.md with shared library documentation
227 lines
6.4 KiB
Markdown
227 lines
6.4 KiB
Markdown
# mpv-scripts
|
|
|
|
Personal collection of Lua scripts for mpv (0.36+).
|
|
|
|
## Installation
|
|
|
|
Copy desired scripts from `scripts/` into `~/.config/mpv/scripts/`. Also copy `scripts/lib/` for the shared utilities required by all scripts.
|
|
|
|
```bash
|
|
cp scripts/lib ~/.config/mpv/scripts/ -r
|
|
cp scripts/ac-power.lua ~/.config/mpv/scripts/
|
|
```
|
|
|
|
Configuration is done by editing the `config` table at the top of each script.
|
|
|
|
---
|
|
|
|
## ac-power.lua
|
|
|
|
Displays Home Assistant AC power sensor readings with a color-coded gauge, delta indicator, and persistent min/max tracking.
|
|
|
|
**Display format:** `[████░░░░] 450W +50`
|
|
|
|
**Features:**
|
|
- Polls Home Assistant API for power sensor data
|
|
- Visual gauge colored by power level (green → yellow → red)
|
|
- Delta indicator showing power change (+/-) colored by trend
|
|
- Persistent min/max tracking across sessions (stored in `~/.cache/mpv/`)
|
|
- Debounces updates to avoid OSD spam
|
|
- Exponential backoff on network failures
|
|
|
|
**Requirements:**
|
|
- Home Assistant instance with a power sensor
|
|
- Long-lived access token from HA
|
|
- `curl` in PATH
|
|
|
|
**Configuration:**
|
|
|
|
```lua
|
|
local config = {
|
|
-- Home Assistant connection (required)
|
|
sensor_id = "sensor.ac_power",
|
|
ha_base_url = "http://homeassistant.local:8123",
|
|
ha_token = "YOUR_LONG_LIVED_TOKEN",
|
|
|
|
-- Polling behavior
|
|
poll_interval = 3, -- seconds between polls
|
|
min_delta_watts = 5, -- minimum change to trigger display
|
|
force_refresh_interval = 30, -- force display even if delta small
|
|
|
|
-- Gauge
|
|
show_gauge = true,
|
|
gauge_width = 8, -- number of bar segments
|
|
gauge_max_watts = 1000, -- scale reference (or uses tracked max)
|
|
|
|
-- Delta indicator
|
|
show_delta = true,
|
|
delta_stable_range = 5, -- watts within which shows as stable (white)
|
|
|
|
-- Min/Max tracking
|
|
track_minmax = true,
|
|
show_minmax = false, -- show [min-max] inline
|
|
persist_minmax = true, -- save to disk across sessions
|
|
|
|
-- Color thresholds (watts)
|
|
color_low_threshold = 200, -- below = green
|
|
color_mid_threshold = 500, -- below = yellow
|
|
color_high_threshold = 800, -- above = red
|
|
}
|
|
```
|
|
|
|
**Script messages:**
|
|
- `script-message ac-power-refresh` — force immediate poll
|
|
- `script-message ac-power-reset-minmax` — clear min/max history
|
|
|
|
---
|
|
|
|
## kb-blackout.lua
|
|
|
|
Dims or disables the keyboard backlight while mpv is playing, restoring it on pause or when mpv loses focus.
|
|
|
|
**Features:**
|
|
- Captures starting brightness and restores exact value
|
|
- Auto-discovers keyboard LED device via `brightnessctl --list`
|
|
- Debounces rapid state changes
|
|
- Optional restore on window unfocus
|
|
|
|
**Requirements:**
|
|
- Linux
|
|
- `brightnessctl` with permission to control LED device
|
|
|
|
**Configuration:**
|
|
|
|
```lua
|
|
local config = {
|
|
timeout_ms = 3000, -- delay before dimming after playback starts
|
|
minimum_brightness = 0, -- target brightness (0 = off)
|
|
restore_on_pause = true, -- restore when paused
|
|
restore_on_unfocus = true, -- restore when mpv loses window focus
|
|
debounce_ms = 250, -- ignore rapid state flips
|
|
led_path = "", -- auto-detect, or set explicitly e.g. "asus::kbd_backlight"
|
|
brightnessctl_path = "brightnessctl",
|
|
}
|
|
```
|
|
|
|
**Example — keep minimal glow instead of full off:**
|
|
|
|
```lua
|
|
minimum_brightness = 10, -- 10% brightness while playing
|
|
```
|
|
|
|
---
|
|
|
|
## playback-health.lua
|
|
|
|
Monitors playback health and shows OSD warnings only when problems occur (buffering, frame drops, low cache).
|
|
|
|
**Features:**
|
|
- Silent during normal playback
|
|
- Detects network streams automatically (cache warnings only for streams)
|
|
- Frame drop monitoring for all sources
|
|
- Buffer prediction (estimates time to stall/resume)
|
|
- Bandwidth monitoring (warns when download can't keep up)
|
|
- Color-coded warnings with cooldown to prevent spam
|
|
|
|
**Configuration:**
|
|
|
|
```lua
|
|
local config = {
|
|
-- Thresholds
|
|
cache_warning_seconds = 5, -- warn when cache falls below (streams)
|
|
cache_critical_seconds = 2, -- critical threshold (red)
|
|
drop_rate_threshold = 1.0, -- drops per second to trigger warning
|
|
drop_window_seconds = 5, -- time window for measuring drops
|
|
|
|
-- Display
|
|
osd_duration = 3,
|
|
show_buffering_percent = true,
|
|
show_buffer_prediction = true, -- "stall in 5s" / "resume in 3s"
|
|
show_recovery = true, -- "✓ Recovered" message
|
|
cooldown_seconds = 10, -- minimum time between same warning type
|
|
|
|
-- What to monitor
|
|
monitor_cache = true,
|
|
monitor_drops = true,
|
|
monitor_bandwidth = true,
|
|
bandwidth_ratio_warn = 0.9, -- warn when download/playback < 90%
|
|
}
|
|
```
|
|
|
|
**Example — more sensitive drop detection:**
|
|
|
|
```lua
|
|
drop_rate_threshold = 0.5, -- warn at 0.5 drops/sec instead of 1.0
|
|
drop_window_seconds = 3, -- shorter measurement window
|
|
```
|
|
|
|
---
|
|
|
|
## touch-gestures.lua
|
|
|
|
Tablet-friendly swipe controls: horizontal swipes seek, vertical edge swipes adjust volume (right) or brightness (left).
|
|
|
|
**Features:**
|
|
- Horizontal swipes anywhere: seek forward/backward
|
|
- Right edge vertical swipes: system volume (PipeWire/PulseAudio)
|
|
- Left edge vertical swipes: screen brightness (brightnessctl)
|
|
- Axis locking prevents accidental cross-axis actions
|
|
- Fine-grained steps at low values
|
|
- OSD feedback after each adjustment
|
|
|
|
**Requirements:**
|
|
- mpv 0.39+ recommended
|
|
- On Wayland: run mpv with `--native-touch=yes`
|
|
- `brightnessctl` for brightness control
|
|
- `wpctl` (PipeWire) or `pactl` (PulseAudio) for volume
|
|
|
|
**Configuration:**
|
|
|
|
```lua
|
|
local config = {
|
|
-- Sensitivity
|
|
steps_per_screen = 40, -- steps across full screen height
|
|
deadzone_px = 4, -- ignore tiny movements
|
|
|
|
-- Step sizes
|
|
volume_step = 5, -- percent per step
|
|
volume_step_fine = 1, -- step when below fine_threshold
|
|
brightness_step = 5,
|
|
brightness_step_fine = 1,
|
|
fine_threshold = 10, -- use fine steps below this %
|
|
seek_step = 5, -- seconds per horizontal step
|
|
|
|
-- Limits
|
|
max_volume = 130,
|
|
min_brightness = 1, -- prevent turning off screen
|
|
|
|
-- Zones (fraction of screen width)
|
|
left_zone_ratio = 0.35, -- brightness zone
|
|
right_zone_ratio = 0.35, -- volume zone
|
|
bottom_exclude_ratio = 0.15, -- ignore bottom (OSC area)
|
|
|
|
-- Direction
|
|
invert_vertical = false,
|
|
invert_horizontal = false,
|
|
}
|
|
```
|
|
|
|
**Example — larger edge zones for easier targeting:**
|
|
|
|
```lua
|
|
left_zone_ratio = 0.4,
|
|
right_zone_ratio = 0.4,
|
|
```
|
|
|
|
**Example — add to mpv.conf for Wayland touch support:**
|
|
|
|
```
|
|
native-touch=yes
|
|
```
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
These scripts are provided as-is for personal use.
|