# python-pptx

**Repository Path**: legand/python-pptx

## Basic Information

- **Project Name**: python-pptx
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-27
- **Last Updated**: 2025-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MD2PPT v2 - 智能多媒体演示制作系统

Convert Markdown files to professional PowerPoint presentations, interactive HTML, and narrated videos with AI integration.

[![Tests](https://github.com/your-org/md2ppt/workflows/tests/badge.svg)](https://github.com/your-org/md2ppt/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

## ✨ Features

### 🎯 Core Capabilities
- **Multi-format Output**: PPTX, HTML, MP4, SRT subtitles
- **AI Integration**: Smart content generation with prompt templates
- **Enhanced Animation System**: Native PowerPoint animations via Aspose.Slides
- **Rich Animation Effects**: 15+ entrance, exit, and emphasis animations
- **Voice Synthesis**: 28+ voices with Edge-TTS integration
- **Platform Optimization**: YouTube, TikTok, Bilibili presets

### 🎬 Advanced Features
- **Native PowerPoint Animations**: Real animations in PPTX files via Aspose.Slides
- **Enhanced Animation Syntax**: `::slideIn[direction=left,duration=1.5]`
- **Multiple Animation Engines**: Aspose.Slides (PPTX), Reveal.js (HTML), FFmpeg (Video)
- **Smart Video Generation**: Timeline synchronization with audio
- **Multi-theme Support**: Professional, education, tech themes
- **Cross-platform**: Windows, macOS, Linux support

## 🚀 Quick Start

### Installation

```bash
# Basic installation
pip install -e .

# With API support
pip install -e .[api]

# With MCP support
pip install -e .[mcp]

# With TTS and video support
pip install -e .[audio]

# With Aspose.Slides for native PowerPoint animations
pip install -e .[aspose]

# Full installation (recommended)
pip install -e .[all]
```

## 💻 CLI Usage

### 🎯 Basic Conversion

```bash
# Simple PPTX conversion
python -m md2ppt presentation.md

# Custom output filename
python -m md2ppt presentation.md -o my_slides.pptx

# Custom theme and verbose output
python -m md2ppt presentation.md --theme blue --verbose
```

### 🎨 Theme Options

```bash
# Available themes
python -m md2ppt presentation.md --theme default  # Clean, professional
python -m md2ppt presentation.md --theme blue     # Business blue
python -m md2ppt presentation.md --theme green    # Fresh green
python -m md2ppt presentation.md --theme dark     # Dark tech style
python -m md2ppt presentation.md --theme red      # Energetic red
```

### 📐 Image Control

```bash
# Control image sizing (default 0.7 = 70% of slide width)
python -m md2ppt presentation.md --image-width-ratio 0.8

# Smaller images
python -m md2ppt presentation.md --image-width-ratio 0.5
```

### 🎬 Enhanced Animation Support (v2 Feature)

```bash
# Enable native PowerPoint animations (Aspose.Slides)
python -m md2ppt presentation.md --enable-animations --animation-engine aspose

# Auto-select best engine for format
python -m md2ppt presentation.md --enable-animations --animation-engine auto

# Generate interactive HTML with animations (Reveal.js)
python -m md2ppt presentation.md --format html --enable-animations

# Enhanced animation syntax in your Markdown:
# ::slideIn[direction=left,duration=1.5,delay=0.5]
# Your animated content here
# ::
#
# ::pulse[duration=0.8,delay=2.0]
# Important highlighted content
# ::
```

### 🎵 TTS Video Generation (v2 Feature)

```bash
# Generate video with AI voice narration
python -m md2ppt presentation.md --format video --generate-tts

# Choose specific voice (28+ available)
python -m md2ppt presentation.md --format video --generate-tts \
  --tts-voice zh-CN-XiaoxiaoNeural    # Chinese female
  
python -m md2ppt presentation.md --format video --generate-tts \
  --tts-voice zh-CN-YunxiNeural       # Chinese male
  
python -m md2ppt presentation.md --format video --generate-tts \
  --tts-voice en-US-AriaNeural        # English female
```

### 📱 Platform-Optimized Video

```bash
# YouTube format (1920x1080, 30fps)
python -m md2ppt presentation.md --format video --video-platform youtube

# TikTok/Douyin format (1080x1920, 30fps, vertical)
python -m md2ppt presentation.md --format video --video-platform tiktok

# Bilibili format (1920x1080, 60fps)
python -m md2ppt presentation.md --format video --video-platform bilibili

# WeChat Video format (1080x1920, 30fps)
python -m md2ppt presentation.md --format video --video-platform wechat_video

# 4K format (3840x2160, 30fps)
python -m md2ppt presentation.md --format video --video-platform 4k
```

### 📁 Multi-format Output

```bash
# Generate all formats at once
python -m md2ppt presentation.md --format all --enable-animations --generate-tts

# Output files created:
# ├── presentation.pptx  (PowerPoint presentation)
# ├── presentation.html  (Interactive web slideshow)
# ├── presentation.mp4   (Video with voice narration)
# └── presentation.srt   (Subtitle file)

# Choose specific format
python -m md2ppt presentation.md --format pptx   # PowerPoint only
python -m md2ppt presentation.md --format html   # HTML only
python -m md2ppt presentation.md --format video  # Video only
```

### 🎵 Audio Enhancement

```bash
# Add background music to video
python -m md2ppt presentation.md --format video --generate-tts \
  --background-music background.mp3

# Create preview version (shorter duration)
python -m md2ppt presentation.md --format video --create-preview
```

### 🛠️ Complete Example

```bash
# Full-featured conversion with all v2 capabilities and native PowerPoint animations
python -m md2ppt my_presentation.md \
  --format all \
  --theme blue \
  --enable-animations \
  --animation-engine aspose \
  --generate-tts \
  --tts-voice zh-CN-XiaoxiaoNeural \
  --video-platform youtube \
  --background-music bgm.mp3 \
  --image-width-ratio 0.8 \
  --verbose \
  -o custom_output_name

# This creates a complete multimedia presentation package:
# - Professional PowerPoint with native animations (Aspose.Slides)
# - Interactive HTML with web animations (Reveal.js)
# - YouTube-optimized video with Chinese voice narration
# - Synchronized subtitles
# - Background music integration
```

### 🚀 Server Modes

```bash
# Start REST API server
python -m md2ppt --api
# Access at: http://localhost:8000
# API docs: http://localhost:8000/docs

# Start MCP server for AI integration
python -m md2ppt --mcp

# Custom API port
python -m uvicorn api.app:app --port 8001
```

### ❓ Help and Version

```bash
# Show all available options
python -m md2ppt --help

# Show version
python -m md2ppt --version

# List available themes
python -m md2ppt --help | grep -A5 "theme"
```

### 📋 Command Reference

| Option | Description | Example |
|--------|-------------|---------|
| `input_file` | Markdown file to convert | `presentation.md` |
| `-o, --output` | Output filename | `-o slides.pptx` |
| `--theme` | Presentation theme | `--theme blue` |
| `--format` | Output format | `--format all` |
| `--enable-animations` | Enable animation support | Flag only |
| `--generate-tts` | Generate voice narration | Flag only |
| `--tts-voice` | Voice selection | `--tts-voice zh-CN-XiaoxiaoNeural` |
| `--video-platform` | Platform optimization | `--video-platform youtube` |
| `--background-music` | Background audio | `--background-music music.mp3` |
| `--create-preview` | Create short preview | Flag only |
| `--image-width-ratio` | Image size control | `--image-width-ratio 0.8` |
| `--verbose` | Detailed output | Flag only |

## 🤖 AI Integration

### 📚 Quick AI Demo

```bash
# See available AI templates
python scripts/quick_ai_demo.py

# Demo education scenario
python scripts/quick_ai_demo.py --demo education

# Demo business scenario with video
python scripts/quick_ai_demo.py --demo business --format video
```

### 🎯 Using AI Templates

1. **Choose a scenario template:**
   - Education: `ai_integration/prompt_templates/scenario_specific/education_template.md`
   - Business: `ai_integration/prompt_templates/scenario_specific/business_template.md`
   - Tech: `ai_integration/prompt_templates/scenario_specific/tech_template.md`

2. **Use with your AI model** (ChatGPT, Claude, etc.)

3. **Convert AI-generated content:**
```bash
# Save AI output to file
echo "AI-generated Markdown content" > ai_content.md

# Convert with appropriate settings
python -m md2ppt ai_content.md --format all --enable-animations --generate-tts
```

### API Server

```bash
# Start API server
python -m md2ppt --api

# API available at http://localhost:8000
# Documentation at http://localhost:8000/docs
```

### MCP Server

```bash
# Start MCP server for AI assistants
python -m md2ppt --mcp
```

### Docker

```bash
# Quick start with Docker
docker-compose -f config/docker/docker-compose.yml up -d
```

## 📖 Documentation

- [📘 **Installation Guide**](docs/installation.md)
- [🔧 **API Reference**](docs/api-reference.md)
- [🤖 **MCP Integration**](docs/mcp-integration.md)
- [🚀 **Deployment Guide**](docs/deployment.md)
- [🏗️ **Architecture**](docs/architecture.md)

## 🎯 Use Cases

- **Technical Presentations**: Convert technical documentation to slides
- **API Integration**: Embed in web applications
- **AI Assistants**: Integrate with Claude, ChatGPT, etc.
- **Automation**: Batch convert documentation to presentations
- **Team Workflows**: Standardize presentation creation

## 📋 Example

**Input Markdown:**
```markdown
# My Presentation

## Introduction
- Welcome to MD2PPT
- Easy conversion process
- Professional results

## Features
![Architecture](./diagram.png)

### Core Capabilities
- Multiple themes
- Video support
- API integration
```

**Output:** Professional PowerPoint presentation with proper formatting, themes, and media handling.

## 🛠️ Development

```bash
# Clone repository
git clone https://github.com/your-org/md2ppt.git
cd md2ppt

# Install development dependencies
pip install -e .[dev]

# Run tests
pytest

# Start development API server
python -m md2ppt --api
```

## 📊 Project Stats

- **Language**: Python 3.9+
- **Framework**: FastAPI (API), MCP (AI Integration)
- **Testing**: 91% test coverage
- **Architecture**: Modular, extensible design
- **Deployment**: Docker, cloud-ready

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [python-pptx](https://github.com/scanny/python-pptx) for PowerPoint generation
- [FastAPI](https://fastapi.tiangolo.com/) for the API framework
- [MCP](https://modelcontextprotocol.io/) for AI assistant integration