Immich Transcode Replace

A native macOS application that replaces original video files in Immich with their smaller transcoded versions, helping you reclaim significant storage space on your server.

Overview

Immich automatically transcodes videos for web playback, creating optimized versions alongside the originals. This means your server stores both versions, often doubling storage requirements for video content.

Immich Transcode Replace safely replaces original videos with their transcoded counterparts when the transcode is smaller, potentially saving gigabytes of storage space while maintaining playback quality.

Features

• Smart Discovery — Scans your Immich library to identify videos where the transcode is smaller than the original
• Safe Operations — Backs up originals before replacement with optional auto-cleanup after verification
• Parallel Processing — Process multiple videos concurrently (1-4 workers) for faster completion
• Live Progress — Real-time dashboard showing progress, current file, and storage savings
• Detailed Logging — Comprehensive logs with filtering by severity level
• Session History — Review past sessions, export reports, and track cumulative savings
• Flexible Filters — Filter by date range, minimum savings threshold, and file size limits
• Dry Run Mode — Preview what would be replaced without making any changes

Screenshots

Setup & Connection

Connect to your Immich server using the server URL and an API key generated from your Immich account settings.

Settings

Configure filters, backup options, performance settings, and safety checks.

Performance Tuning

Adjust concurrent workers, rate limiting, retry behavior, and timeouts.

Session History

Review past processing sessions with detailed statistics and per-asset results.

Requirements

• macOS 14.0 (Sonoma) or later
• Immich server running version 1.106.0 or later
• API key with admin permissions (generated in Immich → Account Settings → API Keys)

Installation

1. Download the latest DMG from the Releases page
2. Open the DMG and drag the app to your Applications folder
3. Launch the app and connect to your Immich server

Usage

Initial Setup

1. Enter your Immich server URL (e.g., http://192.168.1.20:2283)
2. Enter your API key (generate one in Immich → Account Settings → API Keys)
3. Click Test Connection to verify connectivity
4. Click Save & Continue to proceed to the dashboard

Processing Videos

1. Click Scan to discover eligible videos
2. Review the scan results showing potential space savings
3. Configure settings as needed (backup, workers, filters)
4. Click Dry Run to preview changes without making modifications
5. Click Start to begin processing

Recommended Settings

• Backup Originals: Enabled (strongly recommended)
• Verify After Replace: Enabled
• Workers: Start with 1, increase if stable
• Auto-Delete Backups: Enable only after confirming everything works

How It Works

1. Scan — Queries Immich API for all video assets with transcoded versions
2. Compare — Identifies videos where the transcode is smaller than the original
3. Backup — Downloads and saves the original file locally (optional but recommended)
4. Replace — Uses Immich's replaceAsset API to swap the original with the transcode
5. Verify — Confirms the replacement was successful by checking the asset
6. Cleanup — Optionally removes local backups after successful verification

Safety Features

• Backup Before Replace — Original files are backed up locally before any changes
• Verification — Each replacement is verified before marking as successful
• Motion Photo Protection — Automatically skips motion photos and live photo videos
• Pause on Errors — Processing pauses after consecutive errors for review
• Dry Run Mode — Preview all changes before committing
• Session Logs — Complete audit trail of all operations

API Deprecation Notice

The replaceAsset API endpoint used by this application has been deprecated by the Immich team. This means:

• The feature may be removed in a future Immich version
• The app displays a warning if your Immich version no longer supports this API
• Check Immich release notes before upgrading your server

Building from Source

# Clone the repository
git clone https://github.com/bytePatrol/Immich_Replace_Transcoded_Videos.git
cd Immich_Replace_Transcoded_Videos

# Build the app
xcodebuild -project ImmichTranscodeReplace.xcodeproj \
  -scheme ImmichTranscodeReplace \
  -configuration Release \
  -derivedDataPath build/ \
  build

# Create DMG (requires create-dmg)
make release VERSION=1.1.0

License

This project is licensed under the MIT License. See the LICENSE file for details.

Disclaimer

This application is not affiliated with or endorsed by the Immich project. Use at your own risk. Always maintain backups of important data before using tools that modify your media library.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions