MTS-music-another-client/README.md

MTS Music — another client

Неофициальный клиент для своего аккаунта MTS Music: «Моя волна», поиск, избранное, тексты песен, воспроизведение и скачивание в MP3 с полными ID3-тегами. Есть компактный TUI-плеер и настольное Qt-приложение в стиле телефона.

Только для личного использования с собственной платной подпиской MTS. Проект не связан с МТС и Яндексом; контент не перераспространяется.

Внутри используется тот же путь, что и в веб-клиенте: MTS SSO выдаёт OAuth-токен Яндекс.Музыки, дальше запросы идут на api.music.yandex.net.

Установка

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
PLAYWRIGHT_BROWSERS_PATH="$PWD/.playwright" .venv/bin/playwright install chromium

Для Qt-приложения дополнительно:

.venv/bin/pip install -r requirements-qt.txt

Всё локальное лежит рядом с проектом:

• .venv/ — зависимости
• .playwright/ — браузер Chromium
• .mts-music/ — профиль браузера и credentials.json

Вход

.venv/bin/python mtsmusic.py login

Откроется браузер. Нужно вручную войти в MTS и пройти капчу. Токен и cookie сохранятся в .mts-music/credentials.json с правами 600. Повторный вход нужен только когда токен перестанет работать.

TUI-плеер

.venv/bin/python mtsmusic.py tui

Интерфейс в терминале сделан как экран телефона: чёрно-белые элементы и цветная обложка. Обложка по центру, строго под ней по той же ширине — большая кнопка play/pause и по бокам предыдущий/следующий треки, ниже «Текст» и «Избранное». Кнопка «☰» в левом верхнем углу открывает боковое меню: «Моя волна», избранное, история прослушивания, поиск, текст песни, «Скачать трек», «Скачать список», «Настройки» и выход.

Мышь работает: кнопки, меню, строки списков и полоса прогресса кликабельны (клик по прогрессу перематывает трек).

Клавиша	Действие
Space	пауза / продолжить
← / →	перемотка на −5 / +5 секунд
n / p	следующий / предыдущий трек
t	текст песни
l	добавить / убрать из избранного
m	открыть меню
w	список «Моей волны»
f	избранное
h	история
s	поиск
d	скачать выделенный трек в списке
q	выход

История хранится в .mts-music/history.json (последние 100 треков). Плеер — ffplay (или mpv, если установлен). Пауза реализована через SIGSTOP/SIGCONT, а перемотка перезапускает поток с нужной секунды, поэтому отдельный демон не нужен.

Qt-приложение

.venv/bin/python mtsmusic.py qt

Отдельное окно в стиле телефона: крупная цветная обложка, кнопка play/pause, переключение треков, перемотка, текст песни и избранное. Кнопка «☰» открывает боковую панель с «Моей волной», избранным, историей, поиском, скачиванием и настройками.

Воспроизведение — через QMediaPlayer/FFmpeg из PySide6, поэтому работает перемотка и системный звук. По полосе прогресса можно кликнуть в любое место — каретка сразу перейдёт туда (и потянется, если вести мышью). Окно растягивается вместе с обложкой, списки прокручиваются, двойной клик по строке запускает трек.

Tab переключает фокус по элементам: меню, полоса, предыдущий, play, следующий, «Текст», «Избранное». Горячие клавиши: Space, ←/→, N/P, L, T, M, F, H, S, W; Esc закрывает меню/экран, Ctrl+Q — выход.

«Моя волна» продолжается с последних прослушанных треков (берётся история), а не начинается каждый раз с одного и того же места.

Скачивание и метаданные

Скачать трек можно из меню (TUI: «Скачать трек»/«Скачать список»; Qt: те же пункты в боковой панели), клавишей d на экране списка в TUI или командой download. Файлы кладутся в папку download_dir (~/Music/MTS Music по умолчанию), имя — Исполнитель - Название.mp3; существующие файлы не перезаписываются, при совпадении добавляется (2), (3) и т.д.

В скачанный файл пишется максимум метаданных ID3v2.3 (через mutagen, он в requirements.txt):

• название, все исполнители (TPE1), альбом (TALB) и альбомный исполнитель (TPE2);
• номер трека и диска (TRCK/TPOS), год и дата релиза (TYER/TDAT), жанр как в API (TCON), лейбл (TPUB), длительность (TLEN);
• обложка 600×600 (APIC);
• текст песни (USLT) и синхронный текст (SYLT), если он есть: сначала пробуем MTS, затем LRCLIB;
• ссылка на трек (WOAR/COMM), пометка explicit (ITUNESADVISORY) и служебные поля с id трека, альбома и realId (TXXX).

Без mutagen или при --no-tags теги не пишутся, скачивание при этом работает как обычно.

Управление из системной панели (MPRIS)

