云音 YunYin

第三方网易云音乐客户端，按《云音 音乐客户端设计稿》实现：浅色优先的光晕背景、弥散阴影与 Liquid Glass 导航，附完整深色模式。 一套 Flutter 代码同时产出 Android / Windows / Linux / macOS（并保留 iOS、Web 工程），播放源做成可插拔接口，后续可以接入其他平台。

官网与下载：https://marginal-z.github.io/YUNYIN/

功能

模块	内容
首页	每日推荐（登录后为个性化日推，未登录为飙升榜精选）、歌单精选、最近播放；桌面端附私人雷达
发现	推荐（新碟横幅 + 飙升榜）、排行榜、电台、新碟
乐库	我喜欢 / 最近播放 / 已下载 / 收藏的歌单，我创建的歌单，收藏的专辑、关注的歌手
本地音乐	扫描本机歌曲（Android 系统媒体库，桌面端“音乐”“下载”目录）或手动导入 MP3 / FLAC / M4A / OGG / WAV 等文件与文件夹，读取标签、封面与内嵌歌词，缺少的封面与歌词自动联网补全（按歌名 + 歌手或时长匹配网易云），可与在线歌曲混合播放
听歌统计	只统计实际播放的时长：今日 / 本周 / 累计、最近 7 天、最常听的歌曲与歌手，数据只保存在本机
歌单 / 专辑 / 电台	播放全部、随机播放、批量下载、加入队列
正在播放	背景按封面动态取色；封面、进度拖动、随机 / 单曲循环、喜欢、歌词预览
歌词	Apple Music 风格：逐行弹簧滚动、非当前行按距离模糊；网易云逐字歌词按字填色并上浮，长间奏显示呼吸圆点；背景随音乐流动；支持翻译、点击跳转、拖动 / 滚轮浏览；Android 全屏沉浸显示，控件闲置后自动隐藏
播放队列	顺序 / 随机 / 单曲循环，拖动排序，左滑移除，清空
评论	推荐 / 最热 / 最新，点赞，发表评论
搜索	搜索历史、热搜榜；综合 / 歌曲 / 歌手 / 专辑 / 歌单，关键字高亮
歌手页	关注、播放热门、热门歌曲 / 专辑 / 相似歌手
登录	手机验证码、扫码、邮箱 / 手机密码
设置	音质、淡入淡出、音量均衡、睡眠定时、播放源切换、仅 Wi-Fi 下载、下载音质、清除缓存；外观二级页面：浅色 / 深色 / 跟随系统、五种主题色、液态玻璃（清透 / 柔和）、界面背景（默认 / 封面取色 / 自定义图片）、应用图标跟随主题色、播放页封面取色、歌词字号
更新	启动时检查 GitHub Releases，下载与当前平台、架构、安装方式匹配的安装包并覆盖安装（见下文）
桌面端	玻璃侧边栏、前进 / 后退、红黄绿窗口按钮（关闭 / 最小化 / 最大化）、窗口毛玻璃开关、快捷键、迷你模式

桌面快捷键：空格 播放/暂停 · Ctrl+← / → 上一首 / 下一首 · Ctrl+↑ / ↓ 音量 · Ctrl+F 搜索 · Ctrl+M 迷你模式。

窗口宽度 ≥ 860 时使用桌面布局（侧边栏 + 底部播放条），否则使用移动布局（悬浮玻璃导航 + 迷你播放条），所以平板横屏、窄窗口都能自动切换。

技术架构

• Flutter 3.47：Android / Windows / Linux / macOS / iOS / Web 共用一套界面代码。
• media_kit（libmpv）：全平台音频播放；音量均衡按网易云提供的响度增益调整音量。
• provider：AppSettings、SourceManager、PlayerController、DownloadManager、LocalLibrary、UpdateManager、AppNav 等状态对象。
• window_manager：桌面端无边框窗口与自绘窗口按钮。
• 设计 token 集中在 lib/core/theme/palette.dart（浅色 / 深色两套，均取自设计稿）； 玻璃、CSS 风格外阴影 / 内阴影、linear-gradient 角度、三团 radial-gradient 光晕在 lib/core/ui/ 中按 CSS 语义实现，以便一比一还原。

