![\"@dvxch/yandex-music](\"assets/hero.png\")
\n\n \n
\n ![\"npm\"](\"https://img.shields.io/npm/v/@dvxch/yandex-music?color=8b5cf6&logo=npm\")
![\"CI\"](\"https://github.com/thedvxch/yandex-music/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"types\"](\"https://img.shields.io/npm/types/@dvxch/yandex-music?logo=typescript&logoColor=white&color=8b5cf6\")
![\"zero](\"https://img.shields.io/badge/runtime%20deps-0-44cc11\"){kind=icon}
![\"node\"](\"https://img.shields.io/node/v/@dvxch/yandex-music?logo=node.js&logoColor=white&color=44cc11\")
![\"license\"](\"https://img.shields.io/npm/l/@dvxch/yandex-music?color=a78bfa\")
\n 📖 Документация ·\n 🇬🇧 In English ·\n npm\n
\n\nТипизированный асинхронный **TypeScript-клиент для API Яндекс Музыки**.\n\n`@dvxch/yandex-music` — независимая реализация HTTP API Яндекс Музыки на\nTypeScript. Ориентирован на современный Node.js (≥ 20), поставляется как ESM с\nполными декларациями типов и **без рантайм-зависимостей** (использует встроенный\n`fetch`).\n\n> Статус: готово. Реализован и протестирован весь HTTP API — `account` / `tracks`\n> / `albums` / `artists` / `search` / `likes` / `playlists` / `device auth` /\n> `landing` / `radio` / `queue` / `history` / `clips` / `credits` /\n> `disclaimers` / `labels` / `metatags` / `pins` / `presaves` / `concerts`, —\n> включая мутации плейлистов, дизлайки и обратную связь rotor, а также realtime\n> («сейчас играет») через Ynison.\n\nКаждый эндпоинт прогнан на живом API Яндекс Музыки с реальным токеном. Те\nнемногие эндпоинты, которые сервер больше не отдаёт обычному аккаунту (например,\nустаревшее создание очереди, rotor feedback), кидают типизированную ошибку, а не\nпадают молча.\n\n### Оглавление\n\n- [Возможности](#возможности)\n- [Установка](#установка)\n- [Быстрый старт](#быстрый-старт)\n- [Архитектура](#архитектура)\n- [Конфигурация](#конфигурация)\n- [Обработка ошибок](#обработка-ошибок)\n- [Реализованные эндпоинты](#реализованные-эндпоинты)\n- [Realtime](#realtime)\n- [Примеры](#примеры)\n- [Документация](#документация)\n- [Благодарности](#благодарности)\n- [Лицензия](#лицензия)\n\n## Возможности\n\n- **Ноль рантайм-зависимостей.** На встроенном `fetch`; только ESM, Node ≥ 20.\n- **Полная типизация.** У каждого эндпоинта и модели — ручные типы и статический `deJson`, без `any` в публичном API.\n- **Полное покрытие API.** ~145 методов по всем доменам, держим паритет с актуальным API.\n- **Надёжный транспорт.** Автоматические ретраи с экспоненциальным backoff + jitter на транзиентных сбоях (только идемпотентные запросы); типизированные ошибки; пер-вызов таймауты.\n- **Стриминговое скачивание.** `download()` льёт сразу на диск (константная память), на лету расшифровывая lossless (`encraw`/FLAC), с опциональной **гонкой CDN-зеркал** и watchdog'ом зависшего стрима.\n- **Realtime «сейчас играет»** через Ynison — переподключающийся `EventEmitter` + синхронный снимок `nowPlaying`.\n- **Детект дрейфа.** Опциональный хук `onUnknownField` репортит любое поле API, которое модели ещё не мапят, — изменения сервера ловятся, а не теряются.\n- **Подключаемый `fetch`.** Свой транспорт (прокси, TLS-имперсонация, тюнинг пула соединений).\n\n## Установка\n\n```bash\nnpm install @dvxch/yandex-music\n```\n\nТребования: Node.js ≥ 20. Для realtime («сейчас играет») дополнительно нужен\nопциональный пакет `ws`:\n\n```bash\nnpm install ws\n```\n\n## Быстрый старт\n\n```ts\nimport { Client } from '@dvxch/yandex-music';\n\n// Создаём с OAuth-токеном и один раз вызываем init() для загрузки данных аккаунта.\nconst client = await new Client({ token: process.env.YM_TOKEN }).init();\n\n// Получаем трек по id.\nconst [track] = await client.tracks(2);\nconsole.log(track?.title, '—', track?.artists?.[0]?.name);\n\n// Получаем прямую ссылку и скачиваем.\nconst [info] = await track!.getDownloadInfo();\nawait info.download('track.mp3');\n\n// Текст песни (TEXT или LRC).\nconst lyrics = await client.tracksLyrics(2, 'LRC');\nconsole.log(await lyrics?.fetchLyrics());\n```\n\n`new Client({ token })` дёшев. `await client.init()` один раз подгружает данные\nаккаунта, чтобы методы, подставляющие user id по умолчанию (`usersLikes*`,\n`usersPlaylists*`, `pins`, `presaves`), работали без явного `userId`. Каталожные\nread-only запросы (`tracks`, `albums`, `search`, …) работают и без `init()`.\n\n## Архитектура\n\n- **Плоский интерфейс клиента.** Методы лежат прямо на клиенте\n (`client.tracks(...)`, `client.tracksDownloadInfo(...)`), повторяя исходный API.\n Внутри клиент собирается из *миксинов* по доменам — каждая область в своём файле.\n- **Модели в camelCase.** API уже возвращает ключи в camelCase, поэтому модели\n хранят их как есть — без слоя нормализации snake_case. У каждой модели есть\n статический `deJson(raw, client)`, который строит типизированный экземпляр и\n рекурсивно разбирает вложенные модели; массивы обрабатывает\n `deList(Model.deJson, raw, client)`.\n- **Модели несут клиент.** Удобные методы вроде `Track.getDownloadInfo()` или\n `DownloadInfo.download()` переиспользуют клиент-владелец, так что вручную его\n прокидывать почти не нужно.\n- **Типизированные ошибки.** Любая ошибка наследует `YandexMusicError`; сетевые\n дополнительно наследуют `NetworkError` (`BadRequestError`, `NotFoundError`,\n `TimedOutError`, `UnauthorizedError`).\n- **Никогда не `JSON.stringify` модель** — она держит обратную ссылку на клиент\n (циклическая структура). Читайте поля напрямую.\n\n## Конфигурация\n\nВсё, чем клиент представляется API, задаётся через конструктор:\n\n```ts\nconst client = new Client({\n token: process.env.YM_TOKEN,\n userAgent: 'my-app/1.0', // по умолчанию — UA библиотеки\n headers: { 'X-Yandex-Music-Client': 'custom' }, // мержатся с дефолтными\n device: 'os=Linux; model=my-app; ...', // device-дескриптор для очередей\n language: 'en', // язык ответов: en/uz/uk/us/ru/kk/hy\n fetch: myFetch, // свой транспорт (напр. node-wreq)\n retries: 2, // ретраи транзиентных GET-сбоев (0 — выкл.)\n onUnknownField: ({ model, fields }) => // хук дрейфа: немаппленные поля API\n console.warn(`${model}: unmapped ${fields.join(', ')}`),\n});\n```\n\n`userAgent` и `headers` влияют только на автоматически создаваемый транспорт —\nесли передаёшь свой `request`, задавай их прямо в нём. Идентичность устройства\nдля realtime настраивается отдельно через `client.realtime({ deviceInfo })`.\n\n### Все опции `ClientOptions`\n\n| Опция | Назначение |\n| ----- | ---------- |\n| `token` | OAuth-токен |\n| `baseUrl` | переопределить origin API |\n| `language` | язык ответов: `en`/`uz`/`uk`/`us`/`ru`/`kk`/`hy` (по умолчанию `ru`) |\n| `userAgent` | переопределить User-Agent |\n| `headers` | доп. заголовки, мержатся с дефолтными |\n| `device` | device-дескриптор для запросов очереди |\n| `fetch` | свой `fetch` (прокси, моки, ретраи) |\n| `retries` | ретраи транзиентных сбоев для GET (по умолчанию 2, 0 — выкл.) |\n| `reportUnknownFields` | подсветить поля API, которые модели ещё не маппят |\n| `onUnknownField` | хук вместо `console.warn` для того же дрейфа |\n| `request` | полностью преднастроенный транспорт (перекрывает `userAgent`/`headers`/`fetch`) |\n\n## Обработка ошибок\n\nКаждая ошибка библиотеки наследует `YandexMusicError` — одного `catch`\nдостаточно, чтобы перехватить всё. Сетевые и транспортные сбои дополнительно\nнаследуют `NetworkError`:\n\n```ts\nimport {\n YandexMusicError,\n UnauthorizedError,\n NotFoundError,\n TimedOutError,\n} from '@dvxch/yandex-music';\n\ntry {\n await client.tracksLyrics(trackId);\n} catch (error) {\n if (error instanceof UnauthorizedError) {\n // токен отсутствует или истёк — переавторизуйтесь\n } else if (error instanceof NotFoundError) {\n // у трека нет текста\n } else if (error instanceof TimedOutError) {\n // запрос завис — можно повторить\n } else if (error instanceof YandexMusicError) {\n // любая другая ошибка библиотеки\n } else {\n throw error; // не наша ошибка\n }\n}\n```\n\n`GET`-запросы автоматически повторяются при транзиентных сбоях (экспоненциальный\nbackoff + jitter, `retries` попыток сверху, по умолчанию 2). Мутирующие запросы\n(`POST`/`PUT`/`DELETE`) никогда не повторяются автоматически — это защищает от\nдвойных сайд-эффектов (например, двойного лайка).\n\n## Реализованные эндпоинты\n\n| Домен | Методы |\n| ----------- | ------- |\n| account | `init`, `accountStatus`, `accountSettings`, `accountSettingsSet`, `settings`, `permissionAlerts`, `accountExperiments`, `accountExperimentsDetails`, `consumePromoCode` |\n| tracks | `tracks`, `tracksDownloadInfo`, `tracksLosslessInfo`, `tracksLyrics`, `tracksSimilar`, `tracksFullInfo`, `tracksTrailer`, `trackSupplement`, `playAudio`, `afterTrack` |\n| albums | `albums`, `albumsWithTracks`, `albumsSimilarEntities`, `albumsTrailer` |\n| artists | `artists`, `artistsBriefInfo`, `artistsInfo`, `artistsAbout`, `artistsClips`, `artistsDonation`, `artistsSkeleton`, `artistsTracks`, `artistsTrackIds`, `artistsDirectAlbums`, `artistsAlsoAlbums`, `artistsDiscographyAlbums`, `artistsSafeDirectAlbums`, `artistsSimilar`, `artistsLinks`, `artistsTrailer` |\n| search | `search`, `searchSuggest` |\n| likes | `usersLikesTracks`/`Albums`/`Artists`/`Playlists`/`Clips` + add/remove для каждого; `usersDislikesTracks`/`Artists` + add/remove |\n| playlists | `playlist`, `playlists`, `playlistsList`, `playlistsPersonal`, `usersPlaylists`, `usersPlaylistsList`, `usersPlaylistsKinds`, `usersPlaylistsCreate`, `usersPlaylistsDelete`, `usersPlaylistsName`, `usersPlaylistsVisibility`, `usersPlaylistsDescription`, `usersPlaylistsChange`, `usersPlaylistsInsertTrack`, `usersPlaylistsDeleteTrack`, `usersPlaylistsRecommendations`, `usersPlaylistsTrailer`, `usersSettings`, `playlistSimilarEntities`, `playlistsCollectiveJoin` |\n| device auth | `requestDeviceCode`, `pollDeviceToken`, `deviceAuth` (блокирующий flow), `refreshAccessToken` (обновление по refresh-токену) |\n| landing | `landing`, `feed`, `feedWizardIsPassed`, `tags`, `chart`, `newReleases`, `newPlaylists`, `podcasts`, `genres` |\n| radio | `rotorStationsDashboard`, `rotorStationsList`, `rotorStationInfo`, `rotorStationTracks`, `rotorAccountStatus`, `rotorStationFeedback` (+ шорткаты `rotorStationFeedbackRadioStarted`/`TrackStarted`/`TrackFinished`/`Skip`), `rotorStationSettings2` |\n| queue | `queuesList`, `queue`, `queueUpdatePosition`, `queueCreate` |\n| history | `musicHistory`, `musicHistoryItems` |\n| clips | `clips`, `clipsWillLike` |\n| credits | `tracksCredits`, `clipsCredits` |\n| disclaimers | `tracksDisclaimer`, `clipsDisclaimer`, `albumsDisclaimer`, `artistsDisclaimer` |\n| labels | `label`, `labelAlbums`, `labelArtists` |\n| metatags | `metatags`, `metatag`, `metatagAlbums`, `metatagArtists`, `metatagPlaylists` |\n| pins | `pins`, `pin{Album,Artist,Playlist,Wave}`, `unpin{Album,Artist,Playlist,Wave}` |\n| presaves | `usersPresaves`, `usersPresavesAdd`, `usersPresavesRemove` |\n| concerts | `artistsConcerts`, `concertInfo`, `concertSkeleton`, `concertsFeed`, `concertsLocations`, `concertsTabConfig` |\n| realtime | `client.realtime()` → `RealtimeClient` (Ynison; нужен `ws`) |\n\n### Скачивание и качество\n\nДля lossy-вариантов используйте `tracksDownloadInfo` / `track.getDownloadInfo()`\nи выбирайте по битрейту:\n\n```ts\nconst variants = await track!.getDownloadInfo(); // DownloadInfo[]\nconst best = [...variants].sort((a, b) => (b.bitrateInKbps ?? 0) - (a.bitrateInKbps ?? 0))[0];\nawait best!.download('track.mp3');\n```\n\nДля lossless (FLAC) — отдельный путь через `tracksLosslessInfo` /\n`track.getLosslessInfo(quality)` (`LosslessDownloadInfo`, AES-CTR-расшифровка на\nлету), описанный в типах пакета.\n\n## Realtime\n\nУ Яндекс Музыки нет HTTP-вебхуков; единственный канал server-push — **Ynison**\n(WebSocket-протокол синхронизации воспроизведения между устройствами).\n`client.realtime()` оборачивает его в типизированный `EventEmitter`, который сам\nделает рукопожатие, keep-alive и переподключение. Нужен опциональный пакет `ws`\n(`npm install ws`); остальная библиотека рантайм-зависимостей не имеет.\n\n```ts\nconst rt = client.realtime();\nrt.on('trackChange', ({ track }) => console.log('сейчас играет:', track?.title));\nrt.on('playStateChange', (paused) => console.log(paused ? 'пауза' : 'играет'));\nawait rt.start(); // резолвится, когда вы вызовете rt.stop()\n```\n\nДля боевого «наблюдателя» удобнее **синхронный снимок**, чем ожидание\nследующего события — например, чтобы ответить на HTTP-запрос прямо сейчас:\n\n```ts\nconst rt = client.realtime({\n staleTimeoutMs: 120_000, // форс-реконнект, если фреймы замолчали (broken pipe без RST)\n});\nrt.start(); // не await — крутится до rt.stop()\n\nconst np = rt.nowPlaying; // null до первого фрейма / когда ничего не играет\nif (np?.track) {\n console.log(np.track.title, np.paused ? '⏸' : '▶',\n `${Math.round(np.progressMs / 1000)}/${Math.round(np.durationMs / 1000)}с`); // progressMs экстраполируется живьём\n}\n```\n\n`deviceId` по умолчанию генерируется один раз и переиспользуется между\nпереподключениями — **не меняйте его на каждый реконнект**: Ynison дедуплицирует\nрассылку по устройству, и новый id выкидывает вашего наблюдателя из fan-out,\nпосле чего состояние молча замирает. Геттеры `state` / `lastStateAgeMs` /\n`liveProgressMs()` дают остальную часть снимка для `/health`.\n\n## Примеры\n\nЗапускаемые примеры лежат в [`examples/`](./examples):\n\n- `01-quickstart.ts` — трек, прямая ссылка и текст песни;\n- `02-search.ts` — поиск и саджесты;\n- `03-device-auth.ts` — получение токена через device flow;\n- `04-realtime.ts` — слежение за «сейчас играет» через Ynison;\n- `05-likes-library.ts` — просмотр библиотеки, цикл лайк/анлайк;\n- `06-playlists.ts` — полный жизненный цикл плейлиста (создать → изменить → удалить);\n- `07-radio.ts` — станции «Моей волны», пакеты треков, обратная связь;\n- `08-charts-and-new.ts` — чарт, новинки, жанры;\n- `09-lyrics.ts` — синхронизированный по времени (LRC) текст песни;\n- `10-download-quality.ts` — выбор качества/кодека, включая lossless (FLAC);\n- `11-artist.ts` — краткая информация об артисте, треки, дискография, похожие;\n- `12-custom-fetch.ts` — инъекция кастомного `fetch` (например, `node-wreq` для TLS-имперсонации).\n\nПодробности и команды запуска — в [`examples/README.md`](./examples/README.md).\n\n## Документация\n\nПолный справочник — на [сайте документации](https://gh.dvxch.link/yandex-music/),\nразбитый по разделам:\n\n- **[Начало работы](docs/guides/01-getting-started.md)** — установка, быстрый старт, `init()`, ошибки.\n- **[Архитектура и конфигурация](docs/guides/02-architecture.md)** — устройство клиента, все опции `ClientOptions`.\n- **[Реализованные эндпоинты](docs/guides/03-endpoints.md)** — полный каталог методов по доменам, скачивание и качество.\n- **[Realtime «сейчас играет»](docs/guides/04-realtime.md)** — Ynison: события, снимок `nowPlaying`, стабильный `deviceId`.\n- **[Примеры и разработка](docs/guides/05-examples.md)** — запускаемые примеры и команды сборки.\n\nПлюс автогенерируемый **[API-reference](https://gh.dvxch.link/yandex-music/)** по\nвсем классам, методам и моделям (TypeDoc).\n\n## Благодарности\n\nСпасибо [MarshalX](https://github.com/MarshalX) за библиотеку\n[yandex-music](https://github.com/MarshalX/yandex-music-api) — бесценный\nориентир по API Яндекс Музыки.\n\n## Лицензия\n\n[MIT](./LICENSE) © dvxch\n","readmeFilename":"README.md"}