Reusable component library for OpenAdapt visualization, providing building blocks and high-level builders for creating standalone HTML viewers.
Repository: OpenAdaptAI/openadapt-viewer
pip install openadapt[viewer]
# or
pip install openadapt-viewer
The viewer package provides a comprehensive visualization system with:
openadapt capture view my-task
This opens an HTML viewer in your default browser.
Options:
--port - Server port (default: 8080)--no-browser - Don’t open browser automaticallyopenadapt serve --port 8080
Access the dashboard at http://localhost:8080.
from openadapt_viewer import PageBuilder, HTMLBuilder
# Build a viewer page for a demonstration
builder = PageBuilder(demonstration="my-task")
html = builder.build()
# Save to file
with open("viewer.html", "w") as f:
f.write(html)
# Or use HTMLBuilder for custom visualizations
html_builder = HTMLBuilder()
html_builder.add_observation(screenshot_path, actions)
html_builder.add_timeline(actions)
html = html_builder.render()
Browse all captured observations (screenshots) with navigation controls.
Interactive timeline showing:
| Export | Description |
|---|---|
PageBuilder |
Builds trajectory viewer pages |
HTMLBuilder |
Low-level HTML construction |
TimelineWidget |
Action timeline visualization |
ObservationGallery |
Observation browser |
from openadapt_viewer import PageBuilder, Theme
builder = PageBuilder(
demonstration="my-task",
theme=Theme.DARK # or Theme.LIGHT
)
from openadapt_viewer import PageBuilder, ActionRenderer
class CustomRenderer(ActionRenderer):
def render_click(self, action):
return f"<div class='custom-click'>{action}</div>"
builder = PageBuilder(
demonstration="my-task",
renderer=CustomRenderer()
)
NEW (January 2026): Interactive viewer for automatically segmented task episodes.
# Generate segmentation viewer with catalog integration
cd openadapt-viewer
python scripts/generate_segmentation_viewer.py --output viewer.html --open
from openadapt_viewer import generate_segmentation_viewer
# Generate viewer with auto-discovery
viewer_path = generate_segmentation_viewer(
output_path="segmentation_viewer.html",
include_catalog=True, # Enable auto-discovery
)
Episodes are stored in JSON files with this structure:
{
"episodes": [
{
"episode_id": "turn-off-nightshift_001",
"name": "Disable Night Shift",
"description": "Navigate to settings and disable Night Shift",
"start_frame": 0,
"end_frame": 45,
"key_frames": [0, 15, 30, 45],
"steps": [
"Open System Settings",
"Navigate to Displays",
"Disable Night Shift"
],
"recording_name": "turn-off-nightshift"
}
]
}
NEW (January 2026): Automatic discovery and indexing of recordings and segmentation results.
~/.openadapt/catalog.db# Scan for recordings and segmentation results
openadapt-viewer catalog scan
# List all recordings
openadapt-viewer catalog list
# Show statistics
openadapt-viewer catalog stats
from openadapt_viewer import get_catalog, scan_and_update_catalog
# Scan and index recordings
counts = scan_and_update_catalog()
print(f"Indexed {counts['recordings']} recordings")
# Query catalog
catalog = get_catalog()
recordings = catalog.get_all_recordings()
for rec in recordings:
print(f"{rec.name}: {rec.frame_count} frames")
# Get segmentation results
seg_results = catalog.get_segmentation_results("turn-off-nightshift")
NEW (January 2026): Intelligent token-based search algorithm.
// Search episodes
const results = advancedSearch(episodes, "nightshift", ['name', 'description', 'steps']);
// Results include:
// - "Disable Night Shift"
// - "Configure nightshift settings"
// - "Turn off automatic night mode"
| Component | Description |
|---|---|
screenshot_display |
Screenshot with overlays (clicks, bounding boxes) |
playback_controls |
Play/pause/speed controls |
timeline |
Step progress bar |
action_display |
Format actions (click, type, scroll) |
metrics_grid |
Statistics cards and grids |
filter_bar |
Filter dropdowns |
selectable_list |
Selectable list component |
badge |
Status badges |
from openadapt_viewer.components import (
screenshot_display,
metrics_grid,
playback_controls,
)
# Screenshot with overlays
html = screenshot_display(
image_path="screenshot.png",
overlays=[
{"type": "click", "x": 0.5, "y": 0.3, "label": "Human"},
{"type": "click", "x": 0.6, "y": 0.4, "label": "AI", "variant": "predicted"},
],
)
# Metrics cards
html = metrics_grid([
{"label": "Total", "value": 100},
{"label": "Passed", "value": 75, "color": "success"},
{"label": "Failed", "value": 25, "color": "error"},
])
NEW (January 2026): Automated screenshot generation for documentation.
# Install Playwright (one-time setup)
pip install playwright
playwright install chromium
# Generate all screenshots
openadapt-viewer screenshots segmentation --output screenshots/
# Desktop only (faster)
openadapt-viewer screenshots segmentation --skip-responsive
# With metadata
openadapt-viewer screenshots segmentation --save-metadata