Конфигурация

Обзор

Для опытных пользователей, разработчиков и системных администраторов Snapzy поддерживает расширенную программную настройку с помощью стандартного файла TOML (config.toml). Это позволяет управлять всеми параметрами приложения в текстовом формате, синхронизировать их через репозитории dotfiles и настраивать автоматическое развертывание в различных окружениях macOS.

---

Начало работы

1. Предоставление доступа к конфигурации

1. Откройте Настройки (Preferences) Snapzy (Cmd + ,) и перейдите на вкладку Дополнительно (Advanced).
2. Нажмите Настройка config.toml (Set Up config.toml).
3. Появится системное диалоговое окно с запросом на выбор каталога конфигурации или предоставление доступа к нему. Выберите нужную директорию (обычно ~/.config/snapzy/) и нажмите Предоставить доступ (Grant Access).

После предоставления доступа Snapzy автоматически сгенерирует файл config.toml по умолчанию по следующему пути:

~/.config/snapzy/config.toml

2. Синхронизация и фоновая загрузка

• Применение при запуске: Snapzy анализирует и проверяет валидность config.toml при каждом запуске приложения.
• Автоматическая фоновая синхронизация: Приложение отслеживает изменения в файле config.toml в фоновом режиме. Изменения, сохраненные непосредственно в вашем редакторе, автоматически проверяются и применяются в течение нескольких секунд (используется фильтрация дребезга для предотвращения неполного считывания файла во время записи).
• Ручная синхронизация: Вы можете нажать кнопку Синхронизировать config.toml (Sync config.toml) в дополнительных настройках, чтобы мгновенно перезагрузить конфигурацию.
• Сброс настроек: Нажатие кнопки Восстановить настройки по умолчанию перезаписывает существующий TOML-файл заводскими значениями по умолчанию.

---

Шаблон файла TOML с комментариями

Ниже приведен полный шаблон файла config.toml со всеми доступными параметрами и комментариями, объясняющими каждый атрибут.

# Версия схемы Snapzy TOML (должна быть равна 1)
schema_version = 1

# Минимальная версия Snapzy, необходимая для этого файла
snapzy_min_version = "1.20.0"

[general]
language = "system"                # "system" или код языка: "en", "vi", "ja", "ko", "ru", "zh", "zh-tw"
appearance = "system"              # Тема оформления: "system", "light" или "dark"
play_sounds = true                 # Воспроизведение звуковых эффектов при снимке/записи
start_at_login = false             # Автоматический запуск Snapzy при старте macOS
export_location = "~/Pictures"     # Локальная папка для сохранения снимков (поддерживается символ ~)

[updates]
check_automatically = true         # Автоматическая проверка обновлений через Sparkle
download_automatically = false     # Фоновая загрузка обновлений без вывода всплывающих окон

[diagnostics]
enabled = true                     # Включение локального ведения журнала диагностики для отчетов о проблемах
retention_days = 7                 # Количество дней для хранения файлов журналов (от 1 до 30)

[capture]
hide_desktop_icons = false         # Временное скрытие иконок рабочего стола при захвате
hide_desktop_widgets = false       # Временное скрытие виджетов рабочего стола при захвате

[capture.naming]
screenshot_template = "Snapzy_{year}-{month}-{day}_{hour}-{minute}-{second}_{milliseconds}" # Шаблон имени снимков
recording_template = "Snapzy_{year}-{month}-{day}_{hour}-{minute}-{second}_{milliseconds}"  # Шаблон имени видеозаписей

[capture.screenshot]
format = "png"                     # Формат файлов снимков: "png", "jpeg" или "webp"
include_snapzy = false             # Включение панелей управления самого Snapzy в область снимков
show_cursor = false                # Показывать курсор мыши macOS на снимках экрана

[capture.scrolling]
show_hints = true                  # Показывать подсказки во время захвата с прокруткой

[capture.ocr]
success_notification = false       # Отправлять системное уведомление при успешном распознавании текста (OCR)

[capture.object_cutout]
auto_crop = true                   # Автоматическая обрезка пустых полей вокруг вырезанного объекта

[capture.after.screenshot]
save = true                        # Автоматически сохранять скриншоты в целевую папку
quick_access = true                # Показывать панель быстрого доступа после захвата
copy_file = true                   # Копировать путь к сохраненному файлу в буфер обмена
open_annotate = false              # Автоматически открывать изображение в редакторе аннотаций (Annotate)
upload_to_cloud = false            # Мгновенно загружать изображение в настроенное облачное хранилище

[capture.after.recording]
save = true                        # Автоматически сохранять видеозаписи в целевую папку
quick_access = true                # Показывать панель быстрого доступа после завершения записи
copy_file = true                   # Копировать путь к файлу видеозаписи в буфер обмена
open_annotate = false              # Автоматически открывать видео в видеоредакторе (Video Editor)
upload_to_cloud = false            # Мгновенно загружать видео в настроенное облачное хранилище

[recording]
format = "mov"                     # Формат видеоконтейнера: "mov" или "mp4"
quality = "high"                   # Профиль качества видео: "high", "medium" или "low"
fps = 30                           # Целевая частота кадров в секунду (от 1 до 120)
output_mode = "video"              # Формат экспорта медиа: "video" (MP4/MOV) или "gif" (анимированный GIF)
capture_system_audio = true        # Запись системного звука (требуется виртуальный аудиодрайвер)
capture_microphone = false         # Запись звука с микрофона
microphone_device_id = ""          # Идентификатор устройства CoreAudio для записи с микрофона
remember_last_area = true          # Запоминать координаты последней области захвата для следующих сессий
include_snapzy = false             # Включать панели управления Snapzy в финальную видеозапись
show_cursor = true                 # Включать курсор мыши macOS в видеозапись
highlight_clicks = false           # Отображать анимационные кольца вокруг указателя при кликах мыши
show_keystrokes = false            # Отображать нажатые клавиши на экране во время записи

[recording.mouse_highlight]
size = 50                          # Диаметр круга подсветки клика мыши в пикселях (от 20 до 120)
animation_duration = 0.7           # Длительность анимации волны клика в секундах (от 0.1 до 3.0)
color = "#FF000080"                # Шестнадцатеричный код цвета круга подсветки (#RRGGBB или #RRGGBBAA)
opacity = 0.5                      # Непрозрачность круга подсветки (от 0.0 до 1.0)
ripple_count = 3                   # Количество кругов волны на один клик (от 1 до 6)

[recording.keystrokes]
font_size = 18.0                   # Размер шрифта отображения клавиш в пунктах (от 10.0 до 48.0)
position = "bottomCenter"          # Положение оверлея: "topLeft", "topRight", "bottomLeft", "bottomRight", "bottomCenter" и т. д.
display_duration = 2.0             # Время отображения клавиш на экране в секундах (от 0.3 до 10.0)

[recording.annotation_shortcuts]
modifier = "shift"                 # Вспомогательная клавиша для вызова панели аннотаций: "shift", "option", "command", "control"
hold_duration = 1.0                # Время удержания клавиши для активации панели в секундах (от 0.1 до 5.0)

[quick_access]
enabled = true                     # Включение мини-панели быстрого доступа после захвата
position = "bottomRight"           # Угол привязки панели: "topLeft", "topRight", "bottomLeft", "bottomRight"
auto_dismiss = true                # Автоматически скрывать панель по истечении таймера
auto_dismiss_delay = 10.0          # Время ожидания перед скрытием панели в секундах (от 3.0 до 30.0)
pause_countdown_on_hover = true    # Приостанавливать таймер автоскрытия при наведении курсора на панель
overlay_scale = 1.0                # Коэффициент масштаба панели быстрого доступа (от 0.75 до 1.5)
drag_drop = true                   # Разрешить перетаскивание файлов (Drag and Drop) из панели в другие приложения
actions_order = ["copy", "annotate", "save", "cloud", "delete"] # Порядок отображения быстрых кнопок
enabled_actions = ["copy", "annotate", "save", "cloud", "delete"] # Список отображаемых кнопок действий

[quick_access.slots]
center_top = "copy"                # Назначение действия для центрального верхнего слота
center_bottom = "annotate"         # Назначение действия для центрального нижнего слота
top_trailing = "save"              # Назначение действия для верхнего правого слота
top_leading = "cloud"              # Назначение действия для верхнего левого слота
bottom_leading = "delete"          # Назначение действия для нижнего левого слота
bottom_trailing = ""               # Оставьте пустым, если слот не используется

[history]
enabled = true                     # Включение локального сохранения истории захватов в приложении
retention_days = 30                # Период хранения записей в днях (0 для бесконечного хранения)
max_count = 500                    # Максимальное количество записей в истории (от 0 до 1000)
background_style = "hud"           # Стиль фона окна истории: "hud" (полупрозрачное стекло) или "solid" (непрозрачный)
open_on_launch = false             # Автоматически открывать окно истории при каждом запуске Snapzy

[history.floating]
enabled = true                     # Показывать всплывающую панель истории HUD на экране
position = "topCenter"             # Положение всплывающей панели истории: "topCenter", "bottomCenter", "center"
default_filter = "all"             # Фильтр по умолчанию: "all", "screenshot", "recording", "ocr", "cutout"
max_displayed_items = 10           # Максимальное количество отображаемых карточек в панели (от 3 до 20)
scale = 1.0                        # Масштаб всплывающей панели истории (от 0.8 до 1.2)
auto_clear_days = 0                # Автоматически удалять записи истории старше указанных дней (от 0 до 365)

[cloud]
provider = "aws_s3"                # Облачный провайдер: "aws_s3" или "cloudflare_r2"
bucket = "my-snapzy-bucket"        # Имя бакета AWS S3 или Cloudflare R2
region = "us-east-1"               # Идентификатор региона бакета (обязательно для S3)
endpoint = ""                      # URL-адрес конечной точки API (обязательно для Cloudflare R2)
custom_domain = ""                 # Собственный домен для создания коротких ссылок общего доступа
expire_time = "7d"                 # Срок действия ссылок/правило хранения: "1d", "3d", "7d", "14d", "30d", "60d", "90d", "permanent"
uploads_window_position = "center" # Положение панели отслеживания загрузки в облако: "top", "center", "bottom"

[annotate]
clipboard_image_open_behavior = "ask" # Поведение при открытии пустого редактора и наличии картинки в буфере: "ask", "loadAutomatically", "doNothing"
close_after_drag = true            # Автоматически закрывать окно аннотаций после перетаскивания файла наружу
bring_forward_after_drag = false   # Выводить целевое приложение на передний план после завершения перетаскивания
quick_properties_sync = true       # Мгновенно синхронизировать толщину линий и цвет между инструментами рисования

[shortcuts]
enabled = true                     # Включение глобальных горячих клавиш (необходимо для регистрации сочетаний)

[shortcuts.global.fullscreen]
enabled = true
key = "3"
modifiers = ["command", "shift"]

[shortcuts.global.area]
enabled = true
key = "4"
modifiers = ["command", "shift"]

[shortcuts.global.areaAnnotate]
enabled = true
key = "7"
modifiers = ["command", "shift"]

[shortcuts.global.scrollingCapture]
enabled = true
key = "6"
modifiers = ["command", "shift"]

[shortcuts.global.recording]
enabled = true
key = "5"
modifiers = ["command", "shift"]

[shortcuts.global.annotate]
enabled = true
key = "A"
modifiers = ["command", "shift"]

[shortcuts.global.videoEditor]
enabled = true
key = "E"
modifiers = ["command", "shift"]

[shortcuts.global.cloudUploads]
enabled = true
key = "L"
modifiers = ["command", "shift"]

[shortcuts.global.shortcutList]
enabled = true
key = "K"
modifiers = ["command", "shift"]

[shortcuts.global.ocr]
enabled = true
key = "2"
modifiers = ["command", "shift"]

[shortcuts.global.objectCutout]
enabled = true
key = "1"
modifiers = ["command", "shift"]

[shortcuts.global.history]
enabled = true
key = "H"
modifiers = ["command", "shift"]

