Hugging Face's logo

Spaces:
shiva0013
/
YT-AI-Automation
Running

App Files Community
YT-AI-Automation / backend /docs /POWERPOINT_AUTOMATION.md
github-actions
Sync Docker Space
5f3e9f5
preview code
|
raw
history blame contribute delete
17.2 kB

PowerPoint Automation Guide

Transform your AI-generated screenshots into professional 4K video presentations automatically using PowerPoint's native video export capabilities.

Overview

The PowerPoint Automation feature extends Screenshot Studio with the ability to:

  • Automatically create PowerPoint presentations from generated images
  • Configure slide timings and transitions
  • Export presentations as high-quality 4K videos (3840x2160, MP4 format)
  • Monitor progress in real-time
  • Manage operations through a simple web interface

System Requirements

Operating System

  • Windows 10 or later
  • Windows Server 2016 or later
  • Not supported: macOS, Linux (requires Windows COM automation)

Software Requirements

  • Microsoft PowerPoint 2016 or later (must be installed and licensed)
  • Python 3.8 or later
  • 8GB RAM minimum (16GB recommended for 4K export)
  • 10GB free disk space for temporary files and output

Python Dependencies

  • python-pptx==0.6.23 - PowerPoint file manipulation
  • pywin32==306 - Windows COM automation
  • All other dependencies from requirements.txt

Installation

1. Install Python Dependencies 

pip install -r requirements.txt

This installs python-pptx and pywin32 along with other required packages.

2. Run pywin32 Post-Install Script

After installing pywin32, you must run the post-install script to register COM components:

python Scripts/pywin32_postinstall.py -install

Note: On some systems, the script may be in a different location:

python -m pywin32_postinstall -install

3. Verify PowerPoint Installation

Test that PowerPoint is accessible via COM automation:

python -c "import win32com.client; ppt = win32com.client.Dispatch('PowerPoint.Application'); print('PowerPoint version:', ppt.Version); ppt.Quit()"

Expected output: PowerPoint version: 16.0 (or similar)

If you see an error, ensure:

  • PowerPoint is installed and licensed
  • You ran the pywin32 post-install script
  • You're running on Windows

4. Create Required Directories

The application will create these automatically, but you can create them manually:

mkdir output\presentations
mkdir output\videos
mkdir templates\powerpoint

5. Configure Settings

Edit config/config.py to customize PowerPoint settings (optional):

# PowerPoint Automation Settings
POWERPOINT_ENABLED = True
POWERPOINT_TEMPLATE_PATH = "templates/powerpoint/default.pptx"
POWERPOINT_OUTPUT_FOLDER = "output/presentations"
POWERPOINT_VIDEO_FOLDER = "output/videos"

# Slide Settings
DEFAULT_SLIDE_DURATION = 3.0  # Seconds per slide
DEFAULT_TRANSITION_TYPE = "fade"  # fade, push, wipe, none
DEFAULT_TRANSITION_DURATION = 0.5  # Seconds for transition

# Video Export Settings
VIDEO_RESOLUTION_WIDTH = 3840  # 4K width
VIDEO_RESOLUTION_HEIGHT = 2160  # 4K height
VIDEO_FPS = 30  # Frames per second
VIDEO_QUALITY = 5  # 1-5, where 5 is highest quality

Configuration Options

Slide Settings

DEFAULT_SLIDE_DURATION (float)

  • Duration each slide displays in seconds
  • Default: 3.0
  • Range: 0.5 to 30.0
  • Example: 5.0 for 5 seconds per slide

DEFAULT_TRANSITION_TYPE (string)

  • Type of transition between slides
  • Default: "fade"
  • Options: "fade", "push", "wipe", "none"

DEFAULT_TRANSITION_DURATION (float)

  • Duration of transition animation in seconds
  • Default: 0.5
  • Range: 0.1 to 3.0

Video Export Settings

VIDEO_RESOLUTION_WIDTH / VIDEO_RESOLUTION_HEIGHT (int)

  • Video resolution in pixels
  • Default: 3840 x 2160 (4K)
  • Common options:
    • 4K: 3840 x 2160
    • 1080p: 1920 x 1080
    • 720p: 1280 x 720

