The repository contains the yamu library together with its development and
command-line tools.
Packages
yamu— async API client, models and OAuth Device Flow.yamu'scredentialsfeature — shared local credential storage for workspace applications.yamu-auth— login, logout and credential inspection tool.yamu-download— atomic track and collection downloader using negotiated CDN streams.yamu-inspect— read-only API exploration client.yamu-edit— explicit liked-track and playlist mutation client.
All applications share the default credential profile stored outside the
repository. Run cargo run -p yamu-auth -- path to display its location.
The single library crate uses additive feature flags:
oauth(default) — Device Flow and token refresh primitives.credentials— local profiles, locking and automatic refresh; enablesoauth.downloads— signed audio negotiation and CDN response streams.downloader— reusable atomic transfer pipeline with byte progress, cancellation, retries, streaming AES-CTR decryption, and normalization; enablesdownloadsandmedia.lyrics— signed plain-text and synchronized lyrics retrieval.media— backend-neutral audio tagging, normalization, and validation API.media-ffmpeg-cli— desktop backend that invokes an installedffmpeg.media-ffmpeg— in-process backend linked to FFmpeg libraries, intended for Android and other environments without a child-process executable.
The two FFmpeg features implement the same MediaBackend contract and can be
tested together. media-ffmpeg does not require the ffmpeg executable at
runtime, but the target application must build and package compatible FFmpeg
libraries.
The API is private and may change without notice, so the library is currently experimental. A minimal direct client looks like this:
use Client;
async
The protocol-research repositories live in the ignored references/
directory.
First login
cargo run -p yamu-auth -- login
cargo run -p yamu-auth -- status
cargo run -p yamu-auth -- refresh
File profiles are refreshed automatically when they are at least 90 days old
or within 7 days of expiry. yamu-auth refresh forces an immediate rotation.
Environment overrides are never refreshed or persisted.
Refresh, login writes and logout use an exclusive per-profile advisory lock. After acquiring it, refresh reloads the profile before contacting OAuth, so concurrent applications perform at most one token rotation.
The file store uses $XDG_STATE_HOME/yandex-music-rs/profiles/default.json on
Linux, normally ~/.local/state/yandex-music-rs/profiles/default.json.
The legacy directory name is intentionally retained so existing logins continue
to work after the crate rename.
Directories are mode 0700, credential files are mode 0600, and updates use
an atomic same-directory rename. Lock files are also mode 0600. Tokens are
redacted from Debug output.
YANDEX_MUSIC_TOKEN can override the stored profile for a single process.
Inspecting the API
cargo run -p yamu-inspect -- account
cargo run -p yamu-inspect -- search "Boards of Canada"
cargo run -p yamu-inspect -- track 'https://music.yandex.ru/album/1193829/track/10994777'
cargo run -p yamu-inspect -- album 'https://music.yandex.ru/album/1193829'
cargo run -p yamu-inspect -- likes --limit 20
cargo run -p yamu-inspect -- playlists
cargo run -p yamu-inspect -- playlist '<playlist-url>'
cargo run -p yamu-inspect -- artist 'https://music.yandex.ru/artist/1556'
cargo run -p yamu-inspect -- artist-tracks 'https://music.yandex.ru/artist/1556' --page-size 100
cargo run -p yamu-inspect -- artist-albums 'https://music.yandex.ru/artist/1556' --page-size 100
cargo run -p yamu-inspect -- lyrics 'https://music.yandex.ru/album/1193829/track/10994777' --lrc
cargo run -p yamu-inspect -- playlist-recommendations '<owner-kind-playlist-url>'
cargo run -p yamu-inspect -- stations
cargo run -p yamu-inspect -- station-tracks user onyourwave
Pass --json to print the complete modeled response including fields retained
for forward compatibility.
Read-only API calls share a configurable ReadRequestPolicy: the default
spaces GET requests by 25 ms and retries connection failures, HTTP 429, and 5xx
responses up to three times with exponential backoff. POST mutations are never
retried automatically. Artist tracks and albums expose both explicit
PageRequest methods and helpers that collect every page.
Editing the library
yamu-edit keeps mutations separate from the read-only inspector:
cargo run -p yamu-edit -- like 'https://music.yandex.ru/album/1193829/track/10994777'
cargo run -p yamu-edit -- unlike 'https://music.yandex.ru/album/1193829/track/10994777'
cargo run -p yamu-edit -- playlist-create "My playlist"
cargo run -p yamu-edit -- playlist-rename <playlist-kind> "New title"
cargo run -p yamu-edit -- playlist-visibility <playlist-kind> public
cargo run -p yamu-edit -- playlist-add <playlist-kind> 'https://music.yandex.ru/album/1193829/track/10994777' --at 0
cargo run -p yamu-edit -- playlist-remove <playlist-kind> --from 0 --to 1
cargo run -p yamu-edit -- playlist-delete <playlist-kind> --yes
Playlist track changes first fetch the current revision and submit a typed
positional diff against that exact revision. A concurrent edit is reported as
PlaylistRevisionConflict and is not retried automatically. Permanent playlist
deletion requires --yes.
Downloading audio
Desktop requirement: FFmpeg
The workspace yamu-download executable is not self-contained: it starts the
system ffmpeg executable for audio validation, container normalization, and
M4A metadata. Install FFmpeg and make sure this command succeeds before running
the downloader:
ffmpeg -version
On Windows, download a Windows build linked from the
official FFmpeg download page, extract it,
and add the extracted bin directory containing ffmpeg.exe to PATH. Open a
new PowerShell window after changing PATH. ffprobe is not required by the
downloader.
The workspace tools build natively with the Rust MSVC toolchain. A complete Windows setup from a cloned repository is:
cargo build --release -p yamu-auth -p yamu-download
.\target\release\yamu-auth.exe login
.\target\release\yamu-download.exe track "https://music.yandex.ru/album/1193829/track/10994777"
Library users that select the in-process media-ffmpeg backend package FFmpeg
libraries with their application instead and do not need ffmpeg.exe at
runtime.
The downloads feature implements the signed get-file-info negotiation and
opens short-lived CDN response streams without forwarding the OAuth token:
cargo run -p yamu-download -- track 'https://music.yandex.ru/album/1193829/track/10994777'
cargo run -p yamu-download -- track 'https://music.yandex.ru/album/1193829/track/10994777' --quality normal -o track
cargo run -p yamu-download -- album 'https://music.yandex.ru/album/1193829' --jobs 4
cargo run -p yamu-download -- playlist '<playlist-url>' -o ./playlist --jobs 4
cargo run -p yamu-download -- liked -o ./liked --jobs 4
cargo run -p yamu-download -- artist 'https://music.yandex.ru/artist/1556' --limit 100
cargo run -p yamu-download -- sync playlist '<playlist-url>' -o ./playlist
cargo run -p yamu-download -- sync liked -o ./liked --dry-run
cargo run -p yamu-download -- sync liked -o ./liked --prune
cargo run -p yamu-download -- track 'https://music.yandex.ru/album/1193829/track/10994777' --lyrics
cargo run -p yamu-download -- album 'https://music.yandex.ru/album/1193829' --lyrics lrc
Paste the regular Yandex Music link from the browser or app for track, album,
artist, and playlist arguments. Compact IDs are also accepted for scripts and
advanced use. URL query parameters and fragments, including copy-link utm_*
parameters, are discarded during parsing.
Shared playlist links in the current /playlists/<uuid> form are supported,
including the observed two-letter-prefixed UUID forms. User-scoped
/users/<owner>/playlists/<kind> links and compact owner:kind references
remain supported as well.
Album downloads use Artist - Album (year) directories. Multi-disc releases
are split into CD1, CD2, and so on, while files retain disc-local track
numbers. Albums and playlists share the same concurrent, atomic, verified
resume pipeline.
Liked libraries are expanded in bounded API batches before downloading. Artist
catalogs are fetched through every available API page. Both commands accept an
optional --limit and preserve their source ordering in numbered filenames.
sync playlist and sync liked compare the current remote ordering with the
versioned local manifest. They download new or renamed entries and retain stale
files by default. --dry-run reports the plan without touching audio or the
manifest. --prune runs only after every current track succeeds and removes
only previously tracked .flac, .m4a, or .mp3 files whose canonical paths
remain inside the destination directory, together with their generated lyrics
sidecars.
The global --lyrics [text|lrc] option works with every download and sync
source. Omitting the format after --lyrics selects plain text. Lyrics are
written atomically beside the audio as .txt or .lrc and embedded in the
audio tags; synchronized LRC timestamps are retained. Missing remote lyrics
produce a warning without discarding an otherwise valid audio download.
The server can return a lower tier than requested. yamu-download writes to a
same-directory .part file, syncs it, and only then renames it to the final
path. Playlist downloads continue past individual failures and print a final
report. FLAC-in-MP4 is losslessly remuxed to native .flac through the selected
media backend;
AAC-in-MP4 remains .m4a, and MP3 remains .mp3. M4A metadata and its single
attached cover are written by a lossless remux; FLAC and MP3 tags use Lofty.
The workspace yamu-download binary selects media-ffmpeg-cli; applications can
select the in-process media-ffmpeg backend instead. Existing files are
preserved unless --force is passed. Every newly completed or repaired file is
enriched with title, artist, album, album artist, year,
genre, album track/disc position, and an embedded 600×600 front cover.
Resume validates each existing container and its duration before trusting it;
M4A validation also performs a complete audio decode so broken sample tables or
AAC packets cannot pass a shallow container check. Truncated or corrupt files
are atomically replaced. Playlist progress is checkpointed at most once per
second and flushed at the end of the run in
.yamu-download-state.json. Transient negotiation failures and CDN transfers use
bounded exponential retries, and every advertised CDN URL is attempted.
The transfer, retry, decryption, normalization, progress, and cancellation
logic is provided by the library's downloader feature and shared with the
Android client. Frontends receive typed DownloadEvent values instead of
parsing terminal output. Cancellation interrupts active HTTP requests and retry
delays and removes the incomplete temporary file.