specspectacle 0.1.0

Turn specs into spectacles – YAML user journeys to live product demos

SpecSpectacle

Turn specs into spectacles – YAML user journeys to live product demos.

---

What is SpecSpectacle?

SpecSpectacle is an open-source CLI tool that transforms YAML specifications into polished product demo videos. Write a YAML file describing your user journey, run a single command, and get an MP4 video with:

• 🎬 Automated browser recording via Playwright
• 🗣️ English narration with Text-to-Speech
• 📝 On-screen text overlays at precise timestamps
• 🔄 Version-controlled demos that live in your repo

Perfect for developers who want reproducible, code-driven demo videos without manual screen recording or video editing.

---

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• ffmpeg installed (installation guide)

Installation

# Install from PyPI (when v0.1.0 is released)
pip install specspectacle

# Install Chromium browser for Playwright
playwright install chromium

---

📖 Usage

1. Create a YAML Spec

specspectacle scaffold demo.yaml

This generates a template YAML with commented examples.

2. Validate Your Spec

specspectacle validate demo.yaml

3. Generate Your Demo Video

specspectacle run demo.yaml

Your video will be saved to ./output/demo.mp4!

---

📚 Documentation

• YAML Reference - Complete YAML specification guide
• Contributing Guide - How to contribute to SpecSpectacle

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Development environment setup
• How to run tests
• Code style guidelines (Black, isort, type hints)
• Pull request process

---

📜 License

Apache 2.0 - See LICENSE for details.

---

🎬 Example

name: "Simple Login Demo"
version: "0.1.0"

config:
  target_app: "https://app.example.com"
  viewport:
    width: 1280
    height: 720

flows:
  - name: "Login"
    steps:
      - action: "navigate"
        url: "https://app.example.com/login"
        narration:
          text: "Navigate to the login page"
        overlay:
          text: "Step 1: Open login page"
          position: "bottom"
          
      - action: "type"
        selector: "#email"
        text: "[e-mail]"
        narration:
          text: "Enter your email address"

Run with:

specspectacle run login-demo.yaml

---

Future

• Multi-language support
• SaaS backend with cloud rendering
• GitHub Action integration
• Web UI for visual flow editing
• Template library

---

🙏 Acknowledgments

Built with:

• Playwright - Browser automation
• Click - CLI framework
• FFmpeg - Video processing
• Pydantic - Data validation

---

Status: ✅ Phase 1 complete! v0.1.0 released