uosc_danmaku: DanDanPlay comments inside the mpv player

A Lua script that turns mpv into a danmaku player

uosc_danmaku loads DanDanPlay danmaku in the MPV player, and it is an mpv script, which means it is a set of Lua files dropped into the player's scripts directory rather than a separate application. It is built on the uosc UI framework and the DanDanPlay API.

The danmaku themselves are the comment tracks that Chinese and Japanese video sites carry, scrolling across the picture as a form of live commentary. The plugin's job is to fetch the comment track for whatever you are playing and draw it over the video, so you get the collective reaction rather than the video alone.

The feature list in the README is long enough to be worth skimming, because it shows the range. It fetches series and danmaku data from DanDanPlay or from a custom service and loads the danmaku for the episode the user picks. It adds a danmaku search button and a danmaku on/off switch to the uosc control bar, a control that can add danmaku from a supported network source or a local file, a style menu that can be changed while the video plays, and a multi-level settings menu that gathers the graphical functions together. It can set a delay independently per danmaku source, remember the danmaku on/off state between sessions, define a custom default style, merge large numbers of duplicate comments that appear at the same moment, convert between simplified and traditional Chinese characters, and move the position of the plugin's own messages away from the top left corner of the picture.

The plugin supports Linux and Windows, and it depends on the uosc UI framework, with the README saying the project strongly recommends installing uosc in mpv.

The licence is MIT.

The project proxy is what removes the account requirement

The second note in the README is the one that decides whether the plugin is usable out of the box. The plugin accesses the DanDanPlay open danmaku network through an API proxy maintained by the project, at `https://danmaku-api.152468.xyz`. Ordinary users do not need to register an account, and do not need to configure or hold a DanDanPlay AppId or AppSecret.

That is a meaningful simplification, because the alternative is that every user has to obtain application credentials from the upstream service before anything works. The proxy also carries caching and access rate limits, and the README asks that it not be used for bulk scraping.

The trade is that a third-party service now sits between the plugin and the upstream API. The proxy is run by the project author, not by DanDanPlay, and a user who needs a large volume of queries, or who objects to the traffic passing through that host, has to configure the plugin against a custom service instead. The feature list refers to fetching from DanDanPlay or from a custom service, and there is a separate API layer in the source tree with `dandanplay.lua` and `extra.lua` modules, so a custom endpoint is a supported path rather than a hack.

The caching matters for a different reason. Danmaku for a popular series are requested by every viewer of that episode, and a cache at the proxy turns most of those into a lookup instead of an upstream request.

uosc is where most of the interface lives

The plugin's interface is the uosc control bar, and the README is blunt about the consequence: if you do not add the controls, the danmaku search button and the danmaku switch will not appear in the control strip above the progress bar, and you can only reach the search and toggle functions through key bindings.

Adding them means editing the `uosc.conf` file in the `script-opts` folder of the mpv configuration directory. The default uosc controls line looks like this:

controls=menu,gap,subtitles,<has_many_audio>audio,<has_many_video>video,<has_many_edition>editions,<stream>stream-quality,gap,space,speed,space,shuffle,loop-playlist,loop-file,gap,prev,items,next,gap,fullscreen

You then insert a search button and a toggle control into that list, and the position in the string is the position in the control bar. The README notes the author places them after the stream quality control.

The version of uosc matters, and the documentation handles it explicitly. Recent uosc releases updated part of the interface and control code, so older and newer uosc are configured differently, and the README provides two separate procedures, one for the latest uosc and one for older versions that works with both. Users of bundles such as MPV_lazy, which ship uosc themselves, are pointed at the compatibility procedure because the bundle's uosc version may not be the newest.

There is a fallback for people who do not run uosc at all. The plugin supports mpv's internal `mp.input` for menu rendering, and the minimum mpv version for that support is 0.39.0. The style menu and the per-source delay menu are marked as unavailable without uosc, so the fallback covers the basics and not the whole feature set.

Key bindings, script messages and the hash matching caveat

The keyboard path is fully documented, which matters because the control bar is optional. The danmaku search is bound to Ctrl+d by default, and the danmaku toggle to j. The script messages behind them are `open_search_danmaku_menu` for the search and `show_danmaku_keyboard` for the toggle, so a user who wants different keys binds those messages instead.

