Clipcase
Convert screen recording videos of application usage into structured, comprehensive test cases — automatically.
Drop a .mov/.mp4 video, run one command, and get test cases in Markdown, CSV, and Excel formats.
How It Works
Video (.mov/.mp4) ──▶ ffmpeg (frame extraction) ──▶ AI Vision (frame analysis) ──▶ Test Cases (MD/CSV/XLSX)
- Frame extraction — Uses
ffmpegto extract screenshots from the video at a configurable frame rate. - AI analysis — Sends sampled frames to a vision-capable LLM (Claude or GPT-4o) to understand the complete user flow.
- Test case generation — The AI generates structured test cases following QA best practices, covering positive, negative, and edge case scenarios, along with a self-assessed confidence score.
- Export — Outputs test cases in Markdown, CSV, and styled Excel formats.
Prerequisites
| Dependency | Why | Install |
|---|---|---|
| Python 3.9+ | Runtime | python.org |
| ffmpeg | Frame extraction from video | brew install ffmpeg (macOS) / sudo apt install ffmpeg (Linux) / choco install ffmpeg (Windows) |
| API Key | AI analysis (Claude or GPT-4o) | See API Setup below |
Quick Start
1. Clone and install
git clone <repo-url> clipcase
cd clipcase
pip install -r requirements.txt
2. Set your API key
cp .env.example .env
# Edit .env and paste your API key
Or export directly:
export ANTHROPIC_API_KEY=sk-ant-api03-...
# or
export OPENAI_API_KEY=sk-...
3. Run
python -m clipcase your_recording.mov
Prefer a real install instead of running from source? pip install clipcase (or pip install -e . from a clone) registers a clipcase command, so every example below also works as clipcase your_recording.mov — no python -m needed.
That's it. Your test cases will appear as:
your_recording_test_cases.mdyour_recording_test_cases.csvyour_recording_test_cases.xlsx
The markdown export and terminal output also include a confidence score — the model's own self-assessment of how completely it captured the recorded flow.
Usage
python -m clipcase <video_file> [options]
Options
| Flag | Default | Description |
|---|---|---|
--fps |
2 |
Frames per second to extract |
--provider |
anthropic |
LLM provider: anthropic or openai |
--output |
auto | Base name for output files |
--frames-dir |
frames |
Directory for extracted frames |
--frames-only |
off | Only extract frames, skip AI |
--sample-interval |
10 |
Use every Nth frame for analysis |
--principles |
auto | Path to custom principles file |
Examples
# Basic — uses Claude, 2 fps
python -m clipcase recording.mov
# Use OpenAI GPT-4o instead
python -m clipcase recording.mov --provider openai
# Use Google Gemini (free tier)
python -m clipcase recording.mov --provider gemini
# Higher frame rate for fast-paced UI
python -m clipcase recording.mov --fps 4
# Just extract frames (no AI cost), review manually
python -m clipcase recording.mov --frames-only
# Custom output name
python -m clipcase recording.mov --output login_flow_tests
# Analyze more frames (lower interval = more frames sent to AI)
python -m clipcase recording.mov --sample-interval 5
API Setup
Option A: Anthropic (Claude) — Recommended
- Go to console.anthropic.com
- Create an API key
- Add to
.env:ANTHROPIC_API_KEY=sk-ant-api03-...
Option B: OpenAI (GPT-4o)
- Go to platform.openai.com
- Create an API key
- Add to
.env:OPENAI_API_KEY=sk-... - Use
--provider openaiwhen running
Option C: Google Gemini — Free tier available
- Go to aistudio.google.com/app/apikey
- Sign in with your Google account
- Click Create API Key (free, no credit card needed)
- Add to
.env:GEMINI_API_KEY=AIza... - Use
--provider geminiwhen running
Custom Test Case Principles
You can customize how test cases are written by providing your own principles file:
python -m clipcase recording.mov --principles my_standards.md
If you place a file named test_case_creation_principles.md in the same directory as the video, it will be picked up automatically.
The included test_case_creation_principles.md covers:
- Clarity, independence, repeatability, traceability, maintainability
- Naming conventions (Verify that..., Verify if the user...)
- Pre-conditions, expected outcomes, test data guidelines
- Test type classification (Smoke, Sanity, Regression, E2E)
Output Formats
Markdown (.md)
Full document with flow analysis, test case table, and summary statistics.
CSV (.csv)
Tab-importable into Google Sheets, Jira, TestRail, or any test management tool. Checkmarks rendered as ✓.
Excel (.xlsx)
Professionally styled with:
- Color-coded header row
- Alternating row shading
- Auto-filters on every column
- Frozen header row
- Auto-sized columns
Project Structure
clipcase/
├── clipcase/ # Main CLI package (core.py, cli.py)
├── requirements.txt # Python dependencies
├── .env.example # API key template
├── .gitignore # Git ignore rules
├── test_case_creation_principles.md # QA principles (auto-loaded)
├── test_case_template.md # Reference template
└── README.md # This file
Tips
- Short videos work best: 1–5 minute recordings of a single flow produce the most focused test cases.
- Record one flow per video: Login flow, checkout flow, onboarding flow — keep them separate.
- Review and refine: AI-generated test cases are a strong starting point. Have your QA team review and adjust.
- Lower
--sample-intervalfor complex UIs where many small changes happen quickly. - Use
--frames-onlyto preview what the AI will see before spending API credits.
Cost Estimate
Each run makes 2–4 API calls depending on video length:
| Provider | Approximate Cost per Run |
|---|---|
| Claude (Anthropic) | ~$0.30 – $1.00 |
| GPT-4o (OpenAI) | ~$0.50 – $1.50 |
| Gemini 1.5 Pro (Google) | Free tier available (generous quota) |
Costs scale with frame count and video length.
Troubleshooting
| Issue | Fix |
|---|---|
ffmpeg: command not found |
Install ffmpeg (see Prerequisites) |
ANTHROPIC_API_KEY not set |
Add key to .env or export in shell |
| Unicode filename error | Tool handles this automatically via symlink |
openpyxl not installed |
Run pip install openpyxl for Excel support |
| Too few test cases generated | Lower --sample-interval to send more frames |
License
MIT
Metadata
Release files for clipcase 1.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| clipcase-1.1.1.tar.gz | 21.7 kB | Without provenance | Details for clipcase-1.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| clipcase-1.1.1-py3-none-any.whl | Python 3 | none | any | Details for clipcase-1.1.1-py3-none-any.whl |
Total release size: 38.2 kB
Release files / clipcase-1.1.1.tar.gz
| Download URL | clipcase-1.1.1.tar.gz |
|---|---|
| Size | 21.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ba25a3a7b534b90d40e2c2eacf5c97bb842d59b66c45737b205b55cda8aef525
|
|
BLAKE2b-256 checksum How to use checksums |
3c13ed8bbbde5be7df69283c88ccdc67419a907cbf413900e224663c3549ae9d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / clipcase-1.1.1-py3-none-any.whl
| Download URL | clipcase-1.1.1-py3-none-any.whl |
|---|---|
| Size | 16.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d42c73b226c0f83e40a029e769b3eac8e0b288fac590f237b23e1c2ab73ff75e
|
|
BLAKE2b-256 checksum How to use checksums |
62a96173c19463b634547f84d7eaa4021563b052fc0a62400ba2abcd6f010ccc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Security for clipcase 1.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.