Content
# Tool List
Tongpin Clean is an Android + Node.js bridge tool for simultaneous music listening. The mobile app reads the current media state and uploads it to the user's own room server; compatible remote MCP, REST API AI clients or web remotes can read songs, current players, progress and lyrics, and send playback control commands.
> **Public Beta Note**: Background command reception, player progress control, and lyric enhancements may still be affected by different mobile systems, player versions, and power-saving strategies. Please do not share the room key in public areas.
## 1.2.0 Update Highlights
- Added basic adaptation for multiple players: **QQ Music, Kugou Music, NetEase Cloud Music**.
- The mobile app will prioritize the currently playing supported player and display the current player in the status and diagnostic information.
- Room API, web remote, and MCP return add `playerName` to facilitate AI or web direct indication of "which player it is from".
- Play, pause, previous, next, and progress jump continue to use Android MediaSession / media keys; whether different players fully support `seek` needs to be verified on real devices.
- QQ Music interface lyrics reading and OCR remain reserved for QQ Music only; Kugou / NetEase Cloud currently use system media session + LRCLIB timeline lyrics.
[](https://render.com/deploy?repo=https://github.com/linzhi-524/tongpin-clean-public-beta)
## Quick Start
### 1. Deploy Your Own Server
Click on the **Deploy to Render** above:
1. Log in to Render.
2. Check the Web Service to be created and modify it to an unused service name according to the prompts.
3. Confirm using the Free plan and start deployment.
4. Copy the Render address after deployment, for example:
```text
https://your-tongpin.onrender.com
```
5. Open `https://your-tongpin.onrender.com/health` and see `ok: true` to indicate the server is normal.
Each user should fill in the Render address obtained after deployment; the public source code will not pre-fill the author's server.
Fill in the basic address in the App, do not add `/mcp`; when connecting to AI clients that support remote MCP:
```text
https://your-tongpin.onrender.com/mcp
```
If you are not using ChatGPT, you can continue to use Tongpin Clean. The public beta provides three entrances:
| Entrance | Suitable for | Address |
| --- | --- | --- |
| MCP | AI clients that support remote MCP / custom connectors | `/mcp` |
| REST API | Dify, Coze, n8n, self-built Bot, scripts, and workflows | `/api/rooms...` |
| Web Remote | Ordinary chat AI users who do not support tool connections | `/control` |
For detailed tutorials, see: [docs/AI连接教程.md](docs/AI连接教程.md).
### 2. Obtain Android APK
Open the repository's **Actions → Build Tongpin Clean → Latest successful run → Artifacts**, download `tongpin-clean-1.2.0-apk`, and extract and install `app-debug.apk`.
This is a debug APK for public testing. Android may prompt that the source is unknown, please only download and install from the Actions build products of this repository.
### 3. Connect Mobile
1. Replace the example server address in the App with your own Render address and click "Save and Detect".
2. Enable notification usage rights.
3. Play songs on QQ Music, Kugou Music, or NetEase Cloud Music.
4. Create a room and properly save the room code and room key.
5. Enable "Background Standby" when needed to receive commands in the background, and allow background running in the mobile system.
6. When enhanced lyrics are needed, you can actively enable QQ Music lyrics reading; OCR is only used as an optional fallback for QQ Music lyrics reading.
## Supported Players
| Player | Package Name | Current Support |
| --- | --- | --- |
| QQ Music | `com.tencent.qqmusic` | State reading, playback control, progress synchronization/jump, QQ interface lyrics reading, OCR fallback |
| Kugou Music | `com.kugou.android` | State reading, playback control, progress synchronization/jump; lyrics use LRCLIB matching |
| NetEase Cloud Music | `com.netease.cloudmusic` | State reading, playback control, progress synchronization/jump; lyrics use LRCLIB matching |
> Note: Play/pause/skip songs are usually stable; progress jump depends on whether the player exposes `seek` capability to Android media sessions. Automatic song search is not enabled for Kugou and NetEase Cloud yet; this can be adapted in a subsequent beta.
## MCP Tools
- `create_room`: Create a room.
- `get_room`: Read songs, current player, progress, lyrics, playback state, and command results.
- `set_playback_command`: Send play, pause, previous, next, and progress jump commands.
- `add_listening_note`: Add listening notes near the current song and progress.
Each room tool call requires the corresponding room code and room key.
## How Other AI Tools Connect
- **ChatGPT**: When using MCP / Apps entrances, fill in `https://your-service-address/mcp`.
- **Claude**: When using custom connectors / remote MCP, fill in the same `/mcp` address.
- **Gemini / Self-built Agent**: Prioritize using MCP client code or REST API; ordinary chat apps can temporarily use web remotes.
- **Dou bao, Tongyi, Kimi, DeepSeek, Kouzi, Dify, n8n, etc.**: If HTTP tools are supported, configure according to REST API; if not supported temporarily, use `/control` web remote.
Complete steps and example requests see: [docs/AI连接教程.md](docs/AI连接教程.md).
## Directory
- `apps/android`: Android client.
- `services/server`: Room API, MCP, and web remote.
- `render.yaml`: Render one-click deployment configuration.
- `.github/workflows/build.yml`: Server test and Debug APK build.
- `docs`: Version description.
## Lyric Strategy
```text
Current song memory cache
↓
LRCLIB intelligent timeline matching (QQ / Kugou / NetEase Cloud can try)
↓ No or timeout
QQ Music interface text node (user actively authorized)
↓ Still can't read
Local Chinese OCR (user actively enabled, Android 11+, QQ Music exclusive fallback)
```
QQ Music interface reading and OCR are still only for QQ Music. The server only receives the current sentence, next sentence, source, and recognition time, not screenshots.
## Render Free Plan Notes
- Free Web Service may hibernate after 15 minutes of no traffic; the next request needs to wait for the service to restart.
- The default file system is temporary; rooms and notes may disappear after service restart or redeployment.
- One-click deployment has disabled automatic deployment; upstream repository updates will not force synchronization updates for other people's instances.
## Known Issues
- Some Android manufacturers may freeze background services, possibly causing commands to be received after returning to the App.
- Different versions of QQ Music's lyrics interface have different structures; lyrics reading and OCR are not guaranteed to always be available.
- Kugou and NetEase Cloud's automatic song search is not open yet; this version only does basic media session adaptation.
- Free Render service may be slow for the first detection or room creation after waking up.
## Privacy and Testing Permissions
Please read:
- [PRIVACY.md](PRIVACY.md)
- [SECURITY.md](SECURITY.md)
- [TESTING_PERMISSION.md](TESTING_PERMISSION.md)
When submitting issues, please attach the mobile brand, Android version, player name and version, App version, reproduction steps, and screenshots with sensitive information obscured.