При запуске TUI и Qt-приложение регистрируются в сессионном D-Bus как источник звука (org.mpris.MediaPlayer2.mtsmusic). Поэтому плеер виден системе и им можно управлять из панели GNOME — например, расширением media-controls, — а также через playerctl и другие MPRIS-клиенты.

Что работает из панели:

• play/pause, следующий/предыдущий трек;
• перемотка (слайдер и seek);
• отображение названия, исполнителя, альбома, длительности и цветной обложки;
• громкость.

Для этого нужен dbus-next (он уже в requirements.txt). Без сессионного D-Bus или без dbus-next приложение просто работает как обычно, без интеграции.

Настройки

Настройки открываются из меню (пункт «Настройки» в TUI и Qt) или из командной строки и хранятся в .mts-music/settings.json:

# показать текущие настройки
.venv/bin/python mtsmusic.py settings

# изменить: громкость 60%, шаг перемотки 10 секунд
.venv/bin/python mtsmusic.py settings -s volume=60 seek_step=10

Настройка	По умолчанию	Описание
volume	80	громкость плеера, 0–100
seek_step	5	шаг перемотки стрелками, секунды
autoplay	false	начинать воспроизведение сразу при запуске
start_queue	wave	что открыть первым: wave, favorites или history
wave_from_history	true	продолжать «Мою волну» с последних треков
download_dir	~/Music/MTS Music	куда сохранять скачанные MP3

В Qt-приложении на странице настроек дополнительно выбирается устройство вывода звука и папка загрузок (кнопка «Выбрать…»). В TUI путь задаётся в настройках пунктом «Папка загрузок». Громкость меняется на лету, остальные настройки применяются к новым трекам и при следующем запуске.

Команды

# кто я и есть ли подписка
.venv/bin/python mtsmusic.py status

# поиск
.venv/bin/python mtsmusic.py search "miyagi" -n 10

# «Моя волна»: 10 треков, ♥ — уже в избранном
.venv/bin/python mtsmusic.py mix -n 10

# сразу слушать подборку (Ctrl-C — остановить)
.venv/bin/python mtsmusic.py mix -n 5 --play

# избранное: добавить / убрать / показать
.venv/bin/python mtsmusic.py like 12345678
.venv/bin/python mtsmusic.py unlike 12345678
.venv/bin/python mtsmusic.py likes -n 20

# текст песни: показать, сохранить, или с таймкодами
.venv/bin/python mtsmusic.py lyrics 12345678
.venv/bin/python mtsmusic.py lyrics 12345678 -o track.txt
.venv/bin/python mtsmusic.py lyrics 12345678 --lrc -o track.lrc

# только права MTS, без внешнего источника
.venv/bin/python mtsmusic.py lyrics 12345678 --no-fallback

# прямая ссылка на MP3
.venv/bin/python mtsmusic.py url 12345678

# воспроизведение (нужен mpv или ffplay)
.venv/bin/python mtsmusic.py play 12345678

# скачивание: в папку из download_dir, имя «Исполнитель - Название.mp3»
.venv/bin/python mtsmusic.py download 12345678

# скачивание в конкретную папку или файл
.venv/bin/python mtsmusic.py download 12345678 -d ~/Music
.venv/bin/python mtsmusic.py download 12345678 -o track.mp3

# без ID3-тегов (быстрее, без обложки и текста)
.venv/bin/python mtsmusic.py download 12345678 --no-tags

# настройки
.venv/bin/python mtsmusic.py settings
.venv/bin/python mtsmusic.py settings -s volume=60 seek_step=10

Токен можно передать и через переменную окружения:

export MTS_YA_TOKEN='...'

Если TUI не отображается

# диагностика окружения
.venv/bin/python mtsmusic.py tui --check

# без alternate screen (если экран пустой)
.venv/bin/python mtsmusic.py tui --inline

# отключить мышь, если терминал плохо её поддерживает
.venv/bin/python mtsmusic.py tui --inline --no-mouse

TUI нужно запускать в настоящем терминале (stdin/stdout — TTY), а не в панели вывода IDE. При падении traceback пишется в .mts-music/tui-error.log.

Ограничения

• Логин автоматизирован не полностью: QRATOR-капчу проходит человек.
• reference_uri у MTS должен быть на домене music.mts.ru, поэтому локальный callback не используется — токен забирается из браузера.
• Без активной подписки download-info отдаёт preview (короткий фрагмент).
• Тексты песен — отдельная подписка Яндекс Плюс, которой у MTS-аккаунта нет (hasPlus: false), поэтому MTS возвращает 404 даже для треков с текстом. lyrics автоматически берёт текст из бесплатного LRCLIB и помечает источник в выводе. --no-fallback отключает это поведение.
• Использовать только для личного прослушивания, не перераздавать контент.
• Если api.music.yandex.net недоступен, проверь IPv6: клиент принудительно ходит по IPv4.

Лицензия

MIT © 2026 jads. Проект предоставляется «как есть», без гарантий; используйте на свой страх и риск и только со своим аккаунтом.