MusicFree: A Modular Open-Source Music Player for Android and HarmonyOS

MusicFree is an open-source music player designed specifically for Android and HarmonyOS. True to its name, it provides a free and unencumbered environment for your music collection.

The application functions as a shell; it does not ship with any built-in music sources. Search functionality, streaming capabilities, and lyrics—the features that define the experience—are all powered by plugins that you load manually. This modular design keeps the core application lightweight and places complete control in your hands. You choose the sources and decide exactly how music reaches your ears.

Desktop builds are also available for Windows, macOS, and Linux.

Plugin Architecture

By default, the player is a blank canvas. Content is supplied entirely through plugins, which handle the following core functions:

• Search: Locate music by song title, album, artist, or playlist.
• Playback: Stream audio content, browse detailed album information, and view artist profiles.
• Import: Add individual tracks or entire playlists, including synchronized lyrics.

For those familiar with JavaScript, the plugin development documentation provides instructions on how to integrate any music source of your choice.

Custom Themes

The interface is fully customizable through theme packs. Each theme requires two primary files:

1. index.css – This file is used to override the default style variables. The standard variable list is structured as follows:

:root {
  --primaryColor: #f17d34;
  --backgroundColor: #fdfdfd;
  --textColor: #333333;
  /* Refer to the source code for the comprehensive list */
}

You can examine the "Dark Mode" example to see these overrides in practice.

2. config.json – This file manages background assets and provides support for HTML iframes. A standard configuration looks like this:

{
  "name": "Theme Name",
  "preview": "#000000",
  "iframes": {
    "app": "http://musicfree.catcat.work",
    "side-bar": "@/background/sidebar.html"
  }
}

The example repository includes several presets, such as the "Cherry Blossom" theme.

Privacy and Safety

• Ad-Free Experience: Licensed under AGPL 3.0, the app is entirely free and will remain so.
• Local Storage: All user data is stored locally on your device. The application does not transmit your personal information to external servers.
• Auditable Code: As an open-source project, the source code is transparent, allowing anyone to verify the application's behavior.

Installation and Setup

Running the Project

After cloning the repository, execute the following commands from the root directory:

npm install
npm start

Resources

• Theme Examples: https://github.com/maotoumao/MusicFreeThemePacks
• Plugin Documentation: Refer to the plugin section in the Android README.
• Downloads: Binary installers are available via the Feishu cloud document link in the repository.

Theme Preview