CyMusic: a custom-source iOS music player built with React Native

Why CyMusic is built around iOS and imported sources

CyMusic addresses a specific gap between a conventional local-music player and a streaming client whose catalog is fixed by the app vendor. It is aimed at iOS users who want one interface for browsing songs, controlling a queue, following lyrics, saving favorites, building playlists, and playing local or cached files. The application also supports QQ Music playlist import and custom scripts supplied as local files or URLs.

The most important product constraint is that CyMusic contains no built-in playback source. A person can install the App, but online playback depends on importing a source with the right to access the desired content. The first imported source is selected automatically. CyMusic can also receive scripts through the iOS system share sheet as files, links, or text, which makes the source layer more flexible than a player with one hard-coded service.

This design targets an audience comfortable with JavaScript-style source scripts and willing to manage their own content access. It is a poor fit for someone expecting a turnkey commercial catalog immediately after installation. Online availability, sound quality, and playback results also depend on the configured source and its third-party services. The README does not claim that every imported source exposes the same endpoints, metadata, lyrics, or error behavior.

CyMusic's React Native and native module structure

Based on the documented stack, the current `main` branch uses Expo 57.0.21, React Native 0.86.3, React 19.2.3, Fabric, Hermes, and React Native's New Architecture. `expo-router/entry` is the package entry point, so application navigation is organized around Expo Router. Zustand is listed for application state, while MMKV 4 through Nitro and AsyncStorage cover two storage layers.

The player dependency is `@rntp/player` 5.9.2. CyMusic adds native capabilities through Expo Modules for operations such as executing music-source scripts, changing system volume, and scheduling sleep timers. Expo FileSystem handles file access, while the repository keeps an `ios/` project and a sharing extension. That native layout is significant because CyMusic is not merely a collection of Expo screens. It includes code that requires compilation into the iOS application.

The user-facing path starts with a source configuration, followed by browsing or selecting music. The App then presents the selected item through its mini player and full player. Queue controls, playback mode, progress, lyrics, favorites, playlists, downloads, and sleep timers operate around that path. Local and cached tracks sit beside imported-source content in the documented feature set. The README does not expose the source module's exact JavaScript interface, so third-party source compatibility should not be inferred from the name of the example repository alone.

Installing CyMusic and configuring the first source

CyMusic supports iOS 16.4 and above. For end users, the README directs people to GitHub Releases or to the successful `main` Actions run, where an unsigned artifact named `CyMusic-unsigned-ipa` can be downloaded. The artifact requires the user's own valid signing and App Group configuration before installation on a physical device.

For development, the documented toolchain is Node 24.19.0, Yarn 1.22.22, CocoaPods 1.16.2, and Xcode 26.6. The following commands clone the repository, install the locked dependencies, install the iOS pods, and launch a native iOS build:

git clone https://github.com/gyc-12/Cymusic.git
cd Cymusic
yarn install --frozen-lockfile --non-interactive
cd ios
pod _1.16.2_ install --deployment
cd ..
npx expo run:ios --no-install

After the application is installed, open Settings, enter Custom Sources, choose an import option, and select either a local script or a script URL. The README links to `CyMusic-ImportMusicApi-Example` as an example, but does not claim that every script from that repository is suitable for redistribution. After the first source is imported, CyMusic selects it automatically. Browse the available catalog, choose a song, and use the mini player to open the full player.

The source is a prerequisite, not an optional refinement. Without one, the documented online catalog and its dependent features will not have content. Local music remains a separate documented capability, but the README does not state whether every playback and lyrics feature behaves identically for local files.

Why CyMusic requires a native iOS build

CyMusic cannot run in Expo Go because it uses custom native modules and retains native iOS code. Developers must not run `expo prebuild` in this repository because doing so could overwrite the maintained `ios/` project and sharing extension. This makes the project closer to a native React Native application than a portable Expo-managed application.

The native requirement has direct maintenance consequences. Dependency upgrades may require checking `yarn.lock`, files under `patches/`, CocoaPods configuration, and the iOS build. `yarn install` invokes `patch-package --error-on-fail` through the `postinstall` script, so a missing or incompatible patch stops installation rather than being ignored. Changes to native dependencies or patches require the App to be rebuilt.