[shortcuts.overlay.area_application_capture]
enabled = true
key = "SPACE"                      # Дополнительная вспомогательная клавиша при захвате области
modifiers = []

[shortcuts.overlay.recording_application_capture]
enabled = true
key = "SPACE"
modifiers = []

[shortcuts.annotate_tools]
disabled = []
# Назначение цифровых клавиш от «1» до «8» для быстрого выбора инструментов рисования
"1" = "pen"
"2" = "arrow"
"3" = "rect"
"4" = "oval"
"5" = "text"
"6" = "blur"

[shortcuts.annotate_actions.copyAndClose]
enabled = true
key = "C"
modifiers = ["command"]

[shortcuts.annotate_actions.toggleSidebar]
enabled = true
key = "B"
modifiers = ["command"]

[shortcuts.annotate_actions.togglePin]
enabled = true
key = "P"
modifiers = ["command"]

[shortcuts.annotate_actions.cloudUpload]
enabled = true
key = "U"
modifiers = ["command"]

---

Справочник свойств конфигурации

Общий раздел ([general])

Имя свойства	Тип данных	Значение по умолчанию	Допустимые варианты / Диапазон	Описание
language	Строка	"system"	"system", "en", "vi", "ja", "ko", "ru", "zh", "zh-tw"	Настройка языка интерфейса приложения.
appearance	Строка	"system"	"system", "light", "dark"	Режим цветовой темы интерфейса.
play_sounds	Булево	true	true, false	Включение/выключение звуков при захвате.
start_at_login	Булево	false	true, false	Автозапуск приложения при входе в macOS.
export_location	Строка	"~/Pictures"	Корректный путь к папке	Локальный путь для автоматического сохранения файлов.

Обновления и диагностика

Имя свойства	Тип данных	Значение по умолчанию	Допустимые варианты / Диапазон	Описание
updates.check_automatically	Булево	true	true, false	Автоматическая проверка новых обновлений через Sparkle.
updates.download_automatically	Булево	false	true, false	Фоновое скачивание пакетов обновлений без вывода запросов.
diagnostics.enabled	Булево	true	true, false	Включение записи логов диагностики работы для отчетов о сбоях.
diagnostics.retention_days	Целое число	7	От 1 до 30	Количество дней для хранения файлов диагностических логов на диске.

Захват экрана и правила именования ([capture])

Имя свойства	Тип данных	Значение по умолчанию	Допустимые варианты / Диапазон	Описание
hide_desktop_icons	Булево	false	true, false	Автоматически скрывать файлы на рабочем столе при захвате.
hide_desktop_widgets	Булево	false	true, false	Автоматически скрывать виджеты рабочего стола при захвате.
naming.screenshot_template	Строка	"Snapzy_{year}...	Строка шаблона имени	Шаблон для автоматического именования файлов снимков.
naming.recording_template	Строка	"Snapzy_{year}...	Строка шаблона имени	Шаблон для автоматического именования файлов видеозаписей.
screenshot.format	Строка	"png"	"png", "jpeg", "webp"	Формат сохраняемых изображений снимков экрана.
screenshot.include_snapzy	Булево	false	true, false	Захватывать оверлеи и панели управления самого Snapzy на снимках.
screenshot.show_cursor	Булево	false	true, false	Сохранять указатель мыши системы на скриншотах.
scrolling.show_hints	Булево	true	true, false	Показывать визуальные указатели при захвате страниц с прокруткой.
ocr.success_notification	Булево	false	true, false	Отправлять пуш-уведомление при успешном извлечении текста.
object_cutout.auto_crop	Булево	true	true, false	Автоматически кадрировать пустоту по краям вырезанного объекта.

События после захвата (After Capture)

