PlanOpticon

planopticon / docs / getting-started / configuration.md
Source Blame History 224 lines
f0106a3… leo 1 # Configuration
f0106a3… leo 2
3551b80… noreply 3 ## Example `.env` file
3551b80… noreply 4
3551b80… noreply 5 Create a `.env` file in your project directory. PlanOpticon loads it automatically.
3551b80… noreply 6
3551b80… noreply 7 ```bash
3551b80… noreply 8 # =============================================================================
3551b80… noreply 9 # PlanOpticon Configuration
3551b80… noreply 10 # =============================================================================
3551b80… noreply 11 # Copy this file to .env and fill in the values you need.
3551b80… noreply 12 # You only need ONE AI provider — PlanOpticon auto-detects which are available.
3551b80… noreply 13
3551b80… noreply 14 # --- AI Providers (set at least one) ----------------------------------------
3551b80… noreply 15
3551b80… noreply 16 # OpenAI — get your key at https://platform.openai.com/api-keys
3551b80… noreply 17 OPENAI_API_KEY=sk-...
3551b80… noreply 18
3551b80… noreply 19 # Anthropic — get your key at https://console.anthropic.com/settings/keys
3551b80… noreply 20 ANTHROPIC_API_KEY=sk-ant-...
3551b80… noreply 21
3551b80… noreply 22 # Google Gemini — get your key at https://aistudio.google.com/apikey
3551b80… noreply 23 GEMINI_API_KEY=AI...
3551b80… noreply 24
3551b80… noreply 25 # Azure OpenAI — from your Azure portal deployment
3551b80… noreply 26 # AZURE_OPENAI_API_KEY=...
3551b80… noreply 27 # AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
3551b80… noreply 28
3551b80… noreply 29 # Together AI — https://api.together.xyz/settings/api-keys
3551b80… noreply 30 # TOGETHER_API_KEY=...
3551b80… noreply 31
3551b80… noreply 32 # Fireworks AI — https://fireworks.ai/account/api-keys
3551b80… noreply 33 # FIREWORKS_API_KEY=...
3551b80… noreply 34
3551b80… noreply 35 # Cerebras — https://cloud.cerebras.ai/
3551b80… noreply 36 # CEREBRAS_API_KEY=...
3551b80… noreply 37
3551b80… noreply 38 # xAI (Grok) — https://console.x.ai/
3551b80… noreply 39 # XAI_API_KEY=...
3551b80… noreply 40
3551b80… noreply 41 # Ollama (local, no key needed) — just run: ollama serve
3551b80… noreply 42 # OLLAMA_HOST=http://localhost:11434
3551b80… noreply 43
3551b80… noreply 44 # --- Google (Drive, Docs, Sheets, Meet, YouTube) ----------------------------
3551b80… noreply 45 # Option A: OAuth (interactive, recommended for personal use)
3551b80… noreply 46 # Create credentials at https://console.cloud.google.com/apis/credentials
3551b80… noreply 47 # 1. Create an OAuth 2.0 Client ID (Desktop application)
3551b80… noreply 48 # 2. Enable these APIs: Google Drive API, Google Docs API
3551b80… noreply 49 GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
3551b80… noreply 50 GOOGLE_CLIENT_SECRET=GOCSPX-...
3551b80… noreply 51
3551b80… noreply 52 # Option B: Service Account (automated/server-side)
3551b80… noreply 53 # GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
3551b80… noreply 54
3551b80… noreply 55 # --- Zoom (recordings) ------------------------------------------------------
3551b80… noreply 56 # Create an OAuth app at https://marketplace.zoom.us/develop/create
3551b80… noreply 57 # App type: "General App" with OAuth
3551b80… noreply 58 # Scopes: cloud_recording:read:list_user_recordings, cloud_recording:read:recording
3551b80… noreply 59 ZOOM_CLIENT_ID=...
3551b80… noreply 60 ZOOM_CLIENT_SECRET=...
3551b80… noreply 61 # For Server-to-Server (no browser needed):
3551b80… noreply 62 # ZOOM_ACCOUNT_ID=...
3551b80… noreply 63
3551b80… noreply 64 # --- Microsoft 365 (OneDrive, SharePoint, Teams) ----------------------------
3551b80… noreply 65 # Register an app at https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps
3551b80… noreply 66 # API permissions: OnlineMeetings.Read, Files.Read (delegated)
3551b80… noreply 67 MICROSOFT_CLIENT_ID=...
3551b80… noreply 68 MICROSOFT_CLIENT_SECRET=...
3551b80… noreply 69
3551b80… noreply 70 # --- Notion ------------------------------------------------------------------
3551b80… noreply 71 # Option A: OAuth (create integration at https://www.notion.so/my-integrations)
3551b80… noreply 72 # NOTION_CLIENT_ID=...
3551b80… noreply 73 # NOTION_CLIENT_SECRET=...
3551b80… noreply 74
3551b80… noreply 75 # Option B: API key (simpler, from the same integrations page)
3551b80… noreply 76 NOTION_API_KEY=secret_...
3551b80… noreply 77
3551b80… noreply 78 # --- GitHub ------------------------------------------------------------------
3551b80… noreply 79 # Option A: Personal Access Token (simplest)
3551b80… noreply 80 # Create at https://github.com/settings/tokens — needs 'repo' scope
3551b80… noreply 81 GITHUB_TOKEN=ghp_...
3551b80… noreply 82
3551b80… noreply 83 # Option B: OAuth App (for CI/automation)
3551b80… noreply 84 # GITHUB_CLIENT_ID=...
3551b80… noreply 85 # GITHUB_CLIENT_SECRET=...
3551b80… noreply 86
3551b80… noreply 87 # --- Dropbox -----------------------------------------------------------------
3551b80… noreply 88 # Create an app at https://www.dropbox.com/developers/apps
3551b80… noreply 89 # DROPBOX_APP_KEY=...
3551b80… noreply 90 # DROPBOX_APP_SECRET=...
3551b80… noreply 91 # Or use a long-lived access token:
3551b80… noreply 92 # DROPBOX_ACCESS_TOKEN=...
3551b80… noreply 93
3551b80… noreply 94 # --- General -----------------------------------------------------------------
3551b80… noreply 95 # CACHE_DIR=~/.cache/planopticon
3551b80… noreply 96 ```
3551b80… noreply 97
3551b80… noreply 98 ## Environment variables reference
0981a08… noreply 99
0981a08… noreply 100 ### AI providers
0981a08… noreply 101
3551b80… noreply 102 | Variable | Required | Where to get it |
3551b80… noreply 103 |----------|----------|----------------|
3551b80… noreply 104 | `OPENAI_API_KEY` | At least one provider | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
3551b80… noreply 105 | `ANTHROPIC_API_KEY` | At least one provider | [console.anthropic.com](https://console.anthropic.com/settings/keys) |
3551b80… noreply 106 | `GEMINI_API_KEY` | At least one provider | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) |
3551b80… noreply 107 | `AZURE_OPENAI_API_KEY` | Optional | Azure portal > your OpenAI resource |
3551b80… noreply 108 | `AZURE_OPENAI_ENDPOINT` | With Azure | Azure portal > your OpenAI resource |
3551b80… noreply 109 | `TOGETHER_API_KEY` | Optional | [api.together.xyz](https://api.together.xyz/settings/api-keys) |
3551b80… noreply 110 | `FIREWORKS_API_KEY` | Optional | [fireworks.ai](https://fireworks.ai/account/api-keys) |
3551b80… noreply 111 | `CEREBRAS_API_KEY` | Optional | [cloud.cerebras.ai](https://cloud.cerebras.ai/) |
3551b80… noreply 112 | `XAI_API_KEY` | Optional | [console.x.ai](https://console.x.ai/) |
3551b80… noreply 113 | `OLLAMA_HOST` | Optional | Default: `http://localhost:11434` |
0981a08… noreply 114
0981a08… noreply 115 ### Cloud services
0981a08… noreply 116
3551b80… noreply 117 | Variable | Service | Auth method |
3551b80… noreply 118 |----------|---------|-------------|
3551b80… noreply 119 | `GOOGLE_CLIENT_ID` | Google (Drive, Docs, Meet) | OAuth |
3551b80… noreply 120 | `GOOGLE_CLIENT_SECRET` | Google | OAuth |
3551b80… noreply 121 | `GOOGLE_APPLICATION_CREDENTIALS` | Google | Service account |
3551b80… noreply 122 | `ZOOM_CLIENT_ID` | Zoom | OAuth |
3551b80… noreply 123 | `ZOOM_CLIENT_SECRET` | Zoom | OAuth |
3551b80… noreply 124 | `ZOOM_ACCOUNT_ID` | Zoom | Server-to-Server |
3551b80… noreply 125 | `MICROSOFT_CLIENT_ID` | Microsoft 365 | OAuth |
3551b80… noreply 126 | `MICROSOFT_CLIENT_SECRET` | Microsoft 365 | OAuth |
3551b80… noreply 127 | `NOTION_CLIENT_ID` | Notion | OAuth |
3551b80… noreply 128 | `NOTION_CLIENT_SECRET` | Notion | OAuth |
3551b80… noreply 129 | `NOTION_API_KEY` | Notion | API key |
3551b80… noreply 130 | `GITHUB_CLIENT_ID` | GitHub | OAuth |
3551b80… noreply 131 | `GITHUB_CLIENT_SECRET` | GitHub | OAuth |
3551b80… noreply 132 | `GITHUB_TOKEN` | GitHub | API key |
3551b80… noreply 133 | `DROPBOX_APP_KEY` | Dropbox | OAuth |
3551b80… noreply 134 | `DROPBOX_APP_SECRET` | Dropbox | OAuth |
3551b80… noreply 135 | `DROPBOX_ACCESS_TOKEN` | Dropbox | API key |
0981a08… noreply 136
0981a08… noreply 137 ### General
f0106a3… leo 138
f0106a3… leo 139 | Variable | Description |
f0106a3… leo 140 |----------|-------------|
f0106a3… leo 141 | `CACHE_DIR` | Directory for API response caching |
0981a08… noreply 142
0981a08… noreply 143 ## Authentication
0981a08… noreply 144
3551b80… noreply 145 PlanOpticon uses OAuth for cloud services. Run `planopticon auth` once per service — tokens are saved locally and refreshed automatically.
0981a08… noreply 146
0981a08… noreply 147 ```bash
0981a08… noreply 148 planopticon auth google # Google Drive, Docs, Meet, YouTube
0981a08… noreply 149 planopticon auth dropbox # Dropbox
0981a08… noreply 150 planopticon auth zoom # Zoom recordings
0981a08… noreply 151 planopticon auth notion # Notion pages
0981a08… noreply 152 planopticon auth github # GitHub repos and wikis
0981a08… noreply 153 planopticon auth microsoft # OneDrive, SharePoint, Teams
0981a08… noreply 154 ```
0981a08… noreply 155
3551b80… noreply 156 Credentials are stored in `~/.planopticon/`. Use `planopticon auth SERVICE --logout` to remove them.
3551b80… noreply 157
3551b80… noreply 158 ### What each service needs
3551b80… noreply 159
3551b80… noreply 160 | Service | Minimum setup | Full OAuth setup |
3551b80… noreply 161 |---------|--------------|-----------------|
3551b80… noreply 162 | Google | `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` | Create OAuth credentials in [Google Cloud Console](https://console.cloud.google.com/apis/credentials) |
3551b80… noreply 163 | Zoom | `ZOOM_CLIENT_ID` + `ZOOM_CLIENT_SECRET` | Create a General App at [marketplace.zoom.us](https://marketplace.zoom.us/develop/create) |
3551b80… noreply 164 | Microsoft | `MICROSOFT_CLIENT_ID` + `MICROSOFT_CLIENT_SECRET` | Register app in [Azure AD](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps) |
3551b80… noreply 165 | Notion | `NOTION_API_KEY` (simplest) | Create integration at [notion.so/my-integrations](https://www.notion.so/my-integrations) |
3551b80… noreply 166 | GitHub | `GITHUB_TOKEN` (simplest) | Create token at [github.com/settings/tokens](https://github.com/settings/tokens) |
3551b80… noreply 167 | Dropbox | `DROPBOX_APP_KEY` + `DROPBOX_APP_SECRET` | Create app at [dropbox.com/developers](https://www.dropbox.com/developers/apps) |
0981a08… noreply 168
3551b80… noreply 169 For detailed OAuth app creation walkthroughs, see the [Authentication guide](../guide/authentication.md).
f0106a3… leo 170
f0106a3… leo 171 ## Provider routing
f0106a3… leo 172
0981a08… noreply 173 PlanOpticon auto-discovers available models and routes each task to the cheapest capable option:
f0106a3… leo 174
f0106a3… leo 175 | Task | Default preference |
f0106a3… leo 176 |------|--------------------|
0981a08… noreply 177 | Vision (diagrams) | Gemini Flash > GPT-4o-mini > Claude Haiku > Ollama |
0981a08… noreply 178 | Chat (analysis) | Claude Haiku > GPT-4o-mini > Gemini Flash > Ollama |
a0146a5… noreply 179 | Transcription | Local Whisper > Whisper-1 > Gemini Flash |
0981a08… noreply 180
0981a08… noreply 181 Default models prioritize cost efficiency. For complex or high-stakes analysis, override with more capable models using `--chat-model` or `--vision-model`.
a0146a5… noreply 182
a0146a5… noreply 183 If no cloud API keys are configured, PlanOpticon automatically falls back to Ollama when a local server is running. This enables fully offline operation when paired with local Whisper for transcription.
f0106a3… leo 184
f0106a3… leo 185 Override with `--provider`, `--vision-model`, or `--chat-model` flags.
f0106a3… leo 186
f0106a3… leo 187 ## Frame sampling
f0106a3… leo 188
f0106a3… leo 189 Control how frames are extracted:
f0106a3… leo 190
f0106a3… leo 191 ```bash
f0106a3… leo 192 # Sample rate: frames per second (default: 0.5)
f0106a3… leo 193 planopticon analyze -i video.mp4 -o ./out --sampling-rate 1.0
f0106a3… leo 194
f0106a3… leo 195 # Change threshold: visual difference needed to keep a frame (default: 0.15)
f0106a3… leo 196 planopticon analyze -i video.mp4 -o ./out --change-threshold 0.1
ecf907c… leo 197
ecf907c… leo 198 # Periodic capture: capture a frame every N seconds regardless of change (default: 30)
ecf907c… leo 199 # Useful for slow-evolving content like document scrolling
ecf907c… leo 200 planopticon analyze -i video.mp4 -o ./out --periodic-capture 15
ecf907c… leo 201
ecf907c… leo 202 # Disable periodic capture (rely only on change detection)
ecf907c… leo 203 planopticon analyze -i video.mp4 -o ./out --periodic-capture 0
f0106a3… leo 204 ```
f0106a3… leo 205
ecf907c… leo 206 Lower `change-threshold` = more frames kept. Higher `sampling-rate` = more candidates. Periodic capture catches content that changes too slowly for change detection (e.g., scrolling through a document during a screen share).
ecf907c… leo 207
ecf907c… leo 208 People/webcam frames are automatically filtered out using face detection — no configuration needed.
f0106a3… leo 209
f0106a3… leo 210 ## Focus areas
f0106a3… leo 211
f0106a3… leo 212 Limit processing to specific extraction types:
f0106a3… leo 213
f0106a3… leo 214 ```bash
f0106a3… leo 215 planopticon analyze -i video.mp4 -o ./out --focus "diagrams,action-items"
f0106a3… leo 216 ```
f0106a3… leo 217
f0106a3… leo 218 ## GPU acceleration
f0106a3… leo 219
f0106a3… leo 220 ```bash
f0106a3… leo 221 planopticon analyze -i video.mp4 -o ./out --use-gpu
f0106a3… leo 222 ```
f0106a3… leo 223
f0106a3… leo 224 Requires `planopticon[gpu]` extras installed.

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button