Skip to content

a3384379/MusicBleController

Repository files navigation

MusicBleController

English · 简体中文

Turn a Sony Android Walkman into a Bluetooth music bridge for iPhone.
让 iPhone 实时获取 Sony Android 播放器上的 QQ 音乐歌词、封面和播放状态。

iOS 18+ Android 6+ SwiftUI Kotlin

MusicBleController is a source-available iPhone companion for Sony Walkman devices running Android. A lightweight Android agent reads QQ Music playback metadata, QRC lyrics and album art, then streams them to a native SwiftUI app over Bluetooth Low Energy (BLE). The iPhone app provides playback controls, synced lyrics, artwork caching, Dynamic Island and Live Activities.

Important

The current implementation supports QQ Music on Android only. It is an unofficial community project and is not affiliated with Sony, Apple, Tencent or QQ Music.

中文简介

MusicBleController 是面向 Sony Android Walkman 与 iPhone 的 QQ 音乐 BLE 伴侣项目。Sony 端读取 QQ 音乐的播放状态、本地 QRC 逐字歌词和通知封面, 再通过低功耗蓝牙实时同步到 iPhone;iPhone 端负责播放器界面、歌词高亮、封面缓存、 播放控制、锁屏实时活动和灵动岛展示,全程不依赖云端中转服务。

  • 支持 QQ 音乐 QRC 逐字歌词、翻译和罗马音数据;
  • 支持预览封面优先传输、高清封面后台升级和缓存复用;
  • 支持播放、暂停、切歌、进度和音量控制;
  • 针对 Sony 播放器性能和 BLE 带宽做了队列抢占、压缩传输、重试和断线恢复优化。

当前仅支持 Android 版 QQ 音乐,需要自行安装 Sony 端应用,并使用自己的 Apple 开发者签名构建 iOS App。安装、权限、兼容性、排障和开发说明请阅读 完整简体中文文档

Preview

MusicBleController iPhone player UI

More UI and diagnostic previews

iOS preferences and diagnostics UI Sony PlayerAgent debug UI

Why this project?

Sony's Android-based Walkman players can run QQ Music, but their playback state does not naturally integrate with an iPhone. This project connects the two devices without a cloud service:

  • Synced QQ Music lyrics — parses encrypted QRC lyrics, including word-level timing, translation and romanization where available.
  • Fast album art — preview-first BLE delivery, HQ background upgrades, CRC validation and stale-while-revalidate caching.
  • Remote playback controls — play/pause, next, previous, seek and volume.
  • Native iPhone experience — SwiftUI player, full-screen lyrics, lock-screen Live Activity and Dynamic Island support.
  • Connection recovery — capability negotiation, health checks, reconnect protection and old-client protocol fallback.
  • Built for slow hardware — priority-based BLE scheduling, compressed lyric transfers and indexed QRC caches reduce work on the Walkman.
  • Observable and testable — on-device diagnostics plus iOS, Android and cross-device smoke-test suites.

How it works

flowchart LR
    QQ["QQ Music on Sony Walkman"] --> Agent["PlayerAgent · Kotlin"]
    Agent -->|"BLE · lyrics / artwork / state"| iOS["iPhone app · SwiftUI"]
    iOS -->|"BLE · controls / seek / volume"| Agent
    iOS --> Live["Live Activity / Dynamic Island"]
Loading

The Sony device is the authoritative media source. PlayerAgentApp reads MediaSession, notifications and QQ Music's local QRC cache, while the iOS app acts as the BLE controller, cache and presentation layer. No external server is required.

Compatibility

Component Requirement
Music source QQ Music for Android
Sony side Android 6.0+; tested on Sony NW-WM1AM2 (Android 11)
iPhone side iOS 18.0+ with Bluetooth enabled
Development Android Studio/JDK and Xcode with an Apple Development team

Other Android-based Sony Walkman models may work, but hardware and firmware differences have not all been validated. Real-device testing is required; the iOS Simulator cannot validate the BLE media path.

Getting started

1. Build the Sony PlayerAgent

git clone https://github.com/a3384379/MusicBleController.git
cd MusicBleController
bash gradlew :PlayerAgentApp:assembleDebug

Install PlayerAgentApp/build/outputs/apk/debug/PlayerAgentApp-debug.apk on the Sony player. Grant notification access, enable the required accessibility service, then start the PlayerAgent foreground service.

2. Build the iPhone app

  1. Open IOSBleFeasibility/IOSBleFeasibility.xcodeproj in Xcode.
  2. Select your Apple Development team for the app and Live Activity extension.
  3. Replace the sample bundle identifiers and App Group with identifiers owned by your team.
  4. Build and install the app on a physical iPhone running iOS 18 or later.
  5. Keep both devices nearby, open the iPhone app and connect to SonyPlayerAgent.

For deeper implementation and troubleshooting details, see:

Repository layout

Path Purpose
PlayerAgentApp/ Sony/Android media agent and BLE GATT server
IOSBleFeasibility/ Native iPhone app and Live Activity extension
ControllerApp/ Legacy Android controller, retained for compatibility
docs/ Protocol and architecture documentation
tools/ iOS, Android and cross-device smoke tests

Validation

# Android unit tests and debug build
bash gradlew :PlayerAgentApp:testDebugUnitTest :PlayerAgentApp:assembleDebug

# Installed-device quick smoke tests
./tools/smoke/run_all_smoke_tests.sh --quick --json

The repository also includes long-play tests for album art, lyrics, controls, reconnect behavior and current-word timing. See the smoke-test documentation before running tests that operate real devices.

Project status

This is an actively developed, device-specific project rather than a polished App Store product. The BLE protocol preserves compatibility between older and newer builds, but setup currently expects familiarity with Android sideloading and Xcode signing.

Issues and pull requests are welcome, especially for:

  • validation on additional Android-based Walkman models;
  • reproducible BLE performance traces;
  • QQ Music metadata, QRC lyric or album-art edge cases;
  • setup documentation and translations.

If MusicBleController is useful to you, consider starring the repository. It helps other Sony Walkman and iPhone users discover the project.

Acknowledgements

The QRC decryption implementation includes work derived from open-source projects credited in THIRD_PARTY_NOTICES.md.

About

Sony 安卓 Walkman × iPhone 的 QQ 音乐 BLE 伴侣:实时同步 QRC 逐字歌词、封面和播放状态,支持播放控制、Live Activities 与灵动岛。Sony Walkman QQ Music companion over Bluetooth Low Energy.

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages