bilive: automated Bilibili live recording, danmaku rendering and upload

The problem bilive solves: unattended Bilibili recording

Recording a Bilibili live stream by hand is a sequence of chores. You start a recorder before the stream begins, you keep it running for hours, you find the danmaku XML next to the video file, you convert that XML into a subtitle format a player can burn in, you cut the interesting parts out, and then you upload. bilive collapses that sequence into one process that runs continuously. The README describes it as a 7 x 24 hour unattended recorder that renders danmaku, recognises subtitles, slices automatically and uploads, with a stated goal of working on very low-specification machines.

The intended user is someone who archives streams on a schedule rather than occasionally: a fan who wants every broadcast of a channel, or an operator who wants clips published while the stream is still running. It is not aimed at someone who wants to grab one video once. The README also carries an explicit warning that the project is for learning and exchange, that recording requires the other party's permission, that content should not be used commercially without authorisation, and that large-scale recording can get an account banned. That warning is part of the project's own framing, not a footnote.

How the recording pipeline actually flows

The mechanism is a chain of submodules rather than a single binary. Recording is handled by blrec, which is vendored as a wheel in requirements.txt (blrec-2.0.0b4-py3-none-any.whl) rather than pulled from PyPI. Danmaku conversion is handled by DanmakuConvert, which the README says is open sourced separately and turns XML into ASS. Slicing is handled by auto-slice-video, which the README says finds high-energy segments by computing danmaku density. Uploading and persistent login are handled by bilitool, which the README describes as supporting persistent login, downloading videos and danmaku including multi-part, uploading with part splitting, and querying upload status, usable either as a CLI or as an API.

The three processing modes are where the design decision sits. In pipeline mode, which the README calls the default and the fastest, automatic speech recognition and rendering run in parallel and the video is uploaded in parts. In append mode the same work runs serially, which the README estimates as roughly 25 percent slower but with lower VRAM demand. In merge mode everything waits until recording finishes and the upload is a single complete recording rather than parts. The README notes that the GPU description only applies when asr_method is set to deploy; setting it to none or api removes the GPU requirement entirely.

That is a real architectural split. Parallelism buys latency and costs memory. The project lets you pick which one you can afford instead of picking for you.

Installing bilive with submodules and a first recording

The README recommends cloning with submodules, because DanmakuConvert, bilitool and auto-slice-video are pulled in that way. If you cloned without the flag, run the submodule update afterwards.

git clone --recurse-submodules https://github.com/timerring/bilive.git

git submodule update --init --recursive

Dependencies install from the pinned requirements file. The README recommends a virtual environment, and notes that ffmpeg has to be installed separately for your operating system; it links to the ffmpeg download page and to an Ubuntu installation guide.

cd bilive
pip install -r requirements.txt

There is also a container path. The compose file references a published image and mounts the two TOML configuration files, the Videos directory and the logs directory, and exposes port 2233 inside the container mapped to 22333 on the host.

services:
  bilive:
    image: ghcr.io/timerring/bilive:0.3.1
    restart: always
    container_name: bilive_docker
    ports:
      - "22333:2233"
    volumes:
      - ./app:/app
      - your/path/to/bilive.toml:/app/bilive.toml
      - your/path/to/settings.toml:/app/settings.toml
      - your/path/to/Videos:/app/Videos
      - your/path/to/logs:/app/logs
    environment:
      - RECORD_KEY=your_record_password

The image tag and the alternate GPU image tag are both named in the compose comments, and the RECORD_KEY environment variable is the record password. The Dockerfile installs ffmpeg, procps, lsof, curl, vim and gcc, copies a Microsoft YaHei font into the system font directory, sets TZ to Asia/Shanghai, and runs start.sh as the command. Windows users are told to run the project under WSL. Two configuration files, bilive.toml and settings.toml, sit at the repository root and are the files you mount; the README does not enumerate their keys, so read the files themselves before editing.

Where bilive breaks down or is the wrong choice

The GPU story is the first constraint. The README states that any mode using a GPU requires VRAM above what the program needs, and points to a documentation section on calculating VRAM requirements rather than giving a number. If you run pipeline or append mode with local whisper, you are in guesswork territory until you read that page. The README's own hardware table lists a 2 GB machine with no GPU and a 4 GB arm64 machine with no GPU among the tested configurations, which suggests the no-GPU path is the one with the widest margin.

The arm64 path has a documented gap. The README says the aarch64 build of the triton library has no PyPI release, so local whisper deployment is not supported on aarch64, and users are told to comment out the triton entry in requirements themselves. That is a manual edit to a dependency file, and it means arm64 users who want transcription are pushed toward an API-based asr_method or no transcription at all. It is a real limitation, stated plainly.

The README also notes that update speed depends mainly on upload bandwidth rather than rendering speed, so a fast CPU on a thin connection will still lag. And the project is explicit that large-scale recording risks an account ban. If your use case is archiving many channels continuously, that warning is aimed at you. Finally, the README does not document rollback of an upload, and it does not document what happens to partially uploaded parts if the process is killed mid-run.

bilive compared with running blrec and ffmpeg yourself

The obvious alternative is to assemble the same parts by hand: run blrec for recording, convert danmaku XML to ASS with DanmakuConvert, transcribe with whisper, cut with ffmpeg, and upload with bilitool. Every one of those components is already a separate project, and bilive is essentially the glue plus the scheduling policy. The difference in approach is that bilive decides when to run each stage and how to split the upload, and it encodes that decision in the three modes. Doing it by hand gives you the same primitives with no opinion about ordering, which is more flexible and more work.

A second alternative is to skip transcription and slicing entirely and just keep the raw recordings. That removes whisper, removes the VRAM question, and removes the triton problem on arm64. You lose the danmaku-burned video and the automatic clips, which are the parts that make the output watchable without editing. Whether that trade is worth it depends on whether you publish or just archive. If you publish, the rendering and slicing are the value. If you archive, they are overhead.

Maintenance cost, licence and what the release history shows

The repository is not archived, and the last push was on 2026-04-24. The most recent tagged release in the repository is v0.3.1 from 2025-04-27, with v0.3.0 two weeks before it and v0.2.10 a month before that. The compose file pins the image at 0.3.1, so the container path and the release tags are aligned. The gap between the last release tag and the last push means there is work on main that is not in a tagged release, and if you pull the image you are getting the tagged version, not main.

Upgrade cost is dominated by the pinned dependencies. torch is pinned to a range below 2.3.0, numpy is pinned below 1.26.4, and triton is pinned at 3.1.0. Those pins interact: the arm64 triton gap is a consequence of the triton pin, and moving torch forward may force the triton pin to move with it. Expect dependency work, not a drop-in upgrade, when you bump the stack.

The licence is Apache-2.0, which permits commercial use and modification and includes a patent grant. That is the licence of this repository. It does not automatically cover the submodules, the vendored blrec wheel, the ffmpeg build you install, the whisper model weights, or the third-party model APIs the README lists. Check each of those separately; nothing here is legal advice.

Editorial conclusion

Adopt bilive if you already run a small always-on Linux box or container and want one pipeline that records, renders danmaku, transcribes and uploads without babysitting. Do not adopt it if you only need a one-off recording, if you cannot accept that the fastest mode wants a GPU, or if you intend to record streams you do not have permission to record. Before committing, verify three things: that your ffmpeg build is present on the host, that your VRAM fits the mode you plan to run, and that the whisper path on arm64 is workable given the triton wheel gap the README describes.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. timerring/bilive on GitHub