Build the media server locally, verify every interface, then publish only the endpoint you intend to use
Kawaii-Player combines local audio and video management, browser-based media access, playlist generation, remote controls, casting, and an experimental headless media-server mode. This guide explains what can be verified from the available project documentation, how to start and test the HTTP media server, and how to connect the working local service to a Localtonet HTTP tunnel. Where the available project evidence does not establish an installation command, dependency list, or Xvfb launch command, we identify that limitation instead of supplying an unverified command.
📋 What's in this guide
Understand the Kawaii-Player remote-access architecture
Kawaii-Player is a multimedia player and library manager built around mpv and mplayer capabilities. Its documented features include local audio and video management, SQLite-backed library functions, playlists, browser access, remote controls, PC-to-PC casting, torrent streaming, and a portable media server. For this guide, the important component is its built-in HTTP media server.
The media server listens on http://127.0.0.1:9001 by default. The address 127.0.0.1 is the IPv4 loopback address, so a service bound there accepts connections originating from the same machine. Other computers on the local network cannot connect directly to that loopback address.
That default is useful when Localtonet runs on the same machine. The Localtonet client can connect to the local HTTP service and establish an outbound connection to our relay platform. The resulting HTTP tunnel provides a public address while Kawaii-Player can remain bound to loopback. This avoids opening an inbound router port, changing the router firewall, configuring a VPN, or requiring a public IP address.
There are therefore two separate systems to configure and verify:
/admin and /browse endpoints. This remains important even when transport is provided through a tunnel.
Localtonet forwards requests to an already running local service. It does not install Kawaii-Player, create its media library, start its HTTP server, or configure Kawaii-Player credentials. Verify Kawaii-Player locally before creating the tunnel.
Prerequisites and evidence boundaries
A dependable self-hosting setup begins by separating confirmed requirements from assumptions. The Kawaii-Player project README contains sections titled “Dependencies and Installation,” including material for PyQt6, but the installation text and exact commands are not present in the supplied project extract used for this draft. The extract also does not provide a complete operating-system support matrix, package names, Python version, mpv version, Xvfb package command, service-unit definition, or container image.
We therefore cannot responsibly provide a universal package-manager command or claim that a particular distribution is supported. Package names and dependency resolution differ between Linux distributions, and commands copied from an older release can also select the wrong Qt generation.
Before continuing, prepare the following:
- A machine on which the current Kawaii-Player release and its documented dependencies can be installed.
- Enough local storage for the media collection that Kawaii-Player will manage.
- A user account that can read the intended media files and write Kawaii-Player configuration data.
- Access to the graphical application for initial configuration, unless the complete current project documentation provides a tested headless bootstrap procedure for the selected environment.
- A browser on the server for local verification, or another local machine only after the server is deliberately bound to a LAN address.
- The Localtonet client installed on the Kawaii-Player host, or on another device that can reach the configured Kawaii-Player address.
- A Localtonet device authentication token obtained from the current dashboard. Treat that token as a secret and never place it in a public article, screenshot, command history, or shared configuration file.
Choose the current Qt generation carefully
The available release evidence identifies version v8.1.0-1 as the final PyQt5-based release. Its release note states that the next release will use PyQt6 and that PyQt5 will not be supported going forward. That means an old PyQt5 installation recipe should not automatically be applied to a newer checkout or release.
Select one Kawaii-Player release, then follow the dependency and installation section belonging to that release. In particular, do not assume that the final PyQt5 release and newer PyQt6-based code have interchangeable dependencies. Verify the release, dependency set, and installation path together before diagnosing runtime errors.
Decide where Localtonet will run
The simplest topology places the Localtonet client and Kawaii-Player on the same machine. In that arrangement, Kawaii-Player can retain its default loopback binding and the HTTP tunnel can target 127.0.0.1 on port 9001.
A second topology places the Localtonet client on another device on the same private network. In that case, the client device cannot use the Kawaii-Player host’s 127.0.0.1, because loopback always refers to the device making the connection. Kawaii-Player would need to listen on an address reachable from that client, normally the server’s private LAN address. The project documentation says this can be changed under More > Preferences > Media Server.
| Deployment layout | Kawaii-Player address | Important consideration |
|---|---|---|
| Kawaii-Player and Localtonet on one host | 127.0.0.1:9001 |
Retains loopback-only local access while allowing the local tunnel client to reach the server. |
| Localtonet on another LAN device | Reachable private address and port | The media server must accept connections from that device, and the local network policy must permit the traffic. |
| Direct access from other LAN clients | Reachable private address and port | Changing from loopback broadens local exposure to devices that can reach the selected interface. |
Install Kawaii-Player without mixing unsupported instructions
Installation is the one part of this workflow for which the supplied evidence does not contain enough detail to print safe, exact commands. The project index confirms that official dependency and installation sections exist, including a PyQt6 section, but those instructions were not included in the extracted material. Inventing package names, a Python environment command, a desktop launcher, or a distribution-specific sequence would make this guide less reliable.
Use the installation documentation packaged with the exact source revision or release you select. During human editorial review, the following items should be checked against the complete current project README before command-level installation instructions are added:
- The operating systems and distributions covered by the current instructions.
- The required Python and Qt generation.
- The required media backend and any supporting multimedia tools.
- Whether installation is performed from a release asset, source checkout, Python packaging workflow, or distribution package.
- The official application startup command or desktop entry.
- The required Xvfb packages and exact headless launch syntax.
- Any permissions required for media directories and configuration files.
After following the release-matched installation procedure, launch Kawaii-Player in its normal supported mode first. Confirm that its primary interface opens and that it can see the media files intended for the library. This initial interactive run is valuable even when the final goal is a headless server, because it separates installation and library problems from display-server and remote-access problems.
Complete the local application setup first
Add or organize the intended audio and video content inside Kawaii-Player before testing remote access. The documented administrative interface can later add or update video information and metadata in bulk or individually, while the browse interface presents the resulting collection. A remote tunnel cannot compensate for missing library entries, unreadable media files, or an incorrectly configured playback backend.
Keep the application’s configuration directory protected as part of the server account. The project documents ~/.config/kawaii-player/ as the location containing the administrative password and session configuration files used by the web interfaces. Do not publish that directory through a file-sharing service or include it in an unprotected backup.
The available evidence proves that official installation sections exist, but it does not include their commands. This draft therefore stops at a release-matched installation procedure rather than guessing a package manager, Python command, dependency list, or executable name. The media-server configuration below is based on instructions that are present in the supplied project documentation.
Configure and start the Kawaii-Player media server
Once the application is installed and the local library is usable, configure the HTTP service. The project documents the media-server preferences and startup controls in the graphical application. Start with loopback unless another local device must connect directly.
Open the media-server preferences
In Kawaii-Player, open More > Preferences > Media Server. Review the configured listening address before starting the service. The documented default is 127.0.0.1 on port 9001.
Keep loopback or select a reachable private address
Keep 127.0.0.1 when Localtonet will run on the same machine. If the tunnel client or other authorized clients must connect from a different LAN device, select the Kawaii-Player host’s appropriate private network address instead. Do not change the binding merely because remote internet access is planned.
Create the administrative password
Kawaii-Player documents simple username and password authentication for /admin and /browse. The username is admin, and the password must be created from the web UI. Complete this before making those interfaces publicly reachable.
Start the media server
Select More > Start Media Server. Starting the application alone should not be treated as proof that the HTTP server is running. Use the documented menu action, then test the endpoint locally.
Know which web endpoint you are opening
Kawaii-Player provides several HTTP paths with different purposes. Version 7.1.0 added the newer /admin and /browse endpoints. Older browser pages and a direct M3U playlist endpoint are also documented. Test only the interfaces needed for the deployment.
| Path | Purpose | Access consideration |
|---|---|---|
/admin |
Manage the local video collection and add or update metadata in bulk or individually. | Documented behind the admin username and the password created through the web UI. |
/browse |
Browse the prepared collection with filtering capabilities. | Documented behind the same simple username and password authentication. |
/index.htm |
Open the legacy media-server web interface. | The supplied evidence does not establish that it has the same authentication behavior as the newer endpoints. |
/stream_continue.htm |
Open the other documented legacy browser interface. | Review its behavior locally before deciding whether it should be remotely reachable. |
/stream_continue.m3u |
Retrieve the current media-server playlist in M3U format for a compatible player. | The playlist can lead clients to streamable media resources, so treat it as part of the exposed media service. |
/ |
Access the currently running file in a radio-like playback workflow. | Kawaii-Player documents this as streaming without transcoding, not as a full internet-radio service. |
The supplied project documentation explicitly associates simple username and password authentication with /admin and /browse. It does not establish equivalent protection for every legacy page, the root stream, or the M3U endpoint. Test each required path and expose only content you are prepared to make reachable through the public tunnel.
Plan the experimental headless deployment
Kawaii-Player documents an experimental headless media-server mode using Xvfb. Xvfb provides a virtual X display for graphical applications on systems without a physical display. This is relevant because Kawaii-Player is a graphical application even when the intended use is its HTTP media server.
The supplied evidence confirms that Xvfb-based headless operation exists, but the extracted headless section ends before the project’s exact command and startup sequence appear. It does not establish the display number, environment variables, process order, executable invocation, backgrounding behavior, or shutdown procedure. Those values must not be guessed.
A safe headless rollout should proceed in phases:
- Install the release and all release-matched dependencies.
- Run Kawaii-Player interactively and confirm that the application and library work.
- Configure the media-server address and administrative password.
- Start the media server through the documented interface and verify all required URLs.
- Apply the exact Xvfb procedure from the complete documentation for the installed release.
- Repeat the same local HTTP verification while no physical display is attached.
- Only then add automatic startup using the operating system’s appropriate service manager.
Automatic startup deserves particular care. A process manager may launch an application before storage is mounted, before the virtual display is available, or under a user account that cannot read the media collection. It may also restart only one part of a multi-process arrangement. Because the available evidence does not supply a service definition, this guide does not invent one.
What to verify after moving to headless mode
- The virtual display process starts before Kawaii-Player requires it.
- Kawaii-Player runs as the intended unprivileged user.
- The process can read the media collection and write its own configuration.
- The HTTP server is listening on the address selected in the application preferences.
- The
/adminand/browsepages still require the expected credentials. - The media service returns after a controlled server reboot.
- Stopping the application also stops the intended media-server exposure.
Treat the headless workflow as a configuration that needs local testing and operational monitoring. Do not create an internet-facing tunnel until the Xvfb and Kawaii-Player process lifecycle is predictable on the selected host.
Verify the complete media service locally
Local verification prevents tunnel configuration from hiding an application problem. Perform these checks from the same host first when Kawaii-Player is bound to loopback.
Open the local base address
Open http://127.0.0.1:9001 in a browser on the Kawaii-Player host. Confirm that the media server responds. If it does not, return to Kawaii-Player and verify that More > Start Media Server was selected.
Test the administrative interface
Open http://127.0.0.1:9001/admin. Confirm that authentication is requested and that the configured administrative password works. Verify that expected library items and metadata controls are present.
Test the browsing interface
Open http://127.0.0.1:9001/browse. Authenticate and check that the intended collection is visible. Test filtering and open representative items rather than relying only on the first page load.
Test an actual playback path
Play a representative audio or video item through the browser interface or another documented client workflow. A page loading successfully proves only that HTTP is responding, not that the media file is readable or playable.
Test any playlist workflow you intend to expose
If remote clients will use a playlist, open http://127.0.0.1:9001/stream_continue.m3u with a compatible player or save the response as an M3U file. Kawaii-Player documents compatible HTTP-streaming clients such as mpv and VLC.
When the service is bound to a private LAN address instead of loopback, repeat the browser test from the device that will run the Localtonet client. Use the server’s actual private address with port 9001. A successful test from an unrelated LAN device also means the service has broader local reach, so confirm that this is intentional.
Resetting the web administrative password
Kawaii-Player documents a password-reset procedure based on deleting admin_password.json and admin_sessions.json from ~/.config/kawaii-player/. This removes the relevant password and session configuration so a new password can be created through the web UI.
Stop the application before changing its configuration files, preserve appropriate file ownership, and avoid deleting unrelated files from the configuration directory. The project extract does not document a recovery mechanism that preserves the old password, so treat deletion as a reset rather than password retrieval.
Expose the verified service with a Localtonet HTTP tunnel
After local verification succeeds, connect the service through Localtonet. An HTTP tunnel is appropriate because Kawaii-Player is serving browser pages and media resources over HTTP. The Localtonet client establishes an outbound connection to our relay server, so this workflow does not require inbound router port forwarding, a public IP address, or a VPN.
Current relay server values, regions, and plan availability must be taken from the dashboard rather than copied from an article. Likewise, device tokens are specific to the selected client and must never be guessed or published.
Install and run the Localtonet client
Install our client on the Kawaii-Player host or on a device that can reach the configured media-server address. Keep it running for as long as remote access is required.
Authenticate the intended device
Select or authenticate the client using its device-specific token. Do not reuse a token in public examples, expose it in screenshots, or place it in shared source control.
Select an available relay server
Choose from the relay servers or regions currently available in the dashboard. Availability can vary, so this guide does not hardcode a server code or region.
Create an HTTP tunnel to Kawaii-Player
Configure the local target as the Kawaii-Player address and port. When both applications run on the same host with default settings, the target is 127.0.0.1 and port 9001. If the Localtonet client runs elsewhere, use the tested private address instead of loopback.
Start the tunnel
Creating a tunnel does not mean it is active. Use the Start control and wait for the selected client and tunnel to be connected. The tunnel remains available only while the device is connected and the tunnel is running.
Test the assigned public address
Open the assigned public address from a network outside the server’s LAN. Test the base path and each required endpoint, including /admin or /browse. Confirm both authentication and representative media playback.
HTTP tunnels can use a generated subdomain, a selected subdomain where supported, or a custom domain. Exact custom-domain DNS requirements must be checked against the current dashboard and documentation before making DNS changes. For the maintained product workflow, consult the Localtonet HTTP tunnel documentation.
Continue using http://127.0.0.1:9001 for server-side diagnosis. Remote users should use the public address assigned to the active tunnel. Do not replace the Kawaii-Player listening address with the public tunnel hostname.
Secure remote media and administrative access
Publishing a media server changes its risk profile. A local service that was reachable only from loopback can receive requests through the public tunnel while it is active. The tunnel solves network reachability, but application-level authentication, media permissions, and operational access decisions remain the administrator’s responsibility.
Set the administrative password before exposure
Complete the Kawaii-Player password setup for /admin and /browse before starting the public tunnel. Use a unique password that is not shared with the host account or another service. The documented username is admin, so password strength is especially important because the username is predictable.
Limit what needs to be reachable
Decide whether remote users need administration, collection browsing, legacy pages, a playlist, or only current-stream playback. The documented authentication statement covers /admin and /browse, but the supplied evidence does not prove identical access control for every other endpoint.
If a path contains content that should not be public and Kawaii-Player does not protect it as required, do not rely on obscurity or an unlisted URL. Keep the tunnel stopped until an appropriate, verified access-control design is in place.
Prefer loopback for the same-host deployment
When Localtonet and Kawaii-Player share a host, retaining 127.0.0.1 avoids making port 9001 independently reachable across the LAN. Changing the listener to a private address is necessary only when another authorized device, including a separate tunnel client, must connect.
Protect configuration and media files
Run the service using a dedicated or appropriately restricted operating-system account where practical. Grant read access only to the media directories it needs and write access only where Kawaii-Player must maintain configuration or library state. Protect ~/.config/kawaii-player/, especially the password and session files.
Stop access when it is not needed
A Localtonet tunnel can be stopped or deleted from the normal tunnel lifecycle. Stopping it removes the public route while leaving the local application configuration available for later use. Also stop the Kawaii-Player media server when local HTTP access is unnecessary.
The /admin endpoint can manage collection information and metadata. Do not share administrative credentials with users who only need browsing or playback. Before exposing the service, confirm that the application’s available authorization model matches the intended users and content.
Routine operation and maintenance
A working first connection is only the beginning of a reliable self-hosted service. Use a repeatable startup and verification order so that failures can be isolated quickly.
- Confirm that the media storage is available to the Kawaii-Player account.
- Start the required graphical or virtual-display environment.
- Start Kawaii-Player using the release’s documented procedure.
- Start the Kawaii-Player media server.
- Verify the local base URL and the required authenticated endpoint.
- Start or confirm the Localtonet client connection.
- Start the HTTP tunnel.
- Test the public address from an external connection.
Reverse the dependency order during planned shutdown. Stop the tunnel first so new public requests no longer arrive, then stop the media server and Kawaii-Player. If a virtual display is used exclusively for this application, stop it after Kawaii-Player has exited.
When upgrading Kawaii-Player, review the release notes before replacing the application. The transition from the final PyQt5 release to PyQt6-based releases is an example of why dependency assumptions must be revisited. After an upgrade, verify local authentication, collection browsing, playlist generation, and playback before restoring public access.
Troubleshoot Kawaii-Player and Localtonet separately
The local URL does not open
First confirm that Kawaii-Player itself is running. Then confirm that More > Start Media Server was selected. Review More > Preferences > Media Server and verify both the listening address and port. If the server is configured for a different address or port, testing 127.0.0.1:9001 will not represent the active configuration.
Do not change the tunnel while the local endpoint is failing. Localtonet can forward only to a service the selected client can reach.
The service works on the host but not from another LAN device
A listener bound to 127.0.0.1 is available only on the Kawaii-Player host. If another device must connect, configure Kawaii-Player with the appropriate private network address and retest using that address. Also check local firewall policy, but do not disable the firewall broadly as a troubleshooting shortcut.
The Localtonet client runs on another device but cannot reach Kawaii-Player
Do not configure the tunnel target as 127.0.0.1 in this topology. From the client device, that address refers to the client itself. Use the tested private address of the Kawaii-Player host and confirm connectivity from the Localtonet client device before starting the tunnel.
The public address is unavailable
Verify that the selected Localtonet device is connected and that the tunnel was started. Creating the configuration is not sufficient. The public endpoint is available only while the chosen client is connected and the tunnel is running.
If the tunnel is active, verify its local IP address and port against the endpoint that worked during local testing. A wrong target, a stopped Kawaii-Player server, or a changed listener can all produce a public failure.
The web page loads, but media playback fails
Test the same media item through the local Kawaii-Player URL. If local playback also fails, investigate file permissions, storage availability, library metadata, and the installed media backend before changing tunnel settings. If local playback works, test another browser and another media item, then compare the exact local and public paths being requested.
The project describes the radio-like root stream as operating without transcoding. Client compatibility therefore matters. A browser or player must support the media it receives; successful HTTP delivery does not guarantee codec support.
The administrative password no longer works
The documented reset is to remove admin_password.json and admin_sessions.json from ~/.config/kawaii-player/, then create the password again through the web UI. Stop the application before modifying configuration files and avoid deleting other data from that directory.
The server fails only in headless mode
Return temporarily to the known-good interactive startup. Confirm the application, media library, and HTTP service there. Then compare the headless environment, user account, display availability, storage mounts, and configuration directory. Because the supplied evidence does not include the official Xvfb command, use the exact command from the documentation matching the installed release rather than improvising display values or environment variables.
The tunnel works until the machine reboots
Check each dependency independently after reboot: media storage, display or virtual display, Kawaii-Player, its media server, the Localtonet client, and the tunnel state. A tunnel cannot reach an application that has not resumed listening. Likewise, the public endpoint is unavailable if the selected Localtonet client is disconnected or the tunnel is not running.
Frequently asked questions
What is the default Kawaii-Player media-server address?
The documented default is http://127.0.0.1:9001. Because 127.0.0.1 is loopback, it is directly reachable only from the Kawaii-Player host. This is suitable when the Localtonet client runs on that same host.
Do I need to change Kawaii-Player to a 192.168.x.x address?
Not when Kawaii-Player and the Localtonet client run on the same machine. Keep loopback in that topology. Change to an appropriate private address only when another authorized LAN device, including a separate Localtonet client host, must connect directly.
Which Kawaii-Player endpoints require a username and password?
The supplied project documentation explicitly says that /admin and /browse are behind simple username and password authentication. The username is admin, and the password is created through the web UI. The available evidence does not establish identical authentication for every legacy or streaming endpoint.
Can Kawaii-Player run without a physical display?
The project documents an experimental headless media-server mode using Xvfb. However, the supplied evidence does not include the exact Xvfb launch command or complete process sequence. Use the release-matched official instructions and verify the application interactively before moving it to headless operation.
Why does this guide not provide a Kawaii-Player installation command?
The supplied project extract references dependency and installation sections but does not contain their command-level instructions. It also does not establish a complete platform matrix or package list. Rather than inventing commands, this guide requires installation from the documentation belonging to the selected release.
Should I install a PyQt5 or PyQt6 version?
Match the dependencies to the selected Kawaii-Player release. Version v8.1.0-1 is identified as the final PyQt5-based release, and its release note states that later development moves to PyQt6 without continued PyQt5 support. Do not mix the installation instructions of those generations.
Does Localtonet require router port forwarding?
No. Our client establishes an outbound connection to a Localtonet relay server. This allows the working local service to receive traffic through the assigned public endpoint without configuring inbound router port forwarding, requiring a public IP address, or setting up a VPN.
Is creating a Localtonet tunnel enough to make it active?
No. After creating the HTTP tunnel, start it using the Start control. The public endpoint remains available only while the selected client device is connected and the tunnel is running.
Can remote players use an M3U playlist from Kawaii-Player?
Kawaii-Player documents the /stream_continue.m3u endpoint for retrieving the current media-server playlist. A compatible HTTP-streaming player can open the playlist. Verify the workflow locally first, then decide whether its contents are appropriate for remote exposure.
How do I reset the Kawaii-Player administrative password?
The documented reset procedure is to delete admin_password.json and admin_sessions.json from ~/.config/kawaii-player/, then create a new password through the web UI. Stop the application first and avoid deleting unrelated configuration files.
Connect your verified Kawaii-Player server with Localtonet
Once the media server responds locally and its required interfaces are authenticated, create an HTTP tunnel to the tested IP address and port. Start the tunnel only when remote access is needed, then verify the public endpoint from an external network.
Get Started Free →
