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

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

Набор функций для конструирования PutYnisonStateRequest под типичные действия: инициализация подключения, пауза/возобновление, переключение трека, изменение громкости. Используется клиентами (yandex_music.ynison.YnisonClient, yandex_music.ynison.YnisonClientAsync) в их методах управления (pause, next_track и т.д.). Вызывать билдеры напрямую нужно только для собственных сценариев через client.send(request).

yandex_music.ynison.messages.random() → x in the interval [0, 1).
yandex_music.ynison.messages.generate_device_id(seed=None)

Генерирует идентификатор устройства.

Без seed случайный. С seed детерминированный: один и тот же seed всегда даёт один и тот же идентификатор, поэтому повторные запуски не плодят новые устройства в Ynison-сессии.

Parameters:

seed – Произвольная строка для детерминированной генерации.

Returns:

Идентификатор из 12 hex-символов.

Return type:

str

yandex_music.ynison.messages.get_timestamp()

Возвращает текущее unix-время в миллисекундах.

Returns:

Время в миллисекундах от эпохи Unix.

Return type:

int

yandex_music.ynison.messages.generate_request_id()

Генерирует уникальный идентификатор запроса.

Returns:

UUID4 в строковом представлении.

Return type:

str

yandex_music.ynison.messages.build_full_state_request(device_id, title='Python SDK', app_name='yandex-music')

Собирает начальный запрос регистрации устройства как remote control.

Отправляется сразу после подключения state websocket’а. Регистрирует устройство с возможностями дистанционного пульта (не плеер) и пустой очередью воспроизведения.

Parameters:

  • device_id – Идентификатор этого устройства.

  • title – Название устройства, которое увидят другие клиенты в списке устройств.

  • app_name – Название приложения.

Returns:

Запрос UpdateFullState с device capabilities remote control.

Return type:

yandex_music.ynison.models.ynison_state.PutYnisonStateRequest

yandex_music.ynison.messages.build_set_paused_request(device_id, current_status, paused)

Собирает запрос паузы или возобновления воспроизведения.

Клонирует текущий PlayingStatus, меняя флаг paused и обновляя версию. Прогресс пересчитывается на текущий момент (см. yandex_music.ynison.utils.get_current_progress_ms()), иначе пауза откатила бы трек к позиции из последнего фрейма.

Parameters:

  • device_id – Идентификатор устройства, инициировавшего изменение.

  • current_status – Текущий статус воспроизведения с сервера.

  • paused – True, чтобы поставить на паузу, False, чтобы продолжить.

Returns:

Запрос UpdatePlayingStatus с подменённым флагом paused.

Return type:

yandex_music.ynison.models.ynison_state.PutYnisonStateRequest

yandex_music.ynison.messages.build_change_track_request(device_id, current_state, delta)

Собирает запрос перехода на соседний трек в очереди.

Клонирует текущий PlayerQueue, меняя только current_playable_index и версию. Сдвиг считается в порядке воспроизведения, то есть с учётом перемешивания. Статус воспроизведения сбрасывается на нулевой прогресс с сохранением флага паузы; длительность нового трека в очереди неизвестна и выставляется в 0, её заполнит устройство-плеер.

Parameters:

  • device_id – Идентификатор устройства, инициировавшего изменение.

  • current_state – Текущее состояние плеера с сервера.

  • delta – Сдвиг в порядке воспроизведения; 1 для следующего трека, -1 для предыдущего.

Returns:

Запрос UpdatePlayerState с обновлённым индексом и версией.

Return type:

yandex_music.ynison.models.ynison_state.PutYnisonStateRequest

Raises:

yandex_music.exceptions.YnisonQueueBoundaryError – Если сдвиг выходит за пределы очереди (например, next на последнем треке).

yandex_music.ynison.messages.build_next_track_request(device_id, current_state)

Собирает запрос перехода на следующий трек.

Parameters:

  • device_id – Идентификатор устройства, инициировавшего изменение.

  • current_state – Текущее состояние плеера с сервера.

Returns:

Запрос UpdatePlayerState со следующим индексом.

Return type:

yandex_music.ynison.models.ynison_state.PutYnisonStateRequest

Raises:

yandex_music.exceptions.YnisonQueueBoundaryError – Если текущий трек последний.

yandex_music.ynison.messages.build_previous_track_request(device_id, current_state)

Собирает запрос перехода на предыдущий трек.

Parameters:

  • device_id – Идентификатор устройства, инициировавшего изменение.

  • current_state – Текущее состояние плеера с сервера.

Returns:

Запрос UpdatePlayerState с предыдущим индексом.

Return type:

yandex_music.ynison.models.ynison_state.PutYnisonStateRequest

Raises:

yandex_music.exceptions.YnisonQueueBoundaryError – Если текущий трек первый.

yandex_music.ynison.messages.build_set_volume_request(device_id, target_device_id, volume)

Собирает запрос изменения громкости на целевом устройстве.

Parameters:

  • device_id – Идентификатор устройства, инициировавшего изменение.

  • target_device_id – Идентификатор устройства, на котором меняется громкость.

  • volume – Новая громкость в диапазоне [0.0; 1.0]; значения вне диапазона обрезаются.

Returns:

Запрос UpdateVolumeInfo с новым значением громкости и версией.

Return type:

yandex_music.ynison.models.ynison_state.PutYnisonStateRequest