AI Search Setup

Enable CLIP-powered semantic search to find content by natural language description across your entire library.

What Is AI Search?

StreamStash uses OpenCLIP (ViT-B/32) — a vision-language AI model — to understand what's in your downloaded images and videos. Instead of searching by filename or username, you can search by what you see:

• "wearing a red dress"
• "at the beach"
• "dancing in a kitchen"
• "sunset cityscape"
• "group photo with friends"

The model extracts visual embeddings from keyframes and matches them against your text query using cosine similarity.

Requirements

AI search requires the Power tier. All dependencies (OpenCLIP, PyTorch, NumPy) are installed automatically on first launch — no manual setup needed.

How It Works

Indexing

Once the dependencies are installed, StreamStash automatically begins indexing your library in the background:

• Videos — keyframes are extracted every 10 seconds, up to 20 per video. Each frame is resized to 224x224 and embedded.
• Images — resized to 224x224 and embedded directly.
• The auto-indexer runs every 2 minutes, processing up to 50 new items per batch.
• After each batch, the model is unloaded from memory to free RAM.

Searching

When you search, your text query is converted into a CLIP embedding and compared against all stored frame embeddings using a cosine dot-product. The best-matching frame per media item is returned, sorted by confidence score.

Getting Started

AI search is included in the Power tier. No manual installation is needed — StreamStash handles all dependencies automatically on first launch.

1. Open StreamStash. The AI search dependencies are installed automatically. The auto-indexer will start processing your existing library in the background.
2. Navigate to Search in the sidebar. You'll see indexing progress and can start searching immediately — results will improve as more content is indexed.

Triggering a Full Reindex

If you want to reindex all existing content (useful after the initial setup), click the Reindex button on the Search page, or call the API:

POST /api/search/reindex

Search Features

• Per-platform filtering — limit results to TikTok, Instagram, Twitter, etc.
• Confidence scoring — each result shows a match score
• Matched keyframe preview — see exactly which frame matched your query
• Search history — recent queries are saved for quick access
• Results are capped at 200 items per search

Index Storage

The search index is stored in a separate SQLite database at:

<RECORDINGS_DIR>/clip_index.db

This does not affect the main app database. You can safely delete this file to reset the index — it will be rebuilt automatically.

Supported Platforms

AI search indexes content from all platforms:

• TikTok
• Instagram
• Twitter/X
• Telegram
• Reddit
• Snapchat
• Forums

Troubleshooting

Search page shows "CLIP not available"

The automatic dependency installation may have failed. Check Settings → System Status to retry, or check the logs for the exact error.

Indexing is slow

Indexing speed depends on your hardware. A GPU-enabled PyTorch installation is significantly faster. The model processes in batches and unloads between batches to avoid memory issues.

Results don't seem accurate

CLIP works best with descriptive phrases rather than single words. Try "person standing on a beach" instead of just "beach". The model understands visual concepts, not metadata.

API Reference