yandex-music-downloader

KO | EN

gitlite — search

#python #hacktoberfest #go #golang #android #deep-learning #linux #java #windows #cli #kubernetes #awesome-list #vue #ios

yandex-music-downloader

(★ 77)

Download music from Yandex Music

yandex-music-downloader Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Yandex Music Downloader

A GUI application for downloading tracks from the Yandex Music streaming service.

⚠️  This is an unofficial application and is not affiliated with Yandex or its services.

## Why?

-   Because I just want to run `app.exe` and get my tracks. No `apt`, no `brew`, no `pip`, and none of that other annoying stuff
-   It's fun to code new things 🤗

## Features

-   Modern graphical user interface
-   _Blazingly fast, powered by the Go programming language_
-   Download individual tracks, albums, and playlists in MP3 format by default
-   Download Yandex Music chart playlists, including region-specific charts
-   Optional lossless downloads with automatic fallback to the best available MP3
-   Add metadata tags and embedded cover art to downloaded MP3, FLAC, and M4A files
-   Duplicate detection in playlists
-   Concurrent file downloads

## Installation

-   Download the latest release from [GitHub](https://github.com/Stmol/yandex-music-downloader/releases)
-   Select the appropriate binary for your operating system
-   Extract the archive to any directory you prefer
-   For Linux and macOS, make the binary executable: `chmod +x yamdl`
-   Launch the application from the terminal: `./yamdl`
-   Optional: set a download timeout in seconds: `./yamdl --timeout 180`
-   Optional: skip cover download and embedding to save time and traffic: `./yamdl --skip-cover=true`

## Authentication Token

An OAuth token is required for accessing certain tracks and playlists.

🔐 Without a token, you will be able to download only 30 seconds of each track.

You can obtain a Yandex Music OAuth token using **[yandex-oauth-token](https://github.com/Stmol/yandex-oauth-token)**, a local helper that signs you in via QR and exchanges the session into a Music token. Run it on your machine, then paste the token into this app.

For alternative ways to get a token, see the [yandex-music API documentation](https://yandex-music.readthedocs.io/en/main/token.html).

## Usage Guide

### 1. Token Authentication

-   On the first launch, you'll be prompted to enter your [authentication token](#authentication-token)
-   You may proceed without a token by pressing `Enter`, but this may result in errors while downloading

![token input](https://raw.githubusercontent.com/Stmol/yandex-music-downloader/master/assets/img_insert_token.png)

### 2. Token Persistence

-   After entering the token, you'll have the option to save it to `token.txt` in the application directory
-   This eliminates the need to re-enter the token on subsequent launches

![save token](https://raw.githubusercontent.com/Stmol/yandex-music-downloader/master/assets/img_save_token.png)

### 3. Copy Track Link

-   Navigate to the Yandex Music web interface and select `Share` -> `Copy link` for any track, album, or playlist
-   Chart pages such as `https://music.yandex.ru/chart` and `https://music.yandex.ru/chart/world` can also be pasted directly
-   This will copy the URL to your clipboard

### 4. Paste Link

-   Press `<Ctrl+V>`/`<Cmd+V>` to paste the link into the application

![paste link](https://raw.githubusercontent.com/Stmol/yandex-music-downloader/master/assets/img_paste_link.png)

### 5. Download Preparation

-   Upon valid URL input, the next screen displays a track listing with status indicators
-   Use the action bar to choose a format for all tracks and run actions from one place
-   Press `<Tab>` to move between the track list and controls; use arrow keys or `<H>`/`<J>`/`<K>`/`<L>` to move inside controls, `<Esc>` or `<Tab>` to return to the track list, and `<Enter>`/`<Space>` to select the focused control; press uppercase `<D>` to start `Download all` directly
-   Press `<1>` or `<2>` to select MP3 or FLAC, `<b>` to go back, `<q>` to quit or cancel an active download, and `<?>` to toggle expanded command help
-   Format selection applies to the whole current queue; individual tracks still fall back to MP3 when lossless is unavailable
-   Depending on the source returned by Yandex Music, a lossless track may be saved as either `FLAC` or `M4A`
-   Supported source URLs include tracks, albums, playlists, and Yandex Music charts
-   If FLAC is unavailable or cannot be downloaded, the app automatically falls back to the best available MP3
-   Downloads are saved to `./downloads` in the application's working directory
-   Track status indicators:

```
    Ready - Track is queued for download
    Downloading - Download in progress
    Error - Download failed
    Already Exists - File exists in target directory
    Duplicate - Duplicate track in current playlist
    Not Available - Track unavailable (likely due to licensing restrictions)
    ✅ MP3 - Download completed as MP3, including MP3 fallback from FLAC mode
    ✅ FLAC - Download completed as lossless FLAC
    ✅ M4A - Download completed as lossless M4A
```

![tracks list](https://raw.githubusercontent.com/Stmol/yandex-music-downloader/master/assets/img_ready_to_download.png)

### 6. Download Process

-   Press uppercase `<D>` to start `Download all` directly, or focus it in the action bar and press `<Enter>` or `<Space>`
-   The download process will start
-   Track statuses update in real-time
-   Completed tracks show the actual saved format in the status column, for example `✅ FLAC`, `✅ M4A`, or `✅ MP3`
-   If you stop an active queue, interrupted tracks are returned to `Ready` so you can restart the download cleanly
-   If needed, you can relaunch the app with `--timeout <seconds>` to limit how long a single file download may take
-   By default, each MP3, FLAC, or M4A file is tagged with title, artist, album metadata, and Yandex track URL/source metadata. Cover art is optional: when available it is embedded during tagging and the temporary cover file is removed after download
-   MP3 and FLAC of that format are published only after tags are written successfully. If tagging fails, that format is not left in the download folder; in lossless mode a FLAC tagging failure still falls back to MP3
-   M4A tagging covers native MP4/M4A containers only. The downloader creates the required M4A metadata structure even when Yandex Music returns a valid file without initial tags; damaged M4A files are not repaired. M4A is published even when optional metadata writing fails—the CLI logs a warning and the audio file is still saved
-   If cover downloads are slow or expensive, relaunch with `--skip-cover=true`; text tags will still be written

![downloading](https://raw.githubusercontent.com/Stmol/yandex-music-downloader/master/assets/img_download_in_progress.png)

### 7. Completion

-   The progress bar fills completely upon download completion
-   Downloaded tracks are available in the `./downloads` directory
-   A track is marked as completed after the audio file is saved. For MP3 and FLAC of that format, tagging must succeed before the file appears in `./downloads`; in lossless mode a FLAC tagging failure still falls back to MP3. For M4A, metadata is best-effort and tagging failures do not block delivery. Cover download failures are ignored so they do not block the track

![download complete](https://raw.githubusercontent.com/Stmol/yandex-music-downloader/master/assets/img_download_complete.png)

## Troubleshooting

-   If the app reports `TERM=xterm`, run `export TERM=xterm-256color` and start it again; plain `xterm` cannot reliably render the colors, selected row, and focused controls
-   If downloads fail, you can retry by focusing `Download all` after the process completes
-   For persistent errors, try using your personal [authentication token](#authentication-token)
-   In lossless mode, a completed `✅ MP3` status means the app successfully used the MP3 fallback for that track
-   A completed `✅ M4A` status means Yandex Music returned the lossless track in an M4A container
-   You are welcome to open an issue or send a PR

## Acknowledgments

-   [MarshalX/yandex-music-api](https://github.com/MarshalX/yandex-music-api) - Yandex Music API implementation
-   [llistochek/yandex-music-downloader](https://github.com/llistochek/yandex-music-downloader) - Yandex Music download utility

## License

Stay golden and don't be shady. Peace ✌️

yandex-music-downloader

yandex-music-downloader Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

yandex-music-downloader

yandex-music-downloader Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README