Release v1.9.0: Add video-comparer skill and enhance transcript-fixer

## New Skill: video-comparer v1.0.0 - Compare original and compressed videos with interactive HTML reports - Calculate quality metrics (PSNR, SSIM) for compression analysis - Generate frame-by-frame visual comparisons (slider, side-by-side, grid) - Extract video metadata (codec, resolution, bitrate, duration) - Multi-platform FFmpeg support with security features ## transcript-fixer Enhancements - Add async AI processor for parallel processing - Add connection pool management for database operations - Add concurrency manager and rate limiter - Add audit log retention and database migrations - Add health check and metrics monitoring - Add comprehensive test suite (8 new test files) - Enhance security with domain and path validators ## Marketplace Updates - Update marketplace version from 1.8.0 to 1.9.0 - Update skills count from 15 to 16 - Update documentation (README.md, CLAUDE.md, CHANGELOG.md) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-30 00:23:12 +08:00
parent bd0aa12004
commit 9b724f33e3
49 changed files with 15357 additions and 270 deletions
--- a/video-comparer/references/configuration.md
+++ b/video-comparer/references/configuration.md
@@ -0,0 +1,213 @@
+# Script Configuration Reference
+
+## Contents
+
+- [Adjustable Constants](#adjustable-constants) - Modifying script behavior
+- [File Processing Limits](#file-processing-limits) - Size and timeout constraints
+- [Frame Extraction Settings](#frame-extraction-settings) - Visual comparison parameters
+- [Configuration Impact](#configuration-impact) - Performance and quality tradeoffs
+
+## Adjustable Constants
+
+All configuration constants are defined at the top of `scripts/compare.py`:
+
+```python
+ALLOWED_EXTENSIONS = {'.mp4', '.mov', '.avi', '.mkv', '.webm'}
+MAX_FILE_SIZE_MB = 500          # Maximum file size per video
+FFMPEG_TIMEOUT = 300            # FFmpeg timeout (seconds) - 5 minutes
+FFPROBE_TIMEOUT = 30            # FFprobe timeout (seconds) - 30 seconds
+BASE_FRAME_HEIGHT = 800         # Frame height for comparison (pixels)
+FRAME_INTERVAL = 5              # Default extraction interval (seconds)
+```
+
+## File Processing Limits
+
+### MAX_FILE_SIZE_MB
+
+**Default:** 500 MB
+
+**Purpose:** Prevents memory exhaustion when processing very large videos.
+
+**When to increase:**
+- Working with high-resolution or long-duration source videos
+- System has ample RAM (16GB+)
+- Processing 4K or 8K content
+
+**When to decrease:**
+- Limited system memory
+- Processing on lower-spec machines
+- Batch processing many videos simultaneously
+
+**Impact:** No effect on output quality, only determines which files can be processed.
+
+### FFMPEG_TIMEOUT
+
+**Default:** 300 seconds (5 minutes)
+
+**Purpose:** Prevents FFmpeg operations from hanging indefinitely.
+
+**When to increase:**
+- Processing very long videos (>1 hour)
+- Extracting many frames (small `--interval` value)
+- Slow storage (network drives, external HDDs)
+- High-resolution videos (4K, 8K)
+
+**Recommended values:**
+- Short videos (<10 min): 120 seconds
+- Medium videos (10-60 min): 300 seconds (default)
+- Long videos (>60 min): 600-900 seconds
+
+**Impact:** Operation fails if exceeded; does not affect output quality.
+
+### FFPROBE_TIMEOUT
+
+**Default:** 30 seconds
+
+**Purpose:** Prevents metadata extraction from hanging.
+
+**When to increase:**
+- Accessing videos over slow network connections
+- Processing files with complex codec structures
+- Corrupt or malformed video files
+
+**Typical behavior:** Metadata extraction usually completes in <5 seconds; longer times suggest file issues.
+
+**Impact:** Operation fails if exceeded; does not affect output quality.
+
+## Frame Extraction Settings
+
+### BASE_FRAME_HEIGHT
+
+**Default:** 800 pixels
+
+**Purpose:** Standardizes frame dimensions for side-by-side comparison.
+
+**When to increase:**
+- Comparing high-resolution videos (4K, 8K)
+- Analyzing fine details or subtle compression artifacts
+- Generating reports for large displays
+
+**When to decrease:**
+- Faster processing and smaller HTML output files
+- Viewing reports on mobile devices or small screens
+- Limited bandwidth for sharing reports
+
+**Recommended values:**
+- Mobile/low-bandwidth: 480-600 pixels
+- Desktop viewing: 800 pixels (default)
+- High-detail analysis: 1080-1440 pixels
+- 4K/8K analysis: 2160+ pixels
+
+**Impact:** Higher values increase HTML file size and processing time but preserve more detail.
+
+### FRAME_INTERVAL
+
+**Default:** 5 seconds
+
+**Purpose:** Controls frame extraction frequency.
+
+**When to decrease (extract more frames):**
+- Analyzing fast-motion content
+- Detailed temporal analysis needed
+- Short videos where more samples help
+
+**When to increase (extract fewer frames):**
+- Long videos to reduce processing time
+- Reducing HTML output file size
+- Overview analysis (general quality check)
+
+**Recommended values:**
+- Fast-motion/detailed: 1-3 seconds
+- Standard analysis: 5 seconds (default)
+- Long-form content: 10-15 seconds
+- Quick overview: 30-60 seconds
+
+**Impact:**
+- Smaller intervals: More frames, larger HTML, longer processing, more comprehensive analysis
+- Larger intervals: Fewer frames, smaller HTML, faster processing, may miss transient artifacts
+
+## Configuration Impact
+
+### Processing Time
+
+Processing time is primarily affected by:
+1. Video duration
+2. `FRAME_INTERVAL` (smaller = more frames = longer processing)
+3. `BASE_FRAME_HEIGHT` (higher = more pixels = longer processing)
+4. System CPU/storage speed
+
+**Typical processing times:**
+- 5-minute video, 5s interval, 800px height: ~45-90 seconds
+- 30-minute video, 5s interval, 800px height: ~3-5 minutes
+- 60-minute video, 10s interval, 800px height: ~4-7 minutes
+
+### HTML Output Size
+
+HTML file size is primarily affected by:
+1. Number of extracted frames
+2. `BASE_FRAME_HEIGHT` (higher = larger base64-encoded images)
+3. Video complexity (detailed frames compress less efficiently)
+
+**Typical HTML sizes:**
+- 5-minute video, 5s interval, 800px: 5-10 MB
+- 30-minute video, 5s interval, 800px: 20-40 MB
+- 60-minute video, 10s interval, 800px: 30-50 MB
+
+### Quality vs Performance Tradeoffs
+
+**High Quality Configuration (detailed analysis):**
+```python
+MAX_FILE_SIZE_MB = 2000
+FFMPEG_TIMEOUT = 900
+BASE_FRAME_HEIGHT = 1440
+FRAME_INTERVAL = 2
+```
+Use case: Detailed quality analysis, archival comparison, professional codec evaluation
+
+**Balanced Configuration (default):**
+```python
+MAX_FILE_SIZE_MB = 500
+FFMPEG_TIMEOUT = 300
+BASE_FRAME_HEIGHT = 800
+FRAME_INTERVAL = 5
+```
+Use case: Standard compression analysis, typical desktop viewing
+
+**Fast Processing Configuration (quick overview):**
+```python
+MAX_FILE_SIZE_MB = 500
+FFMPEG_TIMEOUT = 180
+BASE_FRAME_HEIGHT = 600
+FRAME_INTERVAL = 10
+```
+Use case: Batch processing, quick quality checks, mobile viewing
+
+## Allowed File Extensions
+
+**Default:** `{'.mp4', '.mov', '.avi', '.mkv', '.webm'}`
+
+**Purpose:** Restricts input to known video formats.
+
+**When to modify:**
+- Adding support for additional container formats (e.g., `.flv`, `.m4v`, `.wmv`)
+- Restricting to specific formats for workflow standardization
+
+**Note:** Adding extensions does not guarantee compatibility; FFmpeg must support the codec/container.
+
+## Security Considerations
+
+**Do NOT modify:**
+- Path validation logic
+- Command execution methods (must avoid `shell=True`)
+- Exception handling patterns
+
+**Safe to modify:**
+- Numeric limits (file size, timeouts, dimensions)
+- Allowed file extensions (add formats supported by FFmpeg)
+- Output formatting preferences
+
+**Unsafe modifications:**
+- Removing path sanitization
+- Bypassing file validation
+- Enabling shell command interpolation
+- Disabling resource limits
--- a/video-comparer/references/ffmpeg_commands.md
+++ b/video-comparer/references/ffmpeg_commands.md
@@ -0,0 +1,155 @@
+# FFmpeg Commands Reference
+
+## Contents
+
+- [Video Metadata Extraction](#video-metadata-extraction) - Getting video properties with ffprobe
+- [Frame Extraction](#frame-extraction) - Extracting frames at intervals
+- [Quality Metrics Calculation](#quality-metrics-calculation) - PSNR, SSIM, VMAF calculations
+- [Video Information](#video-information) - Duration, resolution, frame rate, bitrate, codec queries
+- [Image Processing](#image-processing) - Scaling and format conversion
+- [Troubleshooting](#troubleshooting) - Debugging FFmpeg issues
+- [Performance Optimization](#performance-optimization) - Speed and resource management
+
+## Video Metadata Extraction
+
+### Basic Video Info
+```bash
+ffprobe -v quiet -print_format json -show_format -show_streams input.mp4
+```
+
+### Stream-specific Information
+```bash
+ffprobe -v quiet -select_streams v:0 -print_format json -show_format -show_streams input.mp4
+```
+
+### Get Specific Fields
+```bash
+ffprobe -v quiet -show_entries format=duration -show_entries stream=width,height,codec_name,r_frame_rate -of csv=p=0 input.mp4
+```
+
+## Frame Extraction
+
+### Extract Frames at Intervals
+```bash
+ffmpeg -i input.mp4 -vf "select='not(mod(t\,5))',setpts=N/FRAME_RATE/TB" -vsync 0 output_%03d.jpg
+```
+
+### Extract Every Nth Frame
+```bash
+ffmpeg -i input.mp4 -vf "select='not(mod(n\,150))',scale=-1:800" -vsync 0 -q:v 2 frame_%03d.jpg
+```
+
+### Extract Frames with Timestamp
+```bash
+ffmpeg -i input.mp4 -vf "fps=1/5,scale=-1:800" -q:v 2 frame_%05d.jpg
+```
+
+## Quality Metrics Calculation
+
+### PSNR Calculation
+```bash
+ffmpeg -i original.mp4 -i compressed.mp4 -lavfi "[0:v][1:v]psnr=stats_file=-" -f null -
+```
+
+### SSIM Calculation
+```bash
+ffmpeg -i original.mp4 -i compressed.mp4 -lavfi "[0:v][1:v]ssim=stats_file=-" -f null -
+```
+
+### Combined PSNR and SSIM
+```bash
+ffmpeg -i original.mp4 -i compressed.mp4 -lavfi '[0:v][1:v]psnr=stats_file=-;[0:v][1:v]ssim=stats_file=-' -f null -
+```
+
+### VMAF Calculation
+```bash
+ffmpeg -i original.mp4 -i compressed.mp4 -lavfi "[0:v][1:v]libvmaf=log_path=vmaf.log" -f null -
+```
+
+## Video Information
+
+### Get Video Duration
+```bash
+ffprobe -v quiet -show_entries format=duration -of csv=p=0 input.mp4
+```
+
+### Get Video Resolution
+```bash
+ffprobe -v quiet -show_entries stream=width,height -of csv=p=0 input.mp4
+```
+
+### Get Frame Rate
+```bash
+ffprobe -v quiet -show_entries stream=r_frame_rate -of csv=p=0 input.mp4
+```
+
+### Get Bitrate
+```bash
+ffprobe -v quiet -show_entries format=bit_rate -of csv=p=0 input.mp4
+```
+
+### Get Codec Information
+```bash
+ffprobe -v quiet -show_entries stream=codec_name,codec_type -of csv=p=0 input.mp4
+```
+
+## Image Processing
+
+### Scale to Fixed Height
+```bash
+ffmpeg -i input.jpg -vf "scale=-1:800" output.jpg
+```
+
+### Scale to Fixed Width
+```bash
+ffmpeg -i input.jpg -vf "scale=1200:-1" output.jpg
+```
+
+### High Quality JPEG
+```bash
+ffmpeg -i input.jpg -q:v 2 output.jpg
+```
+
+### Progressive JPEG
+```bash
+ffmpeg -i input.jpg -q:v 2 -progressive output.jpg
+```
+
+## Troubleshooting
+
+### Check FFmpeg Version
+```bash
+ffmpeg -version
+```
+
+### Check Available Filters
+```bash
+ffmpeg -filters
+```
+
+### Test Video Decoding
+```bash
+ffmpeg -i input.mp4 -f null -
+```
+
+### Extract First Frame
+```bash
+ffmpeg -i input.mp4 -vframes 1 -q:v 2 first_frame.jpg
+```
+
+## Performance Optimization
+
+### Use Multiple Threads
+```bash
+ffmpeg -threads 4 -i input.mp4 -c:v libx264 -preset fast output.mp4
+```
+
+### Set Timeout
+```bash
+timeout 300 ffmpeg -i input.mp4 -c:v libx264 output.mp4
+```
+
+### Limit Memory Usage
+```bash
+ffmpeg -i input.mp4 -c:v libx264 -x264-params threads=2:ref=3 output.mp4
+```
--- a/video-comparer/references/video_metrics.md
+++ b/video-comparer/references/video_metrics.md
@@ -0,0 +1,97 @@
+# Video Quality Metrics Reference
+
+## Contents
+
+- [PSNR (Peak Signal-to-Noise Ratio)](#psnr-peak-signal-to-noise-ratio) - Pixel-level similarity measurement
+- [SSIM (Structural Similarity Index)](#ssim-structural-similarity-index) - Perceptual quality measurement
+- [VMAF (Video Multimethod Assessment Fusion)](#vmaf-video-multimethod-assessment-fusion) - Machine learning-based quality prediction
+- [File Size and Bitrate Considerations](#file-size-and-bitrate-considerations) - Compression targets and guidelines
+
+## PSNR (Peak Signal-to-Noise Ratio)
+
+### Definition
+PSNR measures the ratio between the maximum possible power of a signal and the power of corrupting noise. It's commonly used to measure the quality of reconstruction of lossy compression codecs.
+
+### Scale
+- **Range**: Typically 20-50 dB
+- **Higher is better**: More signal, less noise
+
+### Quality Interpretation
+| PSNR (dB) | Quality Level | Use Case |
+|-----------|---------------|----------|
+| < 20 | Poor | Unacceptable for most applications |
+| 20-25 | Low | Acceptable for very low-bandwidth scenarios |
+| 25-30 | Fair | Basic video streaming |
+| 30-35 | Good | Standard streaming quality |
+| 35-40 | Very Good | High-quality streaming |
+| 40+ | Excellent | Near-lossless quality, archival |
+
+### Calculation Formula
+```
+PSNR = 10 * log10(MAX_I^2 / MSE)
+```
+Where:
+- MAX_I = maximum pixel value (255 for 8-bit images)
+- MSE = mean squared error
+
+## SSIM (Structural Similarity Index)
+
+### Definition
+SSIM is a perceptual metric that quantifies image quality degradation based on structural information changes rather than pixel-level differences.
+
+### Scale
+- **Range**: 0.0 to 1.0
+- **Higher is better**: More structural similarity
+
+### Quality Interpretation
+| SSIM | Quality Level | Use Case |
+|------|---------------|----------|
+| < 0.70 | Poor | Visible artifacts, structural damage |
+| 0.70-0.80 | Fair | Noticeable quality loss |
+| 0.80-0.90 | Good | Acceptable for most streaming |
+| 0.90-0.95 | Very Good | High-quality streaming |
+| 0.95-0.98 | Excellent | Near-identical perception |
+| 0.98+ | Perfect | Indistinguishable from original |
+
+### Components
+SSIM combines three comparisons:
+1. **Luminance**: Local brightness comparisons
+2. **Contrast**: Local contrast comparisons
+3. **Structure**: Local structure correlations
+
+## VMAF (Video Multimethod Assessment Fusion)
+
+### Definition
+VMAF is a machine learning-based metric that predicts subjective video quality by combining multiple quality metrics.
+
+### Scale
+- **Range**: 0-100
+- **Higher is better**: Better perceived quality
+
+### Quality Interpretation
+| VMAF | Quality Level | Use Case |
+|-------|---------------|----------|
+| < 20 | Poor | Unacceptable |
+| 20-40 | Low | Basic streaming |
+| 40-60 | Fair | Standard streaming |
+| 60-80 | Good | High-quality streaming |
+| 80-90 | Very Good | Premium streaming |
+| 90+ | Excellent | Reference quality |
+
+## File Size and Bitrate Considerations
+
+### Compression Targets by Use Case
+| Use Case | Size Reduction | PSNR Target | SSIM Target |
+|----------|----------------|-------------|-------------|
+| Social Media | 40-60% | 35-40 dB | 0.95-0.98 |
+| Streaming | 50-70% | 30-35 dB | 0.90-0.95 |
+| Archival | 20-40% | 40+ dB | 0.98+ |
+| Mobile | 60-80% | 25-30 dB | 0.85-0.90 |
+
+### Bitrate Guidelines
+| Resolution | Target Bitrate (1080p equivalent) |
+|------------|-----------------------------------|
+| 480p | 1-2 Mbps |
+| 720p | 2-5 Mbps |
+| 1080p | 5-10 Mbps |
+| 4K | 20-50 Mbps |