viviphi 1.1.2

Turn static graphs into beautiful animations

Turn static graphs into beautiful animations!

Viviphi transforms your Mermaid.js diagrams into stunning animated SVGs with customizable themes and smooth transitions. Perfect for presentations, documentation, or just making your diagrams come alive.

✨ Features

• 🎨 Multiple Themes: Cyberpunk, Corporate, and Hand-drawn styles
• ⚡ Easy to Use: Simple Python API with just a few lines of code
• 🎯 Mermaid Compatible: Works with standard Mermaid.js syntax
• 🚀 Fast Rendering: Powered by Playwright for reliable SVG generation
• 🎛️ Customizable: Adjustable animation speeds and timing

🚀 Quick Start

Installation

# Install viviphi
uv add viviphi

# Install browser dependencies
uv run playwright install chromium

Basic Usage

from viviphi import Graph, MANIM_AQUA

# Define your Mermaid graph
mermaid_code = """
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
"""

# Create and animate
graph = Graph(mermaid_code)
animated_svg = graph.animate(theme=MANIM_AQUA, output="my_graph.svg")

That's it! Your animated SVG is ready.

🎨 Themes

Viviphi comes with three built-in themes:

Manim Aqua 🌊

from viviphi import Graph, MANIM_AQUA

graph = Graph(mermaid_code)
graph.animate(theme=MANIM_AQUA, output="manim_aqua_graph.svg")

Gradient Sunset 🌅

from viviphi import Graph, GRADIENT_SUNSET

graph = Graph(mermaid_code)
graph.animate(theme=GRADIENT_SUNSET, output="gradient_sunset_graph.svg")

Hand Drawn ✏️

from viviphi import Graph, HAND_DRAWN

graph = Graph(mermaid_code)
graph.animate(theme=HAND_DRAWN, output="hand_drawn_graph.svg")

⚡ Animation Speed

Control the animation speed with the speed parameter:

# Slow and dramatic
graph.animate(theme=MANIM_AQUA, speed="slow")

# Default speed
graph.animate(theme=MANIM_AQUA, speed="normal")

# Quick and snappy
graph.animate(theme=MANIM_AQUA, speed="fast")

📊 Supported Diagram Types

Viviphi works with all standard Mermaid diagram types:

Flowcharts

flowchart = """
graph LR
    A[User] --> B[Login]
    B --> C{Valid?}
    C -->|Yes| D[Dashboard]
    C -->|No| E[Error]
"""

Sequence Diagrams

sequence = """
sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob
    B->>A: Hello Alice
"""

Class Diagrams

class_diagram = """
classDiagram
    class Vehicle {
        +String make
        +String model
        +start()
        +stop()
    }
    class Car {
        +openTrunk()
    }
    Vehicle <|-- Car
"""

State Diagrams

state_diagram = """
stateDiagram-v2
    [*] --> Idle
    Idle --> Running: start()
    Running --> Idle: stop()
    Running --> [*]: shutdown()
"""

🔧 Advanced Usage

Batch Processing

Process multiple diagrams at once:

from pathlib import Path
from viviphi import Graph, CYBERPUNK, CORPORATE, HAND_DRAWN

def animate_all_diagrams(input_dir: Path, output_dir: Path):
    themes = {
        "cyberpunk": CYBERPUNK,
        "corporate": CORPORATE, 
        "hand_drawn": HAND_DRAWN
    }
    
    for mermaid_file in input_dir.glob("*.mmd"):
        content = mermaid_file.read_text()
        graph = Graph(content)
        
        for theme_name, theme in themes.items():
            output_file = output_dir / f"{mermaid_file.stem}_{theme_name}.svg"
            graph.animate(theme=theme, output=str(output_file))

Custom Timing

Fine-tune animation timing:

from viviphi import Graph, Theme

# Create a custom theme with specific timing
custom_theme = Theme(
    primary_color="#ff6b6b",
    background="#2d3748",
    edge_style="neon",
    animation_duration=2.5,  # Longer animations
    stagger_delay=0.5        # More delay between elements
)

graph = Graph(mermaid_code)
graph.animate(theme=custom_theme)

🎯 Real-World Examples

Documentation Workflow

from viviphi import Graph, GRADIENT_SUNSET

# Load your workflow diagram
workflow = """
graph TD
    A[Write Code] --> B[Create Mermaid Diagram]
    B --> C[Generate Animated SVG]
    C --> D[Include in Documentation]
    D --> E[Profit! 🎉]
"""

# Generate for docs
graph = Graph(workflow)
graph.animate(theme=GRADIENT_SUNSET, speed="normal", output="docs/workflow.svg")

System Architecture

from viviphi import Graph, MANIM_AQUA

architecture = """
graph TB
    subgraph "Frontend"
        UI[React App]
        API[API Client]
    end
    
    subgraph "Backend" 
        SERVER[Express Server]
        DB[(PostgreSQL)]
        CACHE[(Redis)]
    end
    
    UI --> API
    API --> SERVER
    SERVER --> DB
    SERVER --> CACHE
"""

graph = Graph(architecture)
graph.animate(theme=MANIM_AQUA, output="architecture.svg")

📁 Project Structure

viviphi/
├── viviphi/           # Main package
│   ├── animator.py    # SVG animation engine  
│   ├── graph.py       # Main Graph class
│   ├── mermaid.py     # Mermaid rendering
│   └── themes.py      # Theme definitions
├── examples/          # Usage examples
├── resources/         # Sample Mermaid files
└── tests/            # Test suite

🛠️ Development

# Clone the repository
git clone <repository-url>
cd viviphi

# Install dependencies
uv sync --no-install-project

# Run tests
uv run pytest

# Check code quality
ruff check
ruff format

🤝 Contributing

We welcome contributions! Please feel free to submit issues and pull requests.

📄 License

This project is open source. See LICENSE file for details.

---

Made with ❤️ by the Viviphi team

Transform your static diagrams into dynamic stories!