# timerring/bilive architecture

> Architecture diagram of the GitHub repository timerring/bilive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/timerring/bilive
- Repository: https://github.com/timerring/bilive

## Overview

##### Project Type and Purpose
- This is a backend-oriented, full-stack pipeline application (a modular monolith) for 24×7 automated recording of Bilibili live streams, rendering of subtitles and danmaku, intelligent slicing, thumbnail generation, and automatic upload.
- Key goals:
- Ingest live streams (video + bullet comments)
- Process/transcode/merge segments
- Generate and burn subtitles and danmaku overlay
- Use LLM/image-gen APIs for slice-title and cover creation
- Upload finished assets back to Bilibili

##### High-Level Components
Based on file tree and README, the system breaks down into these main modules:
A. Ingestion & Recording
- blrec (in `src/upload/bilitool` and launched via `record.sh`)
- Web UI / REST API for task management (`settings.toml` config)
- Output: raw video files and XML danmaku

B. Pre-Processing / Merging
- `src/burn/scan.py` & `render_then_merge.py`
- Merges fragmented streams into continuous MP4

C. Subtitle Generation
- `src/subtitle/whisper` (local or Whisper API)
- Produces SRT/ASS transcripts

D. Danmaku Conversion
- `src/danmaku/DanmakuConvert`
- Converts XML bullet files into ASS overlay format

E. Burn / Render
- `src/burn/render_video.py`
- Uses FFmpeg to burn subtitles (ASS) and danmaku onto video

F. Auto-Slicing & Title Generation
- `src/autoslice/auto_slice_video` + `mllm_sdk/*_sdk.py`
- Calls external MLLM APIs (Gemini, Qwen, Zhipu, etc.)
- Identifies high-density segments, returns clip timestamps & titles

G. Cover Generation
- `src/cover/cover_generator.py` + `image_model_sdk/*_sdk.py`
- Takes frame snapshots, calls image-gen APIs (DMXAPI, Stability, etc.)

H. Upload
- `src/upload/upload.py`
- Uses `biliup` submodule to authenticate & upload full videos & slices
- Reads configuration from `bilive.toml`

I. Supporting Services
- Configuration (`bilive.toml`, `settings.toml`)
- Logging (`src/log/logger.py`)
- Database connection (lightweight metadata store, `src/db/conn.py`)
- Shell scripts (`record.sh`, `upload.sh`)
- Containerization (Dockerfiles, `compose.yml`)

##### Relationships and Data Flow
- Live stream ingestion ↦ raw files (Videos/)
- Raw files ↦ scan & merge ↦ continuous MP4
- MP4 ↦ subtitle generation ↦ ASS/SRT
- XML danmaku ↦ DanmakuConvert ↦ ASS overlay
- MP4 + ASS subtitles + ASS danmaku ↦ burn/render ↦ final MP4
- Final MP4 ↦ autoslice ↦ clip segments + titles
- Final MP4 ↦ cover generator ↦ image assets
- Finished artifacts ↦ upload module ↦ Bilibili via bilitool API
- Throughout: logs to `logs/`, metadata to DB

##### Architectural Patterns & Principles
- Pipeline pattern: each stage reads outputs of the previous
- Modular SDK wrappers for external APIs (e.g., one file per model)
- Configuration-driven behavior (three modes: pipeline, append, merge)
- Submodules to separate concerns (DanmakuConvert, bilitool, auto-slice)
- Container-first deployment with Docker & Docker Compose

##### Technologies & Frameworks
- Python 3.10+ with sub-packages in `src/`
- FFmpeg for video encoding and overlay
- OpenAI Whisper (local or API) for ASR
- LLM APIs (Gemini, Qwen, etc.) via DMXAPI.cn
- Image generation APIs (Stable Diffusion, Luma, Ideogram, etc.)
- Bilibili upload via bilitool (Python CLI submodule)
- blrec for Bilibili live capture
- VitePress for docs (not part of runtime)

