mpv-webm turns an mpv clip into a WebM file from inside the player
Simple WebM maker for mpv, with no external dependencies.
At a glance
- What is it?
- mpv-webm is an mpv script that encodes and uploads a clip of what you are playing, with no external dependencies beyond mpv itself and curl for uploads. It suits people who want to share a moment from a video quickly, and its two real constraints are that encoding spawns a second mpv process and that the encoder has to be on the PATH the player inherits.
- Who is it for?
- Adopt mpv-webm if you want to turn a moment of playback into a shareable clip from inside mpv, since the script drives the encoder through a second mpv process and handles the WebM muxing itself. Do not adopt it if you need a general purpose converter, since the project targets mpv playback specifically, and do not expect it to work in a desktop launcher that does not inherit your PATH, because the encoder executable has to be visible to the player.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 19 days ago.
- What is it written in?
- Mainly MoonScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 23, 2026, and from our analysis. They are not legal advice.
Editorial analysis
A script folder drop-in rather than a package
mpv-webm is a script for the mpv media player, and installation is a file placement rather than a package manager operation. The README links to a build artifact and tells you to place it in your mpv scripts folder, which can be created if it does not exist.
On Linux and macOS the path is `~/.config/mpv/scripts`, where ~ is your home folder. On Windows, mpv tries to load scripts from `%APPDATA%\mpv\scripts`, then from `<mpv binary folder>\portable_config\scripts` and `<mpv binary folder>\mpv\scripts`, where the binary folder is the one containing mpv.exe.
The project describes itself as a simple WebM maker for mpv with no external dependencies, and the scripts folder arrangement is the reason for that claim: there is nothing to install, no plugin manager, and no configuration to bootstrap. The only release asset in the README is a webm.lua file plus a sample webm.conf, both linked from the releases download URL, and the repository has a single rolling release named latest, tagged as a Development Build, dated 2026-10-04.
The manual page for mpv file locations is cited for the folder structure, which is a good sign that the script is placed where mpv itself expects to find user scripts.
Encoding starts a second mpv process
The mechanism is worth understanding, because it explains both the smoothness of the integration and the main installation trap. Encoding does not happen inside the player you are watching. The script starts a separate mpv process to do the work.
That means the mpv executable must be available on the PATH inherited by the player, and the README is emphatic that this includes the case where the player is opened from a desktop shortcut or a file manager, where the environment is often much thinner than a login shell.
For Linux and macOS the check is `command -v mpv`, and if encoding reports `mpv: command not found` when launched from the desktop, the fix is to make sure that launch environment also includes the executable's directory. The README names the Homebrew locations, `/opt/homebrew/bin` on Apple Silicon and `/usr/local/bin` on Intel Macs, and points Windows users at a separate encoder setup guide in docs/windows-encoder-setup.md that covers adding mpv to Path, verifying it and troubleshooting desktop launches.
There is a second, subtler failure mode. If encoding reports a missing codec rather than a missing executable, the fix is to check `mpv --ovc=help` for video encoders or `mpv --oac=help` for audio encoders. Those lists come from the FFmpeg libraries used by mpv, so installing a separate ffmpeg executable does not necessarily add codecs to mpv. On macOS, the Homebrew formula is named as one source of an encoder-enabled build.
The W key opens the maker, and the clip follows the playback options
By default the script is activated by the W key, which is shift+w, and from there you follow the on-screen instructions.
The output reflects what the player is currently doing. Encoded WebM files carry audio and subtitles based on the current playback options, so the file is muted if there is no audio, and it does not have hardcoded subtitles if subtitles are not visible at the time. That is a sensible default for a clip tool: what you get is what you saw, rather than a separate encode decision made afterwards.
The source tree shows how much of the script is a UI rather than a codec. The Makefile lists separate modules for MainPage, PreviewPage, CropPage, EncodeOptionsPage, EncodeWithProgress and UploadWithProgress, plus a Page base class and a CropPage that exists to let you trim the clip before encoding. The formats directory holds separate modules for webm, avc, av1, hevc, mp3, gif, webp and rawvideo, so the container and codec handling is pluggable rather than hard coded into one path.
There is also a vp8_twopass_log_patcher module, which suggests the encoder is driven in two passes and the log is patched afterwards, presumably so the progress display can show something meaningful about the second pass.
Uploading to Catbox, and why the u key disappears without curl
The script can upload as well as encode. Pressing u on the WebM maker page encodes a clip and uploads it in one step, and the destination is configured through the options and stored in `webm.conf`.
The options are specific. `upload_host` selects catbox, which is permanent, or litterbox, which is temporary. `litterbox_time` sets the expiry for litterbox uploads, with the values 1h, 12h, 24h or 72h. `catbox_userhash` is an optional Catbox account hash, and account uploads are permanent and manageable. `upload_curl_path` names the curl executable used for the multipart upload, and `open_after_upload` opens the link in the browser as soon as it is ready.
Uploads use curl, and the behaviour when curl is missing is a small design decision worth noticing: the u line is hidden entirely rather than shown and then failing. The resulting URL is copied to the clipboard, using mpv's own clipboard/text facility where it is available and otherwise falling back to wl-copy, xclip or pbcopy, which is a sensible chain for the three main desktop environments.
Only the Catbox services are supported. The README explains that Streamable requires an account for uploads, so it is not offered, which leaves a pair of anonymous file hosts and no account-backed option other than Catbox itself.
Configuring options in the script or in webm.conf
There are two ways to change the defaults, and the README is clear that they are equivalent. You can edit the `options` at the beginning of the script, or you can place a `webm.conf` file inside the mpv script-opts directory. A sample webm.conf with the default options is linked from the releases, and the key detail is that you do not need to specify every option, only the ones you want to override.
That partial override model is what makes the script practical to keep as a downloaded file. You drop in the webm.lua from the release, drop in a small webm.conf with two or three lines, and your own settings survive a later update of the script itself.
The build system is the other side of the same coin. The Makefile is written for MoonScript, the language the project is written in, and it needs moonc, the MoonScript compiler, on the PATH plus a GNUMake compatible make. Running make at the root produces the output files under a build directory. The default target builds two artifacts, a joined Lua file named webm.lua and a webm.conf generated from the options source.
The Makefile shows how the pieces are assembled. A handful of Lua sources are listed separately in the LUASOURCES variable, namely src/requires.lua, src/options.lua and src/base64.lua, and those are concatenated with the compiled MoonScript modules to produce the final script. The config file is generated separately by running lua against build-webm-conf.lua. So the shipped webm.lua is a bundle, not a single source file, which is worth knowing if you ever need to debug it.
A single rolling release and a MIT licence
The release model is unusual and simple. There is one release, named latest, labelled as a Development Build, published on 2026-10-04, and the README links the download URLs through a releases/download/latest path. So the project publishes a continuously updated build rather than a versioned series of tags.
The last push to the master branch was on 2026-10-04 as well, so the tree and the published artifact are in step. In practice this means you take whatever is current, and there is no older version to fall back to if a change breaks your setup, which is a trade worth making explicitly rather than by accident.
The licence is MIT, in a LICENSE file at the root, so the script can be used, modified and redistributed with attribution and no copyleft obligation on code that merely uses it.
The repository layout backs up the script-centric design. There is src/ with the MoonScript sources, tests/, docs/ with the Windows encoder setup guide, a build-webm-conf.lua helper at the root, the Makefile, and img/ for the sample screenshot. There is no dependency manifest, no lock file and no CI configuration directory beyond .github/, which is consistent with a project whose entire dependency surface is mpv, moonc for building, make, and curl for uploads.
Editorial conclusion
Adopt mpv-webm if you want to turn a moment of playback into a shareable clip from inside mpv, since the script drives the encoder through a second mpv process and handles the WebM muxing itself. Do not adopt it if you need a general purpose converter, since the project targets mpv playback specifically, and do not expect it to work in a desktop launcher that does not inherit your PATH, because the encoder executable has to be visible to the player. Before you install, check that mpv is on the PATH the player inherits, confirm your mpv build lists the encoders you want with mpv --ovc=help and mpv --oac=help, and note that only Catbox uploads are supported, with the u key hidden entirely when curl is missing.
Frequently asked questions
How do I install mpv-webm?
Download the webm.lua build from the project's latest release and place it in your mpv scripts folder. On Linux and macOS that is ~/.config/mpv/scripts, and on Windows mpv loads scripts from %APPDATA%\mpv\scripts, then from portable_config\scripts and mpv\scripts next to the mpv.exe binary.
Why does mpv-webm report mpv: command not found?
Encoding starts a separate mpv process, so the executable must be on the PATH the player inherits, including when the player is launched from a desktop shortcut or file manager. Run command -v mpv in a shell to check, and make sure the launch environment also includes the executable's directory.
How do I check which encoders my mpv build supports?
Run mpv --ovc=help for video encoders and mpv --oac=help for audio encoders. Those lists come from the FFmpeg libraries used by mpv, so installing a separate ffmpeg executable does not necessarily add codecs to mpv.
Which upload hosts does mpv-webm support?
Only the Catbox services. The upload_host option selects catbox for permanent uploads or litterbox for temporary ones, with litterbox_time accepting 1h, 12h, 24h or 72h, and catbox_userhash optionally attaching a Catbox account hash. Streamable is not offered because it requires an account for uploads.
How do I change the default options in mpv-webm?
Either edit the options at the beginning of the script, or place a webm.conf file in the mpv script-opts directory, and you only need to specify the options you want to override. A sample webm.conf with the defaults is published with the release.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/ekisu-mpv-webm)Was this useful?