Skip to main content

Crate kugou_sdk

Crate kugou_sdk 

Source
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 inside KugouClient. Every request takes &mut Session so auth changes are visible and serializable (Session::export / Session::import).
  • Platform profiles: PlatformProfile::Standard vs PlatformProfile::Lite fix appid / salts / clientver for the client lifetime.
  • Soft responses: high-churn upstream JSON is mapped to stable SDK types (SongRef, SearchSongs, PlaybackInfo, …). Soft from_value never fails on missing or renamed keys; leftovers go to each type’s extra map. For the business payload as-is, call the matching *_raw method. ApiResponse::extra holds envelope fields only (no second copy of business data); ApiResponse::headers is a diagnostic allowlist and never includes Set-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.

LevelTargetContent
debugkugou_sdk::protocolOne line per HTTP call: method, redacted URL (token/signature → ***), status, elapsed, body lengths
debugkugou_sdk::clientClient build summary (platform, timeout, proxy yes/no)
debugkugou_sdk::protocolUpstream business error_code + short message (still returned as KugouError::Business)
warnkugou_sdk::protocolHTTP non-2xx, SSA ssa-code challenges, truncated bodies
tracekugou_sdk::protocolFull 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=trace

Hosts 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.
DeviceIdentity
Stable device identifiers for query signing and login fingerprints.
DeviceIdentityBuilder
Builder for DeviceIdentity — preferred path for external music apps.
KugouClient
KugouClientBuilder
Pagination
Normalized one-based pagination shared by list endpoints.
SecurityChallenge
Upstream anti-automation challenge. The SDK reports it but does not simulate a browser.
Session
Explicit, serializable authentication and device state.

Enums§

FingerprintMode
How Standard-profile login fills body t1 / t2.
KugouError
Library error type for transport, protocol, auth, and decode failures.
PlatformProfile
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 official BigInteger(md5Hex, 16).toString().

Type Aliases§

Result