VIDEO_FPS (int)

  • Frames per second for video
  • Default: 30
  • Options: 24, 30, 60

VIDEO_QUALITY (int)

  • Video encoding quality
  • Default: 5 (highest)
  • Range: 1 (lowest) to 5 (highest)
  • Higher quality = larger file size

Image Insertion Settings

IMAGE_FIT_MODE (string)

  • How images fit within slides
  • Default: "contain"
  • Options:
    • "contain" - Fit entire image, preserve aspect ratio
    • "cover" - Fill slide, may crop image
    • "fill" - Stretch to fill slide

IMAGE_POSITION (string)

  • Image alignment on slide
  • Default: "center"
  • Options: "center", "top", "bottom"

PRESERVE_ASPECT_RATIO (bool)

  • Whether to maintain image aspect ratios
  • Default: True
  • Set to False to allow stretching

API Endpoints

1. Upload Template

Upload a PowerPoint template file to use for presentation creation.

Endpoint: POST /api/powerpoint/upload-template

Request: Multipart form data

const formData = new FormData();
formData.append('template', templateFile);

fetch('/api/powerpoint/upload-template', {
    method: 'POST',
    body: formData
});

Response:

{
    "success": true,
    "template_path": "templates/powerpoint/my_template.pptx"
}

2. Create Presentation

Create a PowerPoint presentation from images in a folder.

Endpoint: POST /api/powerpoint/create

Request Body:

{
    "template_path": "templates/powerpoint/default.pptx",
    "image_folder": "output/screenshots",
    "slide_duration": 3.0,
    "transition_type": "fade"
}

Response:

{
    "success": true,
    "presentation_path": "output/presentations/presentation_20240101_120000.pptx",
    "operation_id": "create_1704110400000"
}

3. Export Video

Export an existing PowerPoint presentation to 4K video.

Endpoint: POST /api/powerpoint/export-video

Request Body:

{
    "presentation_path": "output/presentations/presentation.pptx",
    "resolution": [3840, 2160],
    "fps": 30,
    "quality": 5
}

Response:

{
    "success": true,
    "video_path": "output/videos/video_20240101_120000.mp4",
    "operation_id": "export_1704110400000"
}

4. Create and Export (Combined)

Create presentation and export to video in one operation.

Endpoint: POST /api/powerpoint/create-and-export

Request Body:

{
    "template_path": "templates/powerpoint/default.pptx",
    "image_folder": "output/screenshots",
    "slide_duration": 3.0,
    "transition_type": "fade",
    "video_resolution": [3840, 2160],
    "video_fps": 30,
    "video_quality": 5
}

Response:

{
    "success": true,
    "presentation_path": "output/presentations/presentation_20240101_120000.pptx",
    "video_path": "output/videos/video_20240101_120000.mp4",
    "operation_id": "create_and_export_1704110400000"
}

5. Monitor Progress

Stream real-time progress updates using Server-Sent Events (SSE).

Endpoint: GET /api/powerpoint/progress/<operation_id>

Usage:

const eventSource = new EventSource(`/api/powerpoint/progress/${operationId}`);

eventSource.addEventListener('slide_inserted', (e) => {
    const data = JSON.parse(e.data);
    console.log(`Slide ${data.slide_number} of ${data.total_slides}`);
});

eventSource.addEventListener('video_export_started', (e) => {
    console.log('Video export started...');
});

eventSource.addEventListener('completed', (e) => {
    const data = JSON.parse(e.data);
    console.log('Completed!', data);
    eventSource.close();
});

eventSource.addEventListener('error', (e) => {
    const data = JSON.parse(e.data);
    console.error('Error:', data.error_message);
    eventSource.close();
});

Event Types:

  • slide_inserted - A slide was added to the presentation
  • video_export_started - Video export has begun
  • video_export_progress - Video export progress update (if available)
  • completed - Operation finished successfully
  • error - Operation failed with error

6. Validate Template

Check if a PowerPoint template file is valid before using it.

Endpoint: POST /api/powerpoint/validate-template

Request Body:

{
    "template_path": "templates/powerpoint/my_template.pptx"
}

Response:

