随便听

walkman-tv（随便听）项目完整总结 一、项目基础概况 仓库地址：SincereXing/walkman-tv，别名随便听，是原生Android TV大屏音乐播放器，全部代码由Claude Code生成，开源协议为Apache 2.0，当前最新版本v1.3.2（2026-07-16更新），仅2位贡献者，语言以Kotlin（95.3%）为主，适配Android 6.0及以上电视/盒子。 核心前提：安装后必须配置lx-music自定义音源脚本才能正常播放音乐。 二、核心定位与设计特点 1. 遥控器D-pad专属适配 全界面围绕电视方向键、OK、返回键交互，记忆焦点、弹窗默认聚焦，远距离大屏友好；纯暗色主题，绿色为主视觉，大卡片、大封面、清晰层级动效（黑胶旋转、歌词滚动、焦点缩放）。 2. 大屏播放器视觉 全屏播放页含模糊封面背景、旋转黑胶、逐行高亮歌词、音频波形进度条，歌词三档字号可调；支持MV视频播放。 3. 跨设备便捷输入 内置NanoHTTPD局域网服务，电视生成二维码，手机浏览器访问网页推送搜索词、歌单链接，省去遥控器打字。 三、核心功能体系 1. 多平台曲库聚合 对接QQ音乐、网易云、酷狗、酷我四大平台，支持搜索、排行榜、歌单广场、在线歌单一键导入（粘贴/扫码分享链接）；内置kw、wy直连兜底，自定义音源解析失败时自动降级。 2. 8级完整高解析音质体系（扩展洛雪原生音质） 从高到低：臻品母带Master、全景声2.0、全景声、Hi-Res、24bit无损、FLAC无损、320k高品、128k标准；播放/下载自动按设置上限逐级降级，脚本仅需声明quality key即可适配新音质档位。 3. 下载与本地音乐管理 - 单曲/整歌单批量下载，支持1–6并发、断点续传、按新音质重下已存歌曲；自动写入ID3v2.4/FLAC元数据（封面、歌词、曲号等）。 - 可自定义存储目录：内置存储、SD卡、U盘，通过SAF访问任意文件夹；本地扫描导入mp3/flac/m4a/wav等音频文件。 4. 个人曲库 收藏歌曲、播放历史、自建歌单本地JSON持久化；支持歌词翻译开关。 5. 系统设置项 全局播放音质上限、音频HDMI直通（Hi-Res Bit-perfect，电视闪退可关闭）、多平台音源开关、自定义音源管理、下载并发、歌词大小等，修改即时生效本地保存。 6. 自定义音源兼容（核心能力） 完整复刻洛雪音乐lx-music v4 JS脚本协议，通过QuickJS引擎运行第三方音源脚本，支持URL/文件/扫码/粘贴四种导入方式；脚本负责解析播放地址、歌词，平台目录数据（搜索/榜单）走原生直连API。 四、安装部署方式 1. 下载APK：仓库Releases页面提供4种安装包 - universal通用包：全机型兼容；arm64-v8a（2018年后64位电视）；armeabi-v7a老32位盒子；x86_64模拟器/PC盒子。 2. 安装途径 - U盘拷贝APK，电视文件管理器安装； - adb远程连接电视执行 adb install 命令； - 需开启系统「未知来源应用安装」权限。 五、技术栈与项目架构 技术依赖 - 开发语言：Kotlin为主，少量Java、JS；UI：Jetpack Compose for TV - 播放内核：Media3 ExoPlayer；网络：OkHttp + kotlinx.coroutines - JS引擎：QuickJS运行音源脚本；图片：Coil + RenderScript模糊 - 配套组件：ZXing二维码、NanoHTTPD局域网服务、DataStore本地持久化、SAF文件访问；无Hilt，手写简易DI容器AppContainer。 项目目录结构 分层清晰：应用入口、依赖注入、数据模型、本地存储、JS脚本运行层、多平台API目录、播放控制器、全页面UI组件、预加载JS脚本资源。 构建编译 Android Studio JDK17+，compileSdk36，支持打包Debug调试包、Release正式签名包、ABundle上架包；根目录配置keystore.properties可自动签名Release包。 六、开源声明与免责 1. 仅复用洛雪音乐脚本运行协议，不内置任何版权音源资源，曲库、播放地址完全依赖用户自行导入的自定义脚本与公开平台API； 2. 项目仅用于个人学习，使用者需遵守当地版权法规，支持正版音乐； 3. 与各音乐平台、洛雪音乐无官方合作隶属关系。 七、核心亮点总结 1. 专为电视遥控器深度优化的原生TV应用，区别于手机APP拉伸适配； 2. 兼容海量洛雪社区音源脚本，同时扩展8级Hi-Res全景声/母带音质； 3. 局域网手机扫码输入，解决电视打字痛点； 4. 完整本地音乐管理、批量无损下载、多存储介质支持； 5. 纯开源无内置资源，高度自定义音源、音质、下载规则。 walkman-tv v1.3.2 版本详情 基本信息 - 版本号：v1.3.2 - 发布时间：2026年7月16日 15:16 - 提交版本： a827146  - 版本类型：Bug 修复版本（v1.3.1 → v1.3.2，共 2 次提交、4 个文件变更） 本次更新内容 核心修复：歌单页首次进入显示"暂无歌单"Bug 问题根因： 歌单页面（SonglistScreen）存在两个  LaunchedEffect  竞态条件。进入页面时，第一个 effect 将排序方式从 null 改为"最新"，触发列表 effect 重启；被取消的旧 effect 中  runCatching  吞掉了  CancellationException ，其尾部代码在新 effect 写入数据之后才恢复执行，用空列表  emptyList  覆盖了已有数据，导致停在"暂无歌单"状态。切换排序后数据又能正常显示。 修复方案： 1. 新增  ui.fetchOr ：只捕获业务异常，透传协程取消异常，被取消的 effect 会停在 fetch 处，不再覆盖新 effect 写入的状态 2. 排序参数  order  初始值直接设为默认源的第一个排序方式（data class 结构相等，避免首次进入触发无效重启） 3. 排行榜页面（LeaderboardScreen）同款模式一并加固 下载安装包（共 4 个 APK） 安装包 大小 适用设备 SHA256 universal（通用包） 20.4 MB 全架构兼容，不确定机型选这个  2f45437c...7b368c  arm64-v8a 16.8 MB 2018年后主流64位电视/盒子  c158d473...23ea29  armeabi-v7a 16.4 MB 老旧32位电视盒子  dd62e33d...8d4b1b  x86_64 16.8 MB 模拟器 / x86架构PC盒子  6b9b8d96...f7b3cf  另附两份源码包（zip / tar.gz）供自行编译。 安装建议 - 普通用户：直接下载  universal  通用包，兼容性最好 - 追求体积：根据电视芯片架构选对应包（大部分新款电视选 arm64-v8a） - 升级用户：直接覆盖安装即可，本地歌单、收藏、设置不会丢失