@vodailoc/kilo-kit-mcp 1.1.0 → 1.2.0

package/skills/ai-media/media-processing/references/format-compatibility.md

@@ -1,375 +1,375 @@
-# Format Compatibility & Conversion Guide
-
-Complete guide to media format support, codec recommendations, and conversion best practices.
-
-## Image Format Support
-
-### ImageMagick Formats
-
-**Raster Formats (Full Support):**
-- JPEG (.jpg, .jpeg) - Lossy, universal
-- PNG (.png) - Lossless, transparency
-- WebP (.webp) - Modern, lossy/lossless
-- GIF (.gif) - Animation, limited colors
-- TIFF (.tif, .tiff) - Professional, lossless
-- BMP (.bmp) - Uncompressed, legacy
-- ICO (.ico) - Icons, multi-size
-
-**Raw Formats (Read Support):**
-- CR2, NEF, ARW, DNG (Canon, Nikon, Sony, Adobe RAW)
-- Requires dcraw or ufraw-batch
-
-**Vector Formats (Limited):**
-- SVG (.svg) - Read only, converts to raster
-- PDF (.pdf) - Read/write, may have policy restrictions
-
-**Other Formats:**
-- HEIC (.heic) - Apple format, requires libheif
-- AVIF (.avif) - Next-gen, requires libavif
-- PSD (.psd) - Photoshop, basic support
-
-### FFmpeg Image Support
-
-**Input Formats:**
-- JPEG, PNG, BMP, TIFF, WebP, GIF
-- Image sequences (frame_%04d.png)
-
-**Output Formats:**
-- JPEG, PNG, BMP, TIFF
-- Video from images
-
-## Video Format Support
-
-### Container Formats
-
-**Universal Containers:**
-- MP4 (.mp4) - Most compatible, streaming
-- MKV (.mkv) - Feature-rich, flexible
-- WebM (.webm) - Web-optimized, open
-- AVI (.avi) - Legacy, broad support
-- MOV (.mov) - Apple, professional
-
-**Streaming Containers:**
-- TS (.ts) - Transport stream, HLS segments
-- M3U8 (.m3u8) - HLS playlist
-- MPD (.mpd) - DASH manifest
-- FLV (.flv) - Flash (legacy)
-
-**Professional Formats:**
-- ProRes (.mov) - Apple professional
-- DNxHD/DNxHR (.mxf, .mov) - Avid professional
-- MXF (.mxf) - Broadcast
-
-### Video Codecs
-
-**Modern Codecs:**
-- H.264/AVC (libx264) - Universal, excellent balance
-- H.265/HEVC (libx265) - Better compression, 4K
-- VP9 (libvpx-vp9) - Open, YouTube
-- AV1 (libaom-av1, libsvtav1) - Next-gen, best compression
-
-**Legacy Codecs:**
-- MPEG-4 (mpeg4) - Older devices
-- MPEG-2 (mpeg2video) - DVD, broadcast
-- VP8 (libvpx) - WebM predecessor
-
-**Professional Codecs:**
-- ProRes (prores) - Apple post-production
-- DNxHD (dnxhd) - Avid editing
-- Uncompressed (rawvideo) - Maximum quality
-
-### Audio Codecs
-
-**Modern Codecs:**
-- AAC (aac) - Universal, streaming
-- Opus (libopus) - Best low-bitrate
-- MP3 (libmp3lame) - Universal compatibility
-
-**Lossless Codecs:**
-- FLAC (flac) - Open, archival
-- ALAC (alac) - Apple lossless
-- WAV (pcm_s16le) - Uncompressed
-
-**Other Codecs:**
-- Vorbis (libvorbis) - Open, WebM
-- AC-3 (ac3) - Dolby Digital, surround
-- DTS (dts) - Cinema surround
-
-## Format Recommendations
-
-### Use Case Matrix
-
-| Use Case | Image Format | Video Container | Video Codec | Audio Codec |
-|----------|--------------|-----------------|-------------|-------------|
-| Web general | JPEG 85% | MP4 | H.264 | AAC 128k |
-| Web transparency | PNG | - | - | - |
-| Web modern | WebP | WebM | VP9 | Opus |
-| Social media | JPEG 85% | MP4 | H.264 | AAC 128k |
-| 4K streaming | - | MP4 | H.265 | AAC 192k |
-| Archive | PNG/TIFF | MKV | H.265 CRF 18 | FLAC |
-| Email | JPEG 75% | - | - | - |
-| Print | TIFF/PNG | - | - | - |
-| YouTube | - | MP4/WebM | H.264/VP9 | AAC/Opus |
-| Live stream | - | FLV | H.264 | AAC |
-| Editing | - | MOV/MXF | ProRes/DNxHD | PCM |
-
-### Platform Compatibility
-
-**Web Browsers (2025):**
-- Images: JPEG, PNG, WebP, GIF, SVG
-- Video: MP4 (H.264), WebM (VP9), MP4 (AV1)
-- Audio: AAC, MP3, Opus, Vorbis
-
-**Mobile Devices:**
-- iOS: JPEG, PNG, HEIC, MP4 (H.264/H.265), AAC
-- Android: JPEG, PNG, WebP, MP4 (H.264/H.265), AAC
-
-**Smart TVs:**
-- Most: MP4 (H.264), AAC
-- Modern: MP4 (H.265), AC-3
-
-**Social Media:**
-- All platforms: JPEG, MP4 (H.264), AAC
-
-## Quality vs Size Trade-offs
-
-### Image Quality Comparison
-
-**JPEG Quality Levels:**
-- 95-100: ~5-10 MB (large image), minimal artifacts
-- 85-94: ~1-3 MB, imperceptible loss
-- 75-84: ~500 KB-1 MB, slight artifacts
-- 60-74: ~200-500 KB, visible artifacts
-- Below 60: <200 KB, poor quality
-
-**Format Comparison (Same quality):**
-- WebP: 25-35% smaller than JPEG
-- HEIC: 40-50% smaller than JPEG
-- AVIF: 50-60% smaller than JPEG
-- PNG: 2-5x larger than JPEG (lossless)
-
-### Video Quality Comparison
-
-**H.264 CRF Values:**
-- CRF 18: Visually lossless, ~8-15 Mbps (1080p)
-- CRF 23: High quality, ~4-8 Mbps (1080p)
-- CRF 28: Medium quality, ~2-4 Mbps (1080p)
-
-**Codec Comparison (Same quality):**
-- H.265: 40-50% smaller than H.264
-- VP9: 30-40% smaller than H.264
-- AV1: 50-60% smaller than H.264
-
-### Audio Quality Comparison
-
-**AAC Bitrates:**
-- 320 kbps: Transparent, archival
-- 192 kbps: High quality, music
-- 128 kbps: Good quality, streaming
-- 96 kbps: Acceptable, low bandwidth
-- 64 kbps: Poor, voice only
-
-**Codec Efficiency (Same quality):**
-- Opus: Best at low bitrates (<128k)
-- AAC: Best overall balance
-- MP3: Less efficient but universal
-
-## Conversion Best Practices
-
-### Image Conversions
-
-**PNG to JPEG:**
-```bash
-# Standard conversion
-magick input.png -quality 85 -strip output.jpg
-
-# With transparency handling
-magick input.png -background white -flatten -quality 85 output.jpg
-```
-
-**JPEG to WebP:**
-```bash
-# FFmpeg
-ffmpeg -i input.jpg -quality 80 output.webp
-
-# ImageMagick
-magick input.jpg -quality 80 output.webp
-```
-
-**RAW to JPEG:**
-```bash
-# Requires dcraw
-magick input.CR2 -quality 90 output.jpg
-```
-
-**HEIC to JPEG:**
-```bash
-# Requires libheif
-magick input.heic -quality 85 output.jpg
-```
-
-### Video Conversions
-
-**MKV to MP4:**
-```bash
-# Copy streams (fast)
-ffmpeg -i input.mkv -c copy output.mp4
-
-# Re-encode if needed
-ffmpeg -i input.mkv -c:v libx264 -crf 23 -c:a aac output.mp4
-```
-
-**AVI to MP4:**
-```bash
-# Modern codecs
-ffmpeg -i input.avi -c:v libx264 -crf 23 -c:a aac output.mp4
-```
-
-**MOV to MP4:**
-```bash
-# Copy if H.264 already
-ffmpeg -i input.mov -c copy output.mp4
-
-# Convert ProRes to H.264
-ffmpeg -i input.mov -c:v libx264 -crf 18 -c:a aac output.mp4
-```
-
-**Any to WebM:**
-```bash
-# VP9 encoding
-ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 -c:a libopus output.webm
-```
-
-### Audio Conversions
-
-**Extract Audio from Video:**
-```bash
-# Keep original codec
-ffmpeg -i video.mp4 -vn -c:a copy audio.m4a
-
-# Convert to MP3
-ffmpeg -i video.mp4 -vn -q:a 0 audio.mp3
-
-# Convert to FLAC (lossless)
-ffmpeg -i video.mp4 -vn -c:a flac audio.flac
-```
-
-**Audio Format Conversion:**
-```bash
-# WAV to MP3
-ffmpeg -i input.wav -c:a libmp3lame -b:a 192k output.mp3
-
-# MP3 to AAC
-ffmpeg -i input.mp3 -c:a aac -b:a 192k output.m4a
-
-# Any to Opus
-ffmpeg -i input.wav -c:a libopus -b:a 128k output.opus
-```
-
-## Codec Selection Guide
-
-### Choose H.264 When:
-- Maximum compatibility needed
-- Targeting older devices
-- Streaming to unknown devices
-- Social media upload
-- Fast encoding required
-
-### Choose H.265 When:
-- 4K video encoding
-- Storage space limited
-- Modern device targets
-- Archival quality needed
-- Bandwidth constrained
-
-### Choose VP9 When:
-- YouTube upload
-- Open-source requirement
-- Chrome/Firefox primary
-- Royalty-free needed
-
-### Choose AV1 When:
-- Future-proofing content
-- Maximum compression needed
-- Encoding time not critical
-- Modern platform targets
-
-## Format Migration Strategies
-
-### Archive to Web
-
-```bash
-# High-res archive -> Web-optimized
-for img in archive/*.tif; do
-  base=$(basename "$img" .tif)
-  magick "$img" -resize 2000x2000\> -quality 85 -strip "web/${base}.jpg"
-  magick "$img" -resize 2000x2000\> -quality 85 "web/${base}.webp"
-done
-```
-
-### Legacy to Modern
-
-```bash
-# Convert old formats to modern codecs
-for video in legacy/*.avi; do
-  base=$(basename "$video" .avi)
-  ffmpeg -i "$video" \
-    -c:v libx264 -crf 23 -preset slow \
-    -c:a aac -b:a 128k \
-    "modern/${base}.mp4"
-done
-```
-
-### Multi-Format Publishing
-
-```bash
-# Create multiple formats for compatibility
-input="source.mp4"
-
-# Modern browsers
-ffmpeg -i "$input" -c:v libx264 -crf 23 -c:a aac output.mp4
-ffmpeg -i "$input" -c:v libvpx-vp9 -crf 30 -c:a libopus output.webm
-
-# Images
-ffmpeg -ss 5 -i "$input" -vframes 1 poster.jpg
-magick poster.jpg -quality 80 poster.webp
-```
-
-## Troubleshooting
-
-### Unsupported Format
-
-```bash
-# Check FFmpeg formats
-ffmpeg -formats
-
-# Check ImageMagick formats
-magick identify -list format
-
-# Install missing codec support
-sudo apt-get install libx264-dev libx265-dev libvpx-dev
-```
-
-### Compatibility Issues
-
-```bash
-# Force compatible encoding
-ffmpeg -i input.mp4 \
-  -c:v libx264 -profile:v high -level 4.0 \
-  -pix_fmt yuv420p \
-  -c:a aac -b:a 128k \
-  output.mp4
-```
-
-### Quality Loss
-
-```bash
-# Avoid multiple conversions
-# Bad: source -> edit -> web -> social
-# Good: source -> final (single conversion)
-
-# Use lossless intermediate
-ffmpeg -i source.mp4 -c:v ffv1 intermediate.mkv
-# Edit intermediate
-ffmpeg -i intermediate.mkv -c:v libx264 final.mp4
-```
+# Format Compatibility & Conversion Guide
+
+Complete guide to media format support, codec recommendations, and conversion best practices.
+
+## Image Format Support
+
+### ImageMagick Formats
+
+**Raster Formats (Full Support):**
+- JPEG (.jpg, .jpeg) - Lossy, universal
+- PNG (.png) - Lossless, transparency
+- WebP (.webp) - Modern, lossy/lossless
+- GIF (.gif) - Animation, limited colors
+- TIFF (.tif, .tiff) - Professional, lossless
+- BMP (.bmp) - Uncompressed, legacy
+- ICO (.ico) - Icons, multi-size
+
+**Raw Formats (Read Support):**
+- CR2, NEF, ARW, DNG (Canon, Nikon, Sony, Adobe RAW)
+- Requires dcraw or ufraw-batch
+
+**Vector Formats (Limited):**
+- SVG (.svg) - Read only, converts to raster
+- PDF (.pdf) - Read/write, may have policy restrictions
+
+**Other Formats:**
+- HEIC (.heic) - Apple format, requires libheif
+- AVIF (.avif) - Next-gen, requires libavif
+- PSD (.psd) - Photoshop, basic support
+
+### FFmpeg Image Support
+
+**Input Formats:**
+- JPEG, PNG, BMP, TIFF, WebP, GIF
+- Image sequences (frame_%04d.png)
+
+**Output Formats:**
+- JPEG, PNG, BMP, TIFF
+- Video from images
+
+## Video Format Support
+
+### Container Formats
+
+**Universal Containers:**
+- MP4 (.mp4) - Most compatible, streaming
+- MKV (.mkv) - Feature-rich, flexible
+- WebM (.webm) - Web-optimized, open
+- AVI (.avi) - Legacy, broad support
+- MOV (.mov) - Apple, professional
+
+**Streaming Containers:**
+- TS (.ts) - Transport stream, HLS segments
+- M3U8 (.m3u8) - HLS playlist
+- MPD (.mpd) - DASH manifest
+- FLV (.flv) - Flash (legacy)
+
+**Professional Formats:**
+- ProRes (.mov) - Apple professional
+- DNxHD/DNxHR (.mxf, .mov) - Avid professional
+- MXF (.mxf) - Broadcast
+
+### Video Codecs
+
+**Modern Codecs:**
+- H.264/AVC (libx264) - Universal, excellent balance
+- H.265/HEVC (libx265) - Better compression, 4K
+- VP9 (libvpx-vp9) - Open, YouTube
+- AV1 (libaom-av1, libsvtav1) - Next-gen, best compression
+
+**Legacy Codecs:**
+- MPEG-4 (mpeg4) - Older devices
+- MPEG-2 (mpeg2video) - DVD, broadcast
+- VP8 (libvpx) - WebM predecessor
+
+**Professional Codecs:**
+- ProRes (prores) - Apple post-production
+- DNxHD (dnxhd) - Avid editing
+- Uncompressed (rawvideo) - Maximum quality
+
+### Audio Codecs
+
+**Modern Codecs:**
+- AAC (aac) - Universal, streaming
+- Opus (libopus) - Best low-bitrate
+- MP3 (libmp3lame) - Universal compatibility
+
+**Lossless Codecs:**
+- FLAC (flac) - Open, archival
+- ALAC (alac) - Apple lossless
+- WAV (pcm_s16le) - Uncompressed
+
+**Other Codecs:**
+- Vorbis (libvorbis) - Open, WebM
+- AC-3 (ac3) - Dolby Digital, surround
+- DTS (dts) - Cinema surround
+
+## Format Recommendations
+
+### Use Case Matrix
+
+| Use Case | Image Format | Video Container | Video Codec | Audio Codec |
+|----------|--------------|-----------------|-------------|-------------|
+| Web general | JPEG 85% | MP4 | H.264 | AAC 128k |
+| Web transparency | PNG | - | - | - |
+| Web modern | WebP | WebM | VP9 | Opus |
+| Social media | JPEG 85% | MP4 | H.264 | AAC 128k |
+| 4K streaming | - | MP4 | H.265 | AAC 192k |
+| Archive | PNG/TIFF | MKV | H.265 CRF 18 | FLAC |
+| Email | JPEG 75% | - | - | - |
+| Print | TIFF/PNG | - | - | - |
+| YouTube | - | MP4/WebM | H.264/VP9 | AAC/Opus |
+| Live stream | - | FLV | H.264 | AAC |
+| Editing | - | MOV/MXF | ProRes/DNxHD | PCM |
+
+### Platform Compatibility
+
+**Web Browsers (2025):**
+- Images: JPEG, PNG, WebP, GIF, SVG
+- Video: MP4 (H.264), WebM (VP9), MP4 (AV1)
+- Audio: AAC, MP3, Opus, Vorbis
+
+**Mobile Devices:**
+- iOS: JPEG, PNG, HEIC, MP4 (H.264/H.265), AAC
+- Android: JPEG, PNG, WebP, MP4 (H.264/H.265), AAC
+
+**Smart TVs:**
+- Most: MP4 (H.264), AAC
+- Modern: MP4 (H.265), AC-3
+
+**Social Media:**
+- All platforms: JPEG, MP4 (H.264), AAC
+
+## Quality vs Size Trade-offs
+
+### Image Quality Comparison
+
+**JPEG Quality Levels:**
+- 95-100: ~5-10 MB (large image), minimal artifacts
+- 85-94: ~1-3 MB, imperceptible loss
+- 75-84: ~500 KB-1 MB, slight artifacts
+- 60-74: ~200-500 KB, visible artifacts
+- Below 60: <200 KB, poor quality
+
+**Format Comparison (Same quality):**
+- WebP: 25-35% smaller than JPEG
+- HEIC: 40-50% smaller than JPEG
+- AVIF: 50-60% smaller than JPEG
+- PNG: 2-5x larger than JPEG (lossless)
+
+### Video Quality Comparison
+
+**H.264 CRF Values:**
+- CRF 18: Visually lossless, ~8-15 Mbps (1080p)
+- CRF 23: High quality, ~4-8 Mbps (1080p)
+- CRF 28: Medium quality, ~2-4 Mbps (1080p)
+
+**Codec Comparison (Same quality):**
+- H.265: 40-50% smaller than H.264
+- VP9: 30-40% smaller than H.264
+- AV1: 50-60% smaller than H.264
+
+### Audio Quality Comparison
+
+**AAC Bitrates:**
+- 320 kbps: Transparent, archival
+- 192 kbps: High quality, music
+- 128 kbps: Good quality, streaming
+- 96 kbps: Acceptable, low bandwidth
+- 64 kbps: Poor, voice only
+
+**Codec Efficiency (Same quality):**
+- Opus: Best at low bitrates (<128k)
+- AAC: Best overall balance
+- MP3: Less efficient but universal
+
+## Conversion Best Practices
+
+### Image Conversions
+
+**PNG to JPEG:**
+```bash
+# Standard conversion
+magick input.png -quality 85 -strip output.jpg
+
+# With transparency handling
+magick input.png -background white -flatten -quality 85 output.jpg
+```
+
+**JPEG to WebP:**
+```bash
+# FFmpeg
+ffmpeg -i input.jpg -quality 80 output.webp
+
+# ImageMagick
+magick input.jpg -quality 80 output.webp
+```
+
+**RAW to JPEG:**
+```bash
+# Requires dcraw
+magick input.CR2 -quality 90 output.jpg
+```
+
+**HEIC to JPEG:**
+```bash
+# Requires libheif
+magick input.heic -quality 85 output.jpg
+```
+
+### Video Conversions
+
+**MKV to MP4:**
+```bash
+# Copy streams (fast)
+ffmpeg -i input.mkv -c copy output.mp4
+
+# Re-encode if needed
+ffmpeg -i input.mkv -c:v libx264 -crf 23 -c:a aac output.mp4
+```
+
+**AVI to MP4:**
+```bash
+# Modern codecs
+ffmpeg -i input.avi -c:v libx264 -crf 23 -c:a aac output.mp4
+```
+
+**MOV to MP4:**
+```bash
+# Copy if H.264 already
+ffmpeg -i input.mov -c copy output.mp4
+
+# Convert ProRes to H.264
+ffmpeg -i input.mov -c:v libx264 -crf 18 -c:a aac output.mp4
+```
+
+**Any to WebM:**
+```bash
+# VP9 encoding
+ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 -c:a libopus output.webm
+```
+
+### Audio Conversions
+
+**Extract Audio from Video:**
+```bash
+# Keep original codec
+ffmpeg -i video.mp4 -vn -c:a copy audio.m4a
+
+# Convert to MP3
+ffmpeg -i video.mp4 -vn -q:a 0 audio.mp3
+
+# Convert to FLAC (lossless)
+ffmpeg -i video.mp4 -vn -c:a flac audio.flac
+```
+
+**Audio Format Conversion:**
+```bash
+# WAV to MP3
+ffmpeg -i input.wav -c:a libmp3lame -b:a 192k output.mp3
+
+# MP3 to AAC
+ffmpeg -i input.mp3 -c:a aac -b:a 192k output.m4a
+
+# Any to Opus
+ffmpeg -i input.wav -c:a libopus -b:a 128k output.opus
+```
+
+## Codec Selection Guide
+
+### Choose H.264 When:
+- Maximum compatibility needed
+- Targeting older devices
+- Streaming to unknown devices
+- Social media upload
+- Fast encoding required
+
+### Choose H.265 When:
+- 4K video encoding
+- Storage space limited
+- Modern device targets
+- Archival quality needed
+- Bandwidth constrained
+
+### Choose VP9 When:
+- YouTube upload
+- Open-source requirement
+- Chrome/Firefox primary
+- Royalty-free needed
+
+### Choose AV1 When:
+- Future-proofing content
+- Maximum compression needed
+- Encoding time not critical
+- Modern platform targets
+
+## Format Migration Strategies
+
+### Archive to Web
+
+```bash
+# High-res archive -> Web-optimized
+for img in archive/*.tif; do
+  base=$(basename "$img" .tif)
+  magick "$img" -resize 2000x2000\> -quality 85 -strip "web/${base}.jpg"
+  magick "$img" -resize 2000x2000\> -quality 85 "web/${base}.webp"
+done
+```
+
+### Legacy to Modern
+
+```bash
+# Convert old formats to modern codecs
+for video in legacy/*.avi; do
+  base=$(basename "$video" .avi)
+  ffmpeg -i "$video" \
+    -c:v libx264 -crf 23 -preset slow \
+    -c:a aac -b:a 128k \
+    "modern/${base}.mp4"
+done
+```
+
+### Multi-Format Publishing
+
+```bash
+# Create multiple formats for compatibility
+input="source.mp4"
+
+# Modern browsers
+ffmpeg -i "$input" -c:v libx264 -crf 23 -c:a aac output.mp4
+ffmpeg -i "$input" -c:v libvpx-vp9 -crf 30 -c:a libopus output.webm
+
+# Images
+ffmpeg -ss 5 -i "$input" -vframes 1 poster.jpg
+magick poster.jpg -quality 80 poster.webp
+```
+
+## Troubleshooting
+
+### Unsupported Format
+
+```bash
+# Check FFmpeg formats
+ffmpeg -formats
+
+# Check ImageMagick formats
+magick identify -list format
+
+# Install missing codec support
+sudo apt-get install libx264-dev libx265-dev libvpx-dev
+```
+
+### Compatibility Issues
+
+```bash
+# Force compatible encoding
+ffmpeg -i input.mp4 \
+  -c:v libx264 -profile:v high -level 4.0 \
+  -pix_fmt yuv420p \
+  -c:a aac -b:a 128k \
+  output.mp4
+```
+
+### Quality Loss
+
+```bash
+# Avoid multiple conversions
+# Bad: source -> edit -> web -> social
+# Good: source -> final (single conversion)
+
+# Use lossless intermediate
+ffmpeg -i source.mp4 -c:v ffv1 intermediate.mkv
+# Edit intermediate
+ffmpeg -i intermediate.mkv -c:v libx264 final.mp4
+```