Ynison — протокол реального состояния плеера Яндекс Музыки

Ynison — протокол реального состояния плеера Яндекс Музыки.

Подпакет требует дополнительных зависимостей [ynison] (betterproto, websockets) и не импортируется основным пакетом yandex_music. Пользователи, которым Ynison не нужен, могут не устанавливать эти зависимости.

class yandex_music.ynison.YnisonClient

Синхронный клиент Ynison.

Блокирующий websocket-клиент для подписки на состояние плеера Яндекс Музыки и отправки команд управления. Под капотом открывает два websocket-соединения: сначала к сервису редиректа, затем к персональному хосту Ynison.

Для разовых сценариев «открыть соединение → сделать одно действие → закрыть» используйте yandex_music.ynison.simple или контекстный менеджер session().

Note

Интерфейс рассчитан на опытных разработчиков, знакомых с работой websocket-подобных долгоживущих соединений. Нужно самостоятельно управлять фоновым потоком connect(), обрабатывать переподключения, возможные ошибки receive-loop’а и вовремя вызывать disconnect(). Если нужны типовые операции (получить текущий трек, поставить паузу, переключить трек) — используйте yandex_music.ynison.simple.

latest_state: Последний полученный фрейм состояния.

device_id: Идентификатор этого клиента в Ynison-сессии.

connect()

Блокирующий цикл подключения.

Последовательно: редиректный websocket → state websocket → receive-loop на входящие фреймы. Возвращает управление только после вызова disconnect() (или фатальной ошибки соединения).

Пример:

>>> import threading
>>> client = YnisonClient(token)
>>> threading.Thread(target=client.connect, daemon=True).start()

disconnect()

Останавливает websocket.

Блокирующий connect() вернёт управление в ближайшем receive-цикле. Повторный вызов — no-op.

send(request)

Отправляет запрос по state websocket’у.

Parameters:: request – Готовый PutYnisonStateRequest; обычно собирается через билдеры из yandex_music.ynison.messages.
Raises:: yandex_music.exceptions.YnisonError – Если state websocket ещё не подключён.

session(timeout=10.0)

Контекстный менеджер для разового подключения.

Запускает connect() в daemon-потоке, ждёт первый фрейм состояния и отдаёт клиента с заполненным latest_state. По выходу из блока вызывает disconnect() и дожидается завершения потока.

Parameters:: timeout – Максимальное время ожидания начального фрейма, в секундах.
Yields:: yandex_music.ynison.YnisonClient – Этот же клиент, уже с загруженным состоянием.
Raises:: yandex_music.exceptions.YnisonError – Если начальный фрейм не пришёл за timeout секунд.

class yandex_music.ynison.YnisonClientAsync

Асинхронный клиент Ynison.

Асинхронный websocket-клиент для подписки на состояние плеера и отправки команд управления. По интерфейсу совпадает с синхронным yandex_music.ynison.YnisonClient: все ключевые операции возвращают корутины.

Для разовых сценариев используйте yandex_music.ynison.simple_async или контекстный менеджер session().

Note

Интерфейс рассчитан на опытных разработчиков, знакомых с работой websocket-подобных долгоживущих соединений. Нужно самостоятельно управлять фоновой задачей connect(), обрабатывать переподключения, возможные ошибки receive-loop’а и вовремя вызывать disconnect(). Если нужны типовые операции (получить текущий трек, поставить паузу, переключить трек) — используйте yandex_music.ynison.simple_async.

latest_state: Последний полученный фрейм состояния.

device_id: Идентификатор этого клиента в Ynison-сессии.

async connect()

Корутина цикла подключения.

Последовательно: редиректный websocket → state websocket → receive-loop на входящие фреймы. Возвращает управление только после disconnect() (или фатальной ошибки).

Пример:

>>> import asyncio
>>> client = YnisonClientAsync(token)
>>> task = asyncio.create_task(client.connect())

async disconnect()

Останавливает websocket.

Корутина connect() завершится в ближайшем receive-цикле. Повторный вызов — no-op.

async send(request)

Отправляет запрос по state websocket’у.

Parameters:: request – Готовый PutYnisonStateRequest; обычно собирается через билдеры из yandex_music.ynison.messages.
Raises:: yandex_music.exceptions.YnisonError – Если state websocket ещё не подключён.

session(timeout=10.0)

Асинхронный контекстный менеджер для разового подключения.

Запускает connect() как asyncio.Task, ждёт первый фрейм состояния и отдаёт клиента с заполненным latest_state. По выходу из блока вызывает disconnect() и дожидается завершения задачи.

Parameters:: timeout – Максимальное время ожидания начального фрейма, в секундах.
Yields:: yandex_music.ynison.YnisonClientAsync – Этот же клиент, уже с загруженным состоянием.
Raises:: yandex_music.exceptions.YnisonError – Если начальный фрейм не пришёл за timeout секунд.

Messages

Билдеры запросов Ynison

Simple

Простой интерфейс Ynison

SimpleAsync

Простой асинхронный интерфейс Ynison