cokit-cli 1.0.0 → 1.0.2

package/skills/ck-media-processing/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: 'ck-media-processing'
+description: 'Process multimedia files with FFmpeg (video/audio encoding, conversion, streaming, filtering, hardware acceleration), ImageMagick (image manipulation, format conversion, batch processing, effects, composition), and RMBG (AI-powered background removal). Use when converting media formats, encoding videos with specific codecs (H.264, H.265, VP9), resizing/cropping images, removing backgrounds from images, extracting audio from video, applying filters and effects, optimizing file sizes, creating streaming manifests (HLS/DASH), generating thumbnails, batch processing images, creating composite images, or implementing media processing pipelines. Supports 100+ formats, hardware acceleration (NVENC, QSV), and complex filtergraphs.'
+---
+
+# Media Processing Skill
+
+Process video, audio, and images using FFmpeg, ImageMagick, and RMBG CLI tools.
+
+## Tool Selection
+
+| Task | Tool | Reason |
+|------|------|--------|
+| Video encoding/conversion | FFmpeg | Native codec support, streaming |
+| Audio extraction/conversion | FFmpeg | Direct stream manipulation |
+| Image resize/effects | ImageMagick | Optimized for still images |
+| Background removal | RMBG | AI-powered, local processing |
+| Batch images | ImageMagick | mogrify for in-place edits |
+| Video thumbnails | FFmpeg | Frame extraction built-in |
+| GIF creation | FFmpeg/ImageMagick | FFmpeg for video, ImageMagick for images |
+
+## Installation
+
+```bash
+# macOS
+brew install ffmpeg imagemagick
+npm install -g rmbg-cli
+
+# Ubuntu/Debian
+sudo apt-get install ffmpeg imagemagick
+npm install -g rmbg-cli
+
+# Verify
+ffmpeg -version && magick -version && rmbg --version
+```
+
+## Essential Commands
+
+```bash
+# Video: Convert/re-encode
+ffmpeg -i input.mkv -c copy output.mp4
+ffmpeg -i input.avi -c:v libx264 -crf 22 -c:a aac output.mp4
+
+# Video: Extract audio
+ffmpeg -i video.mp4 -vn -c:a copy audio.m4a
+
+# Image: Convert/resize
+magick input.png output.jpg
+magick input.jpg -resize 800x600 output.jpg
+
+# Image: Batch resize
+mogrify -resize 800x -quality 85 *.jpg
+
+# Background removal
+rmbg input.jpg                          # Basic (modnet)
+rmbg input.jpg -m briaai -o output.png  # High quality
+rmbg input.jpg -m u2netp -o output.png  # Fast
+```
+
+## Key Parameters
+
+**FFmpeg:**
+- `-c:v libx264` - H.264 codec
+- `-crf 22` - Quality (0-51, lower=better)
+- `-preset slow` - Speed/compression balance
+- `-c:a aac` - Audio codec
+
+**ImageMagick:**
+- `800x600` - Fit within (maintains aspect)
+- `800x600^` - Fill (may crop)
+- `-quality 85` - JPEG quality
+- `-strip` - Remove metadata
+
+**RMBG:**
+- `-m briaai` - High quality model
+- `-m u2netp` - Fast model
+- `-r 4096` - Max resolution
+
+## References
+
+Detailed guides in `references/`:
+- `ffmpeg-encoding.md` - Codecs, quality, hardware acceleration
+- `ffmpeg-streaming.md` - HLS/DASH, live streaming
+- `ffmpeg-filters.md` - Filters, complex filtergraphs
+- `imagemagick-editing.md` - Effects, transformations
+- `imagemagick-batch.md` - Batch processing, parallel ops
+- `rmbg-background-removal.md` - AI models, CLI usage
+- `common-workflows.md` - Video optimization, responsive images, GIF creation
+- `troubleshooting.md` - Error fixes, performance tips
+- `format-compatibility.md` - Format support, codec recommendations

package/skills/ck-media-processing/references/common-workflows.md

