Merge remote-tracking branch 'origin/main'

# Conflicts:
#	README.md
#	mtsmusic.py
#	qt_app.py

README.md

@@ -73,8 +73,15 @@ PLAYWRIGHT_BROWSERS_PATH="$PWD/.playwright" .venv/bin/playwright install chromiu
 
 История хранится в `.mts-music/history.json` (последние 100 треков).
 Плеер — `ffplay` (или `mpv`, если установлен). Пауза реализована через
-`SIGSTOP`/`SIGCONT`, а перемотка перезапускает поток с нужной секунды,
-поэтому отдельный демон не нужен.
+`SIGSTOP`/`SIGCONT`, а перемотка перезапускает воспроизведение с нужной
+секунды, поэтому отдельный демон не нужен.
+
+Треки не транслируются напрямую: сначала они скачиваются в локальный кэш
+`.mts-music/cache/` (до 512 МБ, старые файлы удаляются автоматически), а плеер
+играет уже готовый MP3. Так надёжнее — сервер Яндекса закрывает соединение,
+если клиент читает поток медленнее реального времени, из-за чего трек
+обрывался через полминуты и клиент переключался на следующий. Заодно кэш
+убирает задержку при повторном прослушивании и делает перемотку мгновенной.
 
 ## Qt-приложение
 
@@ -101,11 +108,16 @@ PLAYWRIGHT_BROWSERS_PATH="$PWD/.playwright" .venv/bin/playwright install chromiu
 
 ## Скачивание и метаданные
 
-Скачать трек можно из меню (TUI: «Скачать трек»/«Скачать список»; Qt: те же
-пункты в боковой панели), клавишей `d` на экране списка в TUI или командой
-`download`. Файлы кладутся в папку `download_dir` (`~/Music/MTS Music` по
-умолчанию), имя — `Исполнитель - Название.mp3`; существующие файлы не
-перезаписываются, при совпадении добавляется ` (2)`, ` (3)` и т.д.
+В меню обоих клиентов пункт «Скачать» открывает выбор: текущий трек, всё
+избранное, 20 треков «Моей волны» или результаты поиска; папка выбирается
+диалогом в Qt и вводится вручную в TUI, прогресс и число ошибок видны на
+экране. Быстрые пункты «Скачать трек»/«Скачать список» (и клавиша `d` на
+экране списка в TUI) сразу кладут в папку `download_dir` без диалога. В CLI
+это команда `download` с теми же источниками (`--likes`, `--wave`, `--search`).
+
+Файлы кладутся в папку `download_dir` (`~/Music/MTS Music` по умолчанию),
+имя — `Исполнитель - Название.mp3`; существующие файлы не перезаписываются,
+при совпадении добавляется ` (2)`, ` (3)` и т.д. (`--force` перезаписывает).
 
 В скачанный файл пишется максимум метаданных ID3v2.3 (через `mutagen`, он в
 `requirements.txt`):
@@ -183,10 +195,12 @@ D-Bus или без `dbus-next` приложение просто работае
 # сразу слушать подборку (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 likes            # все любимые треки
+.venv/bin/python mtsmusic.py likes -n 20      # только первые 20
+.venv/bin/python mtsmusic.py likes --ids      # только ID, для скриптов
 
 # текст песни: показать, сохранить, или с таймкодами
 .venv/bin/python mtsmusic.py lyrics 12345678
@@ -205,9 +219,19 @@ D-Bus или без `dbus-next` приложение просто работае
 # скачивание: в папку из 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 87654321 -d ~/Music/MTS
+
+# как в мобильном приложении: избранное, волна или результаты поиска
+.venv/bin/python mtsmusic.py download --likes -d ~/Music/MTS
+.venv/bin/python mtsmusic.py download --wave -n 20 -d ~/Music/MTS
+.venv/bin/python mtsmusic.py download --search "Кино" -n 10 -d ~/Music/MTS
+
+# один трек с явным именем файла, перезапись существующих
 .venv/bin/python mtsmusic.py download 12345678 -o track.mp3
+.venv/bin/python mtsmusic.py download --likes -d ~/Music/MTS --force
+
+# то же самое есть в меню TUI и Qt — пункт «Скачать»
 
 # без ID3-тегов (быстрее, без обложки и текста)
 .venv/bin/python mtsmusic.py download 12345678 --no-tags
@@ -252,6 +276,11 @@ TUI нужно запускать в настоящем терминале (stdi
 - Использовать только для личного прослушивания, не перераздавать контент.
 - Если `api.music.yandex.net` недоступен, проверь IPv6: клиент принудительно
   ходит по IPv4.
+- Кэш треков лежит в `.mts-music/cache/`. Его можно удалить в любой момент —
+  при следующем запуске треки скачаются заново.
+- `download` (и пункт «Скачать» в TUI/Qt) по умолчанию не перезаписывает уже
+  скачанные файлы: повторный запуск докачает только новое. Флаг `--force`
+  в CLI включает перезапись.
 
 ## Лицензия