Skip to content

README.md

Latest commit

 

History

History
300 lines (216 loc) · 9.32 KB

README.md

File metadata and controls

300 lines (216 loc) · 9.32 KB
Raw

Yandex.Music API (Unofficial) для Node

Это Node.js обертка для Yandex.Music API, используемого в мобильных приложениях (iOS/Android).

язык

English, Русский

Установка

NPM

npm install yamd2

Yarn

yarn add yamd2

PNPM

pnpm add yamd2

Bun

bun add yamd2

Из GitHub

npm install github:Dirold2/yamd2#__dist__

Использование

import { YMApi, WrappedYMApi, Types } from "yamd2";

const api = new YMApi();

(async () => {
  try {
    await api.init({ access_token: "EXAMPLE_TOKEN", uid: 0 });
    const result = await api.search.query("gorillaz", { type: "artist" });
    const artist = result.artists?.results?.[0];
    const tracks = await api.artists.getArtistTracks(artist.id);
    console.log(tracks);
  } catch (e) {
    console.log(`api error ${e.message}`);
  }
})();

Получите токен здесь, а uid здесь.

Доступные методы

Методы сгруппированы по доменам — полям на экземпляре YMApi:

api.auth

  • init(config) — Аутентификация и инициализация

api.account

  • getAccountStatus() — Статус аккаунта
  • getFeed() — Лента пользователя

api.landing

  • getChart(chartType?) — Чарт
  • getNewReleases() — Новые альбомы
  • getNewPlaylists() — Новые плейлисты
  • getPodcasts() — Подкасты
  • getGenres() — Список жанров

api.search

  • query(q, options?) — Поиск по всем или конкретному типу
  • artists(q, options?) — Поиск исполнителей
  • tracks(q, options?) — Поиск треков
  • albums(q, options?) — Поиск альбомов
  • all(q, options?) — Поиск по всем типам

api.tracks

  • getTrack(trackId) — Получить трек(и)
  • getSingleTrack(trackId) — Получить один трек
  • getTrackSupplement(trackId) — Доп. информация
  • getTrackDownloadInfo(trackId, quality?, canUseStreaming?) — Информация о загрузке
  • getTrackDownloadInfoNew(trackId, quality?, codecs?, transport?) — Новый endpoint
  • getTrackDirectLink(downloadUrl, short?) — Прямая ссылка
  • getTrackDirectLinkNew(trackUrl) — Прямая ссылка (новый формат)
  • getTrackShareLink(track) — Ссылка для шаринга
  • getSimilarTracks(trackId) — Похожие треки
  • getTrackSupplement(trackId) — Доп. информация о треке

api.albums

  • getAlbum(albumId, withTracks?) — Получить альбом
  • getAlbums(albumIds) — Несколько альбомов
  • getAlbumWithTracks(albumId) — Альбом с треками

api.artists

  • getArtist(artistId) — Информация об исполнителе
  • getArtists(artistIds) — Несколько исполнителей
  • getArtistTracks(artistId, options?) — Треки исполнителя

api.playlists

  • getPlaylist(playlistId, user?) — Получить плейлист
  • getPlaylists(playlistIds, user?, options?) — Несколько плейлистов
  • getUserPlaylists(userId) — Плейлисты пользователя
  • createPlaylist(name, options?) — Создать плейлист
  • removePlaylist(playlistId) — Удалить плейлист
  • renamePlaylist(playlistId, name) — Переименовать плейлист
  • addTracksToPlaylist(playlistId, tracks, revision, options?) — Добавить треки
  • removeTracksFromPlaylist(playlistId, tracks, revision, options?) — Удалить треки

api.radio

  • getAllStationsList(language?) — Все станции
  • getRecomendedStationsList() — Рекомендованные станции
  • getStationTracks(stationId, queue?) — Треки станции
  • getStationInfo(stationId) — Информация о станции
  • createRotorSession(seeds, includeTracksInResponse?) — Создать ротор-сессию
  • postRotorSessionTracks(sessionId, options) — Получить треки сессии

api.user

  • getLikedTracks(userId?) — Понравившиеся треки
  • getDislikedTracks(userId?) — Непонравившиеся треки

api.queues

  • getQueues() — Все очереди
  • getQueue(queueId) — Конкретная очередь

