kawaii-player: a desktop media manager that also serves your library

A player, a library manager and a server in one application

Kawaii-Player is described as an audio and video manager and multimedia player, based on mpv and mplayer, with a PC-to-PC casting feature, along with the functionalities of a portable media server and a torrent streaming server. That is three products in one process, and the feature list in the README runs to thirty numbered items.

The combination is unusual enough to be worth understanding. A media library manager is a catalogue application: it knows about your series, tracks what you have watched, fetches artwork and metadata, and remembers settings. A multimedia player is a video and audio player with a library view and a thumbnail grid. A media server exposes the collection over HTTP so other devices can play from it. And a casting target means a second machine can ask the first one to play something.

The library side is built on sqlite3, and the feature list describes it in concrete terms: bookmark and categorize series in the library, like Watching, Incomplete and Interesting, and manage that with sqlite3. The metadata side pulls fanart, posters, summaries and biographies from sites such as TVDB and last.fm, and there is an internal web browser with a custom right click menu for manually downloading the artwork you want rather than accepting what the site returned.

Other things the list mentions that are worth calling out: a history manager for both addons and local content, a special minimal mode music player reachable from the system tray context menu, MPRIS2 support so the player appears in the desktop sound menu applet, three themes including dark and the system theme from v3.1 onwards, gapless playback of network streams, a live seekbar preview, and a detached video picture-in-picture mode.

The project is GPL-3.0 licensed, written in Python with PyQt, and the last push was on 2026-09-18.

The Python package links to mpv, and on Linux you install the rest yourself

The packaging tells you exactly what is native and what you have to provide.

The build system requires setuptools, wheel and Cython, and the extension is built from `pympv/mpv.pyx`, a Cython source file, linking against the `mpv` library:

