Accessify Play

Ваша вселенная Spotify, управляемая NVDA.

Выйдите за рамки простого воспроизведения. Accessify Play превращает NVDA в мощный командный центр для всего вашего взаимодействия с Spotify. Управляйте воспроизведением на любом из ваших устройств — ПК, телефоне, умной колонке или консоли — прямо с клавиатуры, не прикасаясь к приложению Spotify.

Ищите, открывайте, управляйте плейлистами и контролируйте свою музыку с беспрецедентной свободой. Именно так и должен восприниматься Spotify с экранным диктором.

⚠️ Важно: Требуется Spotify Premium!

Из-за ограничений API Spotify для функций управления воспроизведением требуется активная подписка Spotify Premium. Бесплатные аккаунты имеют ограниченный доступ к API и не будут корректно работать с этим дополнением.

Предварительные требования

• Активная подписка Spotify Premium.
• Версия NVDA 2024.4 или новее.

🎤 Поддержка текстов песен

Accessify Play теперь включает поддержку текстов песен на основе lrclib.net — бесплатной, открытой и развиваемой сообществом базы данных текстов песен. Все тексты, предоставляемые lrclib.net, распространяются под лицензией Creative Commons Zero (CC0), что означает их нахождение в общественном достоянии и возможность свободного использования без каких-либо ограничений по авторским правам. Это ключевое отличие, делающее данную функцию законной, распространяемой и полностью соответствующей требованиям — в отличие от получения данных из нелицензионных источников.

В командном слое (NVDA+Alt+g) доступны два режима работы с текстами песен:

• W — Окно текста песни: Открывает всплывающее окно с полным текстом текущей песни в виде обычного текста. Перемещайтесь по строкам с помощью клавиш со стрелками — NVDA будет читать каждую строку по мере перемещения.
• Y — Автоматическое чтение текста: NVDA автоматически озвучивает каждую строку текста в реальном времени, синхронизируясь с воспроизведением музыки. Нажмите Y снова, чтобы остановить чтение.

Лицензия

Это дополнение распространяется под лицензией GNU General Public License v2.0.

✨ Вселенная возможностей

Accessify Play насыщен функциями, организованными для вашего удобства:

Управление воспроизведением и информация

• Универсальное управление: Воспроизведение, пауза, переключение треков, перемотка и регулировка громкости на любом активном устройстве Spotify Connect.
• Установка точной громкости: Установите уровень громкости с точностью до процента (0-100) через диалог.
• Мгновенная информация: В любой момент озвучьте текущий трек, исполнителя и альбом.
• Информация об очереди: Озвучьте следующий трек в очереди или откройте полный интерактивный список предстоящих композиций.
• Автоматические объявления: При желании NVDA будет автоматически объявлять новый трек при каждой смене композиции.
• Лёгкий обмен: Скопируйте URL-адрес текущего трека из Spotify в буфер обмена.
• Воспроизведение по ссылке: Откройте диалог для воспроизведения любого трека по его URL-адресу из Spotify.
• Окно текста песни (W): Откройте всплывающее окно с полным текстом текущего трека, доступным для построчного чтения с помощью клавиш со стрелками.
• Автоматическое чтение текста (Y): Включите автоматическое озвучивание строк текста в реальном времени в синхронизации с музыкой.

Управление библиотекой и взаимодействие

• Быстрое сохранение: Мгновенно сохраните текущий трек в «Понравившиеся песни» одной командой.
• Добавление в плейлист: Быстро добавьте текущий трек в любой из ваших плейлистов.
• Полный набор инструментов управления: Откройте мощный многозадачный диалог для управления каждым аспектом вашей библиотеки:
  • Плейлисты: Создавайте новые плейлисты, обновляйте данные, удаляйте их и управляйте треками внутри.
  • Сохранённая библиотека: Просматривайте и удаляйте треки из «Понравившихся песен».
  • Отслеживаемые исполнители: Просматривайте всех исполнителей, на которых вы подписаны, с возможностью отписаться или изучить их музыку.

