lxc-streamutils/docs/components/danmaku-overlay.md

danmaku_overlay 弹幕姬

弹幕姬把一个租户直播源的互动事件投影为透明 OBS 消息墙。它是被动展示组件：不记账、不回复弹幕，也不把 WebSocket 当作持久化业务通道。

订阅事件

组件根据设置动态订阅：

• 弹幕、进房、礼物与礼物连击、醒目留言、舰长、点赞、分享。
• 关闭类别后，后端不为该组件投影对应事件，前端也会进行一次兼容性过滤。
• 未归一化的 live.unknown 默认不进入弹幕姬。

设置

字段	范围/单位	行为
fontScale	50–300%	展开与收缩字号的统一比例
maxVisible	1–12	同时保留的消息卡数量
collapseAfterSeconds	2–120 秒	最新卡从展开态切换到紧凑态
unfoldDurationMs	200–5000 ms	横向卷轴展开动画时间
motionIntensity	0–100%	卡片、流光与焦点动画强度
particleCount	0–12	每卡星花粒子数量
particleSpeed	25–300%	粒子动画速度
lowPerformanceMode	boolean	关闭高成本动态效果
highValueThreshold	千分之一元	高价值礼物起点
featuredValueThreshold	千分之一元	焦点礼物起点
show*	boolean	控制各事件类别订阅

后端的 OverlaySettings::sanitize 是最终边界。控制台 range input 只改善交互，不能取代服务端校验。

卡片生命周期

1. 新事件插入队首，以卷轴动画横向展开。
2. 用户名与内容在展开态分行显示，长内容完整换行。
3. 新事件到达或超时后，旧卡变成紧凑态；内容不会隐藏。
4. 紧凑态缩小字号并尽量压缩布局，但仍允许换行避免截断。
5. 超过 maxVisible 的最旧卡才会离开队列。

花纹由事件类型和事件 ID 的稳定 hash 选择。相邻卡会避开完全相同的款式；礼物连击更新沿用原卡片 key 和装饰，避免视觉跳动。

礼物展示

• live.gift 创建礼物卡；live.gift.combo 使用 comboId 更新同一张卡。
• 元数据优先使用礼物目录中的静态图、GIF、币种和价格。
• GIF 加载失败时降级为静态图片；静态图失败时隐藏图片但保留名称、数量和用户。
• 普通、高价值和焦点礼物按 totalPrice 与两个阈值分级。
• priceCny 只用于人类可读展示；整数 totalPrice 用于精确分级。

弹幕表情

文字和表情按 segments 顺序混排。表情 URL 来自消息本身或用户级表情目录补全；图片使用 no-referrer，失败后显示原始表情文字。整条大表情可通过 standalone 使用更合适的尺寸。

OBS 自适应

• 根背景完全透明，不存在 1920×1080 固定画布。
• ResizeObserver 根据浏览器源实际宽高选择 narrow、short 或 standard。
• 字号和间距使用 CSS custom properties 与 clamp()，OBS 自由缩放时不拉伸素材比例。
• 建议从 360×600、440×760、600×1080 或 720×320 开始测试。
• 低高度会减少视觉密度，但不会把仍在队列中的文字裁成省略号。

测试页面

控制台的事件测试直接构造 canonical LiveEvent，使用当前账户、source 和 component 走同一套订阅、handler、projection 与 EventHub。测试事件标记为 simulated=true，不会发送到 Bilibili，也不会跨组件广播。