lib/
├── core/            主题 token、设置、通用组件（玻璃、卡片、按钮、开关、分段控件、图标、封面）
├── data/
│   ├── models.dart  与平台无关的数据模型
│   ├── downloads.dart
│   └── sources/
│       ├── music_source.dart     播放源接口
│       ├── source_manager.dart   注册与切换
│       ├── local/                本地音乐
│       └── netease/              网易云音乐（weapi / eapi 加密，直连官方接口）
├── player/          播放队列、播放模式、淡入淡出、睡眠定时、历史
└── features/        各页面（移动端与桌面端）

接入新的播放源

1. 新建 lib/data/sources/<平台>/<平台>_source.dart，继承 MusicSource。
2. 在 features 中声明支持的能力（SourceFeature），只实现这些方法即可；未实现的入口会自动隐藏或提示不支持。
3. 在 SourceRegistry.create() 中加入实例。设置 → 播放源 里即可切换。

每首歌都带 sourceId，所以播放队列可以混合不同平台的歌曲，播放时会找回各自的源取播放地址。

构建

flutter pub get
flutter run                        # 当前设备
flutter build apk --release        # Android
flutter build windows --release    # Windows（需在 Windows 上构建）
flutter build linux --release      # Linux

Linux 构建需要：clang cmake ninja-build pkg-config libgtk-3-dev libmpv-dev。

推送到 main 后 GitHub Actions 会自动执行检查与测试并构建各平台安装包；推送 v* 标签会发布到 Releases。

发行包与架构

平台	架构	文件	说明
Android	arm64-v8a / armeabi-v7a / x86_64	*-android-<abi>.apk	绝大多数手机选 arm64-v8a；不确定就用 universal
Android	全部	*-android-universal.apk	体积较大，任何设备都能装
Windows	x64	*-windows-x64-setup.exe	安装程序，安装到用户目录，无需管理员权限；推荐
Windows	x64	*-windows-x64.zip	便携版，解压运行 yunyin.exe；Windows on ARM 可通过系统的 x64 转译运行
Linux	x64 / arm64	*-linux-<arch>.deb	sudo apt install ./文件名.deb，自动安装 libmpv
Linux	x64 / arm64	*-linux-<arch>.AppImage	便携版，内置 libmpv，chmod +x 后直接运行
Linux	x64 / arm64	*-linux-<arch>.tar.gz	便携版，内置 libmpv，解压后运行 ./yunyin
macOS	Intel + Apple 芯片	*-macos-universal.zip	未签名，首次打开请右键 → 打开

应用内更新

设置 → 关于与更新 可以手动检查，默认启动时也会自动检查。云音读取 GitHub Releases 的最新版本，只在版本号更高时提示， 按当前的安装方式下载对应安装包并覆盖安装，完成后自动重新打开：

安装方式	更新方式
Android	下载与当前相同 ABI 的 APK，交给系统安装器覆盖安装（首次需允许“安装未知应用”）
Windows 安装程序	静默运行新版安装程序，固定 AppId 覆盖原目录；安装程序拒绝静默降级
Windows 便携版	退出后把新版 zip 解压覆盖到原目录
deb	通过 pkexec apt-get install 升级软件包
AppImage	原子替换 $APPIMAGE 指向的文件
tar.gz 便携版	退出后解压覆盖原目录
macOS	退出后替换 .app

Android 发布包使用固定的发布密钥签名（CI 从 ANDROID_KEYSTORE_BASE64 / ANDROID_KEYSTORE_PASSWORD 两个 secrets 读取， 本地放在 android/key.properties 与 android/app/yunyin-release.keystore，均不入库，可用 tool/android/set_signing_secrets.sh 写入 secrets）。 没有配置密钥时本地构建退回调试签名，而标签发布会直接失败，避免发布无法覆盖安装的 APK。 1.0.x 版本使用的是临时签名，Android 用户需要卸载一次再安装 1.1.0，之后即可应用内更新。