Поиск и открытия

• Расширенный поиск: Мощный диалог поиска песен, альбомов, исполнителей, плейлистов и подкастов.
• Ваши лучшие хиты: Просматривайте ваши самые прослушиваемые треки и исполнителей за последний месяц, 6 месяцев или всё время.
• Новые релизы: Просматривайте новейшие альбомы и синглы, подобранные для вас Spotify.
• Глубокое изучение: Из результатов поиска по исполнителю перейдите к полной дискографии или найдите похожих исполнителей.
• Поиск подкастов: Просматривайте и воспроизводите любые эпизоды из найденных подкастов.

⌨️ Командный центр с клавиатуры

| Команда | Сочетание клавиш | | :--------------------------- | :----------------------------------- | | Воспроизведение/Пауза | NVDA+Shift+Alt+Space | | Следующий трек | NVDA+Shift+Alt+RightArrow | | Предыдущий трек | NVDA+Shift+Alt+LeftArrow | | Увеличить громкость | NVDA+Shift+Alt+UpArrow | | Уменьшить громкость | NVDA+Shift+Alt+DownArrow | | Установить точную громкость | NVDA+Shift+Alt+V | | Перемотка вперёд (настраиваемо)| Control+Alt+NVDA+RightArrow | | Перемотка назад (настраиваемо)| Control+Alt+NVDA+LeftArrow | | Озвучить текущий трек | NVDA+Shift+Alt+I | | Озвучить время воспроизведения| NVDA+Alt+Shift+T | | Скопировать URL трека | NVDA+Shift+Alt+C | | Открыть диалог поиска | NVDA+Shift+Alt+S | | Открыть диалог «Воспроизвести по ссылке» | NVDA+Shift+Alt+P | | Открыть список очереди | NVDA+Shift+Alt+Q | | Озвучить следующий в очереди | NVDA+Shift+Alt+N | | Сохранить трек в библиотеку | NVDA+Alt+Shift+L | | Добавить трек в плейлист | NVDA+Alt+Shift+A | | Открыть диалог управления | NVDA+Alt+Shift+M |

Командный слой (NVDA+Alt+g) — Краткая справка

Сначала нажмите NVDA+Alt+g, чтобы войти в командный слой, затем нажмите одну из перечисленных ниже клавиш.

| Клавиша | Действие | | :-- | :----- | | P | Воспроизведение / Пауза | | N | Следующий трек | | B | Предыдущий трек | | S | Поиск | | V | Установить громкость | | I | Озвучить текущий трек | | T | Озвучить время воспроизведения | | L | Добавить/Удалить из «Понравившихся» | | H | Включить/Выключить перемешивание | | R | Переключить режим повтора | | Q | Список очереди | | A | Добавить в плейлист | | M | Диалог управления | | D | Переключить устройство | | U | Воспроизвести по ссылке | | J | Диалог перемотки | | X | Скопировать универсальную ссылку (Song.link) | | Z | Таймер сна | | W | Окно текста песни | | Y | Включить/Выключить автоматическое чтение текста | | F1 | Показать справку по командам | | F2 | Открыть редактор командного слоя | | F4 | Открыть настройки | | Escape | Закрыть командный слой |

Примечание о функции очереди Spotify: Понимание её поведения

Вы могли заметить, что список очереди в Accessify Play (NVDA+Shift+Alt+Q) может быть одновременно невероятно точным и, в других случаях, совершенно не синхронизироваться с тем, что играет следующим. Такое поведение не является ошибкой, а является прямым следствием данных, предоставляемых API Spotify.

Вот точное описание того, когда список очереди дополнения является надёжным, а когда нет:

Когда список очереди ТОЧЕН

Список очереди, отображаемый дополнением, корректно отражает то, что Spotify будет воспроизводить следующим в двух ключевых сценариях:

1. Последовательное воспроизведение ограниченного контекста: Когда вы воспроизводите плейлист или альбом с выключенным режимом перемешивания, список очереди дополнения будет точно соответствовать списку «Следующие» в приложении Spotify.
2. Вручную добавленные треки: Любая песня, которую вы добавляете вручную через «Добавить в очередь», всегда будет корректно отображаться в верхней части списка.

Когда возникает расхождение

Предсказуемость полностью нарушается в двух очень распространённых ситуациях, вызывая несоответствие между дополнением и приложением Spotify:

1. Когда включено перемешивание (Shuffle): Это самое существенное ограничение. Хотя приложение Spotify знает особый случайный порядок, который оно создало, публичный API, используемый этим дополнением, не имеет доступа к этому перемешанному порядку. API всегда будет сообщать исходную сохранённую последовательность плейлиста, полностью игнорируя тот факт, что перемешивание активно.
2. Когда включается автовоспроизведение (Autoplay): После окончания альбома или плейлиста функция «Автовоспроизведение» Spotify начинает играть похожие треки. Это алгоритмический радио-поток, и API не предоставляет никакой информации о предстоящих треках в этом потоке.

Дизайн дополнения и определение API

Чтобы обеспечить единообразный опыт, Accessify Play разработан для отображения именно тех данных, которые предоставляет API Spotify. Дополнение использует официальную конечную точку /me/player/queue. Согласно документации для разработчиков Spotify, эта конечная точка предназначена для:

Получения списка объектов, составляющих очередь пользователя.

Это означает, что определение «очереди» в API — это прежде всего список вручную добавленных треков. Хотя ответ API также включает следующий трек из текущего контекста (альбом/плейлист), он не может предоставить полную предстоящую последовательность для перемешанного или алгоритмически сгенерированного контента.

Заключение: Как эффективно использовать функцию очереди

Таким образом, функция очереди Accessify Play является вашим надёжным инструментом для двух основных целей:

1. Просмотр предстоящих треков при прослушивании альбома или плейлиста с выключенным перемешиванием.
2. Просмотр и управление треками, которые вы добавили в очередь вручную, независимо от того, что играет в данный момент.

Её не следует использовать как ориентир, когда включено перемешивание или когда запущено автовоспроизведение, поскольку API не предоставляет необходимых данных для этих сценариев.

⚙️ Руководство по настройке

Чтобы использовать это дополнение, вам необходимо получить Client ID и Client Secret из панели разработчика Spotify. Внимательно следуйте этим шагам.

Шаг 1: Создайте приложение Spotify

1. Откройте настройки Accessify Play в NVDA (меню NVDA -> Параметры -> Настройки -> Accessify Play).
2. Нажмите кнопку «Перейти в панель разработчика». Это откроет Панель разработчика Spotify в вашем веб-браузере. Войдите в систему, если потребуется.
3. Нажмите кнопку «Создать приложение».
4. Заполните форму:
   • Название приложения: Дайте ему имя (например, «NVDA Controller»).
   • Описание приложения: Подойдёт краткое описание.
   • Redirect URI: Это самый важный шаг. Дополнение прослушивает ваш локальный компьютер для обратного вызова аутентификации. Вы должны ввести этот URI точно: http://127.0.0.1:8888/callback > Примечание о порте 8888: По сообщениям пользователей, у некоторых возникают ошибки проверки. Это может произойти, если другое приложение на вашем компьютере (часто локальный сервер разработки) уже использует порт 8888. > > Будущее обновление: Чтобы предотвратить этот конфликт, порт по умолчанию для дополнения будет изменён на 8539 в будущей версии.
5. Вас могут спросить, какой API использовать. Пожалуйста, выберите «Web API».
6. Согласитесь с условиями и нажмите «Сохранить».

Шаг 2: Получите свои учётные данные