Имя свойства	Тип данных	Значение по умолчанию	Допустимые варианты / Диапазон	Описание
capture.after.screenshot.save	Булево	true	true, false	Записывать файлы скриншотов в целевую папку экспорта.
capture.after.screenshot.quick_access	Булево	true	true, false	Отображать мини-панель быстрого доступа после снимка.
capture.after.screenshot.copy_file	Булево	true	true, false	Копировать полный путь к сохраненному файлу в буфер обмена.
capture.after.screenshot.open_annotate	Булево	false	true, false	Мгновенно передавать скриншот в графический редактор аннотаций.
capture.after.screenshot.upload_to_cloud	Булево	false	true, false	Автоматически инициировать отправку файла в облако.
capture.after.recording.save	Булево	true	true, false	Записывать видеозаписи в целевую локальную папку экспорта.
capture.after.recording.quick_access	Булево	true	true, false	Отображать мини-панель быстрого доступа после завершения записи.
capture.after.recording.copy_file	Булево	true	true, false	Копировать полный путь к файлу видеозаписи в буфер обмена.
capture.after.recording.open_annotate	Булево	false	true, false	Мгновенно отправлять видеозапись в видеоредактор.
capture.after.recording.upload_to_cloud	Булево	false	true, false	Автоматически инициировать отправку видео в фоновом режиме в облако.

Запись видео экрана ([recording])

