yandex-music 1.0.0

Делаю то, что по определённым причинам не сделала компания Yandex.

API Yandex Music - неофициальная Python библиотека

Делаю то, что по определённым причинам не сделала компания Yandex.

Маленькое сообщество разработчиков общаются и помогают друг другу в Telegram чатике, присоединяйтесь!

Содержание

• Введение

  1. Доступ к вашим данным на Яндексе

• Установка

• Начало работы

  1. Изучение по примерам

  2. Логирование

  3. Документация

• Получение помощи

• Реализации на других языках

  1. C#

  2. PHP

  3. JavaScript

• Разработанные проекты

  1. Плагин для Kodi

  2. Telegram бот-клиент

• Благодарность

• Внесение своего вклада в проект

• Лицензия

Введение

Эта библиотека предоставляется Python интерфейс для никем незадокументированного и сделанного только для себя API Яндекс Музыки.

Она совместима с версиями Python 3.6+.

В дополнение к реализации чистого API данная библиотека имеет ряд классов-обёрток объектов высокого уровня дабы сделать разработку клиентов и скриптов простой и понятной.

Доступ к вашим данным на Яндексе

Значения констант CLIENT_ID и CLIENT_SECRET позаимствовано у официального приложения-клиента сервиса Яндекс.Музыка из магазина Microsoft Store. Так как API является закрытым и используется только внутри компании Яндекс сейчас невозможно зарегистрировать своё собственное приложение на oauth.yandex.ru, а следовательно, использовать свои значения констант.

Установка

Вы можете установить или обновить yandex-music-api при помощи:

$ pip install yandex-music --upgrade

Или Вы можете установить из исходного кода с помощью:

$ git clone https://github.com/MarshalX/yandex-music-api --recursive
$ cd yandex-music-api
$ python setup.py install

Начало работы

Приступив к работе первым делом необходимо создать экземпляр клиента.

Инициализация клиента:

from yandex_music import Client

client = Client()

Для доступа к своим личным данным следует авторизоваться. Это можно осуществить через OAuth токен или логин с паролем.

Авторизация по логину и паролю:

from yandex_music import Client

client = Client.from_credentials('[e-mail]', 'password')

Авторизация по токену:

from yandex_music import Client

client = Client('token')
# или
client = Client.from_token('token')

После успешного создания клиента Вы вольны в выборе необходимого метода из API. Все они доступны у объекта класса Client. Подробнее в методах клиента в документации.

Пример получения первого трека из плейлиста “Мне нравится” и его загрузка:

from yandex_music import Client

client = Client.from_credentials('[e-mail]', 'password')
client.users_likes_tracks()[0].fetch_track().download('example.mp3')

В примере выше клиент получает список треков которые были отмечены как понравившиеся. API возвращает объект TracksList в котором содержится список с треками класса TrackShort. Данные класс содержит наиважнейшую информацию о треке и никаких подробностей, поэтому для получения полной версии трека со всей информацией необходимо обратиться к методу fetch_track(). Затем можно скачать трек методом download().

Пример получения треков по ID:

from yandex_music import Client

client = Client()
client.tracks(['10994777:1193829', '40133452:5206873', '48966383:6693286', '51385674:7163467'])

В качестве ID трека выступает его уникальный номер и номер альбома. Первым треком из примера является следующий трек: music.yandex.ru/album/1193829/track/10994777

Выполнение запросов с использование прокси:

from yandex_music.utils.request import Request
from yandex_music import Client

request = Request(proxy_url='socks5://user:password@host:port')
client = Client(request=request)

Примеры proxy url:

• socks5://user:password@host:port

• http://host:port

• https://host:port

• http://user:password@host

Больше примеров тут: proxies - advanced usage - requests

Пример инициализации клиента с обработкой капчи:

def init_client():
    client = captcha_key = captcha_answer = None
    while not client:
        try:
            client = Client.from_credentials('login', 'pass', captcha_answer, captcha_key)
        except Captcha as e:
            e.captcha.download('captcha.png')

            captcha_key = e.captcha.x_captcha_key
            captcha_answer = input('Число с картинки: ')

    return client

Пример инициализации клиента с обработкой капчи при помощи callback-функции:

def proc_captcha(captcha):
    captcha.download('captcha.png')
    return input('Число с картинки: ')

client = Client.from_credentials('login', 'pass', captcha_callback=proc_captcha)

