Обзор
Для опытных пользователей, разработчиков и системных администраторов Snapzy поддерживает расширенную программную настройку с помощью стандартного файла TOML (config.toml). Это позволяет управлять всеми параметрами приложения в текстовом формате, синхронизировать их через репозитории dotfiles и настраивать автоматическое развертывание в различных окружениях macOS.
Требование для начала работы — Из-за ограничений безопасности песочницы macOS приложению Snapzy требуется разовое предоставление разрешений на доступ к папке, чтобы иметь возможность читать или писать файлы в вашем домашнем каталоге. Настройте это на вкладке «Дополнительно» (Advanced) в настройках приложения.
Начало работы
1. Предоставление доступа к конфигурации
- Откройте Настройки (Preferences) Snapzy (
Cmd + ,) и перейдите на вкладку Дополнительно (Advanced).
- Нажмите Настройка config.toml (Set Up config.toml).
- Появится системное диалоговое окно с запросом на выбор каталога конфигурации или предоставление доступа к нему. Выберите нужную директорию (обычно
~/.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" | Размещение оверлея хода загрузки файлов на экране. |
Важно по безопасности — Секретные ключи авторизации (AWS Access Keys, Secret Tokens и т. д.) никогда не записываются в текстовый файл config.toml для предотвращения их утечки при публикации настроек в открытых репозиториях (например, на GitHub). Они зашифрованы и хранятся в системной Связке ключей macOS (Keychain).
Редактор аннотаций ([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) в разделе статуса синхронизации.