Как пользоваться приложением

In English

Перевод устарел. Английский оригинал изменился 2026-09-30: перевод сделан с версии b3015078, сейчас актуальна fb237a6. Расхождение не проверено построчно — если что-то важно, откройте английскую страницу.

Что делает отдельное приложение после запуска: клавиши, два меню, второе окно, из которого ведут показ, плашка с названием трека и две настройки, которые меняют картинку на ходу. Здесь всё про уже запущенное приложение — флаги и ключи config.toml, решающие, как оно стартует, лежат в Configuration.

Запуск

Готовая сборка распаковывается и запускается; в систему ничего не устанавливается, а файл READ-ME-FIRST в каждом архиве проводит через первый запуск на Windows, macOS и foobar2000.

Из исходников нужен свежий стабильный тулчейн Rust (рабочее пространство на редакции 2024 — Rust 1.85+). Из корня репозитория:

cargo run -p standalone --release

Это соберёт и запустит ritmolux, отдельное окно. На Windows оно захватывает то, что уже играет (системный звук, через петлю WASAPI) — включите музыку, и картинка начнёт реагировать. --release желателен: это графика реального времени, и отладочная сборка заметно медленнее.

Управление

По умолчанию приложение держит одну сцену — выбрали вид, он и остаётся. Нажмите A, чтобы включить автосмену (или задайте auto = true в разделе [rotate] файла config.toml); когда она включена, сцена держится ~20–90 с, а спад энергии может подтолкнуть смену раньше.

Любая смена пресета — Space, выбор из списка или автосмена — идёт переходом примерно за секунду, а не резкой склейкой, поэтому показ читается как непрерывный. Движок перебирает небольшую библиотеку переходов (перекрёстное затухание, аддитивный прожиг, растворение по яркости, шторка), а переключение, пришедшее посреди перехода, доводит текущий до конца и начинает новый — так что вы всегда попадаете туда, куда просили.

Клавиша	Действие
Space	Следующий пресет — через переход (и перезапускает таймер автосмены)
A	Автосмена вкл/выкл (по умолчанию выключена)
Tab	Открыть/закрыть список пресетов — открывается на том, который вы смотрите. Стрелки идут по списку и заворачиваются на обоих концах, влево/вправо шагают на колонку, удержание стрелки прокручивает, набор текста фильтрует, Enter выбирает (тоже через переход), Esc закрывает
S	Открыть/закрыть меню настроек — качество, автосмена, границы выдержки, полный экран, монитор, диагностика, режим входа, устройство входа, имя пресета, название трека, консоль. Вверх/вниз выбирают строку, влево/вправо меняют её, Esc закрывает. Каждое изменение применяется сразу и записывается в config.toml
C	Открыть/закрыть консоль оператора — второе окно на другом мониторе со списком пресетов, меню настроек, полосой управления и живым предпросмотром вывода
[ / ]	Понизить / повысить уровень качества на ходу — закрепляет его на сессию и сохраняет выбор
F	Полный экран
Esc	Выйти из полного экрана (когда меню закрыто). В окне не делает ничего и никогда не закрывает приложение
D	Перейти на следующий монитор
F3	Наложение с диагностикой

Список пресетов и меню настроек

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

Оба меню модальные, и одновременно открыто только одно: S открывает настройки, когда список пресетов закрыт (пока он открыт, s — символ фильтра), а Tab из настроек передаёт управление списку.

Имя активного пресета стоит в левом верхнем углу и само убирается с глаз: любое меню или наложение F3 его прячут, и оно сразу возвращается, когда те закрываются. Если холст нужен чистым всегда, выключите строку Preset name в меню настроек — это [hud] preset_name в config.toml, и он переживает перезапуск.

Консоль оператора

C открывает второе окно на мониторе, отличном от того, где идёт показ, чтобы вести приложение со стола, а не печатать у проектора. В нём есть список пресетов и меню настроек — пока оно открыто, ни то, ни другое больше не рисуется поверх показа — плюс полоса управления (prev, next, rotate, auto, dwell -/+, всё кликабельно), строка с тем, что автосмена возьмёт следующим, и живой предпросмотр вывода, вписанный в угол.

Она выключена по умолчанию и ничего не стоит, пока закрыта: ни второй поверхности, ни промежуточной цели рендера, ни лишней копии на кадр. Открыть её можно строкой Console в меню настроек, клавишей C или при запуске через --console / enabled = true в разделе [console] файла config.toml; все четыре пути — один и тот же код, поэтому разойтись в том, открыта она или нет, они не могут. Монитор консоль выбирает по тому же правилу «имя важнее индекса», что и сам показ — сначала [console] display_name, затем [console] display, — а если это приводит её на монитор показа, она переезжает на другой, если он есть. Закрытие консоли из её собственного меню настроек оставляет это меню на показе, поэтому вместе с окном меню не теряется.

На машине с одним монитором она открывается обычным окном на нём же — это поддерживаемый способ работы, а не ошибка.

Открытая консоль не отнимает у вывода ничего сверх шума измерения. Это измерено на пяти сочетаниях двух ключей темпа — frame_latency и present_every_n, оба описаны в Configuration — и трёх режимах времени кадра на машине разработчика проекта, поэтому значения по умолчанию можно оставить как есть — подстраивать нечего. Строка console opened: в diagnostics.log называет режим, задержку кадра после ограничения и действующий темп, а периодическая заметка console open: несёт итоги показанных / пропущенных / прореженных кадров — именно это делает замер стоимости на чужой машине правдоподобным, а не просто низким.

