BarrageOverlay

一个 Windows 全屏弹幕 HTTP API 服务，支持文字样式、不同运动方式和图片弹幕。

A Windows full-screen danmaku (barrage) overlay controlled via HTTP API. Supports text styles, motion types, and image danmaku.

快速开始

# 启动（自动加载 app.config.json 内建样式）
dotnet run

# 指定配置文件
dotnet run -- --config my-config.json

# 发布为单文件 exe
dotnet publish -c Release -r win-x64 --self-contained -p:PublishSingleFile=true

启动后系统托盘出现图标，右键 → 退出。HTTP 服务默认监听 http://localhost:9527。

配置文件

启动时按以下优先级查找配置：

1. --config <path> 命令行指定
2. exe 同级目录 app.config.json
3. 当前工作目录 app.config.json
4. AppConfig.CreateDefault() 代码默认值

{
    "port": 9527,
    "starUnitSize": 10,
    "builtinStyles": [
        {
            "id": "normal",
            "type": "text",
            "fontFamily": "Microsoft YaHei",
            "fontSize": "36px",
            "color": "#FFFFFF",
            "strokeWidth": "3px",
            "strokeColor": "#000000",
            "opacity": 1.0
        }
    ]
}

内置 6 个默认样式：normal | normal-bold | yellow | cyan | green | heart

---

API 参考

所有接口使用 JSON，路径前缀 /api。

样式管理

创建样式

POST /api/styles
Content-Type: application/json

{
    "id": "my-style",       // 可选，不填自动生成
    "type": "text",
    "fontFamily": "Microsoft YaHei",
    "fontSize": "48px",
    "fontWeight": "bold",
    "color": "#FF4444",
    "strokeWidth": "3px",
    "strokeColor": "#000000",
    "shadowColor": "#000000",
    "shadowOffsetX": "4px",
    "shadowOffsetY": "4px",
    "opacity": 0.9
}

获取/删除样式

GET    /api/styles              # 列出所有
GET    /api/styles/{id}         # 获取一个
DELETE /api/styles/{id}         # 删除

弹幕发送

发送弹幕（可覆盖样式字段）

POST /api/danmaku
Content-Type: application/json

{
    "styleId": "normal",
    "text": "弹幕文字",
    "motion": { "type": "auto", "direction": "right-to-left", "speed": 300 },
    // 可选：覆盖样式（以下均为可选）
    "fontFamily": "Consolas",
    "fontSize": "36px",
    "fontWeight": "bold",
    "color": "#00FF00",
    "strokeColor": "#FF0000",
    "shadowColor": null
}

弹幕管理

GET    /api/danmaku              # 列出活跃弹幕
DELETE /api/danmaku/{id}         # 移除指定弹幕

配置管理

GET /api/config                  # 查看配置
PUT /api/config                  # 更新（仅 runtime 生效）
Content-Type: application/json
{ "starUnitSize": 15 }

健康检查

GET /api/health → {"status":"ok"}

---

样式系统

字段说明

字段	类型	说明
id	string	唯一标识，不填自动生成 8 位
type	string	"text" 或 "image"
fontFamily	string?	字体名，默认系统默认字体
fontSize	string?	字号（UnitValue），默认 24px
fontWeight	string?	"normal" / "bold" / "100"-"900"
color	string?	文字颜色（hex），默认 #FFFFFF
opacity	double?	整体透明度 0-1
strokeWidth	string?	描边宽度（UnitValue），null=无描边
strokeColor	string?	描边颜色（hex）
shadowColor	string?	阴影颜色，null=无阴影
shadowOffsetX	string?	阴影水平偏移，默认 "2px"
shadowOffsetY	string?	阴影垂直偏移，默认 "2px"
imagePath	string?	图片路径（仅 image 类型）
width / height	string?	图片尺寸（UnitValue）

图片样式

{
    "id": "avatar",
    "type": "image",
    "imagePath": "./avatar.png",
    "width": "80px",
    "height": "80px",
    "opacity": 0.85
}

---

运动方式

LinearMotion — 直线运动

沿直线从起点移动到终点。