{
    "valid": true,
    "slide_count": 1,
    "layout_info": {
        "slide_width": 9144000,
        "slide_height": 6858000,
        "layout_names": ["Title Slide", "Content"]
    }
}

UI Usage

Basic Workflow

  1. Generate Screenshots

    • Use the Text-to-Image or HTML-to-Image features to create screenshots
    • Screenshots are saved to output/screenshots/

  2. Open PowerPoint Panel

    • Scroll to the PowerPoint Automation section in the UI
    • The panel contains all PowerPoint controls

  3. Upload Template (Optional)

    • Click "Choose File" to select a .pptx template
    • Click "Validate" to check if the template is valid
    • Or use the default template

  4. Configure Settings

    • Slide Duration: How long each slide displays (seconds)
    • Transition Type: Animation between slides
    • Video Quality: 1 (lowest) to 5 (highest)

  5. Create Presentation

    • Click "Create Presentation" to generate .pptx file only
    • Or click "Create & Export Video" to generate both .pptx and .mp4

  6. Monitor Progress

    • Progress bar shows current operation status
    • Status text displays detailed progress information
    • Download links appear when complete

Advanced Options

Custom Image Folder

  • By default, uses output/screenshots/
  • Can specify different folder via API

Custom Output Paths

  • Presentations saved to output/presentations/
  • Videos saved to output/videos/
  • Filenames include timestamp for uniqueness

Template Customization

  • Create custom .pptx templates with your branding
  • Templates should have at least one slide layout
  • Images will be inserted as new slides

Troubleshooting

PowerPoint Not Found

Error: PowerPointNotFoundError: PowerPoint is not installed or not accessible

Solutions:

  1. Verify PowerPoint is installed: Open PowerPoint manually
  2. Check PowerPoint version: Must be 2016 or later
  3. Verify license: PowerPoint must be activated
  4. Run as Administrator: Some COM operations require elevated privileges
  5. Re-run pywin32 post-install: python -m pywin32_postinstall -install

COM Automation Errors

Error: pywintypes.com_error: (-2147221005, 'Invalid class string', None, None)

Solutions:

  1. Re-register COM components:
    python -m pywin32_postinstall -install
  2. Restart your computer
  3. Check Windows Event Viewer for COM errors
  4. Ensure no other process is using PowerPoint

Video Export Timeout

Error: ExportError: Video export operation timed out

Solutions:

  1. Reduce video quality setting (try 3 instead of 5)
  2. Reduce resolution (try 1080p instead of 4K)
  3. Reduce number of slides (split into multiple videos)
  4. Close other applications to free up CPU/RAM
  5. Check disk space (video export requires significant space)

Template Validation Fails

Error: TemplateError: Template file is invalid or corrupted

Solutions:

  1. Open template in PowerPoint manually to verify it works
  2. Save template as .pptx (not .ppt or .pptm)
  3. Remove macros from template (save as .pptx, not .pptm)
  4. Create new template from scratch
  5. Use the default template provided

Out of Memory

Error: MemoryError or system becomes unresponsive during video export

Solutions:

  1. Close other applications
  2. Reduce video resolution
  3. Reduce video quality setting
  4. Process fewer slides at once
  5. Upgrade RAM (16GB recommended for 4K)

Permission Denied

Error: PermissionError: [Errno 13] Permission denied

Solutions:

  1. Close PowerPoint if it's open
  2. Check file isn't open in another program
  3. Run application as Administrator
  4. Check antivirus isn't blocking file access
  5. Verify write permissions on output folders

Slow Video Export

Issue: Video export takes very long (>10 minutes)

Solutions:

  1. This is normal for 4K video with many slides
  2. Reduce resolution to 1080p for faster export
  3. Reduce video quality setting
  4. Use fewer slides per video
  5. Upgrade CPU (video encoding is CPU-intensive)

Images Not Appearing in Slides

Issue: Presentation created but slides are blank

Solutions:

  1. Verify images exist in the specified folder
  2. Check image file formats (PNG, JPG, JPEG supported)
  3. Ensure images aren't corrupted (open manually)
  4. Check file permissions on image folder
  5. Verify image paths don't contain special characters

Performance Considerations

