showhow 0.1.0

Lightweight tool for turning desktop demonstrations into step-by-step multimodal tutorials.

Demo2Tutorial: From Human Experience to Multimodal Software Tutorials

Zechen Bai, Zhiheng Chen, Yiqi Lin, Kevin Qinghong Lin,
Difei Gao, Xiangwu Guo, Xin Wang, Mike Zheng Shou

Show Lab, National University of Singapore

Paper | PyPI | Quick Start

ShowHow is the minimal public release of Demo2Tutorial: a lightweight tool for recording desktop workflows and turning them into polished step-by-step multimodal tutorials.

---

Overview

Raw screen recordings are useful demonstrations, but they are often long, passive, and difficult to follow. ShowHow turns a recorded desktop workflow into a structured tutorial with concise instructions, selected keyframes, and visual guidance.

This repository keeps the paper-facing identity as Demo2Tutorial, while the public software tool and package are named ShowHow:

• repository: Demo2Tutorial
• Python package: showhow
• local tool / product name: ShowHow

Highlights

Current features

• Browser-based recording UI
• Local macOS recorder for desktop workflows
• Multimodal tutorial generation from recorded sessions
• Editable HTML/PDF export for generated tutorials
• PyPI package for simple installation

Planned

• Windows support after a dedicated public validation pass
• MCP integration as a polished advanced workflow
• Skill-oriented integrations and broader agent-facing tooling

Pipeline

Example Tutorial

Easy-to-use WebUI

Quick Start

Option A: Install from PyPI

pip install showhow
python -m showhow.cli web --host 127.0.0.1 --port 18090

Then open (usually the browser will automatically open):

http://127.0.0.1:18090

Option B: Run from source directly

git clone https://github.com/showlab/Demo2Tutorial.git
cd Demo2Tutorial

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .

python -m showhow.cli web --host 127.0.0.1 --port 18090

Setup

Requirements

• Python 3.10+
• ffmpeg
• OpenAI API access for generation
• macOS (Windows compatibility is not strictly tested)

OpenAI API key

You can either:

• enter the API key directly in the web UI (still only exists locally)
• or export it in your shell

export OPENAI_API_KEY=your_key_here

macOS permissions (optional)

For recording on macOS, you may need to grant if necessary:

• Screen Recording
• Accessibility
• Input Monitoring

If the recorder does not work as expected, run:

python -m showhow.cli doctor

Usage

Web UI

The recommended workflow is the web UI:

python -m showhow.cli web

Then:

1. open the local page in your browser
2. enter the API key if needed
3. start recording
4. perform the task
5. stop recording
6. generate the tutorial

Interactive CLI flow

python -m showhow.cli record --topic "demo_flow" --generate --model gpt-4o

Explicit CLI flow

python -m showhow.cli start --topic "demo_flow"
python -m showhow.cli rec-status
python -m showhow.cli stop
python -m showhow.cli generate --session-id <SESSION_ID>

Output

By default, recordings are saved under:

~/Downloads/record_save

Each session may produce artifacts such as:

• events.jsonl
• metadata.json
• session video
• parsed trace
• tutorial draft
• rendered tutorial assets
• tutorial.html

Troubleshooting

ffmpeg not found

Install ffmpeg and ensure it is available on your PATH.

Recorder fails to start

Run:

python -m showhow.cli doctor

Then check:

• OS permissions
• recorder host/port availability
• ffmpeg availability

OpenAI key errors

Make sure OPENAI_API_KEY is set correctly, or enter it in the web UI.

No tutorial output generated

Check whether the recording session produced:

• a valid event log
• a valid video file
• a valid session directory under the record root

Limitations

• Currently optimized for local single-user usage
• Default generation depends on API-backed captioning and planning
• Desktop recording behavior depends on OS permissions
• Some advanced composition features may require optional dependencies

Citation

If you find this project useful, please cite the paper:

TODO

License

This project is released under the MIT License. See LICENSE.