Skip to main content

​
Configuration File

Camera Workflow supports YAML configuration files for persistent settings. Configuration files are optional but provide a convenient way to set defaults without specifying flags on every run.

​
Default Location

$HOME/.media-converter.yaml

​
Custom Location

Specify a custom configuration file: 
media-converter --config /path/to/config.yaml /source /dest

​
Configuration Format

All configuration options use snake_case keys in YAML:
~/.media-converter.yaml
# Processing
max_jobs: 4
dry_run: false
copy_only: false
verify_checksum: false
json_mode: false

# Image settings
photo_format: "avif"
photo_quality_avif: 80
photo_quality_webp: 85

# Video settings
video_codec: "h265"
video_crf: 28
video_acceleration: true

# Organization
organize_by_date: true
keep_originals: true
language: "en"

# Security
skip_disk_space_check: false
timeout_photo: 300
timeout_video: 1800
min_output_size_ratio: 0.005
min_output_size_ratio_avif: 0.001
min_output_size_ratio_webp: 0.003

# Adaptive workers
adaptive_workers:
  enabled: false
  min: 1
  max: 6
  cpu_high: 80.0
  cpu_low: 50.0
  mem_low_percent: 20.0
  interval_seconds: 3

​
Configuration Priority

Settings are applied in order of priority (highest to lowest):
  1. Command-line flags (highest priority)
  2. Environment variables
  3. Configuration file
  4. Default values (lowest priority)

​
Example Priority Resolution

~/.media-converter.yaml
photo_quality_avif: 80

# Config file sets quality to 80
# Command-line flag overrides to 90
media-converter --photo-quality-avif 90 /source /dest

# Result: Quality is 90 (flag wins)

​
Configuration Options

​
Processing Settings

​
max_jobs
integer
default:"CPU cores - 2"
Number of parallel conversion jobs.Maps to flag: --jobs
​
dry_run
boolean
default:"false"
Enable dry-run mode (preview without converting).Maps to flag: --dry-run
​
copy_only
boolean
default:"false"
Enable copy-only mode (no conversion).Maps to flag: --copy-only
​
verify_checksum
boolean
default:"false"
Verify file integrity using checksums.Maps to flag: --verify-checksum
Automatically enabled when copy_only is true.
​
json_mode
boolean
default:"false"
Enable JSON output for Tauri integration.Maps to flag: --json-mode

​
Image Conversion Settings

​
photo_format
string
default:"avif"
Output format for photos.Options: avif, webpMaps to flag: --photo-format
​
photo_quality_avif
integer
default:"80"
Quality for AVIF images (1-100).Maps to flag: --photo-quality-avif
​
photo_quality_webp
integer
default:"85"
Quality for WebP images (1-100).Maps to flag: --photo-quality-webp

​
Video Conversion Settings

​
video_codec
string
default:"h265"
Video codec for output.Options: h265, h264, av1Maps to flag: --video-codec
​
video_crf
integer
default:"28"
Video CRF value (0-51, lower is better).Maps to flag: --video-crf
​
video_acceleration
boolean
default:"true"
Enable hardware acceleration for video.Maps to flag: --video-acceleration

​
Organization Settings

​
organize_by_date
boolean
default:"true"
Organize files by date in output.Maps to flag: --organize-by-date
​
keep_originals
boolean
default:"true"
Keep original files after conversion.Maps to flag: --keep-originals
​
language
string
default:"en"
Language for month names.Options: en, fr, es, deMaps to flag: --language

​
Security Settings

​
skip_disk_space_check
boolean
default:"false"
Skip disk space verification.Maps to flag: --skip-disk-check
​
timeout_photo
integer
default:"300"
Photo conversion timeout in seconds.Maps to flag: --timeout-photo
​
timeout_video
integer
default:"1800"
Video conversion timeout in seconds.Maps to flag: --timeout-video
​
min_output_size_ratio
float
default:"0.005"
Minimum output size ratio (general).Maps to flag: --min-output-ratio
Set to 0.0 to use format-specific defaults.
​
min_output_size_ratio_avif
float
default:"0.001"
Minimum output size ratio for AVIF.Used when min_output_size_ratio is 0.0.
​
min_output_size_ratio_webp
float
default:"0.003"
Minimum output size ratio for WebP.Used when min_output_size_ratio is 0.0.

​
Adaptive Worker Settings

Adaptive worker settings use a nested structure: 
adaptive_workers:
  enabled: false
  min: 1
  max: 6
  cpu_high: 80.0
  cpu_low: 50.0
  mem_low_percent: 20.0
  interval_seconds: 3
