Skip to content

CONFIGURATION.md

Latest commit

 

History

History
149 lines (114 loc) · 15.6 KB

CONFIGURATION.md

File metadata and controls

149 lines (114 loc) · 15.6 KB

Руководство по конфигурации walltool

walltool использует файл конфигурации в формате TOML, который по умолчанию располагается по пути ~/.config/walltool/config.toml. Конфигурация разделена на три основных логических блока: [walltool] (настройки самого оркестратора), [awww] (параметры отрисовки обоев) и [matugen] (параметры генерации цветовых схем).

Иерархия переопределения (Overwriting Cascade)

Архитектура walltool построена на строгой иерархии приоритетов. Если один и тот же параметр (например, fill_color) задан в нескольких местах, применяется значение с наивысшим приоритетом.

Уровни приоритета (от высшего к низшему):

  1. CLI Флаги (Наивысший приоритет): Значения, переданные в терминале (например, wp set img.jpg --fill-color 000000ff). Они переопределяют абсолютно всё.
  2. База данных (Per-Wallpaper): Индивидуальные настройки для конкретной картинки, сохраненные в SQLite через команду wp options set. Картинка диктует свои правила отрисовки.
  3. Настройки монитора (Per-Monitor): Секции [awww.monitor."ИМЯ_МОНИТОРА"]. Применяются только к конкретному экрану, переопределяя профиль и глобальные дефолты.
  4. Активный профиль (Profile): Секции [walltool.profiles.ИМЯ.awww]. Применяются только тогда, когда сработал триггер профиля (Wi-Fi, время).
  5. Глобальные дефолты (Самый низкий): Секции [awww.global] и [matugen.global]. Фоллбэк, если параметр нигде больше не указан.

1. Основные настройки оркестратора ([walltool])

Демон ([walltool.daemon])

Фундаментальные настройки жизненного цикла фонового процесса.

  • db_path (Путь): Где хранить базу данных SQLite. По умолчанию: ~/.local/share/walltool/database.sqlite.
  • socket_path (Путь): Путь к Unix-сокету для IPC-общения между CLI и демоном. По умолчанию: $XDG_RUNTIME_DIR/walltool.sock.
  • wallpapers_dir (Массив путей): Список директорий, за которыми следит файловый вотчер (inotify) для автоматической индексации новых картинок.

Индексация ([walltool.indexing])

  • exclude_paths (Массив путей/глобов): Папки или маски, которые файловый вотчер и индексатор будут полностью игнорировать (например, ["**/.git/**", "**/NSFW/**"]).
  • startup_sync (Булево): Если true, при каждом запуске демон проверяет физическое наличие файлов из таблицы wallpapers и удаляет записи для несуществующих.

Искусственный Интеллект ([walltool.ai])

Управление локальной моделью (Moondream2) для генерации тегов.

  • ai_tagging (Булево): Глобальный переключатель. Если false, ИИ полностью отключен.
  • model_path (Путь): Путь к .safetensors весам локальной модели.
  • ai_prompt (Строка): Промпт для извлечения тегов.
  • confidence_threshold (Float 0.0-1.0): Порог уверенности нейросети. Теги с уверенностью ниже этого значения не попадут в БД.
  • ai_worker_threads (Целое число): Количество потоков CPU, выделенных под ИИ-генерацию.
  • indexing_strategy ("force" | "idle"):
    • force: Генерировать теги мгновенно при добавлении файла.
    • idle: Откладывать генерацию до момента, пока система не освободится.
  • max_system_load (Целое 0-100): Процент нагрузки системы (нормализованный Load Average). Если indexing_strategy = "idle", ИИ запустится только если нагрузка ниже этого порога.
  • load_average_window ("1m" | "5m" | "15m"): Период времени для расчета средней нагрузки (Load Average), который сглаживает секундные скачки CPU. По умолчанию: "1m".
  • pause_on_battery (Булево): Если true, ИИ-генерация полностью ставится на паузу при работе ноутбука от батареи.
  • min_battery_level (Целое 0-100): Минимальный процент заряда. Если заряд ниже, ИИ не запускается.

Авто-Тема ([walltool.auto_theme])

  • strategy ("time" | "image"):
    • time: Переключает dark/light мод в зависимости от времени.
    • image: Демон сам анализирует установленную картинку и включает светлую тему для ярких обоев, и темную для темных.
  • sunrise (Строка "HH:MM"): Время включения light мода.
  • sunset (Строка "HH:MM"): Время включения dark мода.

Слайд-шоу по умолчанию ([walltool.slideshow])

  • interval (Целое число): Время в секундах между сменой обоев.
  • directory (Массив путей): Папки, откуда брать случайные обои.
  • Фильтры поиска (Применяются к выборке следующей картинки):
    • query (Строка): Поисковый SQL-запрос (поиск по путям, цветам, ИИ-тегам).
    • visibility ("default" | "include-hidden" | "only-hidden"): Искать ли в скрытых файлах (начинающихся с точки).
    • only_favorites (Булево): Выбирать только из таблицы favorites.
    • only_history (Булево): Выбирать только те картинки, которые уже когда-то были установлены.
  • Сортировка:
    • sort_by ("random" | "time" | "color" | "name" | "score"): Правило выбора следующей картинки. Для слайд-шоу стандарт — random.
    • reversed (Булево): Инвертировать порядок сортировки.

2. Унифицированные Профили ([walltool.profiles.ИМЯ])

Профили позволяют менять поведение демона в зависимости от внешних факторов (контекста). Имя профиля задается в ключе, например [walltool.profiles.work].