Как отзеркалить показ в другую программу

--preview stdout отправляет кадры, которые видит проектор, тому, кто запустил приложение, — сырыми пикселями в стандартный вывод. Так редактор смотрит на настоящий показ, а не на второй, безоконный. Зеркало — это масштабированная копия с полями фиксированного размера, 640x360, если --preview stdout@WIDTHxHEIGHT не назвал другой, поэтому изменение размера окна или полный экран никогда не меняют то, что получает читатель; а порядок каналов назван в поле format события stream, а не угадывается. Кадр по-прежнему рисуется в свою настоящую цель без изменений; копия для зеркала снимается рядом. Полное сравнение с безоконным потоком — в Headless capture and video.

Цикл отрисовки никогда его не ждёт. Промежуточная копия снимается заодно с отправкой самого кадра, а её отображение берётся на следующем кадре неблокирующим опросом, поэтому ещё не готовый кадр не стоит показу ничего. Зеркало из-за этого отстаёт от проектора на кадр — в этом вся цена того, что оно никогда не тормозит.

Оно пропускает кадры, а не тормозит. Читатель медленнее показа теряет кадры; показ идёт дальше. Это противоположность безоконному --sink stdout, который блокирует: у безоконного цикла нет срока показа кадра, который можно пропустить, а у этого есть.

Консоль ему не нужна, и закрытие консоли его не убирает: это два независимых потребителя одного промежуточного результата. Геометрия берётся у вывода и объявляется до первого кадра событием stream в стандартном потоке ошибок (при --events), поэтому читатель знает, как разбить поток на кадры.

Цена записана, а не предполагается. При выходе и при закрытии консоли в diagnostics.log добавляется заметка preview с названием режима, p50 и p99 времени кадра показа и — если зеркало было включено — сколько кадров оно записало и сколько потеряло. Счётчики кадров и делают замер замером: прогон, показавший время кадра и ноль записанных кадров, измерял зеркало, которое ничего не доставило. Цену даёт сравнение прогона с флагом и без него; заметка называет свой режим, поэтому перепутать их нельзя.

Название трека

Когда трек меняется, исполнитель и название проявляются поверх картинки в левом нижнем углу, держатся несколько секунд и гаснут — это объявление, а не строка состояния. Слишком длинное название обрезается, а не уезжает за экран.

На Windows метаданные приходят из системной ленты «сейчас играет» (SMTC) — той же, что стоит за всплывающим медиа-окном, — поэтому работает с любым проигрывателем, который туда публикует, включая foobar2000. Публикуют туда не все. Тот, кто не публикует, просто не даёт плашки: это не ошибка, а приятная мелочь, которая молчит, когда ей нечего сказать. Закрытие проигрывателя очищает её.

На macOS отдельное приложение метаданных не получает: у системы нет поддерживаемого аналога (MediaRemote приватный и закрытый) — та же асимметрия, что уже есть у захвата петли звука. Ответ на этой платформе — компонент для foobar2000.

Чтобы выключить это совсем, используйте строку Now playing в меню настроек — это [hud] now_playing в config.toml, и, как и имя пресета, он переживает перезапуск. Выключено — значит, ни один трек до визуализатора не доходит.

Уровни качества

Движок рисует на одном из двух уровней, rich и floor, и floor — тот, что рассчитан на встроенную видеокарту. Если уровень не закреплён, приложение стартует на rich, а регулятор времени кадра один раз понижает его до floor, если бюджет кадра дисплея не выдерживается, — об этом сообщается в stderr и отмечается * в наложении F3.

[ и ] меняют уровень на ходу, как и строка Quality в меню настроек. Изменение из приложения закрепляет уровень на сессию, так что регулятор перестаёт его трогать, и записывает выбор в config.toml. Так же можно удержать rich на машине, где его понизила временная заминка. При переключении следы и обратная связь ненадолго накопятся заново: уровень задаёт размеры ресурсов GPU, поэтому его смена их пересоздаёт.

Уровень можно закрепить и до запуска; что там побеждает — см. порядок приоритетов в Configuration. Измеренные бюджеты, в которых держится каждый уровень, — в Non-functional requirements.

Мониторы и полный экран

D переводит окно на следующий монитор, а F включает безрамочный полный экран на том, где оно сейчас; Esc выходит из полного экрана и никогда не закрывает приложение. Оба пишут себя в config.toml в раздел [output], поэтому настроенное однажды завтра откроется таким же.

Монитор запоминается по имени, а не по индексу — сначала [output] display_name, затем [output] display, — потому что порядок мониторов в оконной системе не сохраняется между перезагрузками и переподключениями, так что один только индекс может указать на не тот экран.

Когда вход пропадает

Если источник захвата исчезает посреди показа — выдернули интерфейс, сбросился драйвер — приложение говорит об этом и переоткрывается на источнике по умолчанию для этого режима, несколько раз, а потом перестаёт. F3 и столбец capture в diagnostics.log называют, на что оно перешло, или пишут lost …, если не сработало ничего.

Обратное подключение не возвращает устройство, и именно поэтому восстановление — единственное изменение входа, которое не пишется в config.toml: ваш [input] device по-прежнему называет выбранный вами интерфейс, поэтому следующий запуск вернётся к нему. Чтобы вернуться к нему в этом прогоне, выберите его снова в меню S.