@@ -0,0 +1,132 @@
+# Common Media Processing Workflows
+
+## Video Optimization
+
+### Optimize for Web
+```bash
+# H.264 with good compression
+ffmpeg -i input.mp4 \
+  -c:v libx264 -preset slow -crf 23 \
+  -c:a aac -b:a 128k \
+  -movflags +faststart \
+  output.mp4
+```
+
+### Multi-Pass Encoding
+```bash
+# Pass 1 (analysis)
+ffmpeg -y -i input.mkv -c:v libx264 -b:v 2600k -pass 1 -an -f null /dev/null
+
+# Pass 2 (encoding)
+ffmpeg -i input.mkv -c:v libx264 -b:v 2600k -pass 2 -c:a aac output.mp4
+```
+
+### Hardware-Accelerated Encoding
+```bash
+# NVIDIA NVENC
+ffmpeg -hwaccel cuda -i input.mp4 -c:v h264_nvenc -preset fast -crf 22 output.mp4
+
+# Intel QuickSync
+ffmpeg -hwaccel qsv -c:v h264_qsv -i input.mp4 -c:v h264_qsv output.mp4
+```
+
+### Extract Video Segment
+```bash
+# From 1:30 to 3:00 (re-encode for precision)
+ffmpeg -i input.mp4 -ss 00:01:30 -to 00:03:00 \
+  -c:v libx264 -c:a aac output.mp4
+```
+
+## Image Workflows
+
+### Create Responsive Images
+```bash
+# Generate multiple sizes
+for size in 320 640 1024 1920; do
+  magick input.jpg -resize ${size}x -quality 85 "output-${size}w.jpg"
+done
+```
+
+### Batch Image Optimization
+```bash
+# Convert PNG to optimized JPEG
+mogrify -path ./optimized -format jpg -quality 85 -strip *.png
+```
+
+### Complex Image Pipeline
+```bash
+# Resize, crop, border, adjust
+magick input.jpg \
+  -resize 1000x1000^ \
+  -gravity center \
+  -crop 1000x1000+0+0 +repage \
+  -bordercolor black -border 5x5 \
+  -brightness-contrast 5x10 \
+  -quality 90 \
+  output.jpg
+```
+
+## GIF Creation
+
+### Video to GIF
+```bash
+# High quality GIF with palette
+ffmpeg -i input.mp4 -vf "fps=15,scale=640:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" output.gif
+```
+
+### Animated GIF from Images
+```bash
+# Create with delay
+magick -delay 100 -loop 0 frame*.png animated.gif
+
+# Optimize size
+magick animated.gif -fuzz 5% -layers Optimize optimized.gif
+```
+
+## Background Removal Workflows
+
+### Batch Background Removal
+```bash
+# Process all images in directory
+for img in *.jpg; do
+  rmbg "$img" -m modnet -o "${img%.jpg}-no-bg.png"
+done
+```
+
+### Product Photography
+```bash
+# 1. Remove background
+rmbg product.jpg -m u2net-cloth -o product-no-bg.png
+
+# 2. Resize to multiple sizes
+magick product-no-bg.png -resize 800x800 product-800.png
+magick product-no-bg.png -resize 400x400 product-400.png
+
+# 3. Add white background if needed
+magick product-no-bg.png -background white -flatten product-white-bg.jpg
+```
+
+## Media Analysis
+
+### Inspect Video Properties
+```bash
+# Detailed JSON output
+ffprobe -v quiet -print_format json -show_format -show_streams input.mp4
+
+# Get resolution
+ffprobe -v error -select_streams v:0 \
+  -show_entries stream=width,height \
+  -of csv=s=x:p=0 input.mp4
+```
+
+### Image Information
+```bash
+# Basic info
+identify image.jpg
+
+# Detailed format
+identify -verbose image.jpg
+
+# Custom format
+identify -format "%f: %wx%h %b\n" image.jpg
+```

package/skills/ck-media-processing/references/ffmpeg-encoding.md

