dsh-blackhole-radio-lab
Verifieddsh-blackhole-radio-lab · v1.2.7 · MIT · Web UI
A 3D black-hole radio stage for DeepSeek Harness: orbit, zoom and play 24,000+ internet radio stations
Install
dsh plugin add dsh-blackhole-radio-lab Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Readme

黑洞电台 · Black Hole Radio
一块给网络电台用的 3D 黑洞舞台:两万多台真实电台绕着一颗可以环绕、可以播放的黑洞运行。
这是什么
DSH(DeepSeek Harness)的插件。装上之后左栏底部多一张电台卡片,点卡片上的黑洞图标进入全屏舞台:
- 中央是事件视界、光子环与吸积盘,外围是三层视差星场;
- 2.4 万台真实网络电台嵌在吸积盘里,远看是一条亮带,靠近才认得出单个电台;
- 黑洞和星团是同一件东西的两相:按住黑洞,盘面散成星团里的星点;按住星团,星点重新凝聚成盘;
- 点一下星点就播放,悬停出卡片,曲目信息直接来自电台流里的 ICY 元数据。
页面没有常驻搜索栏、分类侧栏或读数面板。搜索和分类只在你主动去点的时候出现。
功能
舞台
- 手写轨道相机:左键拖动环绕、滚轮缩放、阻尼收敛,镜头焦点锁在黑洞核心。
- 原生 Three.js,单个
Points+ 自定义着色器承载全部电台,不为每台电台建 Mesh。 - 远中近三级 LOD:远看连续亮带与密度起伏,中距分辨盘面亮结,近距才显示单个电台与附近台名(台名画在 2D canvas 上,不进 DOM)。
- 星团是真实三维体积:径向密度
u^1.9、三条种子纤维、垂直压扁 0.82,每台电台 5 个微 sprite 在目标处散成 2–5 px 的星结。 - 黑洞与星团之间只有形态转换,没有镜头穿越:环形进度、盘面散开与被吸入的黑洞共用同一个 2.3 s 时钟,按下第一帧就开始动;按住 0.6 s 时环外脉冲一圈表示已识别;松手立即就地回抽,不留残余。
电台
- 2.4 万台以内置快照启动(构建时已逐条探活),缺快照时回落实时抓取。
- 搜索覆盖台名、国家地区、语言、分类;13 个流派直接烘进星团的视觉分区,没有分类面板。
- 播放 / 暂停、上一台 / 随机下一台、音量;启动或卡顿超过 15 秒时,同台最多重连一次,不自动换台。
- 记住音量与最后成功播放站,重开不自动出声;支持系统播放 / 暂停 / 停止控制。后台暂停曲目查询,回到前台立即刷新。
- 悬停卡片:点击播放,显示流派与
LIVE徽标;收藏在左栏底部卡片上。 - 转场按可用的帧时间让步:转场期间若连续出现慢帧,先按视口面积把渲染像素压到 70 万以内,仍然吃紧再逐次降到 0.8 倍,最低 0.5;空闲后自动爬回原倍率。星团的星点着色器按真实像素比换算尺寸,降精度不会把星点放大成块;星空层画在降低后的画布上,会随分辨率一起变细,这是等比例降采样,不是把星星画大。
- 正在播放的曲目取自流内
icy-metaint元数据块;点歌名可在 Spotify / 网易云音乐 / QQ 音乐 / Apple Music / YouTube 中搜索该曲(平台可右键切换)。 - 收藏的电台与喜欢的歌曲持久保存在本机,不联网同步。
- 中文 / English 跟随应用语言。
安装
先决条件:Node.js ≥ 20,DSH(已验证 0.2.1-rc.2 / 0.2.2-rc.1)。
# 从 npm(发布版)
dsh plugin --profile <profile> add dsh-blackhole-radio-lab
# 从本地源码
git clone https://github.com/WhatCannotBeSaid/dsh-blackhole-radio-lab.git
dsh plugin --profile <profile> add "C:/path/to/dsh-blackhole-radio-lab"
装完必须重启 DSH。桌面端进程不会自己发现新 bundle,重建 chunk 之后同理——revision 是启动时算的。
卸载:
dsh plugin --profile <profile> remove dsh-blackhole-radio-lab
上手
| 操作 | 结果 |
|---|---|
| 左键拖动 | 绕黑洞旋转 |
| 滚轮 | 以黑洞为中心缩放 |
| 单击黑洞中心 / 回车 | 打开搜索 |
| 黑洞上按住左键 2.3 s | 盘面沿轴散开、旋卷成星团,黑洞缩到消失;按住 0.6 s 时环外脉冲一圈确认已识别,松手 0.22 s 回抽 |
| 星团或空白处按住右键 2.3 s | 星点沿同向旋卷内收、重新凝聚成盘,黑洞由针尖长大到满;短按(120 ms 内松手)不画进度环,改为在按下处打开收藏列表 |
| 转场途中松手 | 就地回抽,不提交;按住期间移动超过 6 px 同样撤销 |
| 星点上悬停 / 点击 | 悬停卡片 / 播放暂停 |
| 星团形态单击中心 | 不响应(搜索只在黑洞形态的黑体圆盘上单击打开) |
Esc |
关闭浮层或退回黑洞 |
底部卡片独占:站名、曲目行、收藏星标、喜欢心标、播放 / 上一 / 下一 / 音量。
配置
cordis.patch.yml 的条目上可挂 config:
- insert:
- id: blackhole-radio-lab
name: 'dsh-blackhole-radio-lab'
config:
antialias: true
pixelRatioCap: 2
reducedMotion: false
wormhole: true
showHints: true
stationCount: 2400
seed: 20261022
featuredCount: 18
catalogAutoRefresh: true
catalogRefreshDays: 7
catalogTarget: 65000
catalogFetch: 65000
catalogConcurrency: 48
catalogTimeoutMs: 2800
| 键 | 默认 | 范围 | 作用 |
|---|---|---|---|
antialias |
true |
布尔 | WebGL 抗锯齿 |
pixelRatioCap |
2 |
1–4 | 渲染倍率上限 |
reducedMotion |
false |
布尔 | 关闭动画,只渲染单帧;转场也更快 |
wormhole |
true |
布尔 | 按住转换的手势与转场;false 恢复瞬时切换 |
showHints |
true |
布尔 | 显示操作提示 |
stationCount |
2400 |
200–20000 | 模拟数据台数(sourceMode=mock 时生效) |
seed |
20261022 |
0–4294967295 | 数据与空间分布随机种子 |
featuredCount |
18 |
4–40 | 内环精选台数 |
catalogAutoRefresh |
true |
布尔 | 是否每周在后台刷新目录快照 |
catalogRefreshDays |
7 |
1–90 | 缓存超过多少天算过期 |
catalogTarget |
65000 |
1000–65000 | 用户侧快照保留台数 |
catalogFetch |
65000 |
1000–65000 | 探测前抓取的候选数,须 ≥ catalogTarget |
catalogConcurrency |
48 |
1–64 | 探测并发 |
catalogTimeoutMs |
2800 |
500–15000 | 单条探测超时 |
未给的键回落到 index.js 里的 DEFAULTS。调试时也可以给页面加 ?bhrlStations=5000 临时覆盖台数,加 ?bhrlWormhole=0 关掉按住转换做 A/B。
数据来源与隐私
- 电台目录来自 Radio Browser 的公开 API。发布包里的快照由
tools/build-catalog.mjs抓取、逐条探活、按国家与流派保底筛洗而成,构建时间与台数写在 THIRD-PARTY-NOTICES.md。 - 用户侧每周在 DSH 运行期间后台重建一次快照,写入
$DSH_HOME/cache/blackhole-radio-lab/;DSH 没开就不跑,失败只记日志、六小时后再试。 - 播放时浏览器直接连电台的流地址,曲目信息来自该流的 ICY 元数据块(Host 只取一个块即断开)。这些连接会把你的 IP 暴露给对应电台,作者服务器不参与、也看不到。
- Host 的曲目查询只发往公网:回环、私网、链路本地地址的任何写法(含
::ffff:127.0.0.1这类 IPv4 映射形式)都拒绝,域名解析结果里出现私网同样拒绝;重定向逐跳校验、最多 5 跳;别的网站发起的查询直接 403。收藏写入同样要求同源来源与 JSON 正文。 - 收藏、喜欢的歌曲、音量与最后成功播放站保存在本机
$DSH_HOME/blackhole-radio-lab/library.json;失效源记录保存在当前浏览器 IndexedDB,不上传。 - 插件不加载远端脚本,不引 CDN,Three.js 与 hls.js 都是包内私有依赖。
架构
插件分两半:Host 半(index.js + src/host/)只做配置、静态路由、目录刷新与曲目探测,零运行时依赖;浏览器半被打成三个按需下载的 chunk(client.stage.js / client.radio.js / client.hls.js,HLS 播放器按需加载)。
| 路径 | 作用 |
|---|---|
index.js |
Host 入口:配置校验(标准 schema)、路由、卸载清理 |
src/host/library.js |
收藏、歌曲与播放偏好的本机记录(原子写) |
src/host/catalog-builder.js |
目录构建:抓取、探活、保底筛洗(CLI 与 Host 共用) |
src/host/catalog-refresh.js |
每周后台刷新调度与回落规则 |
src/host/now-playing.js |
ICY 元数据探测(只读一个块;逐跳校验重定向与解析出的地址) |
client.js |
浏览器入口:React 组件、样式、槽位注册、懒加载、卸载清理 |
src/stage.js |
渲染入口:renderer / 场景 / 相机、rAF、指针状态机、黑洞↔星团形态转换 |
src/scene/ |
黑体、光子环、吸积盘、星场、轨道相机、共用 GLSL |
src/nodes/ |
电台微结构层、星团层、2D canvas 标签层 |
src/cluster/ |
星团布局与离线投影测量 |
client.stage.js / client.radio.js |
构建产物,不要手改 |
client.hls.js |
构建产物(内联 hls.js,仅 HLS 电台按需加载),不要手改 |
cordis.patch.yml |
bundle 补丁层,一行 loader 条目 |
三个 chunk 只在需要时才下载:
window.__ModuleLoader__.load({
id: 'dsh-blackhole-radio-lab',
chunk: 'client.stage.js',
factory(require) { /* three 已内联,没有裸模块请求 */ },
});
chunk 的 URL 取自入口包的 revision,所以构建脚本会在产物真的变化时顶一下 client.js 的 mtime——不顶这一下,浏览器会拿 immutable 缓存里的旧 chunk。
本地开发
npm install # three + esbuild
npm run build # 重建 client.stage.js、client.radio.js 与 client.hls.js
npm test # 契约测试:转场、播放器、曲目查询、产物
- 只改
src/,然后npm run build。 三个client.*.js是产物。 - 不要在
client.js里import 'three':浏览器侧没有three的基座模块,解析会直接失败。 client.js本身不是构建产物,直接改;但改完必须求值一次真实的模块加载路径(npm test会做:在 vm 里提供window.__ModuleLoader__.load,断言factory返回apply/inject)。- 重建目录快照:
npm run build:catalog(CATALOG_TARGET、CATALOG_FETCH、CATALOG_CHECK_CONCURRENCY等环境变量控制,探测两万台第三方流要几分钟到几十分钟,所以不放进npm run build)。
测试覆盖到哪
npm test 是纯 Node 的契约测试,不需要浏览器:61 个转场用例(含按下即动、松手回抽、回弹复按不跳变、一次长按只跨越一次、左右键同一 2.3 s 时钟、右键短按打开收藏列表、回程单向旋卷与近零进度取消)、19 个播放器降级与失效隔离用例、17 个曲目查询用例(私网字面量与 DNS 解析、逐跳重定向、跨站请求、查询超时)、自适应像素比的预算与回落、89 组真实源码取色与投影映射、真实 SVG 环的时序、以及两个产物 chunk 的 loader 注册冒烟。
它不覆盖 GPU 与浏览器观感:着色器编译、实际帧率、HDR 色调映射的观感只能靠人眼在真机上看。
已知限制
- 无账号、无云同步、无歌单:收藏与喜欢只在本机。
- 部分电台会 404、断流或只在特定地区可用。播放失败不会把电台从目录剔除或永久拉黑:单台在本会话内最多重试 3 次(间隔 1s、2s),仍失败就跳下一台;连续失败只影响自动换台的冷却(10 分钟 / 1 小时 / 6 小时 / 24 小时分级,证据 7 天过期),手动点播随时可放。当前会话不会自动重建目录。
- 关闭窗口时
pagehide立即停止播放;最小化但仍出声时每 3 秒探活本机后端,连续 2 次未应答才停,单次探测 2.5 秒超时也算未应答。 - 系统媒体控制以 metadata 身份避让其他播放器,无法识别只更换 handler 而不更新 metadata 的外部接管。
- 实时抓取路径每次最多取 5,000 台(分页 + 时间预算),内置快照远大于此;快照过期 30 天或台数骤减时会回落实时抓取。
- 本地 DNS 把电台域名解析到私网时(自建 sinkhole、部分加速器),曲目查询会被拒绝,卡片只留空标题;播放走浏览器直连,不受影响。
reducedMotion下转场时间更短,不是完全无动画。- 缩放到最近处时,密集区域的台名仍会互相让位,极端密度下会有标签不显示。
贡献
Issue 与 PR 都欢迎。提交前请跑 npm run build && npm test,并且不要手改 client.*.js 或 data/catalog*.json.gz。
来源与致谢
本站的所有代码与美术资源都是自研,没有从下列项目复制代码、样式或文案。它们在这个领域里先走了一步,本站的设计参考过它们的思路与交互:
| 项目 | 许可 | 本站参考了它的什么能力 | 本站自己的做法 |
|---|---|---|---|
| CXZAAA/dsh-radio | MIT | 把电台做成 DSH 的常驻入口、切台不叠音、失败静默降级、曲目信息来自流内元数据、记忆上次收听与音量 | 入口放在左栏底部卡片,台源改用 2.4 万台内置快照;icy-metaint 由 Host 只读一个元数据块,失败按同台重连一次,偏好写入 $DSH_HOME 原子文件 |
| joeseesun/qiaomu-radio-dsh | GPL-3.0-or-later | 全球电台目录与分类浏览、按场景分组收听、本机口味记忆、系统媒体控制 | 目录改为构建期探活筛选的 Radio Browser 快照,分类收进黑洞舞台的 13 个流派形态;口味记在本机,不含任何 GPL 代码,因此本站仍以 MIT 发布 |
| ebruneton/black_hole_shader | BSD-3-Clause | 实时黑洞渲染的参考实现 | 直接沿用它预计算的零测地线查找表与 TraceRay 结构(唯一真正复制代码的地方),盘面材质、背景与相机自研;细节见 THIRD-PARTY-NOTICES.md,BSD 全文随包分发于 LICENSE-BLACK_HOLE_SHADER 并内联在 client.stage.js 顶部 |
| three.js | MIT | 全部三维渲染的基座 | 构建期内联进 client.stage.js |
性能目标与自适应精度策略(降分辨率优先于降帧率)是本站自己的工程约定,没有照搬任何项目;@deepseek-ai/dsh-client-ui-sidebar 只是宿主提供的注入点。
许可
代码以 MIT 发布。第三方组件与数据的来源、许可与义务见 THIRD-PARTY-NOTICES.md。