{
    "type": "linear",
    "startX": "0px",       // UnitValue
    "startY": "30%",
    "endX": "100%",
    "endY": "30%",
    "speed": 300,          // 像素/秒
    "displayTime": 4,      // 可选：存活秒数
    "opacityCurve": "ease-out"  // 可选："linear" | "ease-out" | "ease-in"
}

起点/终点使用 UnitValue，负值可表示屏幕外。

AutoMotion — 自动弹幕

自动分配轨道，避免碰撞，横穿/纵穿屏幕。

{
    "type": "auto",
    "direction": "right-to-left",  // right-to-left | left-to-right | top-to-bottom | bottom-to-top
    "speed": 250,
    "displayTime": 3,        // 可选
    "opacityCurve": "linear" // 可选
}

FloatMotion — 气泡浮动

从起始位置向上飘出，左右正弦晃动模拟气泡物理。

{
    "type": "float",
    "startX": "50%",
    "startY": "80%",
    "speed": 50,                   // 上升速度 px/s
    "wobbleAmplitude": "40px",     // 晃动幅度（UnitValue）
    "wobbleFrequency": 1.5,        // 晃动频率 Hz
    "displayTime": 5,              // 可选：不填则自然飘出屏幕后移除
    "opacityCurve": "ease-out"     // 可选
}

每个气泡有随机初相位，多个同时出现不会同步晃动。

---

数值单位 (UnitValue)

三种格式，同时支持整数和小数：

格式	示例	解析规则
"<n>px"	"48px", "1.5px"	屏幕像素
"<n>*"	"3*", "0.5*"	n × starUnitSize 像素（默认 starUnitSize=10）
"<n>%"	"50%", "3.5%"	水平参考屏宽，垂直参考屏高

可通过 PUT /api/config 在运行时修改 starUnitSize。

---

通用参数

所有运动类型支持（在 motion 对象内）：

参数	类型	说明
displayTime	double?	存活秒数，null=按运动自然结束
opacityCurve	string	淡出曲线 "linear" / "ease-out" / "ease-in"，默认 "linear"

---

线程模型

• 主线程 (STA)：WinForms UI + 渲染循环 (~60fps)
• 后台：ASP.NET Core Kestrel 处理 HTTP 请求
• API 通过 Control.Invoke() 调度到 UI 线程创建弹幕元素

渲染管线

Timer.Tick (15ms)
  → 创建 32bpp ARGB 位图
  → 遍历活跃弹幕：Update() + Draw() (GraphicsPath 描边/阴影)
  → UpdateLayeredWindow() 逐像素 alpha 混合到屏幕
  → 清理过期弹幕

测试

test/ 目录包含 REST Client .http 文件，安装 VS Code 扩展后直接 Send Request：

文件	内容
config.http	健康检查 + 配置管理
styles.http	样式 CRUD（创建→弹幕→删除）
builtin-styles.http	内建样式测试
motions.http	三种运动方式全部变体
override.http	样式覆盖测试
management.http	弹幕管理 + 批量发送
edge-cases.http	边界/错误测试

---

项目结构

BarrageOverlay/
├── Program.cs                  # 入口
├── app.config.json             # 配置文件（可选）
├── Models/
│   ├── UnitValue.cs            # 数值单位解析
│   ├── DanmakuStyle.cs         # 样式模型
│   ├── DanmakuRequest.cs       # 弹幕请求 + 样式覆盖
│   └── MotionConfig.cs         # 运动方式 Union
├── Services/
│   ├── AppConfig.cs            # 应用配置 + 默认样式
│   ├── StyleManager.cs         # 样式 CRUD
│   ├── UnitValueResolver.cs    # UnitValue → 像素
│   └── DanmakuManager.cs       # 弹幕生命周期
├── Overlay/
│   ├── OverlayForm.cs          # 全屏透明窗口 + 渲染循环
│   └── DanmakuElement.cs       # 单条弹幕（更新/绘制/释放）
├── Api/
│   └── ApiEndpoints.cs         # REST API 端点
└── test/                       # .http 测试文件

技术栈

• .NET 10
• WinForms
• ASP.NET Core Kestrel
• System.Text.Json 多态序列化
• UpdateLayeredWindow 逐像素 alpha