PlanOpticon

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

Keyboard Shortcuts

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