# bili_video_kit

**Repository Path**: az13js/bili_video_kit

## Basic Information

- **Project Name**: bili_video_kit
- **Description**: 可能比较乱，还没人工整理。如果你要用建议让AI整一整再用。
- **Primary Language**: Unknown
- **License**: WTFPL
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-20
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# B 站分析视频工具包

把音频取证/技术分析的结果制作成 1080p、可直接上传 B 站的视频。引擎在 `bili_video_kit/`，案例内容在 `project/`；换案例时主要改 `project/`，不需要改渲染器。

关键方法与复用规则见 [AGENTS.md](AGENTS.md)。

本包从实际案例的 `video/` 目录抽取，保留了可复用的部分：TTS 与字幕时间轴、素材抽取、逐帧渲染、混音、封装、封面、发布包、OKLCH 色板、校验。示例项目不依赖任何受版权保护的媒体，可以直接跑通一条最短流程。

## 快速开始

```bash
python3 -m venv .venv
.venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e .

# 编辑 project/case.toml、project/narration.py、project/scenes.py
make all
```

只跑某个阶段：

```bash
make tts       # 生成旁白和 build/timeline.json
make assets    # 抽帧、局部片段、音乐、分析曲线
make audio     # 主混音 + 无音乐备用轨
make render    # 无声 1080p 视频
make mux       # 封装 MP4
make cover     # 1146×717 封面
make publish   # SRT、章节、B 站发布包、审看页
make palette   # OKLCH 色板、对比度、色觉模拟
make verify    # 成片/音频/字幕/封面检查
```

`make all` 会依次执行以上阶段。示例项目没有媒体时会使用深色占位背景；有媒体时 `assets` 才会抽取画面和图表数据。

## 目录

| 路径 | 内容 |
|---|---|
| `bili_video_kit/` | 引擎：配置、TTS、素材、渲染、混音、封装、封面、发布、色板、校验 |
| `project/case.toml` | 案例元数据、路径、音乐、封面、发布文案 |
| `project/narration.py` | 逐幕旁白、章节、停留时间 |
| `project/scenes.py` | 逐幕画面绘制函数；key 必须与 narration 一致 |
| `media/` | 输入视频、参考音频、截图、音乐片段（不提交） |
| `analysis/` | `audio-forensics` 报告和可选曲线（不提交） |
| `examples/myth_studio/` | 实际 13 幕案例的旁白/画面参考，不参与默认构建 |
| `build/` | TTS、时间轴、混音、无声视频（不提交） |
| `assets/` | 抽帧、局部片段、裁剪音乐（不提交） |
| `publish/` | 封面、字幕、发布包、审看页、色板报告 |
| `out/` | 最终 MP4（不提交） |

## 换一个案例

1. 把视频/参考音频/截图放到 `media/`，修改 `project/case.toml` 的 `[paths]`。
2. 修改 `project/narration.py`：每一幕一个 `Scene(key, chapter, narration, lead, tail, min_duration)`。
3. 修改 `project/scenes.py`：为每个 key 写一个 `render(frame, t, duration, ctx)`；`ctx.case` 提供配置，`ctx.fonts` 提供字体，`ctx.report/assets/waveform/coherence` 提供分析数据。
4. `make tts assets audio render mux cover publish palette verify`。

`cold_open` 与 `outro` 会使用整幅背景/片尾逻辑；其余 key 使用通用深色背景。画面遵循“一屏一义”：主标题 + 一个主视觉/关键数字 + 底部字幕。

## 接入分析报告

在分析仓库运行：

```bash
audio-forensics analyze media/source.mp4 \
  --reference media/reference.wav \
  --out analysis \
  --url https://www.bilibili.com/video/BVxxxxxxxxxx
```

然后把 `analysis/report.json` 填到 `project/case.toml` 的 `[paths] report`。`assets.py` 会读取 `alignment.lag_s`，并在安装了 `audio_forensics` 包时重算波形、相干和相位曲线：

```bash
.venv/bin/pip install -e /path/to/audio_forensics_repo
```

没有安装分析包时，仍会抽取画面/音乐，但不会生成 `build/waveform.npz`、`build/coherence.npz`；使用这些数据的图表场景需要先补齐数据。

## 输出规格

- 画面：1920×1080，30 fps，H.264 High@4.2，yuv420p，CRF 18；
- 音频：48 kHz 双声道，AAC 320 kbps；集成响度约 −15.5 LUFS，真峰值 ≤ −1.2 dBTP；
- 字幕：`publish/subtitles.srt`，与画面内字幕同文；
- 封面：`publish/cover.png`，1146×717；
- 发布包：`publish/bilibili.md`；审看页：`publish/viewer.html`；
- 色板：`publish/palette_report.md`、`palette_preview.png`、`palette_cvd.png`。

`verify.py` 会检查分辨率、帧率、编码、音频参数、时长、响度、真峰值、字幕末端和封面尺寸。

## 色板

色板在 OKLCH 中生成 12 级语义阶，`bili_video_kit/palette.py` 定义 token，`theme.py` 从 token 取色。`palette_report.py` 输出：

- 12 级中性/青色/琥珀/红色色阶；
- 语义 token 与 WCAG 2.2 对比度；
- protan/deutan/tritan 色觉模拟与 CAM02-UCS 色差。

修改色板后重新跑 `make palette`，并检查 `publish/palette_preview.png` 和实际视频帧。

## 发布

1. `make verify` 通过后，把 `out/*.mp4` 和 `publish/` 下的文件放到同一目录（或同一静态目录）；
2. 用 `publish/viewer.html` 审看；
3. 按 `publish/bilibili.md` 填标题、封面、分区、标签、简介、章节；
4. 单独上传 `publish/subtitles.srt`；
5. 若音乐版权校验受限，改传 `*_nomusic.mp4`。

## 版权

- 音乐/画面引用仅用于评论、研究和方法演示；引用片段版权归原权利人。
- 不提交受版权保护的媒体、TTS 音频和成片到 git。
- 视频结论是工程判断，不是数学证明；保留样本/母带/声学条件等边界。

## 软件

| 软件 | 用途 |
|---|---|
| Python ≥ 3.11 | 运行工具 |
| ffmpeg / ffprobe | 解码、抽帧、混音、封装、校验 |
| edge-tts | 中文旁白 |
| NumPy / SciPy | 数组、滤波、重采样、波形/相干 |
| Pillow | 逐帧绘制、封面、色板预览 |
| colorspacious | 色觉缺陷模拟与 CAM02-UCS 色差 |
| pytest | 单元测试 |