​
adaptive_workers.enabled
boolean
default:"false"
Enable adaptive worker management.Maps to flag: --adaptive-workers
​
adaptive_workers.min
integer
default:"1"
Minimum concurrent video conversions.Maps to flag: --adaptive-workers-min
​
adaptive_workers.max
integer
default:"6"
Maximum concurrent video conversions.Maps to flag: --adaptive-workers-max
​
adaptive_workers.cpu_high
float
default:"80.0"
CPU threshold to reduce workers (%).Maps to flag: --adaptive-workers-cpu-high
​
adaptive_workers.cpu_low
float
default:"50.0"
CPU threshold to increase workers (%).Maps to flag: --adaptive-workers-cpu-low
​
adaptive_workers.mem_low_percent
float
default:"20.0"
Minimum memory before reducing workers (%).Maps to flag: --adaptive-workers-mem-low
​
adaptive_workers.interval_seconds
integer
default:"3"
Seconds between resource checks.Maps to flag: --adaptive-workers-interval

​
Environment Variables

Camera Workflow automatically reads environment variables through Viper. Any configuration key can be set via environment variable: Format: Uppercase configuration key with underscores

​
Examples

# Set max jobs
export MAX_JOBS=4

# Set photo format
export PHOTO_FORMAT=webp

# Set photo quality
export PHOTO_QUALITY_AVIF=90

# Set video codec
export VIDEO_CODEC=av1

# Enable adaptive workers
export ADAPTIVE_WORKERS_ENABLED=true
export ADAPTIVE_WORKERS_MAX=8

# Run converter (uses environment variables)
media-converter /source /dest

​
Nested Configuration

For nested configuration like adaptive_workers, use dot notation or underscores: 
# Using underscores (recommended)
export ADAPTIVE_WORKERS_ENABLED=true
export ADAPTIVE_WORKERS_MIN=2
export ADAPTIVE_WORKERS_MAX=8

# Using dot notation (also supported)
export ADAPTIVE_WORKERS.ENABLED=true
export ADAPTIVE_WORKERS.MIN=2

​
Configuration Examples

​
High-Quality Archival

~/.media-converter.yaml
photo_format: "avif"
photo_quality_avif: 95
video_codec: "h265"
video_crf: 20
keep_originals: true
organize_by_date: true
max_jobs: 4

​
Fast Web Optimization

~/.media-converter.yaml
photo_format: "webp"
photo_quality_webp: 75
video_codec: "h264"
video_crf: 30
max_jobs: 8
adaptive_workers:
  enabled: true
  max: 8

​
Production Server

~/.media-converter.yaml
json_mode: true
keep_originals: true
verify_checksum: true
max_jobs: 16
adaptive_workers:
  enabled: true
  min: 2
  max: 16
  cpu_high: 85.0
  cpu_low: 60.0
  mem_low_percent: 25.0
timeout_photo: 600
timeout_video: 3600

​
Safe Backup Mode

~/.media-converter.yaml
copy_only: true
verify_checksum: true
organize_by_date: true
language: "en"
max_jobs: 8

​
Validation

Configuration is validated at runtime:

​
Automatic Corrections

  • max_jobs < 1 → set to 1
  • max_jobs > CPU cores → capped at CPU cores
  • min_output_size_ratio ≤ 0 → set to 0.005
  • adaptive_workers.min < 1 → set to 1
  • adaptive_workers.max < min → set to min value
  • adaptive_workers.cpu_low ≥ cpu_high → set to 60% of cpu_high

​
Flag Conflicts

~/.media-converter.yaml
copy_only: true
photo_format: "avif"  # ERROR: incompatible with copy_only
Invalid configurations will cause the application to exit with an error message.

​
Troubleshooting

​
Check Active Configuration

When a config file is found, it’s printed to stderr: 
media-converter /source /dest
# Output: Using config file: /home/user/.media-converter.yaml

​
Debug Configuration Priority

# Show what config file would be used
media-converter --dry-run --config /path/to/config.yaml /source /dest

# Override specific settings
media-converter --photo-quality-avif 95 /source /dest

​
Configuration Not Loading

  1. Check file location: $HOME/.media-converter.yaml
  2. Verify YAML syntax (use online YAML validator)
  3. Check file permissions: must be readable
  4. Use --config flag to specify explicit path

​
Environment Variables Not Working

  1. Ensure variables are exported: export VAR=value
  2. Use correct casing: uppercase with underscores
  3. Check variable name matches config key
  4. Environment variables override config file but not flags

Build docs developers (and LLMs) love

Get started for freeTalk to us