Обернутый API

Почти все методы обернутого API могут быть вызваны с ID сущности или URL

Треки

  • getConcreteDownloadInfo
  • getMp3DownloadInfo
  • getMp3DownloadUrl

Плейлисты

  • getPlaylist

Альбомы

  • getAlbum
  • getAlbumWithTracks

Исполнители

  • getArtist

Прочее

  • getShortenedLink

Особенности WrappedYMApi

Загрузка треков

import { WrappedYMApi } from "yamd2";

const wrappedApi = new WrappedYMApi();
await wrappedApi.init({ access_token: "TOKEN", uid: 123 });

// Получить информацию для загрузки
const downloadInfo = await wrappedApi.getDownloadInfo("123456", {
  codec: "flac",
  quality: "lossless"
});

// Получить прямую ссылку для загрузки
const downloadUrl = await wrappedApi.getDownloadUrl("123456", {
  codec: "flac",
  quality: "lossless"
});

// Получить лучшую доступную ссылку (по приоритету кодеков)
const bestUrl = await wrappedApi.getBestDownloadUrl("123456");

// Получить ссылку для FFmpeg (RAW MP3)
const ffmpegUrl = await wrappedApi.getDownloadUrlForFFmpeg("123456");

Поддержка URL

// Все методы принимают как ID, так и URL
const track = await wrappedApi.getTrack("123456");
const trackFromUrl = await wrappedApi.getTrack(
  "https://music.yandex.ru/track/123456"
);

const playlist = await wrappedApi.getPlaylist("123456");
const playlistFromUrl = await wrappedApi.getPlaylist(
  "https://music.yandex.ru/users/username/playlists/123456"
);

const album = await wrappedApi.getAlbum("123456");
const albumFromUrl = await wrappedApi.getAlbum(
  "https://music.yandex.ru/album/123456"
);

const artist = await wrappedApi.getArtist("123456");
const artistFromUrl = await wrappedApi.getArtist(
  "https://music.yandex.ru/artist/123456"
);

Конкретные методы загрузки

// MP3 загрузка
const mp3Info = await wrappedApi.getMp3DownloadInfo("123456");
const mp3Url = await wrappedApi.getMp3DownloadUrl("123456");

// AAC загрузка
const aacInfo = await wrappedApi.getAacDownloadInfo("123456");
const aacUrl = await wrappedApi.getAacDownloadUrl("123456");

// FLAC загрузка
const flacInfo = await wrappedApi.getFlacDownloadInfo("123456");
const flacUrl = await wrappedApi.getFlacDownloadUrl("123456");

Поддерживаемые кодеки

  • FLAC - Без потерь, высокое качество
  • FLAC-MP4 - Без потерь в MP4 контейнере
  • AAC - Стандартное сжатие
  • AAC-MP4 - AAC в MP4 контейнере
  • HE-AAC - Высокая эффективность
  • HE-AAC-MP4 - HE-AAC в MP4 контейнере
  • MP3 - Широкая совместимость

Приоритет кодеков

При использовании getBestDownloadUrl() кодеки проверяются в следующем порядке:

  1. FLAC-MP4
  2. FLAC
  3. AAC-MP4
  4. AAC
  5. HE-AAC-MP4
  6. HE-AAC
  7. MP3

Обработка ошибок

import { YMApiError, ExtractionError, DownloadError } from "yamd2";

try {
  const result = await wrappedApi.getDownloadUrl("invalid-url");
} catch (error) {
  if (error instanceof ExtractionError) {
    console.log(`Не удалось извлечь ID из URL: ${error.input}`);
  } else if (error instanceof DownloadError) {
    console.log(
      `URL не найден для трека ${error.trackId} с кодеком ${error.codec}`
    );
  } else if (error instanceof YMApiError) {
    console.log(`Ошибка API: ${error.message}`);
  }
}

Особенности

  • Автоматическое извлечение ID из URL
  • Поддержка зашифрованных ссылок для FLAC
  • Приоритет кодеков для автоматического выбора лучшего качества
  • Обработка ошибок с конкретными типами исключений
  • Поддержка FFmpeg для RAW MP3 загрузки
  • Кэширование для повышения производительности

Благодарности