@@ -0,0 +1,358 @@
+# FFmpeg Video & Audio Encoding
+
+Complete guide to codec selection, quality optimization, and hardware acceleration.
+
+## Video Codecs
+
+### H.264 (libx264)
+Most widely supported codec, excellent compression/quality balance.
+
+**Best for:** Universal compatibility, streaming, web video
+
+**Quality range:** CRF 17-28 (lower = better)
+
+```bash
+# High quality
+ffmpeg -i input.mkv -c:v libx264 -preset slow -crf 18 -c:a copy output.mp4
+
+# Standard quality (recommended)
+ffmpeg -i input.mkv -c:v libx264 -preset medium -crf 23 -c:a copy output.mp4
+
+# Fast encoding
+ffmpeg -i input.mkv -c:v libx264 -preset fast -crf 23 -c:a copy output.mp4
+```
+
+### H.265/HEVC (libx265)
+25-50% better compression than H.264, slower encoding.
+
+**Best for:** 4K video, file size reduction, archival
+
+```bash
+# High quality 4K
+ffmpeg -i input.mkv -c:v libx265 -preset medium -crf 24 -c:a copy output.mp4
+
+# Balanced quality
+ffmpeg -i input.mkv -c:v libx265 -preset fast -crf 26 -c:a copy output.mp4
+```
+
+### VP9 (libvpx-vp9)
+Royalty-free, WebM format, good for YouTube and open-source projects.
+
+**Best for:** YouTube, Chrome/Firefox, open platforms
+
+```bash
+# Quality-based (recommended)
+ffmpeg -i input.mkv -c:v libvpx-vp9 -crf 30 -b:v 0 -c:a libopus output.webm
+
+# Two-pass for better quality
+ffmpeg -i input.mkv -c:v libvpx-vp9 -b:v 2M -pass 1 -an -f null /dev/null
+ffmpeg -i input.mkv -c:v libvpx-vp9 -b:v 2M -pass 2 -c:a libopus output.webm
+```
+
+### AV1 (libaom-av1, libsvtav1)
+Next-generation codec, best compression, very slow encoding.
+
+**Best for:** Future-proofing, maximum compression, low bandwidth
+
+```bash
+# Using libaom (slow, highest quality)
+ffmpeg -i input.mkv -c:v libaom-av1 -crf 30 -b:v 0 -strict experimental output.mp4
+
+# Using SVT-AV1 (faster)
+ffmpeg -i input.mkv -c:v libsvtav1 -crf 30 -preset 5 output.mp4
+```
+
+## Audio Codecs
+
+### AAC (Industry Standard)
+Best quality for streaming, universal support.
+
+```bash
+# High quality
+ffmpeg -i input.mp4 -c:a aac -b:a 192k output.mp4
+
+# Standard quality
+ffmpeg -i input.mp4 -c:a aac -b:a 128k output.mp4
+
+# Low bitrate
+ffmpeg -i input.mp4 -c:a aac -b:a 96k output.mp4
+```
+
+### MP3 (libmp3lame)
+Universal compatibility, good quality.
+
+```bash
+# Variable bitrate (best quality)
+ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
+
+# Constant bitrate
+ffmpeg -i input.wav -c:a libmp3lame -b:a 192k output.mp3
+```
+
+### Opus (libopus)
+Best quality at low bitrates, ideal for voice and streaming.
+
+```bash
+# Voice (mono)
+ffmpeg -i input.mp4 -c:a libopus -b:a 32k -ac 1 output.webm
+
+# Music (stereo)
+ffmpeg -i input.mp4 -c:a libopus -b:a 128k output.webm
+```
+
+### FLAC (Lossless)
+No quality loss, archival quality, larger files.
+
+```bash
+# Lossless audio
+ffmpeg -i input.wav -c:a flac output.flac
+
+# Extract audio losslessly
+ffmpeg -i video.mp4 -c:a flac audio.flac
+```
+
+## Quality Optimization
+
+### CRF (Constant Rate Factor)
+Best for quality-focused encoding. Single-pass, adjusts bitrate for complexity.
+
+**CRF Scale:**
+- 0 = Lossless (huge files)
+- 17-18 = Visually lossless
+- 20-23 = High quality (recommended)
+- 24-28 = Medium quality
+- 30+ = Low quality
+- 51 = Worst quality
+
+```bash
+# Visually lossless
+ffmpeg -i input.mp4 -c:v libx264 -crf 18 -preset slow output.mp4
+
+# High quality (recommended)
+ffmpeg -i input.mp4 -c:v libx264 -crf 22 -preset medium output.mp4
+
+# Balanced quality/size
+ffmpeg -i input.mp4 -c:v libx264 -crf 25 -preset fast output.mp4
+```
+
+### Bitrate-Based Encoding
+Target specific file size or quality. Two-pass recommended.
+
+```bash
+# Calculate target bitrate
+# bitrate = (target_size_MB * 8192) / duration_seconds - audio_bitrate
+
+# Two-pass encoding (2600k video, 128k audio)
+ffmpeg -y -i input.mkv -c:v libx264 -b:v 2600k -pass 1 -an -f null /dev/null
+ffmpeg -i input.mkv -c:v libx264 -b:v 2600k -pass 2 -c:a aac -b:a 128k output.mp4
+```
+
+### Presets (Speed vs Compression)
+Trade-off between encoding speed and file size.
+
+**Available presets:**
+- `ultrafast` - Fastest, largest files
+- `superfast`
+- `veryfast`
+- `faster`
+- `fast`
+- `medium` - Default balance
+- `slow` - Better compression
+- `slower`
+- `veryslow` - Best compression
+- `placebo` - Not recommended (minimal gains)
+
+```bash
+# Fast encoding (real-time)
+ffmpeg -i input.mp4 -c:v libx264 -preset ultrafast -crf 23 output.mp4
+
+# Balanced
+ffmpeg -i input.mp4 -c:v libx264 -preset medium -crf 22 output.mp4
+
+# Best compression (slow)
+ffmpeg -i input.mp4 -c:v libx264 -preset veryslow -crf 20 output.mp4
+```
+
+## Hardware Acceleration
+
+### NVIDIA NVENC
+5-10x faster encoding, slightly larger files than software encoding.
+
+**Requirements:** NVIDIA GPU (GTX 10xx or newer)
+
+```bash
+# H.264 with NVENC
+ffmpeg -hwaccel cuda -i input.mp4 -c:v h264_nvenc -preset fast -crf 22 output.mp4
+
+# H.265 with NVENC
+ffmpeg -hwaccel cuda -i input.mp4 -c:v hevc_nvenc -preset slow -crf 24 output.mp4
+
+# Quality levels (instead of CRF)
+ffmpeg -hwaccel cuda -i input.mp4 -c:v h264_nvenc -preset slow -rc vbr -cq 22 output.mp4
+```
+
+**NVENC Presets:**
+- `default` - Balanced
+- `slow` - Better quality
+- `medium`
+- `fast`
+- `hp` - High performance
+- `hq` - High quality
+- `bd` - Bluray disk
+- `ll` - Low latency
+- `llhq` - Low latency high quality
+- `llhp` - Low latency high performance
+
+### Intel QuickSync (QSV)
+Fast hardware encoding on Intel CPUs with integrated graphics.
+
+**Requirements:** Intel CPU with Quick Sync Video support
+
+```bash
+# H.264 with QSV
+ffmpeg -hwaccel qsv -c:v h264_qsv -i input.mp4 \
+  -c:v h264_qsv -preset fast -global_quality 22 output.mp4
+
+# H.265 with QSV
+ffmpeg -hwaccel qsv -c:v hevc_qsv -i input.mp4 \
+  -c:v hevc_qsv -preset medium -global_quality 24 output.mp4
+
+# Quality levels
+ffmpeg -hwaccel qsv -i input.mp4 -c:v h264_qsv -global_quality 20 output.mp4
+```
+
+### AMD VCE/VCN
+Hardware encoding on AMD GPUs.
+
+**Requirements:** AMD GPU with VCE/VCN support
+
+```bash
+# H.264 with AMF
+ffmpeg -hwaccel auto -i input.mp4 \
+  -c:v h264_amf -quality balanced -rc cqp -qp 22 output.mp4
+
+# H.265 with AMF
+ffmpeg -hwaccel auto -i input.mp4 \
+  -c:v hevc_amf -quality quality -rc cqp -qp 24 output.mp4
+```
+
+### Apple VideoToolbox (macOS)
+Hardware encoding on macOS devices.
+
+```bash
+# H.264 with VideoToolbox
+ffmpeg -i input.mp4 -c:v h264_videotoolbox -b:v 2M output.mp4
+
+# H.265 with VideoToolbox
+ffmpeg -i input.mp4 -c:v hevc_videotoolbox -b:v 1.5M output.mp4
+```
+
+## Performance Tuning
+
+### Multi-Threading
+FFmpeg automatically uses multiple cores. Override if needed:
+
+```bash
+# Limit threads
+ffmpeg -threads 4 -i input.mp4 -c:v libx264 output.mp4
+
+# Auto (default)
+ffmpeg -threads 0 -i input.mp4 -c:v libx264 output.mp4
+```
+
+### Tune Options
+Optimize encoder for specific content types:
+
+```bash
+# Film content
+ffmpeg -i input.mp4 -c:v libx264 -tune film -crf 22 output.mp4
+
+# Animation
+ffmpeg -i input.mp4 -c:v libx264 -tune animation -crf 22 output.mp4
+
+# Grain (film with noise)
+ffmpeg -i input.mp4 -c:v libx264 -tune grain -crf 22 output.mp4
+
+# Low latency streaming
+ffmpeg -i input.mp4 -c:v libx264 -tune zerolatency -crf 22 output.mp4
+
+# Screen content (sharp edges)
+ffmpeg -i input.mp4 -c:v libx264 -tune stillimage -crf 22 output.mp4
+```
+
+## Codec Selection Guide
+
+### Use Cases
+
+| Use Case | Codec | Settings |
+|----------|-------|----------|
+| Web video | H.264 | CRF 23, preset medium |
+| 4K streaming | H.265 | CRF 24, preset fast |
+| YouTube upload | VP9 or H.264 | CRF 23 |
+| Archive | H.265 or H.264 | CRF 18, preset slow |
+| Low bandwidth | AV1 or H.265 | CRF 30 |
+| Fast encoding | H.264 NVENC | preset fast |
+| Maximum compatibility | H.264 | profile main, level 4.0 |
+
+### Platform Compatibility
+
+| Platform | Recommended | Supported |
+|----------|------------|-----------|
+| Web browsers | H.264 | H.264, VP9, AV1 |
+| Mobile devices | H.264 | H.264, H.265 |
+| Smart TVs | H.264 | H.264, H.265 |
+| YouTube | VP9, H.264 | All |
+| Social media | H.264 | H.264 |
+
+## Best Practices
+
+1. **Use CRF for most tasks** - Better than bitrate for variable content
+2. **Start with CRF 23** - Good balance, adjust based on results
+3. **Use slow preset** - For archival and final delivery
+4. **Use fast preset** - For previews and testing
+5. **Hardware acceleration** - When speed is critical
+6. **Two-pass encoding** - When file size is fixed
+7. **Match source frame rate** - Don't increase FPS
+8. **Don't upscale resolution** - Keep original or downscale
+9. **Test on short clips** - Verify settings before full encode
+10. **Keep source files** - Original quality for re-encoding
+
+## Troubleshooting
+
+### Poor Quality Output
+```bash
+# Lower CRF value
+ffmpeg -i input.mp4 -c:v libx264 -crf 18 -preset slow output.mp4
+
+# Use slower preset
+ffmpeg -i input.mp4 -c:v libx264 -crf 22 -preset veryslow output.mp4
+
+# Increase bitrate (two-pass)
+ffmpeg -y -i input.mp4 -c:v libx264 -b:v 5M -pass 1 -an -f null /dev/null
+ffmpeg -i input.mp4 -c:v libx264 -b:v 5M -pass 2 -c:a aac output.mp4
+```
+
+### Slow Encoding
+```bash
+# Use faster preset
+ffmpeg -i input.mp4 -c:v libx264 -preset ultrafast output.mp4
+
+# Use hardware acceleration
+ffmpeg -hwaccel cuda -i input.mp4 -c:v h264_nvenc output.mp4
+
+# Reduce resolution
+ffmpeg -i input.mp4 -vf scale=1280:-1 -c:v libx264 output.mp4
+```
+
+### Large File Size
+```bash
+# Increase CRF
+ffmpeg -i input.mp4 -c:v libx264 -crf 26 output.mp4
+
+# Use better codec
+ffmpeg -i input.mp4 -c:v libx265 -crf 26 output.mp4
+
+# Two-pass with target bitrate
+ffmpeg -y -i input.mp4 -c:v libx264 -b:v 1M -pass 1 -an -f null /dev/null
+ffmpeg -i input.mp4 -c:v libx264 -b:v 1M -pass 2 -c:a aac output.mp4
+```