ドキュメント
設定ファイル (config.toml)
Documentation

設定ファイル (config.toml)

config.toml ファイルを使用して Snapzy をプログラムから設定し、ポータブルな設定管理、自動バックアップ、および dotfiles ワークフローの同期を実現します。

概要

パワーユーザー、開発者、およびシステム管理者向けに、Snapzy は標準の TOML ファイル (config.toml) を使用した高度なプログラム構成をサポートしています。これにより、プレーンテキストですべてのアプリケーション設定を管理し、dotfiles リポジトリを使用して同期し、macOS 環境間で自動デプロイを設定できます。

初回セットアップの要件 — macOS のサンドボックスセキュリティのため、Snapzy がホームディレクトリ配下のファイルを読み書きするには、一回限りのフォルダアクセス権限の付与が必要です。これは「設定」の「詳細」タブで設定してください。

クイックスタート

1. 設定へのアクセス許可

  1. 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             # macOS 起動時に Snapzy を自動起動
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 デバイス UID 文字列
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                   # ファイルを直接ドラッグ＆ドロップして他のアプリに共有することを許可する
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             # アプリの起動時に自動的に履歴ブラウザウィンドウを開く

[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 = ""                      # API エンドポイント URL (R2では必須)
custom_domain = ""                 # 共有リンク生成用のカスタムドメイン名
expire_time = "7d"                 # 共有リンクの有効期限/ライフサイクルルール: "1d", "3d", "7d", "14d", "30d", "60d", "90d", "permanent"
uploads_window_position = "center" # アップロード進行バー HUD の配置位置: "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"Snapzy UI の表示言語設定。
appearance文字列"system""system", "light", "dark"UI テーマモード。
play_soundsブーリアンtruetrue, falseキャプチャ時のサウンドエフェクトの有効/無効。
start_at_loginブーリアンfalsetrue, falsemacOS 起動時に自動でアプリを起動。
export_location文字列"~/Pictures"有効なディレクトリパスキャプチャ画像のローカルエクスポート先。

アップデートと診断

プロパティ名データ型デフォルト値有効なオプション / 範囲説明
updates.check_automaticallyブーリアンtruetrue, falseSparkle を使用したアップデートの自動確認。
updates.download_automaticallyブーリアンfalsetrue, falseアップデートパッケージのバックグラウンド自動ダウンロード。
diagnostics.enabledブーリアンtruetrue, falseトラブル報告用の診断ログの記録。
diagnostics.retention_days整数71〜30診断ログファイルの保持日数。

キャプチャと名前テンプレート ([capture])

プロパティ名データ型デフォルト値有効なオプション / 範囲説明
hide_desktop_iconsブーリアンfalsetrue, falseキャプチャ時にデスクトップアイコンを一時非表示。
hide_desktop_widgetsブーリアンfalsetrue, falseキャプチャ時にデスクトップウィジェットを一時非表示。
naming.screenshot_template文字列"Snapzy_{year}...命名テンプレート文字列スクショ画像の保存時ファイル名規則。
naming.recording_template文字列"Snapzy_{year}...命名テンプレート文字列録画動画の保存時ファイル名規則。
screenshot.format文字列"png""png", "jpeg", "webp"スクショ画像の形式。
screenshot.include_snapzyブーリアンfalsetrue, falseSnapzy 自身のユーティリティウィンドウを写り込ませる。
screenshot.show_cursorブーリアンfalsetrue, falseマウスクリッパーを画像に含める。
scrolling.show_hintsブーリアンtruetrue, falseスクロールキャプチャ作業中の指示ガイド表示。
ocr.success_notificationブーリアンfalsetrue, falseテキスト抽出の成功通知を表示。
object_cutout.auto_cropブーリアンtruetrue, false切り抜かれた被写体の周囲の余白を自動トリミング。

キャプチャ後のアクション

プロパティ名データ型デフォルト値有効なオプション / 範囲説明
capture.after.screenshot.saveブーリアンtruetrue, falseスクショファイルを自動保存。
capture.after.screenshot.quick_accessブーリアンtruetrue, false画面隅にクイックアクセスプレビューパネルを表示。
capture.after.screenshot.copy_fileブーリアンtruetrue, false保存ファイルのフルパスをクリップボードにコピー。
capture.after.screenshot.open_annotateブーリアンfalsetrue, falseキャプチャ後、自動的に注釈エディタを開く。
capture.after.screenshot.upload_to_cloudブーリアンfalsetrue, falseキャプチャ後、自動的にクラウドへアップロード。
capture.after.recording.saveブーリアンtruetrue, false録画ビデオファイルを自動保存。
capture.after.recording.quick_accessブーリアンtruetrue, false録画完了後、クイックアクセスパネルを表示。
capture.after.recording.copy_fileブーリアンtruetrue, false保存されたビデオのパスをクリップボードにコピー。
capture.after.recording.open_annotateブーリアンfalsetrue, false録画後、自動的に動画エディタを開く。
capture.after.recording.upload_to_cloudブーリアンfalsetrue, false録画完了後、自動的にクラウドへアップロード。

画面録画 ([recording])

プロパティ名データ型デフォルト値有効なオプション / 範囲説明
format文字列"mov""mov", "mp4"録画動画ファイルの形式。
quality文字列"high""high", "medium", "low"動画の圧縮品質。
fps整数301〜120キャプチャ時のターゲットフレームレート。
output_mode文字列"video""video", "gif"エクスポートするメディア形式。
capture_system_audioブーリアンtruetrue, falseシステム音声の録音設定。
capture_microphoneブーリアンfalsetrue, false外部マイク音声の録音設定。
microphone_device_id文字列""有効なオーディオデバイスID録音に使用するマイクの指定。
remember_last_areaブーリアンtruetrue, false前回の録画領域を記憶する。
show_cursorブーリアンtruetrue, falseビデオにマウスカーソルを表示。
highlight_clicksブーリアンfalsetrue, falseマウスクリック時のアニメーションリング表示。
show_keystrokesブーリアンfalsetrue, false入力されたキーのオーバーレイ表示。
mouse_highlight.size実数50.020.0〜120.0クリックハイライトの直径。
mouse_highlight.color文字列"#FF000080"HEXコード (#RRGGBBAA)ハイライト表示の色コード。
mouse_highlight.opacity実数0.50.0〜1.0ハイライト表示の不透明度。
mouse_highlight.ripple_count整数31〜6クリック波紋エフェクトの発生回数。
keystrokes.font_size実数18.010.0〜48.0キー入力表示のテキストフォントサイズ。
keystrokes.position文字列"bottomCenter"画面位置設定文字列キー入力の画面表示配置位置。
keystrokes.display_duration実数2.00.3〜10.0キー入力を画面に維持する時間。
annotation_shortcuts.modifier文字列"shift"修飾キー設定文字列録画中の注釈呼び出し用のホットキー。
annotation_shortcuts.hold_duration実数1.00.1〜5.0ホットキーを押し続ける必要がある時間。

クイックアクセスパネル ([quick_access])

プロパティ名データ型デフォルト値有効なオプション / 範囲説明
enabledブーリアンtruetrue, falseパネルの自動表示の切り替え。
position文字列"bottomRight"画面隅設定文字列パネルを配置する画面隅。
auto_dismissブーリアンtruetrue, false一定時間経過後にパネルを自動非表示にする。
auto_dismiss_delay実数10.03.0〜30.0自動非表示にするまでの待機秒数。
pause_countdown_on_hoverブーリアンtruetrue, falseパネルにマウスホバー中は自動クローズを一時停止。
overlay_scale実数1.00.75〜1.5パネル全体の表示縮尺比率。
drag_dropブーリアンtruetrue, falseドラッグ＆ドロップエクスポート操作の許可。
actions_order配列デフォルト値アクション識別子リストボタンの配列順序。
enabled_actions配列デフォルト値アクション識別子リスト使用可能なアクションボタンの一覧。

履歴ブラウザ ([history])

プロパティ名データ型デフォルト値有効なオプション / 範囲説明
enabledブーリアンtruetrue, falseアプリケーション内での履歴保存。
retention_days整数300〜90履歴項目の自動クリーンアップ期限。
max_count整数5000〜1000履歴ログの最大格納レコード数。
background_style文字列"hud""hud", "solid"履歴画面の背景描画スタイル。
open_on_launchブーリアンfalsetrue, falseアプリ起動時に履歴を自動で開く。
floating.enabledブーリアンtruetrue, false画面上への履歴フローティングHUDバーの表示。
floating.position文字列"topCenter"配置位置文字列フローティングバーの画面配置基準。
floating.max_displayed_items整数103〜20バー内の表示サムネイル最大個数。
floating.scale実数1.00.8〜1.2フローティング履歴バーの拡大倍率。

クラウドストレージ設定 ([cloud])

プロパティ名データ型デフォルト値有効なオプション / 範囲説明
provider文字列"aws_s3""aws_s3", "cloudflare_r2"クラウドストレージのプロバイダ選択。
bucket文字列""バケット名文字列リモートストレージのバケット名。
region文字列"us-east-1"S3 のリージョンAWS S3のリージョンコード (S3 のみ必要)。
endpoint文字列""HTTP エンドポイントURLAPIのエンドポイントURL (R2 のみ必要)。
custom_domain文字列""ドメインURL文字列共有URL生成時のカスタムドメイン設定。
expire_time文字列"7d""1d", "3d", "7d", "14d", "30d", "60d", "90d", "permanent"ダウンロード用署名リンクの有効期限。
uploads_window_position文字列"center""top", "center", "bottom"アップロード進行状況パネル HUD の画面位置。

セキュリティについて — AWS アクセスキーやシークレットトークンなどの機密度の高い資格情報は、GitHub などのリポジトリに誤って漏洩しないようにプレーンテキストの config.toml には保存されません。代わりに、macOS Keychain 内で安全に暗号化されて管理されます。

注釈エディタ設定 ([annotate])

プロパティ名データ型デフォルト値有効なオプション / 範囲説明
clipboard_image_open_behavior文字列"ask""ask", "loadAutomatically", "doNothing"注釈エディタ起動時、クリップボードに画像がある場合の動作設定。
close_after_dragブーリアンtruetrue, falseドラッグしてエクスポート後に注釈ウィンドウを自動クローズ。
bring_forward_after_dragブーリアンfalsetrue, falseドラッグ完了後、エクスポート先のアプリを前面にする。
quick_properties_syncブーリアンtruetrue, false各種ペンの色や太さプロパティの即時同期。

バリデーションと問題解決

Snapzy は config.toml の属性ロード時に厳格な検証を行います：

  • 値の上限/下限逸脱: 設定値が許可された範囲を逸脱した場合（例: fps = 150 や overlay_scale = 3.0 など）、Snapzy は警告（Warning）をログに出力し、該当プロパティを無視してデフォルト値を使用します。
  • データ型の不整合: 誤った型（例: Boolean 型の項目に文字列を渡すなど）を指定した場合、致命的なエラーが発生し、該当するセクションの設定は読み込まれず、それまでの設定が維持されます。
  • 検証結果の確認: config.toml の読み込みエラーや警告のリストは、「設定」アプリの「詳細 (Advanced)」タブ内の同期状態セクションで直接確認することができます。

最高の作品を
キャプチャする準備はできましたか？

macOS向け最高の画面キャプチャツールを作るオープンソースコミュニティに参加してください。

macOS版をダウンロードGitHubで見る

macOS 13+ · Intel & Apple Silicon