From 5cd98f932726bc864ce14deb7d52830ea6c43189 Mon Sep 17 00:00:00 2001 From: zijunchiang Date: Fri, 4 Sep 2026 21:39:30 +0800 Subject: [PATCH] =?UTF-8?q?README:=20=E6=B3=A8=E6=98=8E=E6=A1=86=E6=9E=B6?= =?UTF-8?q?=E6=9D=A5=E6=BA=90=E4=B8=8EDSH(DeepSeek=20Harness)=E9=87=8D?= =?UTF-8?q?=E5=86=99=E8=AF=B4=E6=98=8E,=20=E6=96=B0=E5=A2=9E=E7=BC=96?= =?UTF-8?q?=E8=AF=91=E6=95=99=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.en.md | 38 +++++++++++++ README.md | 148 ++++++++++++++++++++++++++++++++++++++------------- 2 files changed, 150 insertions(+), 36 deletions(-) diff --git a/README.en.md b/README.en.md index 963177b..5b2d28f 100644 --- a/README.en.md +++ b/README.en.md @@ -56,3 +56,41 @@ - Stable focus during list refreshes, paging, tab changes, and song ordering. - Focus changes color only and preserves each control's original dimensions, corners, and layout. - A consistent circular Maidong logo across the home screen, player, and application information. + +## Project Notice + +> **UI/feature framework credit**: [https://gitee.com/yangyachao-X/maidong-ktv](https://gitee.com/yangyachao-X/maidong-ktv) +> +> This repository reworks the upstream "Maidong KTV" UI and feature framework, and the core/data layer was +> rewritten with **DSH (DeepSeek Harness)**: library sync, song-source integration, device auth, +> risk-control handling, remote logging, and ad blocking are all new implementations. + +Highlights of the reworked data layer: + +- **Library**: synced exclusively from the official Muse service + (`mconn.cherryonline.cn` `mls-api/v1/sqlite/sync`); Gitee hosts code only, no database files. +- **Song source**: `w.w345.my` (`i.php` token → `do.php` playback URL) with fixed device identity and + reproduced signing; ad/mismatched resources (e.g. `wb66.cn/.../719.ts`) are blocked and retried. +- **Remote logging**: optional RFC 3164 syslog over TCP+TLS (`zb.kasugano.cn:514`). +- **JS hot-update**: `app/src/main/assets/mobile/ktv_api.js`, requires the `KTV_BRIDGE_API: 7` marker. + +## Building + +Requirements: JDK 17, Android SDK (`compileSdk 35`, `minSdk 21`, `targetSdk 25`), +Gradle wrapper 8.13 (bundled). + +```bash +cd maidong-ktv +export JAVA_HOME=/path/to/jdk-17 +export ANDROID_HOME=/path/to/android-sdk +export ANDROID_SDK_ROOT=$ANDROID_HOME +./gradlew assembleRelease +``` + +The release signing config in `app/build.gradle` expects `../../ktv_keystore.jks` (one level above the +repo root) with alias `ktv` / password `123456`; adjust paths or use `signingConfigs.debug` for a +quick unsigned build. Output: `app/build/outputs/apk/release/app-release.apk` +(dual ABI: `armeabi-v7a` + `arm64-v8a`). Install with `adb install -r `. + +For non-commercial learning purposes only. Respect upstream copyright and song licensing. + diff --git a/README.md b/README.md index ccabb0c..e26bf81 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,17 @@

麦动 KTV

-

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

+

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

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

-## ⚠️ 严正声明 (Important Notice) +## 📌 项目说明 + +> **内容框架来源**：[https://gitee.com/yangyachao-X/maidong-ktv](https://gitee.com/yangyachao-X/maidong-ktv) +> +> 本仓库基于上游「麦动 KTV」的界面与功能框架进行改造，并使用 **DSH（DeepSeek Harness）** 重写内核与数据源：重新实现曲库同步、歌曲源接入、设备认证、风控应对、远程日志与广告屏蔽等底层逻辑。上游框架的版权归原作者所有，本项目仅作学习与技术交流。 + +## ⚠️ 严正声明 本软件是**完全免费且公开源码**的个人学习与技术交流项目。 @@ -27,56 +33,126 @@ - 已点、已唱和下载列表实时同步歌曲状态。 - 已下载歌曲直接加入队列；未下载歌曲完成下载后自动加入，不打断当前播放。 - 已点列表存在歌曲时自动开始播放，并在切歌后同步队列与播放状态。 +- 手机扫码点歌（局域网 HTTP 服务 + 二维码）。 ## 播放功能 -- 使用 IJK 播放器处理本地和下载歌曲。 +- 使用 IJK 播放器处理本地与下载歌曲（双 ABI：arm64-v8a / armeabi-v7a）。 - 支持小窗播放与全屏播放，切换页面和执行点歌操作时保持视频连续播放。 - 支持播放、暂停、切歌、重唱、进度显示和拖动。 - 支持原唱与伴唱切换，并保持当前播放或暂停状态。 -- 播放状态在小窗、全屏控制栏和提示浮层之间实时同步。 - 支持歌曲片头信息、播放提示和暂停常驻提示。 - 支持视频比例、自动全屏和音画同步设置。 -- 支持歌曲最大音量及原唱、伴唱相关声音策略。 -## 下载与数据 +## 内核与数据源（DSH 重写部分） -- 支持歌曲后台下载、进度展示、断点恢复和失败重试。 -- 下载或解密异常时自动清理损坏数据并重新发起任务。 -- 支持已下载歌曲识别、数量统计和本地文件播放。 -- 支持分片数据库下载、校验、合并和原子更新。 -- 存储权限完成后再启动目录创建、数据库扫描和下载任务。 -- 支持本地硬盘与 U 盘歌曲扫描、存储空间设置和自动删歌。 -- 预留空间提供遥控器可直接选择的容量档位；达到阈值后保护当前及已点歌曲，并按最近使用时间自动清理。 -- 应用数据统一保存在麦动 KTV 目录，避免与其他应用的数据冲突。 +- **曲库**：统一走**官方 Muse 同步**（`mconn.cherryonline.cn` `mls-api/v1/sqlite/sync`，RSA 登录 + 增量文件校验），不再依赖 Gitee 承载数据库；Gitee 仓库仅存代码。 +- **歌曲源**：接入 `w.w345.my`（`i.php` 取 token → `do.php` 解析播放地址），固定设备标识并复刻签名算法；广告/错号资源（如返回 `wb66.cn/.../719.ts` 或文件名与 musicno 不一致）会被拦截并重试。 +- **风控应对**：源对陌生出口 IP 存在试用窗口（约 10 分钟，403"检测到异常行为"），App 检测到 403 后弹窗提示更换公网 IP；同 token 退避重试，不放大请求量。 +- **远程日志**：可选的 syslog 客户端（RFC 3164，TCP+TLS，`zb.kasugano.cn:514`），启动上报设备/网络信息，点歌实时记录「编号 / 标题 / 请求源 / 状态」。 +- **JS 热更新**：歌曲接口逻辑在 `app/src/main/assets/mobile/ktv_api.js`，安装后从本仓库自动拉取兼容版本（须保留 `KTV_BRIDGE_API: 7` 标记）。 +- **应用更新**：以 Gitee Release 标签作为版本号（如 `1.2.5`），Release 需附带一个 `.apk` 附件；仅当标签高于当前 `BuildConfig.VERSION_NAME` 时提示下载。 -## 设置功能 +## 🔧 编译教程 -- 数据设置：曲库更新、本地扫描、预留空间、自动删歌和数据库维护。 -- 播放设置：自动全屏、视频比例、音画同步和片头字幕。 -- 声音设置：音量策略、歌曲最大音量及原唱伴唱策略。 -- 界面设置：语言、悬浮按钮、轮播图和歌曲片头字幕。 -- 设置弹窗支持临时选择、确认保存和关闭取消，遥控器焦点状态清晰可见。 -- 启动时自动检查 Gitee Release；发现更高版本后可在应用内下载并启动系统安装器。 +### 1. 环境要求 -## 界面与交互 +| 项目 | 要求 | +|---|---| +| JDK | OpenJDK **17** | +| Android SDK | `compileSdk 35`、`minSdk 21`、`targetSdk 25` | +| Gradle | 使用仓库自带 wrapper（**8.13**），无需单独安装 | +| 构建系统 | Linux / macOS / Windows（命令行） | -- 界面同时适配电视、横屏手机和平板；窄屏自动压缩栏高、留白、字号和播放器侧栏。 -- 全屏播放右上角常驻小型手机点歌二维码。 -- 顶部播放控制、小窗控制和全屏控制保持一致的状态与语义。 -- 列表刷新、分页、标签切换和点歌后保持真实焦点位置，避免焦点跳动。 -- 焦点选中仅改变颜色，不改变控件原有尺寸、圆角或布局。 -- 使用麦动圆形 Logo，并在首页、播放页和应用信息中保持统一显示。 +### 2. 准备 Android SDK -## 热更新与应用发布 +安装 `platforms;android-35`、`build-tools`（≥ 34）与平台工具，并接受许可： -- 歌曲接口逻辑位于 `app/src/main/assets/mobile/ktv_api.js`，安装后的应用会从本仓库自动拉取兼容版本。 -- JS 热更新文件必须保留 `KTV_BRIDGE_API: 2` 标记，未通过兼容校验的远端脚本不会覆盖内置版本。 -- 应用更新以 Gitee Release 的标签作为版本号，例如 `1.3.0`；Release 中必须包含一个 `.apk` 附件。 -- 只有标签版本高于当前 `BuildConfig.VERSION_NAME` 时，应用才会提示下载更新。 +```bash +export ANDROID_HOME=/path/to/android-sdk +export ANDROID_SDK_ROOT=$ANDROID_HOME +yes | sdkmanager --licenses > /dev/null +sdkmanager "platforms;android-35" "build-tools;35.0.0" "platform-tools" +``` -## 赞助支持 +### 3. 配置签名密钥 -- 感谢各位的使用与支持，留下您的一点小心意，请我媳妇儿喝杯奶茶吧~~ +`app/build.gradle` 的 release 签名默认读取仓库外相对路径的密钥： -![输入图片说明](WX_resized.jpg) +```groovy +storeFile file("../../ktv_keystore.jks") +storePassword "123456" +keyAlias "ktv" +keyPassword "123456" +``` + +即密钥位于仓库根目录的上一级（`<项目根>/../ktv_keystore.jks`）。若没有该密钥，可用 keytool 生成并放到对应位置（或直接改 `app/build.gradle` 中的路径与口令）： + +```bash +keytool -genkeypair -v \ + -keystore ../ktv_keystore.jks \ + -alias ktv -keyalg RSA -keysize 2048 -validity 10000 \ + -storepass 123456 -keypass 123456 \ + -dname "CN=Maidong KTV, OU=Dev, O=Maidong, L=Beijing, ST=Beijing, C=CN" +``` + +> 若只想快速跑通、不关心签名，可把 `app/build.gradle` 的 `signingConfigs.release` 临时替换为 `signingConfigs.debug`。 + +### 4. 执行编译 + +```bash +# 仓库根目录 +cd maidong-ktv + +export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 # 按本机实际 JDK 路径调整 +export ANDROID_HOME=/path/to/android-sdk +export ANDROID_SDK_ROOT=$ANDROID_HOME + +./gradlew assembleRelease +``` + +首次运行会自动下载 Gradle 8.13 与依赖，耗时取决于网络。构建成功后在： + +``` +app/build/outputs/apk/release/app-release.apk +``` + +产物为已签名的 release APK，包含 `armeabi-v7a` 与 `arm64-v8a` 双 ABI。 + +### 5. 安装到设备 + +```bash +adb install -r app/build/outputs/apk/release/app-release.apk +``` + +首次启动会自动初始化曲库（官方 Muse 同步，需联网）；播放歌曲时由 `ktv_api.js` 实时解析 `w.w345.my` 播放地址并下载到本地。 + +### 6. 常见问题 + +- **曲库初始化失败**：检查设备网络能否访问 `mconn.cherryonline.cn`；已在设置页提供「重置数据库」。 +- **点歌报 403 / 无播放地址**：多为歌曲源对当前公网 IP 的试用窗口到期，重启光猫/路由器更换公网 IP 后恢复。 +- **热更新脚本不生效**：确认远端 `ktv_api.js` 保留 `KTV_BRIDGE_API: 7` 标记，否则内置版本优先。 +- **想改签名/ABI**：编辑 `app/build.gradle` 的 `signingConfigs` 与 `ndk.abiFilters` 后重新编译。 + +## 项目结构 + +``` +maidong-ktv/ +├── app/ +│ ├── src/main/java/com/local/ktv/ # Kotlin 源码 +│ │ ├── MainActivity.kt # 主界面 / 播放 / 下载编排 +│ │ ├── MuseDbSync.kt # 官方曲库同步 +│ │ ├── MuseDatabase.kt # 曲库访问 +│ │ ├── KtvJsBridge.kt # JS 桥(HTTP/RSA/热更新) +│ │ ├── MiliLog.kt # 远程 syslog 日志 +│ │ └── SongOkDownloadManager.kt # 下载管理 +│ ├── src/main/assets/mobile/ktv_api.js # 歌曲源逻辑(热更新) +│ └── src/main/res/ # 资源 / 证书 +├── tools/ # 辅助脚本 +├── build.gradle / settings.gradle +└── gradlew +``` + +## 免责声明 + +本项目仅用于个人学习与技术交流。请遵守所在地区法律法规，尊重上游作者版权与歌曲版权；请勿将本软件用于任何商业或侵权用途。