SoranoHako（空之箱）

SoranoHako 是一个使用 Flutter 开发的本地音乐播放器，同时支持通过 JavaScript 音源插件扩展在线音乐搜索、播放、歌词和歌单等能力。

当前版本：0.1.7 Beta

主要功能

• 扫描并播放设备中的本地音乐
• 播放、暂停、切歌、进度跳转和循环模式
• 后台播放、系统媒体通知和播放控制
• 创建、编辑和管理本地歌单
• 收藏歌曲、播放历史和收听统计
• 搜索歌曲、歌手、专辑及远程歌单
• 安装和管理 JavaScript 音源插件
• 在线歌曲及歌词下载
• 下载歌曲封面内置存储，避免封面进入系统相册
• 本地歌词、在线歌词和翻译歌词显示
• 睡眠定时器和音频频谱可视化
• 深色、浅色、跟随系统及自定义主题
• 自定义主题色、背景色、背景图片、模糊度和透明度
• 下载路径、缓存、网络策略、权限和日志管理

在线音乐相关功能需要安装对应的音源插件。项目本身不提供或托管音乐内容。

技术栈

• Flutter / Dart
• just_audio：音频播放
• audio_service：后台播放与系统媒体控制
• Hive：本地数据持久化
• go_router：页面路由
• Dio：网络请求与文件下载
• flutter_qjs_next：JavaScript 音源插件运行环境

支持平台

项目包含以下 Flutter 平台工程：

• Android
• iOS
• Windows
• macOS
• Linux
• Web

部分功能依赖平台能力，例如本地文件访问、后台播放、通知权限和音频频谱，因此不同平台的功能支持可能存在差异。目前建议优先在 Android 上使用和测试。

运行项目

确保本机已安装符合项目要求的 Flutter SDK，然后执行：

flutter pub get
flutter run

运行静态检查和测试：

flutter analyze
flutter test

项目结构

lib/
├── Commons/      路由、图标和通用组件
├── Core/         数据模型、设置、主题和本地存储
├── Data/         数据仓库
├── Extension/    音源插件及 JavaScript 运行环境
├── Pages/        应用页面
├── Services/     播放、下载、缓存、日志等服务
├── Utils/        工具和解析器
└── Widgets/      可复用界面组件

状态说明

项目目前仍处于 Beta 开发阶段，功能和数据结构可能继续调整。使用第三方音源插件前，请确认其来源、权限范围和相关服务条款。

License

本项目许可证见 LICENSE。