Presentation Creation

  • Speed: ~0.2 seconds per slide
  • 10 slides: ~2 seconds
  • 50 slides: ~10 seconds

Video Export (4K, Quality 5)

  • Speed: Varies by CPU and slide count
  • 1 minute video (20 slides @ 3s each): 3-5 minutes
  • 2 minute video (40 slides @ 3s each): 6-10 minutes
  • 5 minute video (100 slides @ 3s each): 15-25 minutes

File Sizes

  • Presentation (.pptx): 5-20MB for 10-50 slides
  • 4K Video (Quality 5): 50-100MB per minute
  • 1080p Video (Quality 5): 20-40MB per minute

Optimization Tips

  1. Use 1080p for faster export: 4K takes 2-3x longer
  2. Lower quality for drafts: Use quality 3 for testing
  3. Batch operations: Process multiple sets separately
  4. Monitor resources: Close unnecessary applications
  5. SSD recommended: Faster disk I/O improves performance

Best Practices

Template Design

  1. Keep it simple: Complex templates may cause issues
  2. Test first: Validate template before production use
  3. Standard layouts: Use PowerPoint's built-in layouts
  4. No macros: Save as .pptx, not .pptm
  5. Backup templates: Keep copies of working templates

Image Preparation

  1. Consistent sizing: Use same dimensions for all images
  2. High resolution: Use at least 1920x1080 for best quality
  3. Proper naming: Use numeric prefixes for ordering (1_image.png, 2_image.png)
  4. Supported formats: PNG and JPEG recommended
  5. Optimize files: Compress images to reduce file size

Video Production

  1. Test with small sets: Create short videos first
  2. Monitor progress: Watch for errors during export
  3. Verify output: Check video plays correctly
  4. Archive source files: Keep .pptx files for re-export
  5. Plan for time: Allow sufficient time for 4K export

Error Handling

  1. Check logs: Review console output for errors
  2. Retry on failure: Transient errors may resolve on retry
  3. Validate inputs: Use template validation before operations
  4. Clean up: Remove partial files after errors
  5. Report issues: Note error messages for troubleshooting

Limitations

Platform

  • Windows only: Requires Windows COM automation
  • PowerPoint required: Must have PowerPoint installed
  • No cloud support: Cannot run on Linux servers

Performance

  • CPU intensive: Video export uses significant CPU
  • Memory intensive: 4K export requires substantial RAM
  • Time consuming: Large videos take many minutes
  • Disk space: Temporary files can be large

Features

  • No audio: Videos are silent (no background music)
  • No animations: Slide content is static
  • Limited transitions: Basic transitions only
  • No text overlays: Cannot add captions automatically
  • Sequential processing: One operation at a time recommended

Security Considerations

File Upload

  • Template files are validated for .pptx extension
  • File size limited to 50MB
  • Files stored in isolated directory
  • Path traversal protection enabled

Resource Limits

  • Maximum 2 concurrent operations
  • Video export timeout: 30 minutes
  • Disk space checked before operations
  • Memory usage monitored

COM Security

  • PowerPoint runs with user privileges
  • COM objects properly cleaned up
  • Exceptions handled to prevent crashes
  • Logging enabled for audit trail

Future Enhancements

Planned features for future releases:

  1. Audio Support: Add background music or narration
  2. Text Overlays: Automatic captions and titles
  3. Batch Processing: Process multiple image sets in parallel
  4. Cloud Export: Direct upload to YouTube, Vimeo
  5. Template Library: Built-in professional templates
  6. Preview Generation: Thumbnail previews before export
  7. Custom Animations: Support for slide animations
  8. Multi-Resolution: Export multiple resolutions simultaneously
  9. Progress Estimation: More accurate time estimates
  10. Template Editor: Web-based template customization

Support

Getting Help

  • Check this documentation first
  • Review troubleshooting section
  • Check console logs for error messages
  • Verify system requirements are met

Reporting Issues

When reporting issues, include:

  • Windows version
  • PowerPoint version
  • Python version
  • Error message (full text)
  • Steps to reproduce
  • Console log output

Additional Resources

Last Updated: 2024
Version: 1.0
Status: Production Ready