Workflow walkthrough media capture

Maintainer notes for regenerating screenshots and GIFs under docs/_static/workflows/.

Sample corpus

Item

Value

Fixture

docs/workflows/fixtures/planning_review.json

Provenance

Synthetic authored text for docs; not a real recording

Speakers

SPEAKER_00 / SPEAKER_01 / SPEAKER_02 (name to Maya / Jordan / Sam in walkthrough 2)

Suggested names

Maya (facilitator), Jordan (engineering), Sam (support)

Import via Import Transcript. Do not commit managed library copies under data/.

Application state

Capture against a disposable data root when practical.

Walkthrough media

Expected state

Import / Run Analysis

Fresh import; no requirement for prior runs

Overview / Insights / Export / Charts

Completed Balanced run on the fixture (re-run after naming if speaker cards should show names)

Speaker Identification

Fixture selected; speakers still diarized or mid-naming

Local AI

llm.enabled with reachable Ollama; modules llm_summary + llm_action_items completed

Groups

At least one managed transcript; create via Groups expander

Corrections

Transcript VIEW with Correct mode; unique find text in a segment

Rename Transcript

Managed transcript selected on Rename page

Speakers

At least one longitudinal profile (link from Speaker ID)

Export HTML preview

Unpacked ZIP index.html opened at file:// (crop to page content)

Viewport and chrome

  • Browser window 1440×900 (or device pixel ratio 1 with that CSS viewport).

  • Capture the Streamlit app pane only — no OS desktop, no browser URL bar if avoidable.

  • Prefer tight crops around the meaningful region (sidebar + main panel, or main panel alone).

  • Scrub usernames, absolute host paths, tokens, and personal transcript titles before committing.

Routes (sidebar labels)

Asset stem

Sidebar page

first-analysis-import

Import Transcript

first-analysis-run-analysis

Run Analysis

first-analysis-overview

Overview

speaker-identification-* (legacy speaker-trust-*)

Speaker Identification / Transcript

investigate-*

Overview / Insights (Highlights) / Transcript

local-ai-*

Run Analysis (LLM setup) / Overview / Insights (Actions)

export-*

Artifacts (Browse / Export) + external HTML preview

charts-*

Charts

Landing gallery (website/images/): Overview, Transcript, Speaker ID, Insights. A dedicated Charts still is not in the set yet; Insights stands in on the public site (Charts is in the same View menu). When capturing Charts, copy it to website/images/ as well. | groups-* | Groups | | corrections-* | Transcript (Correct mode) / Corrections Studio | | rename-* | Rename Transcript | | speakers-* | Speakers |

Capture method

Product policy: do not add Playwright-driven Streamlit acceptance automation for docs media.

Practical approach used for the initial set:

  1. Launch the web UI with a disposable data root (TRANSCRIPTX_*_DIR) and a written schema_epoch.json marker.

  2. Import docs/workflows/fixtures/planning_review.json, name speakers, run Balanced analysis.

  3. Select the transcript and run in the sidebar VIEW pickers before opening Overview / Insights / Artifacts.

  4. Capture stills with Chromium (Playwright one-off helper scripts/docs_capture_workflow_media.py or OS screenshots).

  5. Build short GIFs from a few stills (convert + gifsicle) when a live interaction capture is awkward.

  6. Keep raw files under .local/workflow_media/; promote curated assets to docs/_static/workflows/.

Do not couple production code to documentation capture.

Example compress commands

# PNG (lossy palette when text remains readable)
pngquant --quality=65-85 --ext .png --force docs/_static/workflows/*.png

# or lossless shrink
optipng -o2 docs/_static/workflows/*.png

# GIF
gifsicle -O3 --colors 128 -o out.gif in.gif

If those tools are unavailable, use an equivalent compressor that keeps UI text legible.

Asset checklist

Committed names expected by the walkthrough pages:

  • first-analysis-import.png

  • first-analysis-run-analysis.png

  • first-analysis-run-complete.gif

  • first-analysis-overview.png

  • speaker-identification-page.png (legacy speaker-trust-page.png)

  • speaker-identification-naming.gif (legacy speaker-trust-naming.gif)

  • speaker-identification-transcript.png (legacy speaker-trust-transcript.png)

  • investigate-overview.png

  • investigate-highlights.png

  • investigate-evidence-jump.gif

  • local-ai-llm-setup.png

  • local-ai-overview-summary.png

  • local-ai-meeting-extracts.png

  • export-artifacts-browse.png

  • export-panel.png

  • export-download.gif

  • export-html-preview.png

Embed images with GitHub-compatible Markdown so they render in the GitHub file view and in Sphinx/MyST:

![Descriptive alt text](../_static/workflows/example.png)

Paths are relative to docs/workflows/. Alt text is required; captions are optional and only when they add information beyond surrounding prose.

The public landing hero is a copy of first-analysis-overview.png at website/images/overview.png. When you recapture Overview, copy it there as well.

Rebuild docs

pip install -e '.[docs]'
make docs
# open docs/_build/html/workflows/index.html