PlanOpticon

planopticon / docs / guide / output-formats.md
Source Blame History 329 lines
f0106a3… leo 1 # Output Formats
f0106a3… leo 2
3551b80… noreply 3 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.
3551b80… noreply 4
3551b80… noreply 5 ---
f0106a3… leo 6
f0106a3… leo 7 ## Transcripts
f0106a3… leo 8
3551b80… noreply 9 Video analysis always produces transcripts in three formats, stored in the `transcript/` subdirectory of the output folder.
3551b80… noreply 10
f0106a3… leo 11 | Format | File | Description |
f0106a3… leo 12 |--------|------|-------------|
3551b80… noreply 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. |
3551b80… noreply 14 | Text | `transcript/transcript.txt` | Plain text transcript with no metadata. Suitable for feeding into other tools or reading directly. |
3551b80… noreply 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. |
3551b80… noreply 16
3551b80… noreply 17 ### Transcript JSON structure
3551b80… noreply 18
3551b80… noreply 19 ```json
3551b80… noreply 20 {
3551b80… noreply 21 "segments": [
3551b80… noreply 22 {
3551b80… noreply 23 "start": 0.0,
3551b80… noreply 24 "end": 4.5,
3551b80… noreply 25 "text": "Welcome to the sprint review.",
3551b80… noreply 26 "speaker": "Alice"
3551b80… noreply 27 }
3551b80… noreply 28 ],
3551b80… noreply 29 "text": "Welcome to the sprint review. ...",
3551b80… noreply 30 "language": "en"
3551b80… noreply 31 }
3551b80… noreply 32 ```
3551b80… noreply 33
3551b80… noreply 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.
3551b80… noreply 35
3551b80… noreply 36 ---
f0106a3… leo 37
f0106a3… leo 38 ## Reports
f0106a3… leo 39
3551b80… noreply 40 Analysis reports are generated from the combined transcript, diagrams, key points, action items, and knowledge graph. They live in the `results/` subdirectory.
3551b80… noreply 41
f0106a3… leo 42 | Format | File | Description |
f0106a3… leo 43 |--------|------|-------------|
3551b80… noreply 44 | Markdown | `results/analysis.md` | Structured report with embedded Mermaid diagram blocks, tables, and cross-references. Works in any Markdown renderer. |
3551b80… noreply 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. |
3551b80… noreply 46 | PDF | `results/analysis.pdf` | Print-ready PDF. Requires the `planopticon[pdf]` extra (`pip install planopticon[pdf]`). Generated from the HTML report. |
3551b80… noreply 47
3551b80… noreply 48 ---
f0106a3… leo 49
f0106a3… leo 50 ## Diagrams
f0106a3… leo 51
3551b80… noreply 52 Each visual element detected during frame analysis produces up to five output files in the `diagrams/` subdirectory. The index `N` is zero-based.
f0106a3… leo 53
f0106a3… leo 54 | Format | File | Description |
f0106a3… leo 55 |--------|------|-------------|
3551b80… noreply 56 | JPEG | `diagrams/diagram_N.jpg` | Original video frame captured at the point of detection. |
3551b80… noreply 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. |
3551b80… noreply 58 | SVG | `diagrams/diagram_N.svg` | Vector rendering of the Mermaid source, produced by the Mermaid CLI or built-in renderer. |
3551b80… noreply 59 | PNG | `diagrams/diagram_N.png` | Raster rendering of the Mermaid source at high resolution. |
3551b80… noreply 60 | JSON | `diagrams/diagram_N.json` | Structured analysis data including diagram type, description, extracted text, chart data (if applicable), and confidence score. |
3551b80… noreply 61
3551b80… noreply 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.
3551b80… noreply 63
3551b80… noreply 64 ---
3551b80… noreply 65
3551b80… noreply 66 ## Structured Data
f0106a3… leo 67
3551b80… noreply 68 Core analysis artifacts are stored as JSON files in the `results/` subdirectory.
f0106a3… leo 69
f0106a3… leo 70 | Format | File | Description |
f0106a3… leo 71 |--------|------|-------------|
3551b80… noreply 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. |
3551b80… noreply 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. |
3551b80… noreply 74 | JSON | `results/key_points.json` | Array of extracted key points, each with `text`, `category`, and `confidence` fields. |
3551b80… noreply 75 | JSON | `results/action_items.json` | Array of action items, each with `text`, `assignee`, `due_date`, `priority`, and `status` fields. |
3551b80… noreply 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. |
3551b80… noreply 77
3551b80… noreply 78 ### Knowledge graph JSON structure
3551b80… noreply 79
3551b80… noreply 80 ```json
3551b80… noreply 81 {
3551b80… noreply 82 "entities": [
3551b80… noreply 83 {
3551b80… noreply 84 "name": "Kubernetes",
3551b80… noreply 85 "type": "technology",
3551b80… noreply 86 "descriptions": ["Container orchestration platform discussed in architecture review"],
3551b80… noreply 87 "occurrences": [
3551b80… noreply 88 {"source": "video:recording.mp4", "timestamp": "00:05:23"}
3551b80… noreply 89 ]
3551b80… noreply 90 }
3551b80… noreply 91 ],
3551b80… noreply 92 "relationships": [
3551b80… noreply 93 {
3551b80… noreply 94 "source": "Kubernetes",
3551b80… noreply 95 "target": "Docker",
3551b80… noreply 96 "type": "DEPENDS_ON",
3551b80… noreply 97 "descriptions": ["Kubernetes uses Docker as container runtime"]
3551b80… noreply 98 }
3551b80… noreply 99 ]
3551b80… noreply 100 }
3551b80… noreply 101 ```
3551b80… noreply 102
3551b80… noreply 103 ---
f0106a3… leo 104
f0106a3… leo 105 ## Charts
f0106a3… leo 106
3551b80… noreply 107 When chart data is extracted from diagrams (bar charts, line charts, pie charts, scatter plots), PlanOpticon reproduces them as standalone image files.
3551b80… noreply 108
3551b80… noreply 109 | Format | File | Description |
3551b80… noreply 110 |--------|------|-------------|
3551b80… noreply 111 | SVG | `diagrams/chart_N.svg` | Vector chart rendered via matplotlib. Suitable for embedding in documents or scaling to any size. |
3551b80… noreply 112 | PNG | `diagrams/chart_N.png` | Raster chart rendered via matplotlib at 150 DPI. |
3551b80… noreply 113
3551b80… noreply 114 Reproduced charts are also embedded inline in the HTML and PDF reports.
3551b80… noreply 115
3551b80… noreply 116 ---
3551b80… noreply 117
3551b80… noreply 118 ## Knowledge Graph Exports
3551b80… noreply 119
3551b80… noreply 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.
3551b80… noreply 121
3551b80… noreply 122 | Format | Command / File | Description |
3551b80… noreply 123 |--------|---------------|-------------|
3551b80… noreply 124 | JSON | `knowledge_graph.json` | Default JSON export. Produced automatically alongside the `.db` file. |
3551b80… noreply 125 | SQLite | `knowledge_graph.db` | Primary database format. Can be converted to/from JSON with `planopticon kg convert`. |
3551b80… noreply 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. |
3551b80… noreply 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. |
3551b80… noreply 128 | Mermaid | Inline in reports | Mermaid graph diagrams are embedded in Markdown and HTML reports. Also available programmatically via `GraphQueryEngine.to_mermaid()`. |
3551b80… noreply 129
3551b80… noreply 130 ### Converting between formats
3551b80… noreply 131
3551b80… noreply 132 ```bash
3551b80… noreply 133 # SQLite to JSON
3551b80… noreply 134 planopticon kg convert results/knowledge_graph.db output.json
3551b80… noreply 135
3551b80… noreply 136 # JSON to SQLite
3551b80… noreply 137 planopticon kg convert knowledge_graph.json knowledge_graph.db
3551b80… noreply 138
3551b80… noreply 139 # Sync both directions (updates the stale file)
3551b80… noreply 140 planopticon kg sync results/knowledge_graph.db
3551b80… noreply 141 planopticon kg sync knowledge_graph.db knowledge_graph.json --direction db-to-json
3551b80… noreply 142 ```
3551b80… noreply 143
3551b80… noreply 144 ---
3551b80… noreply 145
3551b80… noreply 146 ## PlanOpticonExchange Format
3551b80… noreply 147
3551b80… noreply 148 The PlanOpticonExchange format (`.json`) is a canonical interchange payload designed for sharing knowledge graphs between PlanOpticon instances, teams, or external systems.
3551b80… noreply 149
3551b80… noreply 150 ```bash
3551b80… noreply 151 planopticon export exchange knowledge_graph.db
3551b80… noreply 152 planopticon export exchange kg.db -o exchange.json --name "My Project"
3551b80… noreply 153 ```
3551b80… noreply 154
3551b80… noreply 155 The exchange payload includes:
3551b80… noreply 156
3551b80… noreply 157 - **Schema version** for forward compatibility
3551b80… noreply 158 - **Project metadata** (name, description)
3551b80… noreply 159 - **Full entity and relationship data** with provenance
3551b80… noreply 160 - **Source tracking** for multi-source graphs
3551b80… noreply 161 - **Merge support** -- exchange files can be merged together, deduplicating entities by name
3551b80… noreply 162
3551b80… noreply 163 ### Exchange JSON structure
3551b80… noreply 164
3551b80… noreply 165 ```json
3551b80… noreply 166 {
3551b80… noreply 167 "schema_version": "1.0",
3551b80… noreply 168 "project": {
3551b80… noreply 169 "name": "Sprint Reviews Q4",
3551b80… noreply 170 "description": "Knowledge extracted from Q4 sprint review recordings"
3551b80… noreply 171 },
3551b80… noreply 172 "entities": [...],
3551b80… noreply 173 "relationships": [...],
3551b80… noreply 174 "sources": [...]
3551b80… noreply 175 }
3551b80… noreply 176 ```
3551b80… noreply 177
3551b80… noreply 178 ---
3551b80… noreply 179
3551b80… noreply 180 ## Document Exports
3551b80… noreply 181
3551b80… noreply 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.
3551b80… noreply 183
3551b80… noreply 184 ### Markdown document types
3551b80… noreply 185
3551b80… noreply 186 There are seven document types plus a CSV export, all generated via `planopticon export markdown`:
3551b80… noreply 187
3551b80… noreply 188 | Type | File | Description |
3551b80… noreply 189 |------|------|-------------|
3551b80… noreply 190 | `summary` | `executive_summary.md` | High-level executive summary with entity counts, top relationships, and key themes. |
3551b80… noreply 191 | `meeting-notes` | `meeting_notes.md` | Structured meeting notes with attendees, topics discussed, decisions made, and action items. |
3551b80… noreply 192 | `glossary` | `glossary.md` | Alphabetical glossary of all entities with descriptions and types. |
3551b80… noreply 193 | `relationship-map` | `relationship_map.md` | Textual and Mermaid-based relationship map showing how entities connect. |
3551b80… noreply 194 | `status-report` | `status_report.md` | Status report format with progress indicators, risks, and next steps. |
3551b80… noreply 195 | `entity-index` | `entity_index.md` | Comprehensive index of all entities grouped by type, with links to individual briefs. |
3551b80… noreply 196 | `entity-brief` | `entities/<Name>.md` | One-pager brief for each entity, showing descriptions, relationships, and source references. |
3551b80… noreply 197 | `csv` | `entities.csv` | Tabular CSV export of entities and relationships. |
3551b80… noreply 198
3551b80… noreply 199 ```bash
3551b80… noreply 200 # Generate all document types
3551b80… noreply 201 planopticon export markdown knowledge_graph.db
3551b80… noreply 202
3551b80… noreply 203 # Generate specific types
3551b80… noreply 204 planopticon export markdown kg.db -o ./docs --type summary --type glossary
3551b80… noreply 205
3551b80… noreply 206 # Generate meeting notes and CSV
3551b80… noreply 207 planopticon export markdown kg.db --type meeting-notes --type csv
3551b80… noreply 208 ```
3551b80… noreply 209
3551b80… noreply 210 ### Obsidian vault export
3551b80… noreply 211
3551b80… noreply 212 Exports the knowledge graph as an Obsidian-compatible vault with YAML frontmatter, `[[wiki-links]]` between entities, and proper folder structure.
3551b80… noreply 213
3551b80… noreply 214 ```bash
3551b80… noreply 215 planopticon export obsidian knowledge_graph.db -o ./my-vault
3551b80… noreply 216 ```
3551b80… noreply 217
3551b80… noreply 218 The vault includes:
3551b80… noreply 219
3551b80… noreply 220 - One note per entity with frontmatter (`type`, `aliases`, `tags`)
3551b80… noreply 221 - Wiki-links between related entities
3551b80… noreply 222 - A `_Index.md` file for navigation
3551b80… noreply 223 - Compatible with Obsidian graph view
3551b80… noreply 224
3551b80… noreply 225 ### Notion markdown export
3551b80… noreply 226
3551b80… noreply 227 Exports as Notion-compatible Markdown with a CSV database file for import into Notion databases.
3551b80… noreply 228
3551b80… noreply 229 ```bash
3551b80… noreply 230 planopticon export notion knowledge_graph.db -o ./notion-export
3551b80… noreply 231 ```
3551b80… noreply 232
3551b80… noreply 233 ### GitHub wiki export
3551b80… noreply 234
3551b80… noreply 235 Generates a complete GitHub wiki with a sidebar, home page, and per-entity pages. Can be pushed directly to a GitHub wiki repository.
3551b80… noreply 236
3551b80… noreply 237 ```bash
3551b80… noreply 238 # Generate wiki pages
3551b80… noreply 239 planopticon wiki generate knowledge_graph.db -o ./wiki
3551b80… noreply 240
3551b80… noreply 241 # Push to GitHub
3551b80… noreply 242 planopticon wiki push ./wiki ConflictHQ/PlanOpticon -m "Update wiki from KG"
3551b80… noreply 243 ```
3551b80… noreply 244
3551b80… noreply 245 ---
3551b80… noreply 246
3551b80… noreply 247 ## Batch Outputs
3551b80… noreply 248
3551b80… noreply 249 Batch processing produces additional files at the batch root directory, alongside per-video output folders.
3551b80… noreply 250
3551b80… noreply 251 | Format | File | Description |
3551b80… noreply 252 |--------|------|-------------|
3551b80… noreply 253 | JSON | `batch_manifest.json` | Batch-level manifest with aggregate stats, per-video status (completed/failed), error details, and paths to all sub-outputs. |
3551b80… noreply 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. |
3551b80… noreply 255 | SQLite | `knowledge_graph.db` | Merged knowledge graph combining entities and relationships across all successfully processed videos. Uses fuzzy matching and conflict resolution. |
3551b80… noreply 256 | JSON | `knowledge_graph.json` | JSON export of the merged knowledge graph. |
3551b80… noreply 257
3551b80… noreply 258 ---
3551b80… noreply 259
3551b80… noreply 260 ## Self-Contained HTML Viewer
3551b80… noreply 261
3551b80… noreply 262 PlanOpticon ships with a self-contained interactive knowledge graph viewer at `knowledge-base/viewer.html` in the repository. This file:
3551b80… noreply 263
3551b80… noreply 264 - Uses D3.js (bundled inline, no CDN dependency)
3551b80… noreply 265 - Renders an interactive force-directed graph visualization
3551b80… noreply 266 - Supports node filtering by entity type
3551b80… noreply 267 - Shows entity details and relationships on click
3551b80… noreply 268 - Can load any `knowledge_graph.json` file
3551b80… noreply 269 - Works offline with no server required -- just open in a browser
3551b80… noreply 270 - Covers approximately 80% of graph exploration needs with zero infrastructure
3551b80… noreply 271
3551b80… noreply 272 ---
3551b80… noreply 273
3551b80… noreply 274 ## Output Directory Structure
3551b80… noreply 275
3551b80… noreply 276 A complete single-video analysis produces the following directory tree:
3551b80… noreply 277
3551b80… noreply 278 ```
3551b80… noreply 279 output/
3551b80… noreply 280 ├── manifest.json # Run manifest (source of truth)
3551b80… noreply 281 ├── transcript/
3551b80… noreply 282 │ ├── transcript.json # Full transcript with segments
3551b80… noreply 283 │ ├── transcript.txt # Plain text
3551b80… noreply 284 │ └── transcript.srt # Subtitles
3551b80… noreply 285 ├── frames/
3551b80… noreply 286 │ ├── frame_0000.jpg # Extracted video frames
3551b80… noreply 287 │ ├── frame_0001.jpg
3551b80… noreply 288 │ └── ...
3551b80… noreply 289 ├── diagrams/
3551b80… noreply 290 │ ├── diagram_0.jpg # Original frame
3551b80… noreply 291 │ ├── diagram_0.mermaid # Mermaid source
3551b80… noreply 292 │ ├── diagram_0.svg # Vector rendering
3551b80… noreply 293 │ ├── diagram_0.png # Raster rendering
3551b80… noreply 294 │ ├── diagram_0.json # Analysis data
3551b80… noreply 295 │ ├── chart_0.svg # Reproduced chart (SVG)
3551b80… noreply 296 │ ├── chart_0.png # Reproduced chart (PNG)
3551b80… noreply 297 │ └── ...
3551b80… noreply 298 ├── captures/
3551b80… noreply 299 │ ├── capture_0.jpg # Medium-confidence screenshots
3551b80… noreply 300 │ ├── capture_0.json # Caption and metadata
3551b80… noreply 301 │ └── ...
3551b80… noreply 302 └── results/
3551b80… noreply 303 ├── analysis.md # Markdown report
3551b80… noreply 304 ├── analysis.html # HTML report
3551b80… noreply 305 ├── analysis.pdf # PDF report (if planopticon[pdf] installed)
3551b80… noreply 306 ├── knowledge_graph.db # Knowledge graph (SQLite, primary)
3551b80… noreply 307 ├── knowledge_graph.json # Knowledge graph (JSON export)
3551b80… noreply 308 ├── key_points.json # Extracted key points
3551b80… noreply 309 └── action_items.json # Action items
3551b80… noreply 310 ```
3551b80… noreply 311
3551b80… noreply 312 ---
3551b80… noreply 313
3551b80… noreply 314 ## Controlling Output Format
3551b80… noreply 315
3551b80… noreply 316 Use the `--output-format` flag with `planopticon analyze` to control how results are presented:
3551b80… noreply 317
3551b80… noreply 318 | Value | Behavior |
3551b80… noreply 319 |-------|----------|
3551b80… noreply 320 | `default` | Writes all output files to disk and prints a usage summary to stdout. |
3551b80… noreply 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. |
3551b80… noreply 322
3551b80… noreply 323 ```bash
3551b80… noreply 324 # Standard output (files + console summary)
3551b80… noreply 325 planopticon analyze -i video.mp4 -o ./output
f0106a3… leo 326
3551b80… noreply 327 # JSON manifest to stdout (for scripting)
3551b80… noreply 328 planopticon analyze -i video.mp4 -o ./output --output-format json
3551b80… noreply 329 ```

Keyboard Shortcuts

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