BiliLocal完整使用指南：如何为本地视频添加B站风格弹幕

BiliLocal完整使用指南：如何为本地视频添加B站风格弹幕

【免费下载链接】BiliLocal add danmaku to local videos 项目地址: https://gitcode.com/gh_mirrors/bi/BiliLocal

BiliLocal 是一款免费开源的本地视频弹幕工具，它能让你的离线影片像在 B 站一样飘满弹幕。 如果你早已厌倦了"下载到本地就变冷清"的观影体验，这篇 BiliLocal 使用教程会带你从零上手，把弹幕的快乐重新装回你的硬盘。

半夜重温老番，总觉得少了点什么？

凌晨一点，你翻出收藏夹里那部看了五遍的旧番，泡好面，点开播放器——画面依旧，声音依旧，可屏幕却安静得让人不习惯。没有"前方高能"，没有"名场面打卡"，也没有那一条条从右向左飞过、与你隔空击掌的弹幕。

这种感觉太熟悉了：在线看有氛围，离线看没灵魂。 于是你开始搜索"本地视频弹幕工具"，然后遇到了 BiliLocal——一个能把 B 站式弹幕完整搬进本地播放器的开源项目。今天，我们就把它彻底讲明白。

BiliLocal 是什么？它替你解决什么

如果把弹幕比作"客厅里陪你追剧的一群朋友"，那么 BiliLocal 就是把这些朋友打包送进你本地播放器的"搬家服务"。

它基于 Qt 框架开发，采用 GPLv3 开源协议，完全免费、支持离线运行，你在线观看时喜欢的那些东西——滚动弹幕、顶部/底部固定弹幕、屏蔽词、自定义颜色和字号——它全都保留了下来。

更妙的是，它不止是"本地播放器 + 弹幕层"这么简单：

• 兼容面极广：视频支持 MP4、AVI、MKV、MOV、FLV、WMV、RMVB 等几十种格式，弹幕直接读取 XML / JSON 文件；
• 跨平台：Windows、macOS、Linux 都能跑，连 Android 也有对应的 Quick2 界面工程；
• 可接在线数据：内置 Access 模块，能解析 B 站、AcFun、吐槽站、土豆、乐视等站点的弹幕数据，让"本地看片 + 在线弹幕"成为可能。

一句话总结：它把"弹幕的热闹"和"本地的安静"两个看似矛盾的需求，缝合在了一起。

从上图可以看到，弹幕整齐地叠在画面上，滚动模式、颜色层次都还原了在线弹幕的观感。

三步拿到手：最快 5 分钟跑起来

BiliLocal 走的是传统 Qt 项目的路线，上手其实非常简单，三步就够。

第一步：获取源码

打开终端，克隆项目：

git clone https://gitcode.com/gh_mirrors/bi/BiliLocal

第二步：安装 Qt 开发环境

建议使用 Qt 5.15 或更高版本：

• Windows：下载 Qt 在线安装包，勾选 MSVC 编译器与 Qt Multimedia 模块；
• macOS：brew install qt，再装好 Xcode 命令行工具；
• Linux（Debian/Ubuntu 系）：sudo apt-get install qt5-default qt5-qmake qtmultimedia5-dev，如需 VLC 后端，再补一个 libvlc-dev。

第三步：编译并运行

cd BiliLocal
qmake
make

编译完成后，项目根目录下会生成名为 BiliLocal 的可执行文件，运行它即可。整个流程熟悉的话，真的用不了五分钟。

跑通第一个完整任务：给本地视频加上弹幕

光说不练假把式，我们直接做一个完整的任务：给一部本地动漫加上弹幕。

第 1 步：准备弹幕文件

弹幕文件是标准的 XML 格式，B 站导出的弹幕通常长这样：

<?xml version="1.0" encoding="UTF-8"?>
<i>
    <chatserver>chat.bilibili.com</chatserver>
    <chatid>123456</chatid>
    <mission>0</mission>
    <maxlimit>1000</maxlimit>
    <source>k-v</source>
    <d p="10.5,1,25,16777215,0,0,123456,0">名场面打卡</d>
    <d p="15.2,5,25,16711680,0,0,123457,0">前方高能预警</d>
</i>

每条 <d> 标签的 p 属性里，依次是时间点、弹幕模式、字号、颜色、时间戳、弹幕池、用户ID。看不懂没关系，BiliLocal 会自动解析这些字段。

第 2 步：让弹幕和视频"同名同住"

把弹幕文件放到视频所在目录，并保持同名。例如：

• 视频文件：my_anime.mp4
• 弹幕文件：my_anime.xml（或 my_anime.json）

BiliLocal 会自动识别并匹配，省去手动绑定的麻烦。

第 3 步：打开视频，享受弹幕

启动 BiliLocal，把视频文件拖进窗口（或在命令行直接传入文件路径），弹幕就会随着播放进度一条条飘出来。你也可以先用命令行参数快速试一下：

./BiliLocal my_anime.mp4 my_anime.xml

