PlanOpticon produces a wide range of output formats from video analysis, document ingestion, batch processing, knowledge graph export, and agent skills. This page is the comprehensive reference for every format the tool can emit.
4
5
---
6
7
## Transcripts
8
9
Video analysis always produces transcripts in three formats, stored in the `transcript/` subdirectory of the output folder.
10
11
| Format | File | Description |
12
|--------|------|-------------|
13
| JSON | `transcript/transcript.json` | Full transcript with segments, timestamps, speaker labels, and confidence scores. Each segment includes `start`, `end`, `text`, and optional `speaker` fields. |
14
| Text | `transcript/transcript.txt` | Plain text transcript with no metadata. Suitable for feeding into other tools or reading directly. |
15
| SRT | `transcript/transcript.srt` | SubRip subtitle format with sequential numbering and `HH:MM:SS,mmm` timestamps. Can be loaded into video players or subtitle editors. |
16
17
### Transcript JSON structure
18
19
```json
20
{
21
"segments": [
22
{
23
"start": 0.0,
24
"end": 4.5,
25
"text": "Welcome to the sprint review.",
26
"speaker": "Alice"
27
}
28
],
29
"text": "Welcome to the sprint review. ...",
30
"language": "en"
31
}
32
```
33
34
When the `--speakers` flag is provided (e.g., `--speakers "Alice,Bob,Carol"`), speaker diarization hints are passed to the transcription provider and speaker labels appear in the JSON segments.
35
36
---
37
38
## Reports
39
40
Analysis reports are generated from the combined transcript, diagrams, key points, action items, and knowledge graph. They live in the `results/` subdirectory.
41
42
| Format | File | Description |
43
|--------|------|-------------|
44
| Markdown | `results/analysis.md` | Structured report with embedded Mermaid diagram blocks, tables, and cross-references. Works in any Markdown renderer. |
45
| HTML | `results/analysis.html` | Self-contained HTML page with inline CSS, embedded SVG diagrams, and a bundled mermaid.js script for rendering any unrendered Mermaid blocks. No external dependencies required to view. |
46
| PDF | `results/analysis.pdf` | Print-ready PDF. Requires the `planopticon[pdf]` extra (`pip install planopticon[pdf]`). Generated from the HTML report. |
47
48
---
49
50
## Diagrams
51
52
Each visual element detected during frame analysis produces up to five output files in the `diagrams/` subdirectory. The index `N` is zero-based.
53
54
| Format | File | Description |
55
|--------|------|-------------|
56
| JPEG | `diagrams/diagram_N.jpg` | Original video frame captured at the point of detection. |
57
| Mermaid | `diagrams/diagram_N.mermaid` | Mermaid source code reconstructed from the diagram by the vision model. Supports flowcharts, sequence diagrams, architecture diagrams, and more. |
58
| SVG | `diagrams/diagram_N.svg` | Vector rendering of the Mermaid source, produced by the Mermaid CLI or built-in renderer. |
59
| PNG | `diagrams/diagram_N.png` | Raster rendering of the Mermaid source at high resolution. |
60
| JSON | `diagrams/diagram_N.json` | Structured analysis data including diagram type, description, extracted text, chart data (if applicable), and confidence score. |
61
62
Frames that score as medium confidence are saved as captioned screenshots in the `captures/` subdirectory instead, with a `capture_N.jpg` and `capture_N.json` pair.
63
64
---
65
66
## Structured Data
67
68
Core analysis artifacts are stored as JSON files in the `results/` subdirectory.
69
70
| Format | File | Description |
71
|--------|------|-------------|
72
| SQLite | `results/knowledge_graph.db` | Primary knowledge graph database. SQLite-based, queryable with `planopticon query`. Contains entities, relationships, source provenance, and metadata. This is the preferred format for querying and merging. |
73
| JSON | `results/knowledge_graph.json` | JSON export of the knowledge graph. Contains `entities` and `relationships` arrays. Automatically kept in sync with the `.db` file. Used as a fallback when SQLite is not available. |
74
| JSON | `results/key_points.json` | Array of extracted key points, each with `text`, `category`, and `confidence` fields. |
75
| JSON | `results/action_items.json` | Array of action items, each with `text`, `assignee`, `due_date`, `priority`, and `status` fields. |
76
| JSON | `manifest.json` | Complete run manifest. The single source of truth for the analysis run. Contains video metadata, processing stats, file paths to all outputs, and inline key points, action items, diagram metadata, and screen captures. |
77
78
### Knowledge graph JSON structure
79
80
```json
81
{
82
"entities": [
83
{
84
"name": "Kubernetes",
85
"type": "technology",
86
"descriptions": ["Container orchestration platform discussed in architecture review"],
"descriptions": ["Kubernetes uses Docker as container runtime"]
98
}
99
]
100
}
101
```
102
103
---
104
105
## Charts
106
107
When chart data is extracted from diagrams (bar charts, line charts, pie charts, scatter plots), PlanOpticon reproduces them as standalone image files.
108
109
| Format | File | Description |
110
|--------|------|-------------|
111
| SVG | `diagrams/chart_N.svg` | Vector chart rendered via matplotlib. Suitable for embedding in documents or scaling to any size. |
112
| PNG | `diagrams/chart_N.png` | Raster chart rendered via matplotlib at 150 DPI. |
113
114
Reproduced charts are also embedded inline in the HTML and PDF reports.
115
116
---
117
118
## Knowledge Graph Exports
119
120
Beyond the default `knowledge_graph.db` and `knowledge_graph.json` produced during analysis, PlanOpticon supports exporting knowledge graphs to several additional formats via the `planopticon export` and `planopticon kg convert` commands.
121
122
| Format | Command / File | Description |
123
|--------|---------------|-------------|
124
| JSON | `knowledge_graph.json` | Default JSON export. Produced automatically alongside the `.db` file. |
125
| SQLite | `knowledge_graph.db` | Primary database format. Can be converted to/from JSON with `planopticon kg convert`. |
126
| GraphML | `output.graphml` | XML-based graph format via `planopticon kg convert kg.db output.graphml`. Compatible with Gephi, yEd, Cytoscape, and other graph visualization tools. |
127
| CSV | `export/entities.csv`, `export/relationships.csv` | Tabular export via `planopticon export markdown kg.db --type csv`. Produces separate CSV files for entities and relationships. |
128
| Mermaid | Inline in reports | Mermaid graph diagrams are embedded in Markdown and HTML reports. Also available programmatically via `GraphQueryEngine.to_mermaid()`. |
129
130
### Converting between formats
131
132
```bash
133
# SQLite to JSON
134
planopticon kg convert results/knowledge_graph.db output.json
135
136
# JSON to SQLite
137
planopticon kg convert knowledge_graph.json knowledge_graph.db
138
139
# Sync both directions (updates the stale file)
140
planopticon kg sync results/knowledge_graph.db
141
planopticon kg sync knowledge_graph.db knowledge_graph.json --direction db-to-json
142
```
143
144
---
145
146
## PlanOpticonExchange Format
147
148
The PlanOpticonExchange format (`.json`) is a canonical interchange payload designed for sharing knowledge graphs between PlanOpticon instances, teams, or external systems.
149
150
```bash
151
planopticon export exchange knowledge_graph.db
152
planopticon export exchange kg.db -o exchange.json --name "My Project"
153
```
154
155
The exchange payload includes:
156
157
- **Schema version** for forward compatibility
158
- **Project metadata** (name, description)
159
- **Full entity and relationship data** with provenance
160
- **Source tracking** for multi-source graphs
161
- **Merge support** -- exchange files can be merged together, deduplicating entities by name
162
163
### Exchange JSON structure
164
165
```json
166
{
167
"schema_version": "1.0",
168
"project": {
169
"name": "Sprint Reviews Q4",
170
"description": "Knowledge extracted from Q4 sprint review recordings"
171
},
172
"entities": [...],
173
"relationships": [...],
174
"sources": [...]
175
}
176
```
177
178
---
179
180
## Document Exports
181
182
PlanOpticon can generate structured Markdown documents from any knowledge graph, with no API key required. These are pure template-based outputs derived from the graph data.
183
184
### Markdown document types
185
186
There are seven document types plus a CSV export, all generated via `planopticon export markdown`:
187
188
| Type | File | Description |
189
|------|------|-------------|
190
| `summary` | `executive_summary.md` | High-level executive summary with entity counts, top relationships, and key themes. |
191
| `meeting-notes` | `meeting_notes.md` | Structured meeting notes with attendees, topics discussed, decisions made, and action items. |
192
| `glossary` | `glossary.md` | Alphabetical glossary of all entities with descriptions and types. |
193
| `relationship-map` | `relationship_map.md` | Textual and Mermaid-based relationship map showing how entities connect. |
194
| `status-report` | `status_report.md` | Status report format with progress indicators, risks, and next steps. |
195
| `entity-index` | `entity_index.md` | Comprehensive index of all entities grouped by type, with links to individual briefs. |
196
| `entity-brief` | `entities/<Name>.md` | One-pager brief for each entity, showing descriptions, relationships, and source references. |
197
| `csv` | `entities.csv` | Tabular CSV export of entities and relationships. |
Generates a complete GitHub wiki with a sidebar, home page, and per-entity pages. Can be pushed directly to a GitHub wiki repository.
236
237
```bash
238
# Generate wiki pages
239
planopticon wiki generate knowledge_graph.db -o ./wiki
240
241
# Push to GitHub
242
planopticon wiki push ./wiki ConflictHQ/PlanOpticon -m "Update wiki from KG"
243
```
244
245
---
246
247
## Batch Outputs
248
249
Batch processing produces additional files at the batch root directory, alongside per-video output folders.
250
251
| Format | File | Description |
252
|--------|------|-------------|
253
| JSON | `batch_manifest.json` | Batch-level manifest with aggregate stats, per-video status (completed/failed), error details, and paths to all sub-outputs. |
254
| Markdown | `batch_summary.md` | Aggregated summary report with combined key points, action items, entity counts, and a Mermaid diagram of the merged knowledge graph. |
255
| SQLite | `knowledge_graph.db` | Merged knowledge graph combining entities and relationships across all successfully processed videos. Uses fuzzy matching and conflict resolution. |
256
| JSON | `knowledge_graph.json` | JSON export of the merged knowledge graph. |
257
258
---
259
260
## Self-Contained HTML Viewer
261
262
PlanOpticon ships with a self-contained interactive knowledge graph viewer at `knowledge-base/viewer.html` in the repository. This file:
263
264
- Uses D3.js (bundled inline, no CDN dependency)
265
- Renders an interactive force-directed graph visualization
266
- Supports node filtering by entity type
267
- Shows entity details and relationships on click
268
- Can load any `knowledge_graph.json` file
269
- Works offline with no server required -- just open in a browser
270
- Covers approximately 80% of graph exploration needs with zero infrastructure
271
272
---
273
274
## Output Directory Structure
275
276
A complete single-video analysis produces the following directory tree:
277
278
```
279
output/
280
├── manifest.json # Run manifest (source of truth)
281
├── transcript/
282
│ ├── transcript.json # Full transcript with segments
Use the `--output-format` flag with `planopticon analyze` to control how results are presented:
317
318
| Value | Behavior |
319
|-------|----------|
320
| `default` | Writes all output files to disk and prints a usage summary to stdout. |
321
| `json` | Writes all output files to disk and also emits the complete `VideoManifest` as structured JSON to stdout. Useful for piping into other tools or CI/CD pipelines. |