1. На панели управления вашего нового приложения нажмите «Настройки».
2. Вы увидите ваш Client ID.
3. Скопируйте эту длинную строку текста.

Шаг 3: Настройте дополнение в NVDA

1. Откройте меню NVDA (NVDA+N), выберите Параметры, затем Настройки.
2. В списке категорий выберите «Accessify Play».
3. Найдите кнопку «Добавить Client ID» (или «Показать/Изменить Client ID»). Нажмите её, чтобы открыть диалог, в который вы можете вставить ваш Client ID.
4. Проверьте другие настройки:
   • Порт обратного вызова: Изменяйте только в случае конфликта портов и если вы также изменили его в панели разработчика Spotify. (См. примечание в Шаге 1).
   • Автоматически объявлять смену трека: Отметьте этот флажок, если хотите, чтобы NVDA объявляла каждый новый трек при его начале.
   • Язык: Выберите язык отображения для дополнения. Эта настройка позволяет Accessify Play использовать язык, отличный от основного интерфейса NVDA. Вы можете выбрать «Следовать языку NVDA (по умолчанию)» или принудительно установить конкретный язык, например «Русский».
   • Канал обновлений: Выберите предпочтительный канал обновлений.
     • Стабильный: Получайте только стабильные, хорошо протестированные обновления. Они соответствуют выпускам из ветки main на GitHub.
     • Бета: Получайте предварительные версии с новейшими функциями и исправлениями ошибок, но потенциально менее стабильные. Они соответствуют выпускам из ветки dev на GitHub.
   • Проверять наличие обновлений автоматически: Если этот флажок установлен, дополнение будет автоматически проверять наличие новых версий при каждом запуске NVDA. Если обновление доступно, появится всплывающее окно. Если флажок не установлен, вы будете получать обновления только при ручной проверке.
5. Нажмите кнопку «Проверить учётные данные». Ваш веб-браузер откроется и попросит предоставить разрешения. Нажмите «Согласиться».
6. В случае успеха вы увидите сообщение «Проверка успешна!» Если нет, внимательно перепроверьте все шаги, особенно Redirect URI и ваш Client ID.
7. Нажмите «OK», чтобы сохранить и закрыть настройки. Дополнение готово к использованию!

✨ Система обновлений

Accessify Play включает встроенную систему обновлений, которая поддерживает ваше дополнение в актуальном состоянии с новейшими функциями и исправлениями ошибок. Обновления загружаются непосредственно из релизов GitHub.

Автоматические обновления

Если в настройках включена опция «Проверять наличие обновлений автоматически», Accessify Play будет выполнять автоматическую проверку новых версий при каждом запуске NVDA. Если обновление доступно для выбранного вами канала (Стабильный или Бета), появится всплывающее окно с информацией о новой версии и списке изменений. Вы можете загрузить и установить обновление или отложить его.

Если обновление недоступно или во время фоновой проверки произошла ошибка (например, отсутствует интернет-соединение), дополнение не будет отображать никаких сообщений.

Ручные обновления

Вы можете вручную проверить наличие обновлений в любое время, перейдя в панель настроек Accessify Play (меню NVDA -> Параметры -> Настройки -> Accessify Play) и нажав кнопку «Проверить наличие обновлений». Процесс аналогичен автоматическому обновлению: если найдена новая версия, появится всплывающее окно; в противном случае появится сообщение, подтверждающее, что у вас установлена последняя версия.

Каналы обновлений

В настройках вы можете выбрать между двумя каналами обновлений:

• Стабильный: Это рекомендуемый канал для большинства пользователей. Вы будете получать только стабильные, тщательно протестированные выпуски. Эти обновления соответствуют релизам из ветки main на GitHub.
• Бета: Этот канал предоставляет доступ к предварительным версиям, предлагая новейшие функции и исправления ошибок до их официального выпуска. Бета-версии соответствуют релизам из ветки dev на GitHub. Хотя они предоставляют ранний доступ, они могут быть менее стабильными, чем официальные выпуски.