##### Detail Level
- 8 major components above as separate nodes.
- 3 operation modes (pipeline, append, merge) as variants or notes on the Burn/Subtitle stages.
- Shell scripts (`record.sh` & `upload.sh`) kicking off the ingestion and upload flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Entry Points"
        RS["record.sh"]:::script
        US["upload.sh"]:::script
    end

    RS --> ING["Ingestion & Recording\n(blrec)"]:::ingest

    ING --> RAW["Filesystem\nRaw Video & XML"]:::data

    subgraph "Processing Pipeline"
        MERGE["Merge\n(scan.py, render_then_merge.py)"]:::process
        SUB["Subtitle Generation\n(Whisper)"]:::process
        DAN["Danmaku Conversion"]:::process
        BURN["Burn & Render\n(render_video.py)"]:::process
        SLICE["Auto-Slicing & Title Gen"]:::process
        COV["Cover Generation"]:::process
    end

    RAW --> MERGE --> MP4["Filesystem\nContinuous MP4"]:::data
    MP4 --> SUB --> SUB_ASS["ASS/SRT Files"]:::data
    RAW --> DAN --> DAN_ASS["ASS Danmaku"]:::data
    SUB_ASS & DAN_ASS & MP4 --> BURN --> FINAL["Filesystem\nFinal MP4"]:::data
    FINAL --> SLICE --> CLIPS["Clips & Titles"]:::data
    FINAL --> COV --> COV_IMG["Cover Images"]:::data
    FINAL & CLIPS & COV_IMG --> UP["Upload Module"]:::ingest
    US --> UP
    UP --> BAPI["Bilibili Upload API"]:::external

    SUB --> WHISPERAPI["Whisper API"]:::external
    SLICE --> LLM["LLM APIs"]:::external
    COV --> IMGAPI["Image Gen APIs"]:::external

    subgraph "Support Services"
        CFG["Configuration\n(bilive.toml, settings.toml)"]:::config
        LOG["Logging Service"]:::config
        DB["Database"]:::config
    end

    CFG --> ING
    CFG --> MERGE
    CFG --> SUB
    CFG --> DAN
    CFG --> BURN
    CFG --> SLICE
    CFG --> COV
    CFG --> UP

    ING & MERGE & SUB & DAN & BURN & SLICE & COV & UP --> LOG
    ING & MERGE & SUB & DAN & BURN & SLICE & COV & UP --> DB

    subgraph "Containerization"
        DO1["Dockerfile"]:::config
        DO2["Dockerfile-GPU"]:::config
        DC["compose.yml"]:::config
    end

    classDef ingest fill:#ACE7FF,stroke:#000;
    classDef process fill:#C6F5C6,stroke:#000;
    classDef external fill:#FFD2A6,stroke:#000;
    classDef data fill:#D3D3D3,stroke:#000;
    classDef config fill:#E0E0E0,stroke:#000;
    classDef script fill:#D0E0FF,stroke:#000;

    click ING "https://github.com/timerring/bilive/tree/main/src/upload/bilitool/"
    click RS "https://github.com/timerring/bilive/blob/main/record.sh"
    click MERGE "https://github.com/timerring/bilive/blob/main/src/burn/scan.py"
    click MERGE "https://github.com/timerring/bilive/blob/main/src/burn/render_then_merge.py"
    click SUB "https://github.com/timerring/bilive/tree/main/src/subtitle/whisper/"
    click SUB "https://github.com/timerring/bilive/blob/main/src/subtitle/subtitle_generator.py"
    click DAN "https://github.com/timerring/bilive/tree/main/src/danmaku/DanmakuConvert"
    click DAN "https://github.com/timerring/bilive/blob/main/src/danmaku/generate_danmakus.py"
    click BURN "https://github.com/timerring/bilive/blob/main/src/burn/render_video.py"
    click SLICE "https://github.com/timerring/bilive/tree/main/src/autoslice/auto_slice_video/"
    click SLICE "https://github.com/timerring/bilive/blob/main/src/autoslice/title_generator.py"
    click COV "https://github.com/timerring/bilive/blob/main/src/cover/cover_generator.py"
    click COV "https://github.com/timerring/bilive/tree/main/src/cover/image_model_sdk/"
    click UP "https://github.com/timerring/bilive/blob/main/src/upload/upload.py"
    click UP "https://github.com/timerring/bilive/tree/main/src/upload/bilitool/"
    click CFG "https://github.com/timerring/bilive/blob/main/bilive.toml"
    click CFG "https://github.com/timerring/bilive/blob/main/settings.toml"
    click CFG "https://github.com/timerring/bilive/blob/main/src/config.py"
    click LOG "https://github.com/timerring/bilive/blob/main/src/log/logger.py"
    click DB "https://github.com/timerring/bilive/blob/main/src/db/conn.py"
    click US "https://github.com/timerring/bilive/blob/main/upload.sh"
    click DO1 "https://github.com/timerring/bilive/tree/main/Dockerfile"
    click DO2 "https://github.com/timerring/bilive/tree/main/Dockerfile-GPU"
    click DC "https://github.com/timerring/bilive/blob/main/compose.yml"
```