The repository was last pushed on 2026-09-14 and is not archived, while releases 1.1.8, 1.1.9, and 1.2.0 were published in March 2026. This indicates recent repository activity, but the README does not provide a release policy or guarantee long-term compatibility with future Expo and React Native versions. It also separates Releases from `main`, warning that they may differ. Users who need Expo 57 and RNTP v5 should therefore verify that they have selected the correct `main` build rather than assuming the newest Release contains that code.

Seeking, FLAC files, and the cost of precise seeking

CyMusic documents a specific failure mode with some FLAC files: seeking forward can leave audio and lyrics out of sync. Settings, Audio Settings, and Precise Seeking contain an option intended to improve this behavior. It is disabled by default, and CyMusic remembers the selected setting while applying it after changing songs.

The improvement has a performance and startup trade-off. Some files may need to load completely before playback begins, which means a longer wait before playback. CyMusic does not describe Precise Seeking as a universal fix, and it does not claim that every format, source, or seeking pattern will improve. Users should treat it as a format-specific option rather than a default quality feature.

This is a good example of CyMusic's broader limitation. The player combines remote source scripts, local files, caching, lyrics, and native playback, so one setting may affect online tracks, downloaded tracks, and local media differently. The documentation does not publish a compatibility matrix for audio formats, source implementations, or caching states. A prospective adopter should reproduce seeking with the actual files and source that matter rather than infer behavior from the general feature list.

CyMusic's source licensing boundaries and distribution constraints

CyMusic's own source is licensed under Apache-2.0. That license does not automatically cover every dependency or the official App's permitted use. The repository gives separate treatment to `@rntp/[email protected]`, which belongs to Double Symmetry GmbH and is governed by the independent license included under `third-party-licenses/`. The README explicitly says that RNTP v5 is outside CyMusic's Apache-2.0 grant and that CyMusic does not add commercial-use or sublicensing rights for it.

The official App has an additional usage boundary: it is described as permanently free for personal, nonprofessional, noncommercial use, with commercial use prohibited. That statement does not remove the existing Apache-2.0 grant over the project's own source, but it means the source license and official App usage terms should not be treated as interchangeable. Other dependencies retain their own copyright and license terms.

For an individual evaluating personal use, this split licensing is a direct check rather than abstract paperwork. For a company planning a branded service or commercial distribution, the Apache-2.0 label alone is not a sufficient basis. The actual RNTP v5 license and the official App usage terms must be reviewed for the planned distribution model. The README does not provide legal advice or state a separate commercial licensing path.

Comparing CyMusic with the projects it cites

The repository credits `CodeWithGionatha-Labs/music-player`, `lyswhut/lx-music-mobile`, and `maotoumao/MusicFree` as references or sources of inspiration. That is the only comparison detail supplied, so it would be inaccurate to assign those projects capabilities that their documentation does not establish here. None of the cited alternatives can be evaluated from this repository as a complete drop-in replacement.

The concrete alternative approach visible in CyMusic is configuration ownership. Instead of requiring the App release to contain an audio source, CyMusic accepts a source file or URL and runs it through a native source capability. That adds flexibility for personal scripts, but it also moves catalog setup, service compatibility, and content-access responsibility to the user. An application centered on a fixed provider would have less setup and a more predictable catalog, although this README provides no CyMusic competitor against which to quantify those differences.

For a team, the choice is therefore architectural rather than cosmetic. CyMusic is appropriate when local playback and user-supplied source scripts must coexist in an iOS application. It is less suitable when a managed catalog, predictable metadata contract, or unrestricted commercial distribution is required. The alternative selected by an adopter must supply those missing guarantees itself, because CyMusic does not remove them from the product requirements.

Editorial conclusion

CyMusic suits personal iOS users who want local music alongside a separately supplied online source and can maintain a native Expo build. It does not fit Expo Go, Android-focused work, or organizations seeking unrestricted commercial use of the official App. Before adopting it, verify `@rntp/player` licensing for the intended use, confirm that an appropriate source is available, and reproduce local and online playback on the target device.

Frequently asked questions

Official sources

1. gyc-12/Cymusic on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases