anchi-kit 1.2.0 → 1.2.2

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

@@ -1,375 +0,0 @@
-# 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
-```