2022-02-16 20:26:29 +09:00
API Yandex Music — неофициальная Python библиотека
2021-02-01 22:09:07 +09:00
==================================================
2019-07-06 18:44:18 +09:00
2022-02-16 20:26:29 +09:00
Делаю то, что по определённым причинам не сделала компания Yandex.
2019-11-10 09:22:32 +09:00
2020-03-24 20:49:13 +09:00
Маленькое сообщество разработчиков общаются и помогают друг другу
2021-02-01 22:15:04 +09:00
в `Telegram чатике <https://t.me/yandex_music_api> `_ , присоединяйтесь!
2019-07-06 18:44:18 +09:00
.. image :: https://img.shields.io/pypi/v/yandex-music.svg
:target: https://pypi.org/project/yandex-music/
:alt: Версия пакета PyPi
2021-09-19 22:47:19 +09:00
.. image :: https://img.shields.io/badge/python-3.7+-blue.svg
2019-07-06 18:44:18 +09:00
:target: https://pypi.org/project/yandex-music/
:alt: Поддерживаемые Python версии
2021-02-28 03:50:04 +09:00
.. image :: https://codecov.io/gh/MarshalX/yandex-music-api/branch/main/graph/badge.svg
2019-11-10 06:49:28 +09:00
:target: https://codecov.io/gh/MarshalX/yandex-music-api
:alt: Покрытие кода тестами
2019-11-10 09:22:32 +09:00
.. image :: https://api.codacy.com/project/badge/Grade/27011a5a8d9f4b278d1bfe2fe8725fed
:target: https://www.codacy.com/manual/MarshalX/yandex-music-api
:alt: Качество кода
2022-02-16 20:26:29 +09:00
.. image :: https://github.com/MarshalX/yandex-music-api/actions/workflows/pytest_full.yml/badge.svg
:target: https://github.com/MarshalX/yandex-music-api/actions/workflows/pytest_full.yml
2019-11-10 09:22:32 +09:00
:alt: Статус тестов
2019-07-06 20:15:03 +09:00
.. image :: https://readthedocs.org/projects/yandex-music/badge/?version=latest
2019-11-10 06:49:28 +09:00
:target: https://yandex-music.readthedocs.io/ru/latest/?badge=latest
:alt: Статус документации
2019-07-06 18:44:18 +09:00
.. image :: https://img.shields.io/badge/license-LGPLv3-lightgrey.svg
:target: https://www.gnu.org/licenses/lgpl-3.0.html
:alt: Лицензия LGPLv3
2019-11-10 09:22:32 +09:00
.. image :: https://img.shields.io/badge/telegram-чат-blue.svg
2021-02-01 22:15:04 +09:00
:target: https://t.me/yandex_music_api
2019-11-10 09:22:32 +09:00
:alt: Telegram чат
2019-07-06 18:44:18 +09:00
==========
Содержание
==========
- `Введение`_
2019-08-12 05:47:02 +09:00
#. `Доступ к вашим данным на Яндексе`_
2019-07-06 18:44:18 +09:00
- `Установка`_
- `Начало работы`_
#. `Изучение по примерам`_
#. `Логирование`_
#. `Документация`_
2019-11-10 09:22:32 +09:00
- `Получение помощи`_
2022-02-16 20:26:29 +09:00
- `Список изменений`_
2020-03-24 20:49:13 +09:00
- `Реализации на других языках`_
#. `C#`_
#. `PHP`_
#. `JavaScript`_
- `Разработанные проекты`_
#. `Плагин для Kodi`_
#. `Telegram бот-клиент`_
2019-07-06 18:49:01 +09:00
- `Благодарность`_
2021-02-04 20:53:43 +09:00
- `Внесение своего вклада в проект`_
2019-07-06 18:44:18 +09:00
- `Лицензия`_
========
Введение
========
Эта библиотека предоставляется Python интерфейс для никем
незадокументированного и сделанного только для себя API Яндекс Музыки.
2021-09-19 22:47:19 +09:00
Она совместима с версиями Python 3.7+.
2019-07-06 18:44:18 +09:00
В дополнение к реализации чистого API данная библиотека имеет ряд
классов-обёрток объектов высокого уровня дабы сделать разработку клиентов
и скриптов простой и понятной.
2019-08-12 05:47:02 +09:00
--------------------------------
Доступ к вашим данным на Яндексе
--------------------------------
2020-03-24 20:49:13 +09:00
Значения констант
2021-02-28 00:40:29 +09:00
`CLIENT_ID и CLIENT_SECRET <https://github.com/MarshalX/yandex-music-api/blob/main/yandex_music/client.py#L52> `_
2019-08-24 19:53:04 +09:00
позаимствовано у официального приложения-клиента сервиса Яндекс.Музыка из магазина
Microsoft Store. Так как API является закрытым и используется только внутри
компании Яндекс сейчас невозможно зарегистрировать своё собственное приложение на
`oauth.yandex.ru <https://oauth.yandex.ru/> `_ , а следовательно, использовать свои
значения констант.
2019-08-12 05:47:02 +09:00
2019-07-06 18:44:18 +09:00
=========
Установка
=========
2022-02-16 20:26:29 +09:00
Вы можете установить или обновить Yandex Music API при помощи:
2019-07-06 18:44:18 +09:00
.. code :: shell
2019-07-06 19:34:14 +09:00
$ pip install yandex-music --upgrade
2019-07-06 18:44:18 +09:00
Или Вы можете установить из исходного кода с помощью:
.. code :: shell
2022-02-16 20:26:29 +09:00
$ git clone https://github.com/MarshalX/yandex-music-api
2019-07-06 18:49:01 +09:00
$ cd yandex-music-api
2019-07-06 18:44:18 +09:00
$ python setup.py install
=============
Начало работы
=============
2019-08-24 19:53:04 +09:00
Приступив к работе первым делом необходимо создать экземпляр клиента.
Инициализация клиента:
.. code :: python
2021-02-04 19:48:42 +09:00
from yandex_music import Client
2019-08-24 19:53:04 +09:00
client = Client()
Для доступа к своим личным данным следует авторизоваться.
Это можно осуществить через OAuth токен или логин с паролем.
2019-07-06 18:44:18 +09:00
2019-07-09 14:54:25 +09:00
Авторизация по логину и паролю:
2019-07-09 14:58:17 +09:00
2019-07-09 14:54:25 +09:00
.. code :: python
2021-02-04 19:48:42 +09:00
from yandex_music import Client
2019-07-09 14:54:25 +09:00
2019-08-24 19:53:04 +09:00
client = Client.from_credentials('example@yandex.com', 'password')
2019-07-09 14:54:25 +09:00
Авторизация по токену:
2019-07-09 14:58:17 +09:00
2019-07-09 14:54:25 +09:00
.. code :: python
2021-02-04 19:48:42 +09:00
from yandex_music import Client
2019-07-09 14:54:25 +09:00
2019-08-24 19:53:04 +09:00
client = Client('token')
2021-02-04 19:48:42 +09:00
# или
client = Client.from_token('token')
2019-07-09 14:54:25 +09:00
После успешного создания клиента Вы вольны в выборе необходимого метода
2022-02-16 20:26:29 +09:00
из API. В с е они доступны у объекта класса `` Client `` . Подробнее в методах клиента
2019-07-09 14:54:25 +09:00
в `документации <https://yandex-music.readthedocs.io/ru/latest/yandex_music.client.html> `_ .
Пример получения первого трека из плейлиста "Мне нравится" и е г о загрузка:
2019-07-09 14:58:17 +09:00
2019-07-09 14:54:25 +09:00
.. code :: python
2021-02-04 19:48:42 +09:00
from yandex_music import Client
2019-07-09 14:54:25 +09:00
2019-08-24 19:53:04 +09:00
client = Client.from_credentials('example@yandex.com', 'password')
2021-01-28 02:04:02 +09:00
client.users_likes_tracks()[0].fetch_track().download('example.mp3')
2019-07-09 14:54:25 +09:00
В примере выше клиент получает список треков которые были отмечены как
понравившиеся. API возвращает объект
`TracksList <https://yandex-music.readthedocs.io/ru/latest/yandex_music.tracks_list.html> `_
в котором содержится список с треками класса
`TrackShort <https://yandex-music.readthedocs.io/ru/latest/yandex_music.track_short.html> `_ .
2021-03-11 19:24:26 +09:00
Данный класс содержит наиважнейшую информацию о треке и никаких подробностей,
2019-07-09 14:54:25 +09:00
поэтому для получения полной версии трека с о всей информацией необходимо
2022-02-16 20:26:29 +09:00
обратиться к методу `` fetch_track() `` . Затем можно скачать трек методом `` download() `` .
2019-07-09 14:54:25 +09:00
Пример получения треков по ID:
2019-07-09 14:58:17 +09:00
2019-07-09 14:54:25 +09:00
.. code :: python
2021-02-04 19:48:42 +09:00
from yandex_music import Client
2019-07-09 14:54:25 +09:00
2019-08-24 19:53:04 +09:00
client = Client()
2019-07-09 14:54:25 +09:00
client.tracks(['10994777:1193829', '40133452:5206873', '48966383:6693286', '51385674:7163467'])
2019-07-06 18:44:18 +09:00
2019-08-24 19:53:04 +09:00
В качестве ID трека выступает е г о уникальный номер и номер альбома.
Первым треком из примера является следующий трек:
music.yandex.ru/album/**1193829** /track/**10994777**
2019-11-19 05:54:46 +09:00
Выполнение запросов с использование прокси:
.. code :: python
from yandex_music.utils.request import Request
2021-02-04 19:48:42 +09:00
from yandex_music import Client
2019-11-19 05:54:46 +09:00
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 <https://2.python-requests.org/en/master/user/advanced/#proxies> `_
2021-02-28 06:16:50 +09:00
Пример инициализации клиента с обработкой капчи при помощи callback-функции:
.. code :: python
def proc_captcha(captcha_image_url):
print(captcha_image_url)
return input('Код с картинки: ')
client = Client.from_credentials('login', 'pass', captcha_callback=proc_captcha)
2019-11-20 00:38:00 +09:00
Пример инициализации клиента с обработкой капчи:
.. code :: python
def init_client():
2021-02-28 06:16:50 +09:00
client = track_id = captcha_image_url = captcha_answer = None
2019-11-20 00:38:00 +09:00
while not client:
try:
2021-02-28 06:16:50 +09:00
client = Client.from_credentials('login', 'pass', track_id, captcha_answer)
2019-11-20 00:38:00 +09:00
except Captcha as e:
2021-02-28 06:16:50 +09:00
track_id = e.track_id
if e.captcha_image_url:
captcha_image_url = e.captcha_image_url
else:
print('Вы отправили ответ не посмотрев на картинку..')
2019-11-20 00:38:00 +09:00
2021-02-28 06:16:50 +09:00
captcha_answer = input(f'{captcha_image_url}\nВ ве дите код с картинки: ')
2019-11-20 00:38:00 +09:00
2021-02-28 06:16:50 +09:00
return client
2019-11-23 20:42:08 +09:00
2019-07-06 18:44:18 +09:00
--------------------
Изучение по примерам
--------------------
Вот несколько примеров для обзора. Даже если это не Ваш подход к
обучению, пожалуйста, возьмите и бегло просмотрите их.
Код примеров опубликован в открытом доступе, поэтому
Вы можете взять е г о и начать писать вокруг своё.
2021-02-28 00:40:29 +09:00
Посетите `эту страницу <https://github.com/MarshalX/yandex-music-api/blob/main/examples/> `_
2019-07-06 18:44:18 +09:00
чтобы изучить официальные примеры.
-----------
Логирование
-----------
2019-08-24 19:53:04 +09:00
Данная библиотека использует `` logging `` модуль. Чтобы настроить логирование на
стандартный вывод, поместите
2019-07-06 18:44:18 +09:00
.. code :: python
import logging
logging.basicConfig(level=logging.DEBUG,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
в начало вашего скрипта.
2019-08-24 19:53:04 +09:00
Вы также можете использовать логирование в вашем приложении, вызвав
`` logging.getLogger() `` и установить уровень какой Вы хотите:
2019-07-06 18:44:18 +09:00
.. code :: python
logger = logging.getLogger()
logger.setLevel(logging.INFO)
2022-02-16 20:26:29 +09:00
Если Вы хотите `` DEBUG `` логирование:
2019-07-06 18:44:18 +09:00
.. code :: python
logger.setLevel(logging.DEBUG)
2020-03-25 16:07:38 +09:00
============
2019-07-06 18:44:18 +09:00
Документация
2020-03-25 16:07:38 +09:00
============
2019-07-06 18:44:18 +09:00
2020-03-24 20:49:13 +09:00
Документация `` yandex-music-api `` расположена на
2019-08-24 19:53:04 +09:00
`readthedocs.io <https://yandex-music.readthedocs.io/> `_ .
2021-02-04 19:48:42 +09:00
Вашей отправной точкой должен быть класс `` Client `` , а точнее е г о методы.
Именно они выполняют все
2020-03-25 16:07:38 +09:00
запросы на API и возвращают Вам готовые объекты.
`Класс Client на readthedocs.io <https://yandex-music.readthedocs.io/ru/latest/yandex_music.client.html> `_ .
2019-07-06 18:44:18 +09:00
2019-11-10 09:22:32 +09:00
================
Получение помощи
================
Получить помощь можно несколькими путями:
2021-02-01 22:15:04 +09:00
- Задать вопрос в `Telegram чатике <https://t.me/yandex_music_api> `_ , где мы помогаем друг другу, присоединяйтесь!
2022-02-16 20:26:29 +09:00
- Сообщить о б а г е можно `создав Bug Report <https://github.com/MarshalX/yandex-music-api/issues/new?assignees=MarshalX&labels=bug&template=bug-report.md&title=> `_ .
- Предложить новую фичу или задать вопрос можно `создав discussion <https://github.com/MarshalX/yandex-music-api/discussions/new> `_ .
2019-11-10 09:22:32 +09:00
- Найти ответ на вопрос в `документации библиотеки <https://yandex-music.readthedocs.io/ru/latest/> `_ .
2022-02-16 20:26:29 +09:00
================
Список изменений
================
Весь список изменений ведётся в файле `CHANGES.rst <CHANGES.rst> `_ .
2020-03-24 20:49:13 +09:00
===========================
Реализации на других языках
===========================
--
C#
--
Реализация с совершенно другим подходом, так как используется API для frontend'a,
а не мобильных и десктопных приложений:
`Winster332/Yandex.Music.Api <https://github.com/Winster332/Yandex.Music.Api> `_ .
2021-02-04 19:48:42 +09:00
`@Winster332 <https://github.com/Winster332> `_ не сильно проявляет активность,
но существует форк, который продолжил начатое. Эндпоинты изменены с фронтовых на
мобильные: `K1llMan/Yandex.Music.Api <https://github.com/K1llMan/Yandex.Music.Api> `_ .
2020-03-24 20:49:13 +09:00
---
PHP
---
Частично переписанная текущая библиотека на PHP:
`LuckyWins/yandex-music-api <https://github.com/LuckyWins/yandex-music-api> `_ .
----------
JavaScript
----------
API wrapper на Node.JS. Н е обновлялся больше двух лет:
`itsmepetrov/yandex-music-api <https://github.com/itsmepetrov/yandex-music-api> `_ .
2021-02-01 22:05:33 +09:00
Продолжение разработки заброшенной библиотеки: `kontsevoye/ym-api <https://github.com/kontsevoye/ym-api> `_ .
2020-03-24 20:49:13 +09:00
=====================
Разработанные проекты
=====================
---------------
Плагин для Kodi
---------------
2021-02-04 19:48:42 +09:00
Плагин может проигрывать пользовательские плейлисты и плейлисты Яндекса, поиск
по Яндекс Музыке, радио.
2020-03-24 20:49:13 +09:00
2020-03-25 16:07:38 +09:00
Сайт проекта: `ymkodi.ml <https://ymkodi.ml/> `_ .
2021-02-04 19:48:42 +09:00
Исходный код: `kodi.plugin.yandex-music <https://github.com/Angel777d/kodi.plugin.yandex-music> `_ .
Автор: `@Angel777d <https://github.com/Angel777d> `_ .
2020-03-24 20:49:13 +09:00
.. image :: https://raw.githubusercontent.com/Angel777d/kodi.plugin.yandex-music/master/assets/img/kody_yandex_music_plugin.png
2020-03-25 16:07:38 +09:00
:target: https://ymkodi.ml/
2020-03-24 20:49:13 +09:00
:alt: Плагин для Kodi
-------------------
Telegram бот-клиент
-------------------
Неофициальный бот. Умные и ваши плейлисты, понравившиеся треки. Лайки, дизлайки, текста песен,
поиск, распознавание песен, похожие треки! Полноценный клиент на базе мессенджера.
2021-02-04 19:48:42 +09:00
Сайт проекта: `music-yandex-bot.ru <https://music-yandex-bot.ru/> `_ .
Бот в Telegram: `@music_yandex_bot <https://t.me/music_yandex_bot> `_ .
2022-02-16 20:26:29 +09:00
Автор: `@MarshalX <https://github.com/MarshalX> `_ .
2020-03-24 20:49:13 +09:00
2021-02-04 19:48:42 +09:00
Статья на habr.com с описанием реализации: `Под капотом бота-клиента Яндекс.Музыки <https://habr.com/ru/post/487428/> `_ .
2020-03-24 20:49:13 +09:00
.. image :: https://hsto.org/webt/uv/4s/a3/uv4sa3pslohuzlmuzrjzteju2dk.png
:target: https://music-yandex-bot.ru/
:alt: Telegram бот-клиент
2019-07-06 18:49:01 +09:00
=============
Благодарность
=============
Спасибо разработчикам `` python-telegram-bot `` . Выбрал В а с в качестве примера.
2021-02-04 20:53:43 +09:00
===============================
Внесение своего вклада в проект
===============================
Внесение своего вклада максимально приветствуется! Есть перечень пунктов,
который стоит соблюдать. Каждый пункт перечня расписан в `CONTRIBUTING <CONTRIBUTING.md> `_ .
Вы можете помочь и сообщив о `б а г е <https://github.com/MarshalX/yandex-music-api/issues/new?assignees=MarshalX&labels=bug&template=bug-report.md&title=> `_
или о `новом поле пришедшем от API <https://github.com/MarshalX/yandex-music-api/issues/new?assignees=&labels=feature&template=found-unknown-fields.md&title=%D0%9D%D0%BE%D0%B2%D0%BE%D0%B5+%D0%BD%D0%B5%D0%B8%D0%B7%D0%B2%D0%B5%D1%81%D1%82%D0%BD%D0%BE%D0%B5+%D0%BF%D0%BE%D0%BB%D0%B5+%D0%BE%D1%82+API> `_ .
2019-07-06 18:44:18 +09:00
========
Лицензия
========
2019-08-24 19:53:04 +09:00
Вы можете копировать, распространять и модифицировать программное обеспечение
при условии, что модификации описаны и лицензированы бесплатно в соответствии
с `LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html> `_ . Произведения
производных (включая модификации или что-либо статически связанное с библиотекой)
могут распространяться только в соответствии с LGPL-3, но приложения, которые
используют библиотеку, необязательно.