Yandex Music Downloader
A TUI 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, artist discographies, 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
- 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
- Check the installed binary version:
./yamdl --version
- 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
- Optional: set a default download directory via environment variable:
export YAMDL_DOWNLOAD_DIR="/path/to/music"
Development
Run the application from the command package:
go run ./cmd/yamdl
go build ./cmd/yamdl
bash scripts/verify.sh
Run the complete test suite with:
go test ./...
Command-Line Downloads
Use the download subcommand to fetch a track, album, artist discography, playlist, or chart without opening the terminal UI:
./yamdl download \
--token TOKEN \
--link https://music.yandex.ru/album/10733135 \
--format mp3 \
--output ./downloads
Available options:
--token <token> is required. Provide your Yandex Music OAuth token.--link <url> is required. Provide a Yandex Music track, album, artist, playlist, or chart URL. For an artist, an album that cannot be loaded after several retries is skipped with a warning on stderr, and the summary shows Albums not loaded: N.--proxy <url> optionally routes all connections through an HTTP, HTTPS, or SOCKS5 proxy, for example --proxy socks5://127.0.0.1:1080. Supported forms are http://[user:password@]host[:port], https://[user:password@]host[:port], and socks5://[user:password@]host[:port]; an omitted port defaults to 80, 443, and 1080 respectively. An invalid value makes the command exit with code 2 before any request is sent. Note that credentials passed as a command-line argument are visible in ps output and your shell history. HTTPS proxies are verified against the system root CAs; proxies using a custom CA are not supported. When --proxy is omitted, the standard HTTP_PROXY/HTTPS_PROXY environment variables are honored.--format <mp3|flac> selects MP3 or lossless download; MP3 is the default.--output <directory> selects the destination directory (defaults to YAMDL_DOWNLOAD_DIR if set, or ./downloads). Passing this flag overrides the environment variable.--timeout <seconds> limits the download time for each audio file. Use 0, the default, to disable the limit.--skip-cover skips downloading and embedding cover art. Text metadata is still written.
During the download, each track event is appended to stdout as it happens. A track first prints [downloading] Artist — Track title, then a final line such as [done] Artist — Track title or [already exists] Artist — Track title. Previous lines are never cleared or overwritten. Press Ctrl+C to stop scheduling remaining tracks: in-flight downloads can still finish. Press Ctrl+C again to force-cancel their active HTTP requests. The command then prints Interrupted: remaining tracks stayed queued followed by the partial summary and exits with code 130.
[downloading] Artist — Track title
[done] Artist — Track title
[already exists] Artist — Another track
[unavailable] Artist — Restricted track
Finished: 1 downloaded, 2 skipped, 0 failed
Output: ./downloads
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, 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.
Usage Guide
1. Token Authentication
- On the first launch, you’ll be prompted to enter your authentication token
- You may proceed without a token by pressing
Enter, but this may result in errors while downloading
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
3. Copy Track Link
- Navigate to the Yandex Music web interface and select
Share -> Copy link for any track, album, artist, or playlist
- Artist pages such as
https://music.yandex.ru/artist/170660 download the artist’s own albums and singles (not compilation appearances). An album that cannot be loaded after several retries is skipped, and the download screen lists it in red above the track list
- 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
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, artists, 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 (or to the directory specified by the YAMDL_DOWNLOAD_DIR environment variable)
- 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
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
7. Completion
- The progress bar fills completely upon download completion
- Downloaded tracks are available in the
./downloads directory (or the directory specified by YAMDL_DOWNLOAD_DIR environment variable)
- 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 the destination directory; 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
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
- 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
License
This project is licensed under the MIT License. See LICENSE.
评论