Имя свойства	Тип данных	Значение по умолчанию	Допустимые варианты / Диапазон	Описание
format	Строка	"mov"	"mov", "mp4"	Формат контейнера видеозаписи.
quality	Строка	"high"	"high", "medium", "low"	Качество сжатия видеоряда.
fps	Целое число	30	От 1 до 120	Целевая плотность кадров в секунду при записи.
output_mode	Строка	"video"	"video", "gif"	Итоговый экспортируемый медиаформат.
capture_system_audio	Булево	true	true, false	Записывать общие звуки, воспроизводимые на компьютере.
capture_microphone	Булево	false	true, false	Включать в видеоряд аудиопоток с микрофона.
microphone_device_id	Строка	""	Идентификатор аудиоустройства	Ручной выбор внешнего аппаратного микрофона для записи.
remember_last_area	Булево	true	true, false	Запоминать границы области последнего захваченного видеоряда.
show_cursor	Булево	true	true, false	Записывать видео с указателем мыши.
highlight_clicks	Булево	false	true, false	Показывать эффектные круги вокруг курсора при нажатиях.
show_keystrokes	Булево	false	true, false	Показывать плашку с нажатыми клавишами на видеоряде.
mouse_highlight.size	Вещественное	50.0	От 20.0 до 120.0	Внешний диаметр круга индикации клика.
mouse_highlight.color	Строка	"#FF000080"	HEX-код цвета (#RRGGBBAA)	Цвет подсветки клика мыши.
mouse_highlight.opacity	Вещественное	0.5	От 0.0 до 1.0	Непрозрачность индикации кликов.
mouse_highlight.ripple_count	Целое число	3	От 1 до 6	Количество волн анимации клика.
keystrokes.font_size	Вещественное	18.0	От 10.0 до 48.0	Высота шрифта клавиш в пунктах.
keystrokes.position	Строка	"bottomCenter"	Положение оверлея	Расположение плашки вывода горячих клавиш на видео.
keystrokes.display_duration	Вещественное	2.0	От 0.3 до 10.0	Время удержания плашки с клавишами на экране.
annotation_shortcuts.modifier	Строка	"shift"	Код клавиши-модификатора	Горячая клавиша для быстрого вызова рисования на видео.
annotation_shortcuts.hold_duration	Вещественное	1.0	От 0.1 до 5.0	Длительность зажатия клавиши для вызова панели.

Панель быстрого доступа ([quick_access])

Имя свойства	Тип данных	Значение по умолчанию	Допустимые варианты / Диапазон	Описание
enabled	Булево	true	true, false	Отображение всплывающей мини-панели после создания снимка.
position	Строка	"bottomRight"	Положение оверлея	Угол экрана для размещения плашки быстрого доступа.
auto_dismiss	Булево	true	true, false	Включение таймера автоматического скрытия плашки.
auto_dismiss_delay	Вещественное	10.0	От 3.0 до 30.0	Тайм-аут скрытия панели быстрого доступа (в секундах).
pause_countdown_on_hover	Булево	true	true, false	Замораживать таймер скрытия при наведении курсора на панель.
overlay_scale	Вещественное	1.0	От 0.75 до 1.5	Коэффициент изменения размера панели быстрого доступа.
drag_drop	Булево	true	true, false	Возможность прямого экспорта файлов методом перетаскивания.
actions_order	Массив	По умолчанию	Идентификаторы кнопок	Порядок сортировки управляющих кнопок.
enabled_actions	Массив	По умолчанию	Идентификаторы кнопок	Набор функций, отображаемых на панели быстрого доступа.

Журнал истории файлов ([history])

Имя свойства	Тип данных	Значение по умолчанию	Допустимые варианты / Диапазон	Описание
enabled	Булево	true	true, false	Включение сохранения метаданных об истории снимков в приложении.
retention_days	Целое число	30	От 0 до 90	Лимит хранения записей в днях (0 — хранить бесконечно).
max_count	Целое число	500	От 0 до 1000	Квота на максимальное число записей истории в базе.
background_style	Строка	"hud"	"hud", "solid"	Стиль отрисовки подложки окна просмотра истории.
open_on_launch	Булево	false	true, false	Показывать окно истории при старте программы Snapzy.
floating.enabled	Булево	true	true, false	Вывод на экран плавающей полосы быстрого доступа к истории.
floating.position	Строка	"topCenter"	Направление привязки	Направление выравнивания плавающей полосы истории на экране.
floating.max_displayed_items	Целое число	10	От 3 до 20	Макс. число превью карточек внутри плавающей HUD панели.
floating.scale	Вещественное	1.0	От 0.8 до 1.2	Коэффициент размера плавающей панели истории.

Облачное хранилище ([cloud])

Имя свойства	Тип данных	Значение по умолчанию	Допустимые варианты / Диапазон	Описание
provider	Строка	"aws_s3"	"aws_s3", "cloudflare_r2"	Тип удаленного хранилища для экспорта.
bucket	Строка	""	Имя корзины / бакета	Имя бакета хранилища S3 или R2.
region	Строка	"us-east-1"	Код региона S3	Идентификатор зоны расположения сервера (требуется для S3).
endpoint	Строка	""	Ссылка endpoint URL	API URL конечной точки доступа к серверу (требуется для R2).
custom_domain	Строка	""	Ссылка на домен	Собственный хостнейм домена для генерации коротких публичных ссылок.
expire_time	Строка	"7d"	"1d", "3d", "7d", "14d", "30d", "60d", "90d", "permanent"	Время жизни генерируемой временной ссылки.
uploads_window_position	Строка	"center"	"top", "center", "bottom"	Размещение оверлея хода загрузки файлов на экране.

Редактор аннотаций ([annotate])

Имя свойства	Тип данных	Значение по умолчанию	Допустимые варианты / Диапазон	Описание
clipboard_image_open_behavior	Строка	"ask"	"ask", "loadAutomatically", "doNothing"	Действие при открытии пустого редактора при наличии картинки в буфере обмена.
close_after_drag	Булево	true	true, false	Закрывать окно редактирования сразу после экспорта перетаскиванием.
bring_forward_after_drag	Булево	false	true, false	Переводить целевое приложение на передний план по окончании перетаскивания.
quick_properties_sync	Булево	true	true, false	Мгновенно синхронизировать цвет и толщину пера между инструментами.

---

Валидация и проблемы

Snapzy осуществляет строгую валидацию параметров config.toml при загрузке:

• Выход за границы значений: Если параметр превышает допустимый лимит (например, fps = 150 или overlay_scale = 3.0), Snapzy выведет предупреждение в журнал, проигнорирует неверное значение и использует значение по умолчанию.
• Неверный тип данных: Указание неверного типа (например, строка вместо булева значения) приведет к ошибке разбора. Snapzy откажется применять блок настроек и восстановит старые параметры приложения.
• Просмотр списка предупреждений: Список всех ошибок разбора TOML или предупреждений можно просмотреть непосредственно в настройках на вкладке Дополнительно (Advanced) в разделе статуса синхронизации.