🔒 Обновление аутентификации и миграции (Версия 1.3.0)

В версии 1.3.0 система аутентификации Accessify Play была значительно обновлена для повышения безопасности и улучшения пользовательского опыта, особенно для портативных установок NVDA.

• Повышенная безопасность с PKCE: Дополнение теперь использует поток аутентификации Proof Key for Code Exchange (PKCE). Этот современный и более безопасный метод устраняет необходимость в Client Secret, делая интеграцию с Spotify более безопасной.
• Переносимое хранение Client ID: Ваш Client ID Spotify больше не хранится в конфигурационных файлах NVDA. Вместо этого он теперь сохраняется в специальном переносимом файле по пути %userprofile%/.spotify_client_id.json. Это гарантирует, что ваш Client ID останется неизменным даже при перемещении или переустановке NVDA, и им легче управлять.
• Упрощённые настройки: Поле 'Client Secret' было удалено из панели настроек Accessify Play, что упрощает процесс настройки. Ввод 'Client ID' теперь осуществляется через динамическую кнопку, которая позволяет легко добавлять, просматривать или редактировать ваш Client ID.
• Плавная миграция: Если вы обновляетесь с более старой версии Accessify Play и ваш Client ID (или Client Secret) всё ещё хранится в конфигурации NVDA, в панели настроек Accessify Play появится новая кнопка «Перенести старые учётные данные». Нажатие этой кнопки автоматически:
  1. Перенесёт ваш существующий Client ID в новый переносимый файл %userprofile%/.spotify_client_id.json.
  2. Удалит старый Client ID и устаревший Client Secret из конфигурации NVDA. Это обеспечивает плавный переход к новой, более безопасной системе.

🤔 Почему такой метод аутентификации? (Вместо простой кнопки входа)

Возможно, вы задаётесь вопросом, почему Accessify Play требует от вас создания собственного приложения Spotify и ввода Client ID, вместо того чтобы предлагать простую кнопку «Войти в Spotify», как во многих других приложениях (например, Alexa, Google Home и т.д.). Ответ кроется в политике API Spotify и проблемах, с которыми сталкиваются независимые разработчики.

Чтобы обеспечить удобный вход в Spotify без необходимости для пользователей становиться «мини-разработчиками», приложение должно подать заявку и получить Расширенную квоту от Spotify. Требования для получения такой квоты весьма значительны и часто включают:

• Значительная пользовательская база: Демонстрация большой и активной пользовательской базы.
• Бизнес-модель: Чёткая и устойчивая бизнес-модель.
• Юридические проверки и проверки безопасности: Обширные юридические проверки и проверки безопасности со стороны Spotify.
• Соответствие бренду: Сильное соответствие бренду и стратегическим целям Spotify.

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

Поэтому текущий метод, хотя и требует от пользователя выполнения дополнительных шагов, является необходимым обходным путём. Он позволяет Accessify Play функционировать и предоставлять свои ценные функции доступности, используя стандартный доступ разработчика Spotify, без необходимости соответствовать запретительным критериям для получения расширенных квот. Этот подход даёт вам, пользователю, возможность напрямую контролировать доступ к API Spotify, гарантируя, что дополнение останется функциональным и доступным.

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

Этот проект не был бы там, где он находится сегодня, без невероятной поддержки и преданности нашего сообщества. Искренняя благодарность всем тестировщикам, которые предоставили бесценные идеи, неустанно помогали с отладкой и оказывали поддерживающее поощрение на протяжении всего процесса разработки. Ваш вклад сыграл важную роль в формировании Accessify Play таким, какой он есть. Спасибо за то, что сделали этот проект успешным!

❤️ Поддержка разработчика

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

• Пожертвовать через PayPal
• Для альтернативных способов пожертвования, пожалуйста, свяжитесь: rafli08523717409@gmail.com