# blivechat: a YouTube-style bilibili live chat overlay for OBS

> blivechat renders bilibili live comments, gifts and Super Chats as a browser source styled like YouTube's chat, either from the author's public servers or from a local Python server. It is aimed at streamers who want a readable chat overlay without building one themselves, and the trade-off is a Python 3.12 backend, a Node build step, or a dependency on someone else's node.

**xfgryujk/blivechat** — 用于OBS的仿YouTube风格的bilibili直播评论栏

- Repository: https://github.com/xfgryujk/blivechat
- Website: https://blive.chat
- Stars: 2,733 · Forks: 280
- Language: JavaScript
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/xfgryujk-blivechat

## The gap blivechat fills between bilibili's chat and OBS

bilibili's own live room chat is a web page built for viewers, not for a video canvas. Putting it into OBS means cropping a browser source, fighting the page layout, and losing any control over how a gift or a Super Chat appears next to an ordinary danmaku line. blivechat exists to replace that page with a dedicated overlay. The README describes it as a YouTube-style comment column for bilibili live streams, used inside OBS, and the screenshots in the repository show the same overlay rendered in OBS, in Chrome, and in the project's style generator.

The audience is narrow and specific. You need to be streaming on bilibili, you need OBS (or another tool that accepts a browser source URL), and you need the streamer's identity code that bilibili issues when a broadcast starts. The README's online flow is: open one of the public servers, enter the identity code, copy the room URL, generate a style, copy the CSS, and paste both into an OBS browser source. Nothing about that requires a server of your own, which is the point. A streamer who only wants comments on screen never touches Python, Node or Docker.

## Two data paths: direct from the browser or through the backend

The README lists frontend direct connection to bilibili's servers and backend forwarding as two supported modes, and that choice shapes everything else. In the direct mode the overlay page talks to bilibili itself, so the server in the middle only serves static files and configuration. In the forwarding mode the Python backend holds the connection to bilibili and pushes messages to the page, which is what makes server-side features possible: automatic translation of danmaku and Super Chats into Japanese, with a configurable target language, and the settings that merge gifts or block danmaku.

The repository layout matches that split. There is a frontend directory (the overlay and the style generator, built with Node), a backend made of main.py plus api, models, services, utils and config.py, a blcsdk workspace package that is referenced as an editable local dependency in pyproject.toml, and a plugins directory. The backend depends on blivedm, pinned in pyproject.toml to a specific git revision rather than a released version, which means the chat protocol handling is not something you upgrade independently of blivechat itself. The Dockerfile builds the frontend with Node 18.17.0 and runs the backend on python3.12, and it rewrites data/config.example.ini so that host becomes 0.0.0.0 and loader_url is emptied before starting. That sed line is the container equivalent of the README's warning to delete loader_url on a self-hosted server.

## Running blivechat locally from source

The README gives three install paths: public servers, a local distribution, and source. The local distribution is x64 Windows only, which is why the source path matters for anyone on Linux, macOS or a server. It needs Node.js for the frontend build and uv for the Python side. Both commands below are copied from the README's source section, run from the repository root.

```bash
cd frontend
npm i
npm run build
```

After the frontend build finishes, frontend/dist holds the overlay assets. The backend is started with uv, and the README shows that host and port can be overridden:

```bash
uv run main.py --host 127.0.0.1 --port 12450
```

Open http://localhost:12450 in a browser. From there the flow is the same as the online one: enter the streamer's identity code, copy the generated room URL, generate a style, and paste the URL and the CSS into an OBS browser source. If you prefer containers, the README's Docker example maps port 12450 and keeps state in a named volume:

```bash
docker run --name blivechat -d -p 12450:12450 \
  --mount source=blivechat-data,target=/mnt/data \
  xfgryujk/blivechat:latest
```

Server settings live in data/config.ini, and the README states that edits require a restart to take effect. It also states, in bold in the original, that a self-hosted server must delete the loader_url setting or the room page will not load. That is the single most common way a fresh self-hosted install appears broken while the server itself is running fine.

## Where blivechat is the wrong choice

The online path is convenient and it is also the path with the least control. The README says advanced features are disabled when you use the public servers, and that plugins and translation therefore require a local install. It also notes that the local distribution does not auto-upgrade, so a problem fixed upstream stays broken on your machine until you download a new release, while the online servers can fix things without you doing anything. Those two statements pull in opposite directions, and the README resolves them by recommending local use only if you need the advanced features.

