Sonic Topography 是一个基于 TypeScript 的本地音乐可视化项目，将音乐频段实时映射为 3D 棋盘式海浪/地形效果，包含起伏、发光、波纹、流星、歌词展示等视觉元素。项目支持本地音频上传、内置 Demo、系统音频采集，以及通过手动填写网易云 Cookie 搜索和播放当前账号可播放的网易云歌曲。它还支持主题自定义、视觉 EQ、特效触发器、本地歌单、预设导入导出、Windows 单 EXE 打包和 Wallpaper Engine Web 壁纸构建。
适用领域
音乐可视化 / Web 3D 交互 / 音频分析 / 前端创意编程 / 个人娱乐工具 / 桌面本地应用 / Wallpaper Engine 壁纸 / 网易云音乐相关工具
配置难度
中等。普通用户通过 Windows EXE 或启动脚本使用难度较低；开发者从源码运行只需 Node.js、npm install 和 npm run dev。若涉及 Windows EXE 打包、Go 构建、macOS 交叉编译、Wallpaper Engine 构建、网易云 Cookie 配置或音频采集兼容性调试，则需要一定前端、Node.js、Go 和浏览器调试经验。
商业价值
商业价值受限。项目视觉表现强，适合音乐可视化展示、动态壁纸、个人娱乐、前端创意技术学习和非商业作品展示；但 README 明确禁止未经许可用于商业项目、商业演出、商业展示、付费服务、二次销售或任何营利用途，且许可证不明确、网易云接口和 Cookie 方案存在合规与稳定性风险。因此它更适合作为学习研究、个人作品、开源参考和非商业体验项目，而不适合直接商业化落地。
01
技术亮点
- 视觉效果完整：低频、中频、高频分别驱动地面起伏、波纹、发光和细节闪烁。
- 交互体验丰富：包含侧边栏、播放卡片、歌词、底部频段数据、全屏、主题切换等界面元素。
- 本地和在线音乐结合：既支持上传本地音频，也支持网易云搜索和账号权限过滤。
- 支持系统音频采集，可让电脑上其他播放器的声音驱动画面。
- 可配置性强：主题、视觉 EQ、脉冲、流星、播放卡片显示都可调整。
- 支持预设导入导出，方便迁移主题、EQ、触发器和歌单配置。
- 可打包为 Windows 单 EXE，降低普通用户使用门槛。
- 可构建为 Wallpaper Engine Web 壁纸，适合动态桌面场景。
- README 中文说明详细，对国内开发者和用户较友好。
- 项目 star 数和 fork 数相对可观，说明已有一定关注度。
02
目标用户
- 喜欢音乐可视化和动态桌面的个人用户
- 前端开发者、Three.js/WebGL/音频可视化学习者
- 希望制作本地音乐展示效果的创意开发者
- Wallpaper Engine 壁纸创作者
- 需要在本地展示音乐响应视觉效果的非商业用户
- 想研究网易云网页接口调用和 Cookie 鉴权逻辑的开发者
03
配置要求
- 基础源码运行需要 Node.js 和 npm。
- Windows 单 EXE 打包需要 Node.js 和 Go。
- 网易云搜索和账号相关功能需要用户手动从 music.163.com 复制 Cookie 并粘贴到设置页。
- 网易云 Cookie 保存在浏览器 localStorage，并同步到本地代理内存；默认不会导出到预设文件。
- 主题、触发器、地面 EQ、Cookie 等设置主要保存在浏览器 localStorage。
- 源码运行时本地歌单由 /api/playlists 保存到项目 data/playlists.json，同时浏览器保留 fallback。
- Go EXE 运行时本地歌单默认保存到用户配置目录，例如 Windows 的 %APPDATA%/SonicTopography/playlists.json。
- EXE 固定使用 http://127.0.0.1:4173，如果端口被其他程序占用，需要先关闭占用程序。
- macOS 二进制交叉编译需要 Go 环境，生成文件未经过 Apple 签名和公证，首次运行可能需要手动允许。
- 系统音频采集能力依赖浏览器和系统权限，实际效果可能因环境不同而不同。
04
适用场景
- 播放本地音乐时生成 3D 音频响应地形
- 上传本地音频和 LRC 歌词，进行沉浸式音乐播放
- 采集系统正在播放的声音，用于驱动可视化画面
- 通过网易云 Cookie 搜索和播放账号权限内可播放歌曲
- 查看网易云喜欢、歌单、每日推荐等入口
- 保存本地歌单，重启后继续使用
- 自定义主题颜色、发光强度、旋转速度和播放器卡片显示
- 调节视觉 EQ、脉冲特效、流星特效来改变画面响应
- 导出和导入主题、EQ、触发器、歌单等预设
- 打包成 Windows 单 EXE，方便普通用户直接运行
- 构建为 Wallpaper Engine Web 壁纸目录
05
部署与配置
- 安装 Node.js。
- 克隆或下载仓库：git clone https://github.com/yin-yizhen/sonic-topography.git。
- 进入项目目录：cd sonic-topography。
- 安装依赖：npm install。
- 开发模式运行：npm run dev。
- 浏览器打开：http://127.0.0.1:3000。
- 生产构建：npm run build。
- 生产本地运行：npm start。
- 生产服务默认打开：http://127.0.0.1:4173。
- Windows 用户也可以双击 start-sonic-topography.bat 自动安装依赖、构建并启动本地服务，但仍需要安装 Node.js。
- 如需打包 Windows 单 EXE，需额外安装 Go，然后执行：npm run build:go-exe。
- 生成的 SonicTopography.exe 可直接双击运行，普通使用者不需要安装 Node.js 或 Go。
- 如需构建 Wallpaper Engine 壁纸，执行：npm run build:wallpaper，产物在 dist-wallpaper/。
06
风险与注意事项
- 许可证为 NOASSERTION，仓库未明确标准开源许可证，二次开发、分发和商用存在法律不确定性。
- README 明确声明仅供学习、研究和个人非商业体验使用，不授权商业用途。
- 网易云功能依赖网页接口和 Cookie，可能受版权、会员、地区、账号状态、接口变更影响，稳定性不可完全保证。
- Cookie 属于敏感登录凭证，用户复制和保存 Cookie 存在泄露风险。
- 通过 Cookie 使用网易云相关能力可能触及平台服务条款风险，需要谨慎使用。
- 系统音频采集在不同浏览器、操作系统和权限设置下表现可能不一致。
- 3D 可视化和发光特效可能对低性能设备、集显或移动设备造成较高性能压力。
- 本地数据部分存储在 localStorage，清理浏览器数据可能导致设置丢失。
- EXE 固定使用 4173 端口，端口冲突时需要用户手动处理。
- macOS 构建未签名和公证，对普通用户分发体验不佳。
2026-06-25
第22名
新收录 · github_search