更新说明取自 CHANGELOG.md 中对应版本的段落。

官网

website/ 是静态官网（截图均为应用实际渲染画面），推送到 main 后由 .github/workflows/pages.yml 部署到 GitHub Pages；下载链接在访问时从 GitHub Releases 读取，发布新版本无需改动官网。

测试：

flutter test                                   # 单元测试（加密算法、歌词解析与动效、更新）
flutter test --run-skipped --tags live         # 联网测试网易云接口与真实播放（需要 libmpv）
flutter test integration_test -d <设备>         # 音频链路集成测试（CI 在 Android 模拟器与三大桌面系统上运行）

平台说明

• 刷新率：Android 启动时请求屏幕支持的最高刷新率（90 / 120 / 144Hz…），iOS 开启 ProMotion，Windows 与 macOS 由 Flutter 引擎跟随显示器刷新率出帧。 Linux 版 Flutter 引擎目前没有接入系统垂直同步，固定以 60Hz 出帧，这是引擎本身的限制。
• Linux 流畅度：Wayland 下默认让 GTK 用 OpenGL 绘制窗口（GDK_GL=always），并让 Dart UI 在独立线程运行； 若个别驱动出现显示异常，可用 YUNYIN_GDK_GL=0 yunyin 启动关闭前者。
• 登录：手机号登录优先使用验证码；网易云经常对密码登录要求安全验证，此时会提示改用验证码或扫码。
• Web：网易云接口不允许浏览器跨域请求，Web 版无法使用，不作为发行目标。
• 字体：界面英文数字使用内置 Inter；中文使用系统字体（Android / Linux 为 Noto Sans CJK，Windows 为微软雅黑，macOS / iOS 为苹方）。
• 未登录：网易云对未登录用户只提供部分歌曲的完整播放，会员歌曲为试听片段。
• 性能测试：设置环境变量 YUNYIN_BENCH=1 启动桌面版，会自动滚动页面并在终端输出每帧耗时与帧间隔。
• 截图模式：设置 YUNYIN_SHOTS=<目录> 启动桌面版，应用会以 1440×900 桌面尺寸与 392×850 手机尺寸依次打开首页、播放页、歌词、发现与歌单，把真实渲染结果保存为 PNG 后退出；官网 website/shots/ 中的截图即由此生成（使用全新的配置目录，未登录状态）。

流畅度与适配

• 页面数据按键缓存：再次进入页面直接显示上次的数据，过期后在后台静默刷新；首页数据保存在本机，冷启动立即显示。
• 液态玻璃：「清透」只有一层着色器；「柔和」的模糊层通过 BackdropGroup 共享一次背景截取；静态背景上的侧边栏不做模糊。
• 界面整体等比缩放：手机按 390 宽的设计稿排版后缩放到屏幕（按短边计算，0.82–1.18 倍），桌面窗口小于 1180×760 时等比缩小；系统字体放大限制在 0.9–1.15 倍。横屏播放页与歌词页为左右两栏。
• YUNYIN_BENCH=1 输出各场景的帧耗时；YUNYIN_SHOTS=<目录> 额外生成小屏大字体、横屏与最小桌面窗口的截图，用于检查适配。

液态玻璃

玻璃控件的效果由片段着色器 shaders/liquid_glass.frag 实现，光学模型移植自 liquid-glass-studio（MIT）：边缘厚度内按斯涅尔定律折射并分通道色散、菲涅尔提亮、按法线角度的高光； 「柔和」材质先做半径 16 的高斯模糊并叠加白色色调。着色器作为 BackdropFilter 的图像滤镜运行，需要 Impeller 渲染引擎 （Android、Windows、Linux、macOS 默认启用），其他情况退回普通毛玻璃。第三方许可证见 shaders/THIRD_PARTY_NOTICES.txt，应用内“开源许可”中也可查看。

隐私

云音不收集任何数据。登录凭据（Cookie）只保存在本机，只发送给网易云音乐官方接口。

免责声明

本项目是非官方的第三方客户端，与网易公司及网易云音乐无关，仅供学习交流。音乐内容的版权归各权利人所有，请支持正版。