Skip to main content
The Raycast extension provides a polished, user-friendly interface for Camera Workflow’s media conversion engine. It combines Raycast’s native UI components with an embedded Go binary to deliver a seamless backup preparation experience.

​
Architecture

The extension follows a layered architecture that separates concerns between UI and processing: 
┌─────────────────────────────────────┐
│   Raycast Extension (TypeScript)    │
│  - Guided workflow UI               │
│  - Dependency checking              │
│  - Form validation                  │
│  - Progress monitoring              │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  Embedded media-converter (Go)      │
│  - File discovery & analysis        │
│  - Parallel conversion engine       │
│  - Security & integrity checks      │
│  - Progress reporting               │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│   System Dependencies               │
│  - ffmpeg (video conversion)        │
│  - ffprobe (video analysis)         │
│  - magick (image conversion)        │
└─────────────────────────────────────┘

​
Components

​
Extension Metadata

Defined in package.json:
  • Name: camera-workflow
  • Title: Camera Workflow
  • Description: Prepare your camera library for cloud backup: shrink files, organize by date, keep originals safe
  • Categories: Productivity, Developer Tools
  • License: MIT

​
Commands

The extension provides a single command: Prepare Library for Backup (convert-media.tsx)
  • Single-command guided flow from source selection to completion report
  • View mode with real-time progress updates
  • Comprehensive dependency validation before execution

​
Source Files

Main command entry point that orchestrates the workflow:
  • Dependency checking: Validates system binaries and embedded converter
  • Source detection: Automatically detects mounted volumes (SD cards, cameras)
  • Source analysis: Scans selected directory for images and videos, calculates total size
  • Destination setup: Auto-generates timestamped folder on Desktop or manual selection
  • Preset management: Applies conversion presets or custom settings
  • Form validation: Ensures paths exist and are writable
Execution view that runs the conversion process:
  • Process spawning: Launches embedded binary with proper environment
  • Live output: Captures and displays stdout/stderr in real-time
  • Progress tracking: Updates UI with conversion status
  • Report parsing: Extracts key metrics from log output
  • Quick actions: Opens log file and destination folder

​
Embedded Binary Strategy

The extension embeds platform-specific Go binaries in assets/bin/:
  • media-converter-darwin-arm64 (Apple Silicon)
  • media-converter-darwin-amd64 (Intel Mac)

​
Benefits

Zero Installation

Users don’t need to install or configure the converter separately.

Version Lock

Extension and converter versions are synchronized automatically.

PATH Independence

No reliance on user’s shell configuration or PATH setup.

Distribution

Single package contains everything needed to run.

​
Resolution Process

The extension resolves the converter binary using this logic:
  1. Detect platform and architecture (embeddedBinaryName())
  2. Resolve embedded binary from environment.assetsPath/bin/
  3. Development fallback (optional): If CAMERA_WORKFLOW_ALLOW_PATH_FALLBACK=1 is set and running in development mode, falls back to media-converter in PATH
Production builds always use the embedded binary. PATH fallback is only available in development mode with explicit environment variable.

​
System Dependencies

While the converter is embedded, it relies on external system tools:
DependencyPurposeDetection
ffmpegVideo conversion and encodingResolved from PATH
ffprobeVideo metadata extractionResolved from PATH
magickImage conversion (ImageMagick)Resolved from PATH
The extension performs comprehensive PATH resolution by checking:
  1. Current process PATH
  2. Login shell PATH (via $SHELL -lc)
  3. macOS path_helper output
  4. Common installation locations (/opt/homebrew/bin, /usr/local/bin, etc.)
If any system dependency is missing, the extension will show an error and prevent execution. Users must install ffmpeg and ImageMagick before using the extension.

​
Conversion Presets

The extension offers four preset configurations:
  • Photo format: AVIF at quality 78
  • Video codec: H.265 at CRF 28
  • Optimized for Google Photos free tier storage limits

​
High Quality

  • Photo format: AVIF at quality 90
  • Video codec: H.265 at CRF 23
  • Prioritizes visual quality with moderate compression

​
Max Compression

  • Photo format: AVIF at quality 70
  • Video codec: AV1 at CRF 33
  • Maximum space savings with acceptable quality loss

​
Custom

  • All settings manually configurable
  • Full control over format, codec, and quality parameters

​
Platform Support

Currently supports macOS only:
  • macOS on Apple Silicon (arm64)
  • macOS on Intel (amd64)
The Go converter engine supports Linux and Windows, but Raycast extension binaries are currently built for macOS only. To use on other platforms, use the CLI interface instead.

​
Next Steps

Setup Guide

Install and configure the extension

Workflow Guide

Learn the guided conversion workflow

Build docs developers (and LLMs) love

Get started for freeTalk to us