到这一步，你已经成功复现了"本地看片 + 在线氛围"的完整流程。

从设置面板可以看到，字体、颜色、速度、透明度等弹幕参数都可以按需调整，后面我们详细展开。

核心功能逐个拆解

智能屏蔽系统：把讨厌的弹幕挡在门外

这是我最喜欢的模块之一。在 src/Model/Shield.cpp 中，屏蔽系统把弹幕分成了顶部、底部、滚动、反向、游客、高级、彩色、全局八大分组，你可以：

• 按关键词屏蔽：比如一键屏蔽剧透、引战词；
• 按用户屏蔽：拉黑某些"弹幕话痨"；
• 按正则屏蔽：用模式匹配一网打尽复杂变体。

看到满屏"前方高能"刷屏烦了？加个关键词，世界立刻清净。

多种弹幕模式：滚动、顶部、底部随意切换

在 src/Graphic/ 目录下，每个 Mode 文件对应一种渲染模式：

• Mode1：经典从右向左滚动弹幕；
• Mode4：顶部固定弹幕，适合官方注释和高能预警；
• Mode5：底部固定弹幕，常用来做字幕补充；
• Mode6/Mode7：特殊效果与高级模式，给追求炫酷的用户。

同一部视频，你可以把三种模式混着用，观感立刻立体起来。

多播放后端：VLC、Qt Multimedia 自由选择

不同设备对视频解码的需求不同，BiliLocal 在 src/Player/ 里做了多个播放后端：

• VLC 后端（libvlc）：解码能力强，推荐日常使用；
• Qt Multimedia 后端：Qt 自带方案，依赖更轻；
• 哑播放后端：仅处理弹幕层，适合纯弹幕场景。

Linux 版本默认同时编译 VLC 与 QtMultimedia 后端，运行时按需切换即可。

在线弹幕接入：本地视频也能"蹭"站内弹幕

项目里的 src/Access/ 模块负责网络访问与数据解析，支持 B 站、AcFun、吐槽站、土豆、乐视等站点的弹幕格式。把在线弹幕拉取下来挂到本地视频上，等于给老片子续上了当年直播时的"现场弹幕"——0.4.2 版本还特别加入了 A 站番剧与 C 站的支持。

个性化与进阶玩法

玩法一：纯弹幕透明模式

0.4.2 版本新增的"纯弹幕透明模式"，可以让播放器只显示弹幕层。把它叠加在其他播放器窗口上，等于给任意视频软件都装上了弹幕引擎，玩法瞬间打开。

玩法二：时间轴校准

从其他站点抓来的弹幕，时间点常常对不齐。此时可以用弹幕偏移功能，手动调整全局时间差，把"提前了 3 秒"之类的误差一次修正，再保存配置。相关逻辑可以在 src/Model/Running.cpp 中看到实现细节。

玩法三：界面多语言

项目自带 res/zh_CN.ts 与 res/zh_TW.ts 两份翻译文件，简体、繁体中文都能顺畅切换，字幕方面则支持 SRT、ASS、SSA 等常见格式的外挂加载。

常见问题与避坑指南

Q1：弹幕和视频不同步怎么办？

先确认弹幕文件的来源站点与视频版本是否一致；若整体偏差固定，用"弹幕偏移"功能一次性校正；若单条不同步，检查该条弹幕的 p 属性时间戳格式。

Q2：弹幕显示乱码？

BiliLocal 的解析模块会尝试从 XML 声明或 HTML 的 charset 中自动识别编码，优先确保你的弹幕文件是 UTF-8 编码。用文本编辑器另存为 UTF-8 后重新导入，通常即可解决。

Q3：视频很卡或无法解码？

检查播放后端设置，优先切换到 VLC 后端；Windows 用户建议装好显卡驱动，并在工程配置中确认 OpenGL 渲染路径已启用（RENDER_OPENGL）。

Q4：命令行传入多个文件怎么玩？

直接一次性传多个路径，BiliLocal 支持按序播放；如果开启了单实例模式，后续传入的文件会自动转发给已运行的窗口。

Q5：想用命令行批量处理视频？

逐个传入文件路径即可串联处理，例如 ./BiliLocal a.mp4 a.xml b.mp4 b.xml，批量导入弹幕顺手就完成了。

现在就动手，把弹幕装回你的硬盘

回到开头那个深夜——那部旧番还在硬盘里等你。这一次，不用再对着安静的画面发呆了。克隆项目、编译运行、丢进弹幕文件，三分钟之后，"前方高能""泪目""爷青回"会重新飘满你的屏幕。BiliLocal 并不复杂，它只是把你在线观看时最舍不得的那部分热闹，原封不动地还给了你的本地视频。

💡 小贴士：开始之前，先在网上下载一两部经典作品的弹幕 XML 文件备着，跑通第一个流程后，你会立刻明白什么叫"离线观看的乐趣"。祝你弹幕愉快！

【免费下载链接】BiliLocal add danmaku to local videos 项目地址: https://gitcode.com/gh_mirrors/bi/BiliLocal