Триггеры (Когда включается профиль)

  • trusted_wifi (Массив строк): Профиль активен, если устройство подключено к одной из указанных Wi-Fi сетей (например, ["Office_Corp"]).
  • time_between (Массив из двух строк "HH:MM"): Профиль активен в указанном промежутке времени (например, ["08:00", "18:00"]).

Действия (Что делает профиль)

  • wallpaper (Путь): Установить статичную картинку.
  • directory и Фильтры поиска (query, sort_by, only_favorites и т.д.): Настройки динамического слайд-шоу для этого профиля. Аналогичны блоку [walltool.slideshow].
  • Секции [walltool.profiles.ИМЯ.awww] и [walltool.profiles.ИМЯ.matugen] позволяют переопределить эффекты отрисовки и параметры генерации темы на время работы профиля.

3. Параметры рендеринга awww ([awww])

Настройки awww могут располагаться в [awww.global], [awww.monitor."DP-1"], [awww.wallpaper."/path.jpg"] или внутри профилей.

  • resize ("no", "crop", "fit", "stretch", "adaptive"): Как масштабировать картинку.
  • fill_color (Строка): Hex-цвет заливки пустых краев (RRGGBBAA без решетки, например 1e1e2eff). Особое значение: "adaptive" (демон возьмет доминантный цвет картинки из БД).
  • filter ("nearest", "bilinear", "catmull-rom", "mitchell", "lanczos3"): Алгоритм скейлинга картинки.
  • transition_type ("none", "simple", "fade", "left", "right", "top", "bottom", "wipe", "wave", "grow", "center", "any", "outer", "random"): Тип анимации перехода.
  • transition_step (Целое 1-255): Скорость шага анимации. 255 означает мгновенное переключение.
  • transition_duration (Целое): Длительность транзишена в секундах (не работает для типа simple).
  • transition_fps (Целое): Ограничение частоты кадров анимации.
  • transition_angle (Целое): Угол в градусах (используется для wipe и wave).
  • transition_pos (Строка): Центр анимации (для grow, outer). Может быть алиасом ("center", "top-left" и др.) или координатами в процентах/пикселях ("0.5,0.5", "200,400").
  • transition_bezier (Строка): Кривая Безье для fade (например, "0.54,0.0,0.34,0.99").
  • transition_wave (Целое): Размер волны для wave.
  • invert_y (Булево): Инвертировать координату Y для transition_pos.

Умная адаптация ([awww...adaptive])

Применяется, если resize = "adaptive". Позволяет элегантно обрабатывать вертикальные картинки на горизонтальных мониторах (и наоборот).

  • type ("fill-blur" | "fill-color"):
    • fill-blur: walltool генерирует размытый фон из самой картинки.
    • fill-color: walltool делает fit и заливает края доминантным цветом из БД.
  • blur_radius (Float): Сила размытия (для fill-blur).
  • threshold (Float): Порог срабатывания. Например 0.8 означает, что адаптация включится, только если соотношение сторон картинки и экрана отличается более чем на 20%.

4. Параметры генерации темы matugen ([matugen])

Настройки matugen также могут располагаться глобально, по мониторам, по обоям или в профилях.

  • type (Строка): Схема генерации Material You (scheme-content, scheme-expressive, scheme-fidelity, scheme-fruit-salad, scheme-monochrome, scheme-neutral, scheme-rainbow, scheme-tonal-spot, scheme-vibrant).
  • config (Путь): Путь к кастомному файлу конфигурации/шаблонов для matugen.
  • mode ("light" | "dark"): Принудительный режим.
  • resize_filter ("nearest", "triangle", "catmull-rom", "gaussian", "lanczos3"): Алгоритм сжатия перед извлечением цвета.
  • fallback_color (Hex-строка): Цвет-заглушка на случай, если извлечь цвет не удалось.
  • prefer ("darkness", "lightness", "saturation", "less-saturation", "value", "closest-to-fallback"): Критерий выбора цвета при неоднозначности.
  • lightness_dark (Float 0.0-1.0): Яркость для темной темы.
  • lightness_light (Float 0.0-1.0): Яркость для светлой темы.
  • source_color_index (Целое 0-4): Какой доминантный цвет выбрать (0 — самый частый).
  • opacity (Float 0.0-1.0): Прозрачность сгенерированных цветов.

5. Игнорируемые параметры и Конфликты (Важно!)

Система спроектирована так, чтобы избегать логических тупиков. В определенных ситуациях одни параметры полностью блокируют или отменяют другие:

1. Статика отменяет Динамику (В Профилях)

Если в профиле указан путь к статичной картинке: [walltool.profiles.work] wallpaper = "~/img.jpg" То параметры directory, query, visibility, sort_by и другие фильтры слайд-шоу внутри этого профиля полностью игнорируются. Профиль считается статичным.

2. Стратегия авто-темы

Если в [walltool.auto_theme] параметр strategy = "image" (цвет темы вычисляется по яркости обоев), то параметры sunrise и sunset игнорируются.

3. Режимы батареи (AI)

Если в [walltool.ai] указано pause_on_battery = true, то при отключении от сети параметр min_battery_level игнорируется (ИИ ставится на паузу независимо от того, 99% заряда или 10%).

4. Стратегия индексации

Если [walltool.ai] использует indexing_strategy = "force", то параметр max_system_load игнорируется (ИИ генерирует теги на максимальной скорости, невзирая на загрузку процессора).

5. Переопределение темы профилем

Если сработал профиль, в котором жестко задан режим темы (например, [walltool.profiles.work.matugen] mode = "dark"), то глобальный блок [walltool.auto_theme] временно игнорируется (даже если сейчас день, и авто-тема просит светлую палитру). Контекст профиля всегда важнее.