Skip to main content

​
Introduction

Camera Workflow provides a powerful command-line interface for converting and organizing media files. The CLI is designed to be safe, efficient, and flexible with extensive configuration options.

​
Basic Usage

media-converter [source] [destination]
The converter requires exactly two positional arguments:
  • source - Directory containing media files to convert
  • destination - Directory where converted files will be saved

​
Quick Examples

# Dry run to preview what will be converted
media-converter --dry-run /path/to/photos /path/to/output

# Convert photos to AVIF format
media-converter /path/to/photos /path/to/output

# Convert with custom quality settings
media-converter --photo-quality-avif 90 /source /dest

# Copy files without conversion (archive mode)
media-converter --copy-only /source /dest

# Enable JSON output for programmatic use
media-converter --json-mode /source /dest

​
Command Structure

Camera Workflow uses a single root command with numerous flags for customization. The application follows this execution flow:
  1. Initialization - Validates directories and checks dependencies
  2. Safety Test - Tests conversion on a sample file (unless --dry-run)
  3. File Discovery - Scans source directory for supported media files
  4. Parallel Conversion - Processes files using worker pools
  5. Progress Tracking - Shows real-time progress with ETAs
  6. Final Report - Displays statistics and cost estimations

​
Configuration Priority

Settings are applied in the following order (highest priority first):
  1. Command-line flags
  2. Environment variables
  3. Configuration file (~/.media-converter.yaml)
  4. Default values

​
Output Structure

By default, converted files are organized by date: 
destination/
├── 2024/
│   ├── 01-January/
│   │   ├── 2024-01-15/
│   │   │   ├── images/
│   │   │   │   ├── photo1.avif
│   │   │   │   └── photo2.avif
│   │   │   └── videos/
│   │   │       └── video1.mp4
│   └── 02-February/
└── conversion.log
Dates are extracted from file metadata (EXIF, video metadata), not filesystem timestamps, ensuring accurate chronological organization.

​
Logging

All operations are logged to {destination}/conversion.log with detailed timing and error information. The log includes:
  • Conversion start/end times
  • File-by-file processing details
  • Error messages and stack traces
  • Statistics and performance metrics

​
Safety Features

​
Idempotent Operations

The converter is designed to be run multiple times safely:
  • Already converted files are automatically skipped
  • Interrupted conversions can be resumed
  • Atomic file operations prevent partial writes

​
Data Protection

  • Original files are preserved by default (--keep-originals=true)
  • Processing markers track active conversions
  • Automatic recovery from crashes
  • Corruption detection and re-conversion

​
Verification

Before any destructive operation:
  1. Verify output file exists
  2. Check file integrity
  3. Validate file size against minimum ratios

​
Dependencies

Required external tools (checked automatically):
  • FFmpeg - Video conversion and metadata extraction
  • ImageMagick - Image conversion and EXIF data reading
In --copy-only mode, dependency checks are skipped as no conversion tools are needed.

​
Exit Codes

The CLI uses standard exit codes:
  • 0 - Success
  • 1 - Error (configuration, validation, or conversion failure)

​
JSON Mode

When --json-mode is enabled, the application outputs structured JSON events to stdout for integration with GUI applications: 
{"type":"progress","file":"photo.jpg","percent":50}
{"type":"complete","file":"photo.jpg","size":1024}
{"type":"error","message":"conversion failed","fatal":false}
This mode silences standard CLI output and is designed for Tauri integration.

​
Next Steps

Commands

Detailed command documentation with examples

Flags Reference

Complete flag documentation with defaults

Configuration

Configuration file format and environment variables

Build docs developers (and LLMs) love

Get started for freeTalk to us