Изучение по примерам

Вот несколько примеров для обзора. Даже если это не Ваш подход к обучению, пожалуйста, возьмите и бегло просмотрите их.

Код примеров опубликован в открытом доступе, поэтому Вы можете взять его и начать писать вокруг своё.

Посетите эту страницу чтобы изучить официальные примеры.

Логирование

Данная библиотека использует logging модуль. Чтобы настроить логирование на стандартный вывод, поместите

import logging
logging.basicConfig(level=logging.DEBUG,
                    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')

в начало вашего скрипта.

Вы также можете использовать логирование в вашем приложении, вызвав logging.getLogger() и установить уровень какой Вы хотите:

logger = logging.getLogger()
logger.setLevel(logging.INFO)

Если Вы хотите DEBUG логирование:

logger.setLevel(logging.DEBUG)

Документация

Документация yandex-music-api расположена на readthedocs.io. Вашей отправной точкой должен быть класс Client, а точнее его методы. Именно они выполняют все запросы на API и возвращают Вам готовые объекты. Класс Client на readthedocs.io.

Получение помощи

Получить помощь можно несколькими путями:

• Задать вопрос в Telegram чатике, где мы помогаем друг другу, присоединяйтесь!

• Сообщить о баге, предложить новую фичу или задать вопрос можно создав issue.

• Найти ответ на вопрос в документации библиотеки.

Реализации на других языках

C#

Реализация с совершенно другим подходом, так как используется API для frontend’a, а не мобильных и десктопных приложений: Winster332/Yandex.Music.Api.

@Winster332 не сильно проявляет активность, но существует форк, который продолжил начатое. Эндпоинты изменены с фронтовых на мобильные: K1llMan/Yandex.Music.Api.

PHP

Частично переписанная текущая библиотека на PHP: LuckyWins/yandex-music-api.

JavaScript

API wrapper на Node.JS. Не обновлялся больше двух лет: itsmepetrov/yandex-music-api. Продолжение разработки заброшенной библиотеки: kontsevoye/ym-api.

Разработанные проекты

Плагин для Kodi

Плагин может проигрывать пользовательские плейлисты и плейлисты Яндекса, поиск по Яндекс Музыке, радио.

Сайт проекта: ymkodi.ml. Исходный код: kodi.plugin.yandex-music. Автор: @Angel777d.

Telegram бот-клиент

Неофициальный бот. Умные и ваши плейлисты, понравившиеся треки. Лайки, дизлайки, текста песен, поиск, распознавание песен, похожие треки! Полноценный клиент на базе мессенджера.

Сайт проекта: music-yandex-bot.ru. Бот в Telegram: @music_yandex_bot. Автор: @MarshalX.

Статья на habr.com с описанием реализации: Под капотом бота-клиента Яндекс.Музыки.

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

Спасибо разработчикам python-telegram-bot. Выбрал Вас в качестве примера.

Внесение своего вклада в проект

Внесение своего вклада максимально приветствуется! Есть перечень пунктов, который стоит соблюдать. Каждый пункт перечня расписан в CONTRIBUTING.

Вы можете помочь и сообщив о баге или о новом поле пришедшем от API.

Лицензия

Вы можете копировать, распространять и модифицировать программное обеспечение при условии, что модификации описаны и лицензированы бесплатно в соответствии с LGPL-3. Произведения производных (включая модификации или что-либо статически связанное с библиотекой) могут распространяться только в соответствии с LGPL-3, но приложения, которые используют библиотеку, необязательно.

Список изменений

Версия 1.0.0

06.02.2021

Стабильная версия библиотеки

Переломные изменения

• Поле error класса Artist теперь называется reason.

• Метод users_playlists класса Client теперь возвращает один объект плейлиста, когда был передан один kind. При передаче списка в kind вернётся список плейлистов (#318).

• Поле labels класса Album теперь может содержать список из строк, а не только список объектов класса Label.

Крупные изменения

• Добавлены примеры в папку examples.

• Добавлена поддержка рекомендаций для плейлистов (#324):

  • Добавлен класс PlaylistRecommendations.

  • Добавлен метод клиента для получения рекомендаций (users_playlists_recommendations).

  • Добавлен метод get_recommendations классу Playlist для получения рекомендаций.

• Добавлено получение чартов (#294):

  • Добавлены новые классы: ChartInfo, ChartInfoMenu, ChartInfoMenuItem.

  • Добавлен метод клиента для получения чарта (chart).

• Добавлена поддержка тегов/подборок (#192):

  • Добавлены новые классы: TagResult, Tag.

  • Добавлен новый метод клиента для получения тегов (tags).

• Добавлено присоединение к коллективному плейлисту (#317):

  • Добавлен новый метод клиента для присоединения (playlists_collective_join).

• Добавлена поддержка очередей прослушивания (#246):

  • Добавлены новые классы: Context, Queue, QueueItem.

  • Добавлены новые методы в Client: queues_list, queue, queue_update_position, queue_create.

  • Добавлены поля track_id и from_ в класс TrackId.

  • Добавлена возможность смены языка у клиента для ответов от API.

  • Добавлена десериализация любого объекта в JSON пригодного для отправки в запросе на Яндекс API.

• Добавлены следующие методы для Client:

  • new_releases – получение полного списка всех новых релизов.

  • new_playlists – получение полного списка всех новый плейлистов.

  • podcasts – получение подкаста с лендинга.

• Добавлены новые сокращения в модели:

  • download_cover_white, download_cover_uri в MixLink.

  • download_image в Promotion.

  • artists_name в Album и Track.

  • fetch_track, track_full_id в TrackId.

  • fetch_tracks в TracksList.

  • insert_track, delete_tracks, delete в Playlist.

  • playlist_id, fetch_playlist в PlaylistId.

  • get_current_track в Queue.

  • fetch_queue в QueueItem.

  • next_page, get_page, prev_page в Search.

  • и другие…

• Добавлена поддержка новых типов поиска: подкасты, выпуски, пользователи.

• Добавлен коллбек для обработки новых полей.

• Добавлена информацию по поводу запуска потока по треку, плейлисту и др.

• Добавлена десериализация decomposed у Artist (#10).

• Добавлен __len__ для TracksList (#380).

• Добавлены __iter__, __len__ и __getitem__ для классов представляющих список каких-либо объектов.

• Добавлено сокращение fetch_tracks классу Playlist для получения треков плейлиста.

• Добавлен метод get_url классу Icon для получения прямой ссылки на изображение.

• Класс User расширен для поддержки поля user_info из Track (поля full_name, display_name).

• Добавлены новые классы по отчётам с Telegram бота (#306, #398):

  • LandingList.

  • RenewableRemainder.

  • Alert.

  • AlertButton.

  • StationData.

  • Brand.

  • Contest.

  • OpenGraphData.

  • NonAutoRenewable.

  • Operator.

  • Deactivation.

  • PoetryLoverMatch.

  • Deprecation.

• Добавлены новые поля классам по отчётам с Telegram бота (#306, #398):

  • plus в Product.

  • non_auto_renewable_remainder в Subscription.

  • og_image в Artist.

  • meta_type в Album.

  • advertisement в Status.

  • best в Track.

  • offer_id и artist_ids в Vinyl.

  • playlists в BriefInfo.

  • is_custom в Cover.

  • play_count, recent, chart, track в TrackShort.

  • url_part, og_title, image, cover_without_text, background_color, text_color, id_for_from, similar_playlists, last_owner_playlists в Playlist.

  • bg_color в Chart.

  • error в Artist.

  • substituted, matched_track, can_publish, state, desired_visibility, filename, user_info, meta_data в Track.

  • copyright_name, copyright_cline в Cover.

  • direct в DownloadInfo.

  • cheapest, title, family_sub, fb_image, fb_name, family, intro_period_duration, intro_price, start_period_duration, start_price, licence_text_parts в Product.

  • storage_dir, duplicates в Album.

  • subscribed в ArtistEvent.

  • description в GeneratedPlaylist.

  • genre в Event.

  • show_in_regions в Genre.

  • cover_uri в MixLink.

  • og_description, top_artist в Playlist.

  • full_image_url, mts_full_image_url в Station.

  • coauthors и recent_tracks в Playlist.

  • regions в User.

  • users, podcasts, podcast_episodes, type_, page, per_page в Search.

  • short_description, description, is_premiere, is_banner в Like.

  • master_info в AutoRenewable.

  • station_data и bar_below в Status.

  • family_auto_renewable в Subscription.

  • misspell_result и misspell_original в Search.

  • experiment в класс Status.

  • operator и non_auto_renewable в Subscription.

  • text_color, short_description, description, is_premiere и is_banner в Album.

  • hand_made_description в Artist.

  • metrika_id в Playlist.

  • og_image в Tag.

  • url в Lyrics.

  • number, genre в MetaData.

  • poetry_lover_matches в Track.

  • contest, dummy_description, dummy_page_description, dummy_cover, dummy_rollover_cover, og_data, branding в Playlist.

  • available_as_rbt, lyrics_available, remember_position, albums, duration_ms, explicit, start_date, likes_count, deprecation в Album.

  • lyricist, version, composer в MetaData.

  • last_releases в BriefInfo.

  • ya_money_id в Artist (#351, #370).

  • playlist_uuid в Playlist.

  • sync_queue_enabled в UserSettings.

  • background_video_uri, short_description, is_suitable_for_children в Track (#376).

  • meta_type, likes_count в Album (#386).

  • deprecation в Album.

  • available_regions в Album.

  • type, ready в Playlist.

  • description в Supplement.

Незначительные изменения и/или исправления

• Добавлена опциональность следующим полям:

  • все поля в MetaData.

  • advertisement в Status.

  • text_language в Lyrics.

  • provider_video_id в VideoSupplement.

  • title в VideoSupplement (#403).

  • instructions в Deactivation (#402).

  • id в Album (#401).

• Исправлена десериализация подкастов, эпизодов подкастов и пользователей в лучшем результате поиска.

• Исправлена десериализация альбомов. В зависимости от запроса содержимое лейблов может быть списком объектом или списком строк (в поиске).

• Исправлен выбор настроек радио.

• Исправлены ошибки в документации.

• Протестирована работа на Python 3.9.

Версия 0.1.1

25.03.2020

Закончено документирование всех классов и основных методов!

Переломные изменения

• Классы отметок “мне нравится” для альбомов, плейлистов и исполнителей обобщены. Теперь представлены одним классом.

  • Удаленные классы:

    • ArtistsLikes.

    • AlbumsLikes.

    • PlaylistsLikes.

  • Новый класс: Like (поле type для определения содержимого).

• Изменено название пакета с status на account (#195).

• Исправлено выбрасываемое исключение при таймауте:

  • Прошлое исключение: TimeoutError (built-in).

  • Новое исключение: TimedOut (yandex_music.exceptions).

• Удалены следующие файлы: requirements.txt, requirements-dev.txt, requirements-docs.txt.

Крупные изменения

• Добавлено обнаружение новых полей с просьбой сообщить о них (#216).

  • Добавлена проверка на неизвестные поля.

  • Добавлен вывод отладочной информации в виде warning’a.

  • Добавлен шаблон issue для отправки логов.

• Добавлено поле type для класса SearchResult для определения типа результата поиска по объекту.

• Добавлены настройки пользователя (#195):

  • Добавлен класс UserSettings.

  • Добавлен метод для получения своих настроек (account_settings).

  • Добавлен метод для получения настроек другого пользователя (users_settings).

  • Добавлен метод для изменения настроек (account_settings_set).

• Добавлен возможность получить похожие треки (#197):

  • Добавлен класс TracksSimilar с полями трека и списка похожих треков.

  • Добавлен метод для получения похожих треков (tracks_similar).

• Добавлены шоты от Алисы (#185):

  • Добавлен метод after_track в класс Client для получения контента для воспроизведения после трека (реклама, шот).

  • Добавлены методы для загрузки обложки и аудиоверсии шота.

  • Добавлены новые классы:

    • Shot

    • ShotData

    • ShotEvent

    • ShotType

• Добавлен метод для изменения видимости плейлиста (#179).

• Добавлена поддержка Яндекс.Радио (#20):

  • Исправлена отправка фидбека.

  • Написана инструкция по использованию (в доке к методу).

  • Добавлен аргумент для перехода по цепочке треков.

  • Добавлен метод для изменения настроек станции.

Незначительные изменения и/или исправления

• Убрано дублирование информации в документации (#247).

• Добавлены новые поля в класс Track: version, remember_position (#238).

• Добавлено исключение InvalidBitrate при попытке загрузить недопустимый трек по критериям (кодек, битрейт).

• Исправлено получение прямой ссылки на файл с кодеком AAC (#237, #25).

• Исправлено получение плейлиста с Алисой в лендинге (#185).

• Исправлено название поля с ссылкой на источник в классе Description (с url на uri).

• Исправлена десериализация несуществующего исполнителя.

• Добавлено поле version в класс Album (#178).

• Поле picture класса Vinyl теперь опциональное.

• Поле week класса Ratings теперь опциональное.

• Поле product_id класса AutoRenewable теперь опциональное (#182).

• Правки замечаний по codacy.

Версия 0.0.16

29.12.2019

Переломные изменения

• Поле account переименовано в me и теперь содержит объект Status, вместо Account (#162).

• Убрано использование зарезервированных имён в аргументах конструкторов (теперь они с _ на конце). Имена с нижними подчёркиваниями есть как при сериализации так и при десериализации (#168).

Крупные изменения

• Добавлены аннотации типов во всей библиотеке!

Незначительные изменения и/или исправления

• Добавлен аргумент fetch_account_status для опциональности получения информации об аккаунте при инициализации клиента (#162).

• Добавлены тесты c передачей пустого словаря в de_json и de_list (#174).

• Использование ujson при наличии, обновлены зависимости (#161).

• Добавлен в зависимости для разработки importlib_metadata для поддержки старых версий (в новой версии pytest его больше не используют, в угоду importlib.metadata #pytest-5537)) (#161).

• Добавлен в зависимости для разработки atomicwrites, который используется pytest теперь только на Windows - #pytest-6148 (#161).

• Исправлен баг с передачей timeout аргумента в аргумент params в следующих методах: artists, albums, playlists_list (#120).

• Исправлена инициализация клиента при помощи логина и пароля с использованием прокси (#159).

• Исправлен баг в загрузке обложки альбома.

Версия 0.0.15

01.12.2019

Переломные изменения

• У классов Artist, Track и Playlist изменился перечень полей для генерации хеша.

Крупные изменения

• Добавлена возможность выполнять запросы через прокси-сервер для использовании библиотеки на зарубежных серверах (#139).

  • Добавлен пример использования в README.

• Добавлена обработка капчи при авторизации с возможностью использования callback-функции для её обработки (#140):

  • Новые исключения:

    • Captcha:

      • CaptchaRequired.

      • CaptchaWrong.

  • Новые классы:

    • CaptchaResponse.

  • Новые примеры в README:

    • Пример обработки с использованием callback-функции.

    • Пример полностью своей обработки капчи.

• Добавлена документация для класса Search (#83).

• Добавлена возможность получения всех альбомов исполнителя (#141):

  • Новые классы:

    • ArtistAlbums.

  • Новые методы:

    • artists_direct_albums у Client.

    • get_albums у Artist.

• Добавлена обработка несуществующего плейлиста (#147):

  • Новые классы:

    • PlaylistAbsence.

Незначительные изменения и/или исправления

• Исправлен баг с загрузкой файлов (#149).

• Исправлен баг некорректной десериализации плейлиста при отсутствии прав на него (#147).

• Исправлен баг неправильной десериализации треков и артистов у собственных загруженных файлов (#154).

Версия 0.0.14

10.11.2019

Переломные изменения

• Практически у всех классов был обновлён список полей участвующих при сравнении объектов.

• Если в атрибутах для сравнения объектов присутствуют списки, то они будут преобразованы к frozenset.

• Убрано конвертирование даты из строки в объект. Теперь все даты представлены строками в ISO формате.

• Классы AlbumSearchResult, ArtistSearchResult, PlaylistSearchResult, TrackSearchResult, VideoSearchResult были объединены в один - SearchResult.

Крупные изменения

• Добавлен метод получения треков исполнителя (#123).

• Добавлены классы-обёртки над пагинацией (Pager) и списка треков артиста (ArtistsTracks).

• Добавлено 554 unit-теста для всех классов-обёрток над объектами API.

• Добавлен codecov и workflows для GitHub Actions.

Незначительные изменения и/или исправления

• Поле cover_uri класса Album теперь опциональное.

• Поле region у класса Account теперь не обязательное.

• Исправлен баг в .to_dict() методе, связанный с десериализцией объектов списков и словарей.

• Исправлен баг в .to_dict() методе, связанный с не рекурсивной десериализацией.

• Исправлена десериализация similar_artists в BriefInfo.

• Исправлен баг с десериализацией artist в классе ArtistEvent.

• Исправлен баг десериализации списка альбомов и артистов у класса Track (#122).

• Исправлена загрузка обложки у трека.

• Исправлены сравнения объектов.