MoeKoe Music Mobile 酷狗音乐 Third-party Mobile Player

Rules:

• Preserve Markdown structure.
• Do not translate URLs and code.
• Return only the translated content without additional commentary.

# MoeKoe Music Mobile

An open-source, simple, and aesthetically pleasing third-party Kugou Music mobile player

Built on Expo / React Native, it is the mobile implementation of the MoeKoeMusic desktop version

🌎 GitHub Repository   |  
📦️ Download Installer   |  
💬 Visit Blog   |  
🏠 Project Homepage

An open-source, simple, and aesthetically pleasing third-party Kugou Music mobile player

Built on Expo / React Native, it is the mobile implementation of the MoeKoeMusic desktop version

✨ Features

• 🎵 No need to build your own server — The Kugou API adapter directly connects to the official server, ready to use out of the box, without relying on external API addresses
• 🏠 Home Page Recommendations — Daily recommendations, selected playlists, and charts
• 🧭 Discovery Page — Category playlists, new song updates, and content exploration
• 🔍 Search — Fast search for songs, playlists, and albums
• 📀 Playlists / Albums / Charts — Complete detail pages and track lists
• 🎧 Player — Scrolling lyrics, play queue, mini player, and background play
• 🎚️ Audio Quality Detection — Automatically detects and selects available audio quality
• 📱 Phone Number Login — Syncs the Kugou account’s favorites and playlists
• 🌗 Dark Mode — Automatically switches between light and dark themes according to the system

📝 Todo List

• [x] Home Page Daily Recommendations / Selected Playlists / Charts
• [x] Discovery Page Category Content Browsing
• [x] Search for Songs, Playlists, and Albums
• [x] Playlists / Albums / Charts Detail Pages
• [x] Player: Scrolling Lyrics, Play Queue, Mini Player, Background Play
• [x] Audio Quality Detection and Automatic Selection
• [x] Phone Number Login
• [x] Account Password Login
• [x] Scan Login (Other Devices)
• [x] Sync of My Favorites / Collections
• [x] User Playlist Management (Create / Collect / Edit)
• [ ] Notification Bar / Lock Screen Play Control
• [ ] Song Detail Browsing
• [ ] Desktop Lyrics
• [ ] Song Recognition
• [ ] Tablet and Landscape Adaptation
• [ ] Performance Optimization

📸 Preview

🚀 Quick Start

Environment Requirements

• Node.js ≥ 22
• Git
• iOS Simulator / Android Simulator, or a real device with the development client installed

Development and Running

# Clone repository (including api submodule)
git clone --recurse-submodules https://github.com/MoeKoeMusic/MoeKoeMusic-Mobile.git
cd MoeKoeMusic-Mobile

# Install dependencies
npm install
npm --prefix api install

# Generate mobile API entry (api/ updated, need to run again)
npm run generate:mobile-api

# Start development server
npx expo start

If you missed the submodule during cloning, you can execute git submodule update --init to fill it in.

Build and Package

The project uses EAS Build :

# Development Client
eas build --profile development --platform android

# Preview Version (internal distribution)
eas build --profile preview --platform android

# Production
eas build --profile production --platform all

🏗️ Project Structure

├── api/                    # KuGouMusicApi（git submodule）
├── scripts/
│   └── generate-mobile-api-entry.mjs   # Scan api/module to generate mobile entry
├── src/
│   ├── app/                # expo-router routes
│   │   ├── (tabs)/         # Home, Discovery, My
│   │   ├── player.tsx      # Full-screen play page
│   │   ├── search.tsx      # Search page
│   │   ├── login.tsx       # Login page
│   │   └── playlist|album|rank/[id].tsx  # Detail page
│   ├── components/ui/      # General UI components (lyrics, queue, mini player, etc.)
│   ├── features/           # Business modules (player / discover / search / account ...)
│   ├── lib/kugou-api/      # In-app API runtime adapter
│   ├── hooks/              # General Hooks
│   └── constants/          # Theme and layout constants
├── app.json                # Expo app configuration
└── eas.json                # EAS build configuration

🔧 Technology Stack

🤝 Related Projects

• MoeKoeMusic — Desktop version (Windows / macOS / Linux)
• KuGouMusicApi — Kugou Music Node.js API, data source for this project

💬 Contributions

Welcome to any form of contribution!

1. Fork this repository
2. Create a feature branch: git checkout -b feat/amazing-feature
3. Commit changes: git commit -m 'feat: add amazing feature'
4. Push branch and initiate Pull Request

If you find a bug or have feature suggestions, please submit Issue .

⚠️ Disclaimer

1. This project is forlearning and technical researchonly, please do not use it for any commercial purposes.
2. This project does not store or distribute any audio resources, all data comes from the official Kugou Music interface.
3. The copyright of the music belongs to Kugou Music and the respective copyright holders, please support authorized music.
4. All consequences arising from the use of this project are borne by the user, and are not related to the developers.

📄 License

This project is open-source under the GPL-2.0 License.