install_requires = []
if system in ["darwin", "nt"]:
    install_requires = [
        "PyQt6",

The `install_requires` list is empty on Linux, and the comment in the setup file explains why: GNU/Linux users should install dependencies manually using their native package manager. On macOS and Windows the list is filled in, with PyQt6, bs4, Pillow, mutagen, lxml, yt-dlp, PyQt6-WebEngine, PyOpenGL, python-vlc and certifi.

The macOS case also sets a library path:

library_path = None
if system == "darwin":
    library_path = ["/usr/local/lib"]

and the extension is declared differently depending on whether that path is set, with the macOS build getting an extra `library_dirs` argument. The upshot is that the mpv shared library has to be findable at build time on macOS, which is the kind of thing that bites people on a fresh machine.

The version in setup.py is 9.0.0, while the latest tagged release in the release history is v8.1.0-1 from 2026-03-19, ahead of 8.0.0-1 from 2026-02-23 and v7.1.0-1-beta from 2026-01-08. So the working tree is ahead of the published release, and the version scheme carries a packaging suffix of -1 on the distribution tags.

The repository layout is a Python package `kawaii_player/` plus a `pympv/` directory for the Cython binding, with `arch/` and `ubuntu/` directories for packaging, an `Images/` directory for the screenshots, a `test/` directory and a MANIFEST.in.

The media server, its two admin endpoints and its loopback default

The media server is started from the More menu, and its default address is the part that matters.

By default the media server starts on http://127.0.0.1:9001, the loopback address of the machine. To use it as a media server that can be accessed from any device on the same local network, you have to change that loopback address to your local network address, which normally starts with 192.168.x.y, and you can check and change it under More, then Preferences, then Media Server.

The web interface has been restructured twice recently. From v7.0.0 the web interface underwent a significant change, and from v7.1.0 two new endpoints were added. `/admin` is for managing the video collection from the web UI itself, and `/browse` is for browsing the collection with filtering capability. Both sit behind simple username and password authentication, the username is `admin`, and the password is created from the web UI itself.

The password reset mechanism is worth noting because it tells you what kind of authentication this is. To reset the password you delete the config files `admin_password.json` and `admin_sessions.json` from the config directory `~/.config/kawaii-player/`. There is no password reset flow, no token rotation and no role model. Anyone who can read that config directory can take over the admin interface, and anyone who can reach the network address can try the credentials.

The admin endpoint is described as something that can be considered a CMS for local video management, from where you can add or update most of the information and metadata about videos in bulk or individually, and once the info is added correctly the collection can be browsed at the browse endpoint.

For players, there is a universal playlist in m3u format that can be played by any media player on the local network supporting http streaming, such as mpv or VLC, on any platform. It can be generated from the web interface, fetched directly at `http://192.168.2.2:9001/stream_continue.m3u` from within a player, or retrieved with curl or wget and saved with the .m3u extension for any player that recognises the format. A legacy web interface remains at `/stream_continue.htm` and `/index.htm`.

Addons, casting, torrents and a YouTube wrapper

Four capabilities extend the player beyond local files, and each has a different dependency profile.

The addon structure is the extension mechanism. Custom addons are supported for viewing content of various sites directly on the player, and a history manager covers both addons and local content, so what you watched through an addon is recorded alongside what you watched from disk. The YouTube support is described as a wrapper using qtwebengine or qtwebkit, which is why PyQt6-WebEngine appears in the macOS and Windows dependency list.

Casting comes in two forms. PC-to-PC casting is the headline feature in the project description, and browser-to-PC casting is listed separately, with the same casting section covering both. The remote control path is the web interface: you can control the player remotely from a browser, and the peer to peer mode is listed as its own feature alongside the casting ones.

The torrent streaming player and server is the piece with the broadest implications, and the README does not hedge it. It is listed as a numbered feature and has its own section, which means the application can act as a torrent client and stream what it downloads rather than only playing files you already have.

The playing mode is the default, and the thumbnail mode is described as unique in the sense that users can watch video within the thumbnail itself by selecting the appropriate mode from 3 to 5, with the option to change the default generated thumbnail. Thumbnails of local video files are generated automatically with the help of ffmpegthumbnailer, which is an external tool and therefore another dependency you install yourself.

External players are supported too, so video can be opened in vlc, smplayer or kodi, and there is better buffer management for mplayer on a low bandwidth network.

Where this sits against a bare mpv and against a dedicated media server

The comparison worth making is with the two alternatives that cover parts of what this does.

The first is plain mpv with a file manager. mpv is a better video player than any wrapper is likely to be, it has a large configuration surface, and it handles formats and hardware decoding well. What mpv does not do is maintain a library, fetch artwork, track watch history, serve the collection to other devices, or cast to another machine. If you keep a small collection of files and open them by hand, the wrapper adds a dependency and a layer of indirection for no benefit, and the feature list even acknowledges that the player is the internal mplayer/mpv one.

The second is a dedicated media server such as Jellyfin, Emby or Plex. Those are built for the server role, with proper user accounts, transcoding, multi-user access and a mature client ecosystem. Kawaii-Player's media server is one application serving its own library, with a single admin credential, no roles, and no transcoding. In exchange it does not require a separate service, and it can play the files locally at the same time, which a media server cannot do.

The torrent streaming feature is where the comparison gets sharper. A general purpose media server does not fetch torrents, and a separate torrent client such as qBittorrent does not serve your library over HTTP. Combining them in one application is convenient for someone who wants one process, and it is also the feature that most affects the security posture of the whole thing, since a torrent client opens outbound connections to a peer network.

The realistic user is a Linux desktop user with a collection on disk, a household or a few friends on the same network, and a preference for a single application that does the playing, the organising and the serving. For anything with multiple accounts or untrusted clients, the trade is not worth making.

Editorial conclusion

Adopt kawaii-player if you have a local media collection on Linux and want one application to play it, organise it with artwork and metadata, and serve it to other devices or another machine over the network. Do not adopt it if you need a hardened server for untrusted clients, because the web interface relies on a single admin credential with a password reset that means deleting config files, and check first that the mpv or mplayer backend and the system libraries the Cython extension links against are present, since the Python package does not install them for you on Linux.

Frequently asked questions

Official sources

1. Issues
2. kanishka-linux/kawaii-player on GitHub
3. License: GPL-3.0
4. README
5. Releases