Skip to content
Grail Docs

Storage Sources

Storage sources connect Grail to your SMB file shares so the agent can discover and index media assets.

Adding a Storage Source

  1. Open storage sources

    In the Grail web app, navigate to Storage Sources and click Add Storage Source.

  2. Select an agent

    Choose which agent will scan this share. The agent must have network access to the SMB server.

  3. Name the source

    Give it a descriptive name like “Main NAS” or “Archive SAN”.

  4. Configure the SMB connection

    • SMB Host — The hostname or IP address of your file server (e.g., nas.church.local or 192.168.1.100)
    • SMB Share — The share name (e.g., media)
    • Base Path (optional) — A subfolder within the share to index (e.g., /Videos/2024). Leave empty to index the entire share.
    • Username and Password — Credentials with read access to the share

    The full path is previewed below the fields (e.g., smb://nas.church.local/media/Videos/2024).

  5. Choose a change detection mode

    • Watch + Poll (recommended) — Real-time SMB change notifications with scheduled polling as a backup. Works with most NAS devices (Synology, QNAP).
    • Poll Only — Scheduled polling without real-time notifications. Use this if your NAS doesn’t support SMB change notifications.

  6. Set a scan schedule

    Choose how often the agent performs a full scan of the share. Presets include every 6 hours, daily, or weekly. You can also enter a custom cron expression or disable scheduled scans entirely.

    The default is daily at 2 AM.

  7. Configure proxy generation and thumbnails

    • Pregenerate — Generate preview proxies for all assets on discovery
    • On-Demand (NAS) (default) — Generate and cache proxies on the NAS with automatic eviction. Requires a proxy path pattern to define where proxies are stored on the NAS.
    • On-Demand (Agent) — Generate and cache proxies locally on the agent

    For on-demand modes, set the max cache size (default 100 GB).

    Pre-generate thumbnails is enabled by default. The agent generates thumbnail images for all discovered assets, providing visual previews in the asset browser. Disable this if you want to minimize agent processing.

  8. Auto-transcribe (optional)

    Enable Auto-transcribe to automatically queue transcription for video and audio files after they are discovered and hashed. This uses Whisper AI to generate searchable transcripts without manual intervention.

    If enabled, you can add exclude patterns (regex) to skip specific files from auto-transcription. For example, use \.mp3$ to skip MP3 files or ^Music/ to skip a folder. Quick-add buttons are provided for common patterns.

  9. Save

    Click Create Storage Source. The source will appear in the grid but won’t start scanning until you trigger it.

Starting a Scan

After creating a storage source, click Start Scan on the storage source card to begin indexing. The agent will discover files, generate thumbnails, and create preview proxies based on your configuration.

Subsequent scans run automatically based on your scan schedule.

Exclude Patterns

You can add regex patterns to exclude files from indexing. Common patterns include:

PatternExcludes
^\.Hidden files (dotfiles)
\.tmp$Temporary files
\.DS_Store$macOS metadata
Thumbs\.db$Windows thumbnails
\._macOS resource forks

Add patterns in the Exclude Patterns section of the form using the quick-add buttons or by entering custom regex.

Editing a Storage Source

Click a storage source card and select Edit to modify its configuration. When editing, credentials are preserved unless you check Update credentials and enter new ones.

When you toggle Pre-generate thumbnails or Auto-transcribe on an existing storage source, a confirmation dialog will ask how to handle existing assets:

  • Enabling — Choose to process all existing assets (backfill) or only apply to newly discovered assets going forward.
  • Disabling — Choose to cancel any pending jobs for that feature or let them finish.