Expand description
Async, typed SDK for a focused subset of KuGou Music APIs.
§Design
- Explicit session: device identity and login state live in
Session, not insideKugouClient. Every request takes&mut Sessionso auth changes are visible and serializable (Session::export/Session::import). - Platform profiles:
PlatformProfile::StandardvsPlatformProfile::Litefix appid / salts /clientverfor the client lifetime. - Soft responses: high-churn upstream JSON is mapped to stable SDK types
(
SongRef,SearchSongs,PlaybackInfo, …). Softfrom_valuenever fails on missing or renamed keys; leftovers go to each type’sextramap. For the business payload as-is, call the matching*_rawmethod.ApiResponse::extraholds envelope fields only (no second copy of businessdata);ApiResponse::headersis a diagnostic allowlist and never includesSet-Cookie.
KuGou endpoints are not a public stable API. Fields, signatures, and availability may change with official clients. Prefer this crate for learning and protocol research; respect platform terms and copyright.
§Quick start
use kugou_sdk::{KugouClient, PlatformProfile, Session, SearchRequest};
let client = KugouClient::builder()
.platform(PlatformProfile::Standard)
.build()?;
let mut session = Session::random();
let songs = client
.search()
.songs(&mut session, SearchRequest::new("海阔天空"))
.await?;
for (i, hit) in songs.data.items.iter().enumerate() {
println!("#{i} {} {:?}", hit.display_name(), hit.primary_hash());
}See the repository README.md and docs/ for protocol notes, changelog, and
the interactive test_client example.
§Logging
This crate uses the log facade only — it never installs
a global logger. If the host does not call log::set_logger (or an equivalent
such as env_logger::init), all macros are no-ops.
| Level | Target | Content |
|---|---|---|
debug | kugou_sdk::protocol | One line per HTTP call: method, redacted URL (token/signature → ***), status, elapsed, body lengths |
debug | kugou_sdk::client | Client build summary (platform, timeout, proxy yes/no) |
debug | kugou_sdk::protocol | Upstream business error_code + short message (still returned as KugouError::Business) |
warn | kugou_sdk::protocol | HTTP non-2xx, SSA ssa-code challenges, truncated bodies |
trace | kugou_sdk::protocol | Full wire dump (URL with secrets, headers including Set-Cookie, bodies) |
Do not enable trace in production — it intentionally includes tokens and
cookies for protocol investigation.
RUST_LOG=kugou_sdk=debug
RUST_LOG=kugou_sdk::protocol=traceHosts typically add env_logger (or tracing + tracing-log) and call
try_init once at process start. The test_client example does this with a
default filter of warn.
Re-exports§
pub use album::AlbumDetail;pub use album::AlbumDetailList;pub use album::AlbumSongs;pub use artist::ArtistAlbums;pub use artist::ArtistDetail;pub use artist::ArtistList;pub use artist::ArtistSongs;pub use auth::DeviceRegistration;pub use auth::SmsLogin;pub use auth::TokenRefresh;pub use discovery::DiscoveryCard;pub use discovery::DiscoveryCardRequest;pub use discovery::DiscoveryTag;pub use discovery::card_id as discovery_card;pub use lyric::LyricCandidate;pub use lyric::LyricCandidates;pub use lyric::LyricContent;pub use lyric::LyricDocument;pub use lyric::LyricFormat;pub use lyric::LyricLine;pub use lyric::LyricSearchRequest;pub use lyric::LyricWord;pub use lyric::decode_krc;pub use lyric::parse_krc_text;pub use lyric::parse_lrc_text;pub use playlist::CollectRequest;pub use playlist::PlaylistAdd;pub use playlist::PlaylistDelete;pub use playlist::PlaylistDetail;pub use playlist::PlaylistDetailList;pub use playlist::PlaylistEdit;pub use playlist::PlaylistEditRequest;pub use playlist::PlaylistKind;pub use playlist::PlaylistTag;pub use playlist::PlaylistTags;pub use playlist::PlaylistTrackInput;pub use playlist::PlaylistTracks;pub use playlist::PlaylistTracksWrite;pub use rank::RankEntry;pub use rank::RankInfo;pub use rank::RankList;pub use rank::RankSongs;pub use recommend::CLIENT_PLAYLIST_T_EPOCH_MS;pub use recommend::CLIENT_PLAYLIST_T_WEEK_MS;pub use recommend::ClientPlaylistItem;pub use recommend::EverydayRecommend;pub use recommend::FreshSongAction;pub use recommend::FreshSongs;pub use recommend::FreshSongsRequest;pub use recommend::HeartRadio;pub use recommend::HeartRadioRequest;pub use recommend::PersonalFm;pub use recommend::PersonalFmRequest;pub use recommend::RecommendReportResult;pub use recommend::ReportHistoryRequest;pub use recommend::ReportRepeatedRequest;pub use recommend::client_playlist_week_bucket;pub use search::SearchAlbum;pub use search::SearchAlbums;pub use search::SearchArtist;pub use search::SearchArtists;pub use search::SearchHot;pub use search::SearchHotItem;pub use search::SearchPlaylist;pub use search::SearchPlaylists;pub use search::SearchRequest;pub use search::SearchSongs;pub use search::SearchSuggestion;pub use search::SearchSuggestions;pub use search::SearchVideo;pub use search::SearchVideos;pub use song::AudioQuality;pub use song::MultiQualityPlaybackRequest;pub use song::PlaybackInfo;pub use song::PlaybackOutcome;pub use song::PlaybackRequest;pub use song::ResourceHashes;pub use song::SongDetailList;pub use song::SongRef;pub use user::HISTORY_OP_ADD;pub use user::HISTORY_OP_DELETE;pub use user::HISTORY_SOURCE_APP;pub use user::HISTORY_SOURCE_HARDWARE;pub use user::HistoryDeviceTabs;pub use user::HistoryFetchRequest;pub use user::HistoryRecoverRequest;pub use user::HistorySong;pub use user::HistorySongOp;pub use user::HistoryUploadRequest;pub use user::HistoryUploadResult;pub use user::LatestSongEntry;pub use user::LatestSongs;pub use user::LatestSongsRequest;pub use user::ListenRank;pub use user::ListenRankRequest;pub use user::UpdateCurrSongRequest;pub use user::UserDetail;pub use user::UserHistory;pub use user::UserPlaylist;pub use user::UserPlaylistList;pub use user::UserVip;
Modules§
- album
- Album detail and album song list APIs.
- artist
- Artist detail, songs and albums APIs.
- auth
- Authentication APIs (QR login, SMS send + login, token refresh, device registration, …).
- discovery
- Lite homepage Discovery Card song modules (
single_card_recommend). - lyric
- Lyric search, download, KRC/LRC decode and structured parse for players.
- playlist
- Playlist detail, tracks and mutation APIs.
- rank
- Rank catalogue and rank song list APIs.
- recommend
- Recommendation APIs: 每日推荐 / 猜你喜欢(私人 FM) / 红心电台 + report 反馈.
- search
- Multi-kind search APIs (song / playlist / album / artist / MV).
- song
- Song detail and playback APIs.
- user
- User profile, VIP, cloud play-history, cloud playlist, and Lite youth VIP claim APIs.
Structs§
- ApiResponse
- Successful SDK response with typed data and optional protocol envelope.
- Device
Identity - Stable device identifiers for query signing and login fingerprints.
- Device
Identity Builder - Builder for
DeviceIdentity— preferred path for external music apps. - Kugou
Client - Kugou
Client Builder - Pagination
- Normalized one-based pagination shared by list endpoints.
- Security
Challenge - Upstream anti-automation challenge. The SDK reports it but does not simulate a browser.
- Session
- Explicit, serializable authentication and device state.
Enums§
- Fingerprint
Mode - How Standard-profile login fills body
t1/t2. - Kugou
Error - Library error type for transport, protocol, auth, and decode failures.
- Platform
Profile - Official-client profile whose identifiers and signing salts are emulated.
- Service
- Configurable upstream service used by an endpoint.
Functions§
- calculate_
mid - Decimal digit string of
MD5(value)digest (big-endian), matching officialBigInteger(md5Hex, 16).toString().