Skip to content

Add NetEase Cloud Music provider#3640

Merged
MarvinSchenkel merged 16 commits intomusic-assistant:devfrom
xiasi0:NeteaseCloudMusic
Apr 20, 2026
Merged

Add NetEase Cloud Music provider#3640
MarvinSchenkel merged 16 commits intomusic-assistant:devfrom
xiasi0:NeteaseCloudMusic

Conversation

@xiasi0
Copy link
Copy Markdown
Contributor

@xiasi0 xiasi0 commented Apr 10, 2026

Summary

  • Add a new NetEase Cloud Music provider for Music Assistant.
  • Implement QR-code login flow (scan with NetEase Cloud Music app) and provider setup UX.
  • Implement core capabilities aligned with existing streaming providers: library sync (artists/albums/tracks/playlists), search, playback, recommendations, lyrics, and quality selection/fallback.
  • Add dynamic recommendation entries for Private FM and Heart Mode, with request/caching safeguards to avoid excessive refresh traffic.

External Service Requirement

  • This provider depends on a NeteaseCloudMusicApi-compatible backend (api_base_url, default http://127.0.0.1:3000).
  • The companion Home Assistant add-on is optional and only intended for plug-and-play setup. It is not a hard project requirement.
  • If the companion add-on is unavailable or blocked in some environments, users can still run any compatible backend service manually and keep using this provider.

Compliance and Access Policy

  • This provider integration itself does not implement unlock, bypass, or crack logic for restricted content.
  • Playback follows account permissions returned by the upstream API service.
  • For non-entitled content, behavior is constrained by upstream response (preview/fallback), without circumvention.
  • We are aware that upstream compatible API documentation mentions capabilities related to forced requests for restricted content; this provider does not use that path, and we have not implemented or tested such behavior in this integration.

Audio Quality Notes

  • Quality is requested via a level ladder with graceful fallback based on account and song entitlement.
  • In testing, high-tier Master 192k can be obtained for eligible advanced subscribers.
  • Standard Hi-Res entitlement often resolves below expected 192k in current upstream behavior; this path still needs further investigation.
  • NetEase Hi-Res catalog spans multiple tiers (for example, ~48k to 192k depending on track/entitlement), but this API path often does not return the expected highest Hi-Res tier for regular subscriptions in current testing.

Related

Testing

  • Local venv checks passed for provider scope (ruff, mypy, compile).
  • Existing related provider tests passed (QQ Music and DLNA test targets).

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Apr 10, 2026

🔒 Dependency Security Report

✅ No dependency changes detected in this PR.

@xiasi0 xiasi0 marked this pull request as draft April 10, 2026 17:59
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ae304cc636

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
@xiasi0 xiasi0 force-pushed the NeteaseCloudMusic branch from ae304cc to 89f5009 Compare April 10, 2026 18:05
@xiasi0
Copy link
Copy Markdown
Contributor Author

xiasi0 commented Apr 10, 2026

Thanks for the heads-up. I cleaned up the branch history and force-pushed.

This PR now contains only one commit for the NetEase Cloud Music provider:

  • 89f5009 Add NetEase Cloud Music provider

The QQ Music commits are no longer part of this PR.\n

Comment thread music_assistant/providers/neteasecloudmusic/manifest.json
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py
Comment thread music_assistant/providers/neteasecloudmusic/constants.py
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py
@xiasi0 xiasi0 marked this pull request as ready for review April 11, 2026 06:17
@xiasi0 xiasi0 requested a review from OzGav April 11, 2026 06:18
Copy link
Copy Markdown
Contributor

@OzGav OzGav left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an initial review. One of the other guys will check this over as well.

Comment thread music_assistant/providers/neteasecloudmusic/__init__.py
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Copy link
Copy Markdown
Contributor Author

xiasi0 commented Apr 11, 2026

Thanks for the initial review.

I’ve addressed the points raised in this round in 02c3519f, and replied inline on each thread. Happy to iterate further after the next review pass.

@xiasi0 xiasi0 requested a review from OzGav April 11, 2026 14:21
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py
@xiasi0 xiasi0 requested a review from OzGav April 19, 2026 14:01
Copy link
Copy Markdown
Contributor

@OzGav OzGav left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Other than the need to remove the Chinese strings once testing is complete I dont see anything else noteworthy. Marvin will get to this when he can I just ask for your patience from here.

@OzGav
Copy link
Copy Markdown
Contributor

OzGav commented Apr 19, 2026

Actually small lint issue

Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
@MarvinSchenkel
Copy link
Copy Markdown
Contributor

Two small things + the Chinese strings and then this should be good to go :)

@xiasi0 xiasi0 requested a review from MarvinSchenkel April 20, 2026 12:48
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Comment thread music_assistant/providers/neteasecloudmusic/__init__.py Outdated
Copy link
Copy Markdown
Contributor

@MarvinSchenkel MarvinSchenkel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You forgot the translations. I put them as inline comments now.

@xiasi0 xiasi0 requested a review from MarvinSchenkel April 20, 2026 13:32
@xiasi0
Copy link
Copy Markdown
Contributor Author

xiasi0 commented Apr 20, 2026

@MarvinSchenkel All translation items from review #4140315742 have now been updated to English in commit c598240, and I also replied on each inline thread. Could you please take another look when you have time? Thank you.

Copy link
Copy Markdown
Contributor

@MarvinSchenkel MarvinSchenkel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, thanks for another great music provider @xiasi0 ! 🙏

@MarvinSchenkel MarvinSchenkel merged commit 9174695 into music-assistant:dev Apr 20, 2026
6 of 7 checks passed
@xiasi0 xiasi0 deleted the NeteaseCloudMusic branch April 21, 2026 12:03
OzGav added a commit to music-assistant/music-assistant.io that referenced this pull request Apr 21, 2026
## Summary
- Add NetEase Cloud Music provider documentation in English and Chinese.
- Add language switch links between EN/ZH pages.
- Add provider icon asset and docs sidebar entry.
- Document local API service requirement and QR login flow.

## Related
- Music Assistant provider PR:
music-assistant/server#3640
- Companion Home Assistant add-on PR:
music-assistant/home-assistant-addon#16

## Notes
- This docs update reflects current integration behavior, including
local NeteaseCloudMusicApi dependency and entitlement-based playback
constraints.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants