maidong-ktv/README.md

麦动 KTV

面向 Android TV 和横屏点歌设备的本地 KTV 应用

遥控器操作 · 歌曲检索 · 点播队列 · 下载管理 · 稳定播放

⚠️ 严正声明 (Important Notice)

本软件是完全免费且公开源码的个人学习与技术交流项目。

• 【禁止任何形式的营利性使用】：本软件（包括源码和编译后的 APK）严禁任何商家或个人进行打包售卖、硬件预装、收费技术支持或商业运营。
• 【侵权必究】：如果您是付费购买的本软件，说明您已被骗，请立即向平台举报商家并退款。
• 完整授权条款请参见项目根目录下的 LICENSE 文件。

核心功能

• TV 遥控器全局导航，支持方向键、确认键、返回键和长按操作。
• 统一焦点反馈，按钮、列表、卡片、开关和弹窗均提供清晰的选中状态。
• 首页提供排行榜、歌名、歌星、常唱、收藏、分类和本地歌曲入口。
• 支持全网与本地歌曲检索、语种筛选、分页浏览和首字母键盘输入。
• 歌星页面支持头像标签分类和歌手歌曲浏览。
• 支持歌曲点播、批量点歌、置顶、收藏、取消收藏和文件管理。
• 已点、已唱和下载列表实时同步歌曲状态。
• 已下载歌曲直接加入队列；未下载歌曲完成下载后自动加入，不打断当前播放。
• 已点列表存在歌曲时自动开始播放，并在切歌后同步队列与播放状态。

播放功能

• 使用 IJK 播放器处理本地和下载歌曲。
• 支持小窗播放与全屏播放，切换页面和执行点歌操作时保持视频连续播放。
• 支持播放、暂停、切歌、重唱、进度显示和拖动。
• 支持原唱与伴唱切换，并保持当前播放或暂停状态。
• 播放状态在小窗、全屏控制栏和提示浮层之间实时同步。
• 支持歌曲片头信息、播放提示和暂停常驻提示。
• 支持视频比例、自动全屏和音画同步设置。
• 支持歌曲最大音量及原唱、伴唱相关声音策略。

下载与数据

• 支持歌曲后台下载、进度展示、断点恢复和失败重试。
• 下载或解密异常时自动清理损坏数据并重新发起任务。
• 支持已下载歌曲识别、数量统计和本地文件播放。
• 支持分片数据库下载、校验、合并和原子更新。
• 存储权限完成后再启动目录创建、数据库扫描和下载任务。
• 支持本地硬盘与 U 盘歌曲扫描、存储空间设置和自动删歌。
• 预留空间提供遥控器可直接选择的容量档位；达到阈值后保护当前及已点歌曲，并按最近使用时间自动清理。
• 应用数据统一保存在麦动 KTV 目录，避免与其他应用的数据冲突。

设置功能

• 数据设置：曲库更新、本地扫描、预留空间、自动删歌和数据库维护。
• 播放设置：自动全屏、视频比例、音画同步和片头字幕。
• 声音设置：音量策略、歌曲最大音量及原唱伴唱策略。
• 界面设置：语言、悬浮按钮、轮播图和歌曲片头字幕。
• 设置弹窗支持临时选择、确认保存和关闭取消，遥控器焦点状态清晰可见。
• 启动时自动检查 Gitee Release；发现更高版本后可在应用内下载并启动系统安装器。

界面与交互

• 界面同时适配电视、横屏手机和平板；窄屏自动压缩栏高、留白、字号和播放器侧栏。
• 全屏播放右上角常驻小型手机点歌二维码。
• 顶部播放控制、小窗控制和全屏控制保持一致的状态与语义。
• 列表刷新、分页、标签切换和点歌后保持真实焦点位置，避免焦点跳动。
• 焦点选中仅改变颜色，不改变控件原有尺寸、圆角或布局。
• 使用麦动圆形 Logo，并在首页、播放页和应用信息中保持统一显示。

热更新与应用发布

• 歌曲接口逻辑位于 app/src/main/assets/mobile/ktv_api.js，安装后的应用会从本仓库自动拉取兼容版本。
• JS 热更新文件必须保留 KTV_BRIDGE_API: 2 标记，未通过兼容校验的远端脚本不会覆盖内置版本。
• 应用更新以 Gitee Release 的标签作为版本号，例如 1.3.0；Release 中必须包含一个 .apk 附件。
• 只有标签版本高于当前 BuildConfig.VERSION_NAME 时，应用才会提示下载更新。

赞助支持

• 感谢各位的使用与支持，留下您的一点小心意，请我媳妇儿喝杯奶茶吧~~