Spotify
VibeOS может напрямую управлять Spotify — воспроизведением, очередью, поиском, плейлистами, сохранёнными треками/альбомами и историей прослушивания — используя официальный Web API Spotify с PKCE OAuth. Токены хранятся в ~/.vibeos/auth.json и автоматически обновляются при получении 401; вам нужно войти только один раз на каждое устройство (токены обновления истекают через ~6 месяцев; когда это произойдёт, повторно запустите vibeos auth spotify).
В отличие от встроенных OAuth-интеграций VibeOS (Google, GitHub Copilot, Codex), Spotify требует, чтобы каждый пользователь зарегистрировал собственное лёгкое приложение разработчика. Spotify не позволяет сторонним разработчикам публиковать общедоступное OAuth-приложение, которое мог бы использовать кто угодно. Это занимает около двух минут, и vibeos auth spotify проведёт вас через весь процесс.
Предварительные требования
- Учётная запись Spotify. Бесплатная подходит для поиска, плейлистов, библиотеки и инструментов активности. Premium требуется для управления воспроизведением (воспроизведение, пауза, пропуск, перемотка, громкость, добавление в очередь, передача).
- VibeOS установлен и запущен.
- Для инструментов воспроизведения: активное устройство Spotify Connect — приложение Spotify должно быть открыто хотя бы на одном устройстве (телефон, компьютер, веб-плеер, колонка), чтобы Web API было чем управлять. Если ничего не активно, вы получите
403 Forbiddenс сообщением «no active device»; откройте Spotify на любом устройстве и повторите попытку.
Настройка
Одношаговая: vibeos tools или настройка при первом запуске
Самый быстрый путь. Выполните:
vibeos tools
Прокрутите до 🎵 Spotify, нажмите пробел, чтобы включить, затем s для сохранения. Тот же переключатель доступен и во время первого запуска vibeos setup / vibeos setup tools. Spotify остаётся опциональным, поэтому его включение запускает ту же конфигурацию с учётом провайдера, что и vibeos tools.
VibeOS сразу переводит вас в OAuth-поток — если у вас ещё нет приложения Spotify, он проведёт вас через его создание прямо в процессе. После завершения набор инструментов будет включён И аутентифицирован за один проход.
Если вы предпочитаете выполнять шаги отдельно (или повторно проходите аутентификацию позже), используйте двухшаговый процесс ниже.
Двухшаговый процесс
1. Включите набор инструментов
vibeos tools
Включите 🎵 Spotify, сохраните, и когда откроется встроенный мастер, закройте его (Ctrl+C). Набор инструментов останется включённым; откладывается только шаг аутентификации.
2. Запустите мастер входа
vibeos auth spotify
7 инструментов Spotify появляются в наборе инструментов агента только после шага 1 — по умолчанию они отключены, чтобы пользователи, которым они не нужны, не отправляли лишние схемы инструментов при каждом API-вызове.
Если VIBEOS_SPOTIFY_CLIENT_ID не установлен, VibeOS проведёт вас через регистрацию приложения прямо в процессе:
- Открывает
https://developer.spotify.com/dashboardв вашем браузере - Выводит точные значения, которые нужно вставить в форму «Create app» Spotify
- Запрашивает полученный Client ID
- Сохраняет его в
~/.vibeos/.env, чтобы будущие запуски пропускали этот шаг - Продолжает сразу к OAuth-потоку согласия
После вашего одобрения токены записываются в раздел providers.spotify файла ~/.vibeos/auth.json. Активный провайдер вывода НЕ меняется — аутентификация Spotify независима от вашего LLM-провайдера.
Создание приложения Spotify (что запрашивает мастер)
Когда откроется панель управления, нажмите Create app и заполните:
| Поле | Значение |
|---|---|
| App name | любое (например, vibeos-agent) |
| App description | любое (например, personal VibeOS integration) |
| Website | оставьте пустым |
| Redirect URI | http://127.0.0.1:43827/spotify/callback |
| Which API/SDKs? | отметьте Web API |
Примите условия и нажмите Save. На следующей странице нажмите Settings → скопируйте Client ID и вставьте его в приглашение VibeOS. Это единственное значение, которое нужно VibeOS — PKCE не использует секретный ключ клиента.
Работа через SSH / в среде без графического интерфейса
Если установлены SSH_CLIENT или SSH_TTY, VibeOS пропускает автоматическое открытие браузера как на этапе мастера, так и на этапе OAuth. Скопируйте URL панели управления и URL авторизации, которые выводит VibeOS, откройте их в браузере на вашем локальном компьютере и действуйте как обычно — локальный HTTP-слушатель всё ещё работает на удалённом хосте на порту 43827. Браузер вашего ноутбука не может подключиться к удалённому локальному адресу без SSH-перенаправления:
ssh -N -L 43827:127.0.0.1:43827 user@remote-host
Для настроек с промежуточным сервером / бастионом и других особенностей (mosh, tmux, конфликты портов) см. OAuth через SSH / удалённые хосты.
Проверка
vibeos auth status spotify
Показывает, присутствуют ли токены и когда истекает токен доступа. Обновление происходит автоматически: когда любой вызов API Spotify возвращает 401, клиент обменивает токен обновления и повторяет попытку один раз. Токены обновления сохраняются между перезапусками VibeOS, поэтому повторная аутентификация требуется только если вы отозвали приложение в настройках учётной записи Spotify или выполнили vibeos auth logout spotify.
Использование
После входа в систему агент получает доступ к 7 инструментам Spotify. Вы общаетесь с агентом естественным языком — он выбирает правильный инструмент и действие. Для наилучшего поведения агент загружает вспомогательный навык, который обучает каноническим шаблонам использования (один поиск-затем-воспроизведение, когда не нужно предварительно проверять get_state и т.д.).
> включи немного майлза дэвиса
> что я сейчас слушаю
> добавь этот трек в мой плейлист Late Night Jazz
> переключи на следующий трек
> создай новый плейлист «Focus 2026» и добавь туда последние три трека, которые я слушал
> какие из моих сохранённых альбомов принадлежат Radiohead
> найди акустические каверы на Blackbird
> передай воспроизведение на мою кухонную колонку
Справочник инструментов
Все действия, изменяющие воспроизведение, принимают опциональный параметр device_id для указания конкретного устройства. Если он опущен, Spotify использует текущее активное устройство.
spotify_playback
Управление и просмотр воспроизведения, а также получение истории недавно прослушанного.
| Действие | Назначение | Premium? |
|---|---|---|
get_state | Полное состояние воспроизведения (трек, устройство, прогресс, перемешивание/повтор) | Нет |
get_currently_playing | Только текущий трек (возвращает пустой результат при 204 — см. ниже) | Нет |
play | Запуск/возобновление воспроизведения. Опционально: context_uri, uris, offset, position_ms | Да |
pause | Пауза воспроизведения | Да |
next / previous | Пропуск трека | Да |
seek | Переход к position_ms | Да |
set_repeat | state = track / context / off | Да |
set_shuffle | state = true / false | Да |
set_volume | volume_percent = 0-100 | Да |
recently_played | Последние прослушанные треки. Опционально limit, before, after (Unix ms) | Нет |
spotify_devices
| Действие | Назначение |
|---|---|
list | Все устройства Spotify Connect, видимые вашей учётной записью |
transfer | Передача воспроизведения на device_id. Опционально play: true запускает воспроизведение при передаче |
Колонки, управляемые Home Assistant
Если Home Assistant управляет колонками, которые уже поддерживают Spotify Connect (например, Sonos, Echo, Nest или другие колонки с поддержкой Connect), они автоматически появляются в spotify_devices list, когда Spotify может их видеть. VibeOS не нуждается в мосте Home Assistant ↔ Spotify для этого пути — Spotify обрабатывает маршрутизацию устройств нативно.
Попросите VibeOS передать воспроизведение по отображаемому имени колонки (например, «передай Spotify на кухонную колонку») или вызовите spotify_devices list и передайте точный device_id в spotify_devices transfer при написании скриптов. Если колонка отсутствует, откройте приложение Spotify или интеграцию Spotify на колонке один раз, чтобы Spotify зарегистрировал её как активную цель Connect.
spotify_queue
| Действие | Назначение | Premium? |
|---|---|---|
get | Текущие треки в очереди | Нет |
add | Добавить uri в очередь | Да |
spotify_search
Поиск по каталогу. query обязателен. Опционально: types (массив из track / album / artist / playlist / show / episode), limit, offset, market.
spotify_playlists
| Действие | Назначение | Обязательные аргументы |
|---|---|---|
list | Плейлисты пользователя | — |
get | Один плейлист + треки | playlist_id |
create | Новый плейлист | name (+ опционально description, public, collaborative) |
add_items | Добавить треки | playlist_id, uris (опционально position) |
remove_items | Удалить треки | playlist_id, uris (+ опционально snapshot_id) |
update_details | Переименовать / изменить | playlist_id + любое из name, description, public, collaborative |
spotify_albums
| Действие | Назначение | Обязательные аргументы |
|---|---|---|
get | Метаданные альбома | album_id |
tracks | Список треков альбома | album_id |
spotify_library
Унифицированный доступ к сохранённым трекам и сохранённым альбомам. Выберите коллекцию с помощью аргумента kind.
| Действие | Назначение |
|---|---|
list | Постраничный список библиотеки |
save | Добавить ids / uris в библиотеку |
remove | Удалить ids / uris из библиотеки |
Обязательно: kind = tracks или albums, плюс action.
Матрица возможностей: Free vs Premium
Инструменты только для чтения работают на бесплатных аккаунтах. Всё, что изменяет воспроизведение или очередь, требует Premium.
| Работает на Free | Требуется Premium |
|---|---|
spotify_search (всё) | spotify_playback — play, pause, next, previous, seek, set_repeat, set_shuffle, set_volume |
spotify_playback — get_state, get_currently_playing, recently_played | spotify_queue — add |
spotify_devices — list | spotify_devices — transfer |
spotify_queue — get | |
spotify_playlists (всё) | |
spotify_albums (всё) | |
spotify_library (всё) |
Планирование: Spotify + cron
Поскольку инструменты Spotify — это обычные инструменты VibeOS, задача cron, запущенная в сессии VibeOS, может запускать воспроизведение по любому расписанию. Новый код не требуется.
Утренний плейлист для пробуждения
vibeos cron add \
--name "morning-commute" \
"0 7 * * 1-5" \
"Передай воспроизведение на мою кухонную колонку и запусти мой плейлист 'Morning Commute'. Громкость на 40. Включи перемешивание."
Что происходит в 7 утра каждый будний день:
- Cron запускает сессию VibeOS без графического интерфейса.
- Агент читает запрос, вызывает
spotify_devices listдля поиска «кухонной колонки» по имени, затемspotify_devices transfer→spotify_playback set_volume→spotify_playback set_shuffle→spotify_search+spotify_playback play. - Музыка начинается на целевой колонке. Общая стоимость: одна сессия, несколько вызовов инструментов, без участия человека.
Успокаивающая музыка на ночь
vibeos cron add \
--name "wind-down" \
"30 22 * * *" \
"Поставь Spotify на паузу. Затем установи громкость на 20, чтобы было тихо, когда я снова запущу его завтра."
Особенности
- Активное устройство должно существовать в момент срабатывания cron. Если ни один клиент Spotify не запущен (телефон/компьютер/колонка Connect), действия воспроизведения вернут
403 no active device. Для утренних плейлистов хитрость в том, чтобы указать устройство, которое всегда включено (Sonos, Echo, умная колонка), а не ваш телефон. - Premium требуется для всего, что изменяет воспроизведение — play, pause, skip, volume, transfer. Задачи cron только для чтения (запланированная отправка «недавно прослушанных треков» по электронной почте) отлично работают на Free.
- Агент cron наследует ваши активные наборы инструментов. Spotify должен быть включён в
vibeos tools, чтобы сессия cron видела инструменты Spotify. - Задачи cron выполняются с
skip_memory=True, поэтому они не записывают данные в ваше хранилище памяти.
Полный справочник по cron: Cron Jobs.
Выход из системы
vibeos auth logout spotify
Удаляет токены из ~/.vibeos/auth.json. Чтобы также очистить конфигурацию приложения, удалите VIBEOS_SPOTIFY_CLIENT_ID (и VIBEOS_SPOTIFY_REDIRECT_URI, если вы его установили) из ~/.vibeos/.env или запустите мастер заново.
Чтобы отозвать приложение на стороне Spotify, посетите Приложения, подключённые к вашей учётной записи и нажмите REMOVE ACCESS.
Устранение неполадок
403 Forbidden — Player command failed: No active device found — Вам нужно, чтобы Spotify был запущен хотя бы на одном устройстве. Откройте приложение Spotify на телефоне, компьютере или веб-плеере, запустите любой трек на секунду, чтобы зарегистрировать устройство, и повторите попытку. spotify_devices list показывает, что сейчас видно.
403 Forbidden — Premium required — Вы используете бесплатный аккаунт и пытаетесь выполнить действие, изменяющее воспроизведение. См. матрицу возможностей выше.
204 No Content при get_currently_playing — ничего не воспроизводится ни на одном устройстве. Это нормальный ответ Spotify, а не ошибка; VibeOS отображает его как поясняющий пустой результат (is_playing: false).
INVALID_CLIENT: Invalid redirect URI — URI перенаправления в настройках вашего приложения Spotify не совпадает с тем, что использует VibeOS. По умолчанию используется http://127.0.0.1:43827/spotify/callback. Либо добавьте его в список разрешённых URI перенаправления вашего приложения, либо установите VIBEOS_SPOTIFY_REDIRECT_URI в ~/.vibeos/.env на то значение, которое вы зарегистрировали.
429 Too Many Requests — Лимит запросов Spotify. VibeOS возвращает понятную ошибку; подождите минуту и повторите попытку. Если это продолжается, вероятно, вы выполняете плотный цикл в скрипте — квота Spotify сбрасывается примерно каждые 30 секунд.
401 Unauthorized постоянно возвращается — Ваш токен обновления был отозван (обычно потому, что вы удалили приложение из своей учётной записи или приложение было удалено). Запустите vibeos auth spotify снова.
Мастер не открывает браузер — Если вы работаете через SSH или в контейнере без дисплея, VibeOS обнаруживает это и пропускает автоматическое открытие. Скопируйте URL панели управления, который он выводит, и откройте его вручную.
Расширенное: пользовательские области доступа
По умолчанию VibeOS запрашивает области доступа, необходимые для каждого поставляемого инструмента. Переопределите, если хотите ограничить доступ:
vibeos auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"
Справочник областей доступа: Области доступа Spotify Web API. Если вы запросите меньше областей, чем требуется инструменту, вызовы этого инструмента будут завершаться с ошибкой 403.
Расширенное: пользовательский Client ID / Redirect URI
vibeos auth spotify --client-id <id> --redirect-uri http://localhost:3000/callback
Или установите их постоянно в ~/.vibeos/.env:
VIBEOS_SPOTIFY_CLIENT_ID=<ваш_id>
VIBEOS_SPOTIFY_REDIRECT_URI=http://localhost:3000/callback
URI перенаправления должен быть добавлен в белый список в настройках вашего приложения Spotify. Значение по умолчанию подходит почти для всех — меняйте его только если порт 43827 занят.
Где что находится
| Файл | Содержимое |
|---|---|
~/.vibeos/auth.json → providers.spotify | токен доступа, токен обновления, срок действия, область доступа, URI перенаправления |
~/.vibeos/.env | VIBEOS_SPOTIFY_CLIENT_ID, опционально VIBEOS_SPOTIFY_REDIRECT_URI |
| Приложение Spotify | принадлежит вам на developer.spotify.com/dashboard; содержит Client ID и белый список URI перенаправления |