Blogfoon

Blogfoon is a personal space for thoughtful notes on technology, coding, travel, and ordinary life.

  • Published:

MoeKoe Music

MoeKoe Music Mobile is an open-source, clean-looking third-party KuGou Music player for mobile devices. It is built with Expo and React Native and written in TypeScript, and it serves as the mobile counterpart to the MoeKoeMusic desktop app. The app targets iOS and Android, and its KuGou API adapter connects directly to official endpoints, so there is no need to run a separate server or point the app at an external API address.

Features

  • 🎵 No self-hosted server — the KuGou API adapter talks to official services directly and works out of the box
  • 🏠 Home recommendations — daily recommendations, curated playlists, and rankings
  • 🧭 Discover page — category playlists, new releases, and other browsing sections
  • 🔍 Search — look up songs, playlists, and albums
  • 📀 Playlist, album, and ranking pages — full detail views and track lists
  • 🎧 Player — scrolling lyrics, play queue, mini player, and background playback
  • 🎚️ Audio quality detection — automatically detects and selects an available quality level
  • 📱 Phone number login — sync favorites and playlists from a KuGou account
  • 🌗 Dark mode — follows the system light/dark theme automatically

Status

  • [x] Home daily recommendations / curated playlists / rankings
  • [x] Discover page category browsing
  • [x] Search for songs, playlists, and albums
  • [x] Playlist / album / ranking detail pages
  • [x] Player: scrolling lyrics, play queue, mini player, background playback
  • [x] Audio quality detection and automatic selection
  • [x] Phone number login
  • [x] Username and password login
  • [x] QR code login (from another device)
  • [x] Likes / favorites sync
  • [x] User playlist management (create / favorite / edit)
  • [ ] Notification bar / lock screen playback controls
  • [ ] Song detail browsing
  • [ ] Floating lyrics overlay
  • [ ] Audio recognition (song identification)
  • [ ] Tablet and landscape adaptation
  • [ ] Performance optimization

Preview screenshots are available in the project repository.

Getting started

Requirements

  • Node.js ≥ 22
  • Git
  • An iOS simulator, an Android emulator, or a physical device with a development build installed

Development

# Clone the repository (includes 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 the mobile API entry (re-run after api/ updates)
npm run generate:mobile-api

# Start the development server
npx expo start

If the submodule was missed during cloning, run git submodule update --init to add it.

Building

The project uses EAS Build:

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

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

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

Project structure

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

Tech stack

<table> <thead> <tr> <th>Category</th> <th>Choice</th> </tr> </thead> <tbody> <tr> <td>Framework</td> <td>Expo SDK 57 + React Native 0.86 + React 19 (React Compiler enabled)</td> </tr> <tr> <td>Routing</td> <td>expo-router (file-based routing + Typed Routes)</td> </tr> <tr> <td>UI</td> <td>Tamagui v2</td> </tr> <tr> <td>Audio</td> <td>expo-audio (background playback support)</td> </tr> <tr> <td>Animation</td> <td>react-native-reanimated 4</td> </tr> <tr> <td>Data source</td> <td>KuGouMusicApi (runs inside the app, no deployment needed)</td> </tr> </tbody> </table>

Related projects

  • MoeKoeMusic — desktop version for Windows / macOS / Linux
  • KuGouMusicApi — Node.js API for KuGou Music, used as the data source for this app

Contributing

Contributions are welcome in any form.

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

If you find a bug or have a feature suggestion, please open an Issue.

Disclaimer

  1. This project is intended for learning and technical research only. Do not use it for commercial purposes.
  2. The project does not store or distribute any audio resources. All data comes from official KuGou Music endpoints.
  3. Music copyright belongs to KuGou Music and the respective rights holders. Please support legitimate music.
  4. Any consequences arising from use of this project are the responsibility of the user and are unrelated to the developers.

License

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

Related Posts