[Phase 1] Document JSON Editing Step System

[aserranoni]

Overview

Document the complete JSON-based editing step system that powers ShortGPT's video editing capabilities.

Background

The editing framework uses 16+ predefined JSON steps located in shortGPT/editing_framework/editing_steps/ but lacks comprehensive documentation. Understanding and documenting this system is critical for future enhancements.

Objectives

• Document all 16 existing editing steps with complete parameter descriptions
• Create JSON schema definitions for validation
• Document the z-ordering and layering system
• Explain the actions vs parameters distinction
• Document timing and synchronization mechanisms

Technical Details

Files to Analyze

• shortGPT/editing_framework/editing_engine.py
• shortGPT/editing_framework/editing_steps/*.json
• shortGPT/editing_framework/core_editing_engine.py

Expected Documentation Structure

1. Overview: How the editing engine processes JSON steps
2. Step Types: Visual vs Audio assets
3. Parameter Reference: Complete list with types and examples
4. Action System: How actions modify step behavior
5. Layering: Z-order and composition rules
6. Examples: Real-world usage patterns

Deliverables

• Complete markdown documentation in docs/editing_framework.md
• JSON schema files for validation
• Example JSON files demonstrating complex edits
• Inline code documentation improvements

Acceptance Criteria

• All 16 steps fully documented
• JSON schemas validate existing step files
• Documentation includes visual diagrams
• Examples are runnable and tested

Team Assignment

Lead: Editing Framework Expert
Support: Documentation Specialist

Priority

🔴 HIGH - Blocking other editing framework improvements

Labels

• documentation
• editing-framework
• phase-1
• high-priority