Two automatic behaviours are worth understanding before you turn them on.

The first is memory based auto loading. Once you have loaded danmaku for one episode in a folder, that association is remembered, so replaying the file loads the comments again, and the other episodes in the same folder load their comments automatically too, with no need to type the series name again. This is off by default and the README points to the `auto_load` configuration item for turning it on.

The second is hash matching, which is the more interesting and the more risky. For a file that has never been matched, the plugin can match it by file hash and load the danmaku automatically, adding the association to its memory as well. The README states plainly that the accuracy of hash matching is low, and that if it associates the wrong series you should load the correct one manually. It also notes that hash matching now works for network video as well as local files, and that the feature requires mpv to be built against LuaJIT or Lua 5.2, since Lua 5.1 is not supported for it.

For network playback tools such as Play-With-MPV or ff2mpv, there is a separate `autoload_for_url` option, and the README is specific that automatic loading currently covers the bilibili and bahamut sites.

Where the files go and what the tree looks like

Installation is a copy into the mpv scripts directory. The typical mpv configuration layout is:

~/.config/mpv
├── fonts
├── input.conf
├── mplayer-input.conf
├── mpv.conf
├── script-opts
└── scripts

On Windows the equivalent global configuration path is `%APPDATA%/mpv/`, and the portable_config folder next to mpv.exe works as well. You either download the plugin or clone it into the `scripts` directory, and the expected layout inside it is:

~/.config/mpv/scripts
└── uosc_danmaku
    ├── apis
    │   ├── dandanplay.lua
    │   └── extra.lua
    ├── LICENSE
    ├── main.lua
    ├── modules

The `apis` directory holds the API clients, and a `modules` directory in the full tree holds the internal pieces, among them `base64.lua`, `guess.lua`, `md5.lua`, `menu.lua`, `options.lua`, `render.lua` and `utils.lua`. The `md5` and `base64` modules are what the hash matching and the data encoding need, and the `guess` module is the part that works out what a given file is.

Two installation rules are marked important. The folder under `scripts` must be named `uosc_danmaku`, or the uosc control configuration has to be edited to match whatever name you used instead, and the files in the `bin` folder have to be given executable permission.

The repository root mirrors this structure with `apis/`, `dicts/`, `modules/`, `sites/` and `main.lua` at the top, so the source tree and the installed tree are the same shape.

Version warnings, platforms and the state of the project

The first warning in the README concerns old releases. Release 1.2.0 and the releases before it partially stopped working because the DanDanPlay interface usage policy was revised, and the README says that if the plugin misbehaves, for example if the danmaku search always shows no results, you should pull the latest source from the main branch or download the newest release.

That is a useful piece of context for how the project is run. The service it depends on can change its policy underneath it, and the plugin is expected to keep working against the current interface. The current release line is v2, with v2.0.0 from 2025-09-02, v2.1.0 from 2026-04-03 and v2.2.0-alpha from 2026-04-07. The repository is not archived and the last push was on 2026-10-11, so development is continuing between tagged releases, and the alpha suffix on the newest tag is the maintainer's own signal about its state.

The other configuration items the README calls out are worth a mention for anyone deciding whether the feature set fits. There is `save_danmaku` to write the current comments to a local file, `merge_tolerance` to control how many duplicate comments appearing in the same time window are merged, `chConvert` for the simplified and traditional character conversion, and `message_x` and `message_y` to move the plugin's own messages away from the top left of the picture.

The plugin also checks for script updates, and the project ships a `sites/` and `dicts/` directory at the root of the repository for the per-site danmaku sources and their dictionaries.

In short, this is an actively changing project with a single external dependency it does not control, an optional but strongly recommended UI framework, and a feature set that is far larger behind uosc than in front of it.

Editorial conclusion

uosc_danmaku suits an mpv user on Linux or Windows who watches series with DanDanPlay comments and wants the comments inside the player, and who is prepared to install uosc and to configure the control bar. It does not suit a player without uosc if you want the menus, since the styling and delay menus are unavailable without it, and it does not suit someone who needs the hash matching to be right, because the project states its accuracy is low. Before installing, read the warning about release 1.2.0 and earlier, which broke when the DanDanPlay interface policy changed, and use a current release or the main branch rather than an old archive.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. Tony15246/uosc_danmaku on GitHub