YandexMusic for .NET

🌐 English · Русский

Unofficial asynchronous library for the Yandex Music API. Runs on .NET 8, .NET 9 and .NET 10.

⚠️ Unofficial project, not affiliated with Yandex. Use at your own risk and comply with the service's terms of use.

Features

• ✅ Fully asynchronous API with CancellationToken support on every call
• ✅ Full catalogue coverage — tracks (metadata, direct download/stream link, lyrics, full-info, similar, trailer), search (+ autocomplete), albums, artists, playlists, genres, labels, clips, credits, disclaimers, concerts, meta-tag pages
• ✅ Personalised endpoints — account & settings, library likes/dislikes (read & write), playlist editing, radio (rotor) stations, landing & feed, cross-device queues, pins, pre-saves, listening history
• ✅ Multiple sign-in flows — OAuth token, the official OAuth device-code flow, and best-effort cookie, QR or login + password; all over a serializable session you can persist and restore
• ✅ System.Text.Json source generation — allocation-conscious and trim/AOT-friendly (IsAotCompatible)
• ✅ Typed exceptions, first-class dependency-injection integration, full XML documentation
• ✅ Clean, extensible design: add an endpoint group and you have a new domain

Installation

# Core client
dotnet add package YandexMusic

# Optional: dependency-injection integration
dotnet add package YandexMusic.DependencyInjection

Package	Purpose
YandexMusic	The YandexMusicClient, models, authentication and endpoint groups.
YandexMusic.DependencyInjection	AddYandexMusic() — a scoped client over an IHttpClientFactory pool.

Quick start

using YandexMusic;

await using var client = new YandexMusicClient();

// Authorize with an OAuth token (never hardcode it — use an environment variable or a secure store)
client.Authentication.SignInWithToken(Environment.GetEnvironmentVariable("YANDEX_MUSIC_TOKEN")!);

// Track metadata and a direct media link
var track = await client.Tracks.GetAsync("4");
Console.WriteLine(track?.Title);
var link = await client.Tracks.GetDirectLinkAsync("4");

// Search and autocomplete
var results = await client.Search.SearchAsync("Queen");
var hints = await client.Search.SuggestAsync("que");

// Albums, artists, playlists (all catalogue ids are strings)
var album = await client.Albums.GetWithTracksAsync("3");
var artist = await client.Artists.GetBriefInfoAsync("79215");
var playlist = await client.Playlists.GetAsync("yamusic-daily", "1000");

// Account and library
var status = await client.Account.GetStatusAsync();
var uid = status!.Account.Uid.ToString();
var liked = await client.Library.GetLikedTracksAsync(uid);
await client.Library.AddLikedTracksAsync(uid, ["4"]);

// Discovery: radio, landing, charts
var dashboard = await client.Radio.GetStationsDashboardAsync();
var chart = await client.Landing.GetChartAsync("russia");
var newReleases = await client.Landing.GetNewReleasesAsync();

Sign in with the OAuth device-code flow

No password handling — show the user a short code, then poll until they confirm it:

await using var client = new YandexMusicClient();
var token = await client.Authentication.SignInWithDeviceFlowAsync(code =>
    Console.WriteLine($"Open {code.VerificationUrl} and enter code {code.UserCode}"));
// The client is now authenticated; persist token.AccessToken if you want to reuse it.

Every method accepts a CancellationToken:

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
var track = await client.Tracks.GetAsync("4", cts.Token);

Authentication & session persistence

Getting an OAuth token

The simplest way to obtain a token is Yandex's OAuth implicit flow. Open this URL in a browser, sign in, and confirm access:

https://oauth.yandex.ru/authorize?response_type=token&client_id=23cabbbdc6cd418abb4b39c32c41195d

You'll be redirected to a music.yandex.ru URL with the token in the fragment (after the #):

https://music.yandex.ru/#access_token=y0__xExampleFAKEtokenDoNotUse000000000000000000&token_type=bearer&expires_in=24752795&cid=ab1cd23efghij4klmn5opqrs6

Copy the value of access_token (here y0__xExampleFAKEtokenDoNotUse000000000000000000) — that is your token. Keep it secret; pass it via the YANDEX_MUSIC_TOKEN environment variable (or paste it into the sample player's OAuth token sign-in). The token_type, expires_in and cid parts are not needed.

Sign in & persist a session

Sign in with an OAuth token, then export the session to resume it later:

client.Authentication.SignInWithToken("<oauth-token>");

var snapshot = client.Authentication.Session.Export();      // serializable record
var json = System.Text.Json.JsonSerializer.Serialize(snapshot);
// ... store json securely ...
client.Authentication.Session.Import(
    System.Text.Json.JsonSerializer.Deserialize<YandexMusic.Authentication.AuthSnapshot>(json)!);

Dependency injection

services.AddYandexMusic(options =>
{
    options.Timeout = TimeSpan.FromSeconds(30);
    options.DeviceId = "my-app";
});

// IYandexMusicClient is registered as scoped, isolated per scope.

Documentation

Full guides and API reference: https://jrfrigat.github.io/YandexMusic/

• Getting started
• Authentication
• Architecture
• FAQ

Repository layout

.
├── src/
│   ├── YandexMusic/                     # core library (client, models, endpoints, auth, JSON)
│   └── YandexMusic.DependencyInjection/ # AddYandexMusic() integration
├── tests/
│   └── YandexMusic.Tests/               # unit + (token-gated) integration tests (xUnit)
├── samples/
│   └── YandexMusic.Player/              # interactive terminal music player (TUI demo)
├── docs/                                # documentation site (DocFX)
└── .github/workflows/                   # CI, release (NuGet), docs publishing

Sample: terminal music player

samples/YandexMusic.Player is a full interactive TUI built on the library — search, browse your albums and playlists, and a live "now playing" view with an animated equalizer, a real-time progress bar and keyboard volume/transport controls.

Download: grab a ready-to-run Windows build from the Releases page (yandexmusic-player-<version>-win-x64.zip — self-contained, no .NET install needed; unzip and run yandexmusic-player.exe). Or run it from source:

dotnet run --project samples/YandexMusic.Player

• Sign in with an OAuth token, the device-code flow, a QR code, or login + password; the session is cached so the next run starts already signed in.
• Playback uses NAudio on Windows; everywhere else (and as a fallback) it runs a silent simulation that drives the same UI. The audio backend is a single IAudioPlayer seam, so swapping in a cross-platform backend changes one line.
• Main menu is cursor-driven with a hotkey bar along the bottom — single-key shortcuts jump straight to a section (s search · a albums · l playlists · p open player · q quit).
• Controls (now-playing view): space play/pause · ←/→ prev/next · ↑/↓ volume · s stop · q back.

See the sample's README for the architecture.

Build and test

dotnet restore
dotnet build -c Release
dotnet test  -c Release

The .NET SDK 10 is required (it builds the net8.0/net9.0/net10.0 targets). Integration tests hit the real API and are skipped automatically unless YANDEX_MUSIC_TOKEN is set:

YANDEX_MUSIC_TOKEN=<your-token> dotnet test -c Release

License

MIT © FrigaT