Mediawarrior is a time-tracking plugin for mpv. It talks to Timewarrior to help you track what you watch or listen to in mpv player. Language learners will appreciate Mediawarrior's ability to automatically add a language tag to a Timewarrior entry and an increased awareness of how much time you spend consuming content in your target language.
Video tutorials:
| Mediawarrior v0.1.0 |
Related: watchtower (useful Timewarrior-related scripts) |
|
|
| 0.1.2 | 2025-12-18 |
Fixed a timezone conversion issue: was setting a wrong date/time when using |
Required dependencies must be installed in order for Mediawarrior to work.
| Name | Installation | Notes |
|---|---|---|
| Timewarrior | sudo apt install timewarrior |
Homepage: https://timewarrior.net/ |
# Install:
cd ~/.config/mpv/scripts
git clone https://github.com/linguisticmind/mediaw.git
# Upgrade:
cd ~/.config/mpv/scripts/mediaw
git pullOptions can be set either on the command line, or in a configuration file.
In both cases, this script's identifier – mediaw – will be needed.
Use --script-opts=<identifier>-<option>=<value>,... to set options on the command line.
To set options in a configuration file, create the following file: ~/.config/mpv/script-opts/<identifier>.conf. Set options in the file, one per line, in the following fashion: <option>=<value>.
More information on mpv's script-opts command line and configuration file syntax can be found here (based on the example of the built-in osc.lua script).
The table below lists the options that are available for this script.
NOTE: The default values are shown as they appear in the script's source code written in Lua. In mpv, when passing script options on the command line, or setting them in a configuration file, the words yes and no are used for Lua's true and false, and string values are not quoted.
| Option | Default value | Description |
|---|---|---|
tag
|
'mediaw'
|
Main Timewarrior tag. |
language_tag
|
true
|
Whether to add a language tag. |
language_props_check
|
'current-tracks/sub/lang,slang,current-tracks/audio/lang,alang'
|
A comma-separated list of
Properties are checked in the specified order. The first non- |
language
|
''
|
Set the language used for the language tag manually.
If set to a non-empty string, overrides
Must be a valid two- or three-letter ISO 639 language code. The language tag will then be formatted according to the value of |
language_tag_format
|
'alpha_2'
|
Format of the language tag. Possible values:
|
osd
|
true
|
Whether to show on-screen messages. |
debug
|
false
|
Show debug messages in the console. |
dry_run
|
false
|
Suppress execution of shell commands. |
Keybindings can be remapped in ~/.config/mpv/input.conf. Add a line in the following format to remap a keybinding: <key> script-binding <name>.
If you remap a keybinding, you will likely want to disable the default keybinding by adding <default key> ignore to ~/.config/mpv/input.conf. See the video tutorial linked to above for a demonstration and for information on how to see what a given key is currently mapped to in mpv.
The following keybindings are available for this script:
| Key | Name | Description |
|---|---|---|
Ctrl+t |
mediaw-start |
Start tracking. |
Ctrl+Alt+t |
mediaw-start-retro |
Start tracking and retroactively correct the start time to the time when the file was open. |
Ctrl+T |
mediaw-stop |
Stop tracking. |
Ctrl+Alt+T |
mediaw-cancel |
Stop tracking and delete the entry. |
Ctrl+SPACE |
mediaw-pause |
Pause playback and tracking. Tracking will resume when the player is unpaused. |
Ctrl+Alt-SPACE |
mediaw-pause-on-next |
Pause playback and tracking when the next file in the playlist is reached. |