Availability is a real constraint rather than a hypothetical one. The README describes four public nodes with different failure profiles: the automatic node normally equals the China node and takes time to switch when that one fails, the China node resists blocking but degrades under attack, and the Cloudflare and Vercel nodes resist attack but are easier to block. There is no node that is both. A streamer in a region where the US nodes are blocked and the China node is under attack has no good option except self-hosting.

Self-hosting has its own boundary. The frontend must be built before the server is useful, the backend requires Python 3.12 or newer per pyproject.toml, and blivedm is pinned to a git revision, so you are tracking a moving target if you build from source. blivechat also assumes bilibili. It is not a general chat overlay, and none of the README's features translate to Twitch or YouTube, where the platform already provides a chat widget.

## How blivechat differs from blivedm and from recording tools

The related searches around this project mix it up with two neighbouring things: blivedm and bilibili live recorders. They solve different problems, and the difference is worth stating plainly. blivedm is the library blivechat itself depends on to talk to bilibili's live protocol; pyproject.toml pulls it from a pinned git revision. Using blivedm directly means writing your own consumer of the message stream, which is the right choice if you want to log, analyse or route comments somewhere other than a video overlay. blivechat is the finished consumer: it renders, styles and translates.

Recorders are the other direction. A recorder's job is to capture the stream to disk; a chat overlay's job is to display messages on top of a stream that is already being captured. They can run side by side, but blivechat gives you nothing for archiving and a recorder gives you nothing for on-screen styling. If your actual requirement is a comment log, blivechat's overlay is the wrong output format even though the underlying data is the same.

## Licence, maintenance and what an upgrade costs

blivechat is MIT licensed, with the licence text in the repository root and declared in pyproject.toml. MIT is permissive: you can modify and redistribute it, including in a commercial streaming setup, provided the copyright notice and licence text are kept. That is a statement about the licence text, not legal advice, and the bundled or pinned dependencies (blivedm, tornado, aiohttp, sqlalchemy, pycryptodome and the rest) carry their own licences that you would need to check separately if you redistribute a built artifact.

The repository is not archived, and the last push was on 2026-08-19, the same day as the v1.10.4 release. The two releases before that were v1.10.3 on 2026-05-06 and v1.10.2 on 2026-02-08, so the release cadence over 2026 has been roughly one every three months. That is a usable rhythm for a project of this size, and it also means you should not expect a fix the same week you report it. The default branch is dev rather than main, so anyone building from source should be explicit about which branch they are on.

Upgrade cost depends on which path you chose. Public servers upgrade themselves and cost you nothing but the loss of advanced features. The Windows distribution does not auto-upgrade, so you re-download. Source and Docker installs mean pulling the new code, rebuilding the frontend, and re-running uv sync, and because blivedm is pinned to a revision, a new blivechat release may move that pin in ways that change behaviour before you notice. Budget for a restart of the server after any config.ini change, since the README is explicit that edits only take effect after a restart.

## Conclusion

Adopt blivechat if you stream on bilibili through OBS and want a chat overlay that already handles fleet badges, gifts, Super Chats and style generation without you writing frontend code. Skip it if you are not on bilibili, or if you cannot accept a Python 3.12 backend plus a Node build for source installs, or a third-party node for the online path. Verify first that the public node you pick actually loads the room page, because the README warns that self-hosted servers must delete the loader_url setting or the room page will not load, and check whether the advanced features you want (plugins, translation) are disabled on the online servers you plan to use.

## FAQ

### How do I install blivechat and use it in OBS?

Pick one of four paths from the README: open a public server such as blive.chat, download the x64 Windows local distribution and run blivechat.exe, build the frontend with npm and run uv run main.py, or start the Docker image with port 12450 mapped. Then enter the streamer's identity code, copy the room URL, generate a style, and paste the URL plus the generated CSS into an OBS browser source.

### Why does the room page fail to load on my own blivechat server?

The README warns that self-hosted servers must delete the loader_url setting in data/config.ini, otherwise the room page cannot load. The Dockerfile does this automatically by rewriting config.example.ini, but a manual install does not. Remember that config.ini changes require a restart.

### Can I use blivechat plugins and automatic translation on the public servers?

No. The README states that advanced features are disabled when you use the public servers, so plugins and translation require a local install. The trade-off is that a local install does not auto-upgrade, while the public servers can be fixed without any action from you.

## Sources

- [License: MIT](https://github.com/xfgryujk/blivechat/blob/dev/LICENSE)
- [Project website](https://blive.chat)
- [README](https://github.com/xfgryujk/blivechat/blob/dev/README.md)
- [Releases](https://github.com/xfgryujk/blivechat/releases)
- [xfgryujk/blivechat on GitHub](https://github.com/xfgryujk/blivechat)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xfgryujk-blivechat