Your first conversion This guide walks through a basic conversion workflow using the CLI tool. For the Raycast extension, see Raycast workflow .
Prepare your directories
Create a source directory with some test media files: mkdir -p ~/test-media/source mkdir -p ~/test-media/output
Copy a few photos or videos to ~/test-media/source for testing.
Run a dry-run
Preview what will be converted without actually processing files: media-converter --dry-run ~/test-media/source ~/test-media/output
You’ll see output like: ┌────────────────────────────────────────────────────────────────┐ │ Secure Media Converter - Starting Run │ │ Keep originals: true │ └────────────────────────────────────────────────────────────────┘ Starting secure media conversion Source: /Users/you/test-media/source Destination: /Users/you/test-media/output DRY RUN MODE - No files will be converted Keep originals: true Scanning source directory... Found 15 photos, 3 videos (2.3 GB) Would convert: • 15 photos → AVIF (quality: 80) • 3 videos → H.265 (CRF: 28) Estimated output size: ~650 MB Estimated AWS S3 cost: $0.015/month
Run the conversion
Remove --dry-run to perform the actual conversion: media-converter ~/test-media/source ~/test-media/output
The converter will:
Check disk space
Test conversion on a sample file
Process files in parallel with progress bars
Organize output by date
Generate a summary report
Review the output
Check the organized output: output/ ├── 2024/ │ ├── 01-January/ │ │ └── 2024-01-15/ │ │ ├── images/ │ │ │ ├── IMG_1234.avif │ │ │ └── IMG_1235.avif │ │ └── videos/ │ │ └── VID_2024.mp4 ├── conversion.log └── media-converter-checksums.json
Review the log file for detailed information: cat ~/test-media/output/conversion.log
Common usage patterns Convert to WebP instead of AVIF media-converter --photo-format webp ~/source ~/output
Use H.264 for broader compatibility media-converter --video-codec h264 ~/source ~/output
Limit parallel jobs media-converter --jobs 4 ~/source ~/output
Copy files without conversion Copy-only mode is ideal for creating verified archives of your originals before converting.
media-converter --copy-only ~/source ~/backup
This mode:
Copies all files without conversion
Automatically enables checksum verification
Organizes by date
Creates integrity checksums for verification
Enable adaptive workers for video Adaptive workers automatically adjust the number of concurrent video conversions based on system resources:
media-converter --adaptive-workers \ --adaptive-workers-min 1 \ --adaptive-workers-max 4 \ ~/source ~/output
Adaptive workers prevent system overload during video encoding. They scale workers up when CPU is available and down when resources are constrained.
Command structure The basic command structure is:
media-converter [flags] < source > < destination >
Required arguments:
<source> - Path to directory containing media files<destination> - Path where converted files will be saved
Common flags: Preview operations without converting files
Keep source files after conversion
--jobs
integer
default: "CPU cores - 2"
Number of parallel conversion jobs
Copy files without conversion (archive mode)
Output format for photos: avif or webp
Video codec: h265, h264, or av1
Organize files by date into YYYY/MM-Month/YYYY-MM-DD structure
Enable file integrity verification with checksums
See CLI flags for the complete reference.
Real-world examples High quality AVIF conversion
Cloud-optimized conversion
Maximum compatibility
Safe archive copy
Resume interrupted conversion
# Convert photos to high-quality AVIF, videos to H.265 media-converter \ --photo-format avif \ --photo-quality-avif 90 \ --video-codec h265 \ --video-crf 23 \ ~/camera-library ~/prepared-library
Understanding the output When a conversion completes, you’ll see a summary:
╔════════════════════════════════════════════════════════════════╗ ║ Conversion Complete ║ ╚════════════════════════════════════════════════════════════════╝ Processing Summary: • Total files: 127 • Processed: 124 (15 photos, 109 videos) • Skipped: 2 (already converted) • Failed: 1 • Recovered: 0 Size Analysis: • Input size: 47.3 GB • Output size: 12.8 GB • Space saved: 34.5 GB (72.9% reduction) • AWS S3 cost estimate: $0.29/month Performance: • Duration: 2h 15m 34s • Average speed: 15.4 MB/s • Photos: 1.2s average • Videos: 3m 45s average Output directory: /Users/you/prepared-library Log file: /Users/you/prepared-library/conversion.log
The AWS S3 cost estimate assumes Standard storage at $0.023/GB/month and helps you plan cloud storage expenses.
Handling errors Dependency check failed Error: dependency check failed: ffmpeg not found in PATH
Solution : Install FFmpeg and ImageMagick. See Installation .Disk space check failed Error: disk space check failed: insufficient space on destination
Solution : Free up disk space or use a different destination. You can bypass this check with --skip-disk-check (use with caution).Conversion timeout Warn: Video conversion timed out after 30m0s: /path/to/large-video.mov
Solution : Increase timeout for large files:media-converter --timeout-video 3600 ~/source ~/output # 60 minutes
File corrupted or too small Error: Output file suspiciously small (0.05% of input), possible corruption
Solution : This safety check prevents corrupted conversions. The file will be skipped and logged. Check the source file or adjust --min-output-ratio if needed.Next steps
Explore CLI commands Learn about all available commands and flags
Use Raycast extension Try the guided workflow with live progress
Configure adaptive workers Optimize video conversion performance
Learn about copy mode Create safe, verified archives