Storage Sources

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

Note

You must have at least one activated agent before adding a storage source.

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. Grail normalizes leading and trailing slashes when saving the source.
   • Username and Password — SMB credentials for the share (see SMB permissions below)

   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 for the configured share or base path, with scheduled polling as a backup. If real-time watching is unavailable, polling continues on schedule. 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

   • On-Demand (NAS) (default, recommended) — Generate and cache proxies on the NAS with automatic eviction. Requires a proxy path pattern to define where proxies are stored (default: grail-proxies). The SMB credentials must have write access to this folder.
   • On-Demand (Agent) — Generate and cache proxies locally on the agent
   • Pregenerate — Generate preview proxies for all assets on discovery

   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.

If the agent cannot reach the configured share or base path, the scan will fail and the storage source card will show the latest mount error. Fix the path, credentials, or network access, then start another scan.

Storage Source Health

Storage source cards show separate health for the share mount and change detection:

• Mount — Whether the agent can reach the configured SMB share and base path.
• Detection — Whether real-time watching is active, or whether the source is using scheduled polling or polling fallback.

An Active source has a reachable mount and healthy detection. A Degraded source can still be partially usable, such as a reachable share with watcher issues. An Offline source cannot currently be reached by the assigned agent.

SMB Permissions

We recommend giving Grail read-only access to your media shares and read/write access to the proxy folder.

When using the On-Demand (NAS) proxy mode (recommended), the agent writes generated proxies to a folder on the NAS (default: grail-proxies). This is the only folder that requires read/write access. All other operations — scanning, indexing, thumbnail generation, and streaming — only need read access.

Tip

On most NAS devices, you can create the proxy folder (e.g. grail-proxies) as a separate shared folder with write permissions, and keep your media shares read-only. This limits the agent’s ability to modify your source media.

Exclude Patterns

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

Pattern	Excludes
^\.	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.

Tip

Common NAS system folders (like @eaDir, #recycle, .SynologyWorkingDirectory) are automatically excluded — you don’t need to add patterns for these.

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.

Caution

Changing the agent requires the new agent to have network access to the same SMB share.

Tiered Storage (Archive / Cold Storage)

Grail supports tiered storage environments like Quantum StorNext where files may be archived to tape or other cold storage. When enabled, Grail detects offline files during scanning and handles them appropriately.

Enabling Tiered Storage

Toggle Tiered storage on the storage source form. When enabled:

• Cold files are skipped — The agent detects archived/offline files and skips them during scanning. No thumbnails, proxies, or transcriptions are generated, and no tape recalls are triggered.
• Hot files are processed normally — Files on fast storage (SSD/disk) are indexed and processed as usual.
• Cold-to-hot transitions are detected — When a file is recalled from tape, the next scan detects the change and creates jobs for it automatically.

How Archived Assets Appear

Assets that exist only on cold storage are marked with an archive indicator:

• Asset browser — An archive icon is shown in place of the thumbnail
• Asset detail page — An “Archived Asset” banner is displayed with a Restore from Archive button
• Transcription — Disabled for cold-only assets

If an asset has copies on both cold and hot storage, Grail uses the hot copy for streaming and job creation.

Restoring Archived Assets

Click Restore from Archive on the asset detail page to request a restore. This creates a proxy generation job that will process the file once it becomes available on hot storage.

Tip

Tiered storage detection works with Quantum StorNext on macOS. The agent reads the SF_ARCHIVED file flag to identify tape-archived files without triggering a recall.