iphone-photo-backup 1.0.0
Fast iPhone photo backup and organizer for external SSD on macOS
License: MIT
Requires Python: >=3.8
Keywords: iphone, photo, backup, macos, ssd, ios, photos, transfer, organize, dedup, duplicate, pymobiledevice3

# iPhone Photo Backup / Respaldo de Fotos iPhone

[English](#english) | [Español](#español)

---

## English

### Description

A fast, reliable tool to backup and organize photos from your iPhone to an external SSD on macOS. Uses `pymobiledevice3` for direct device communication - no jailbreak required.

**Three commands included:**
- `ibackup` - Backup photos from iPhone to SSD
- `iorganize` - Organize existing photos into Year/Month folders
- `idedup` - Find and remove duplicate files

### Features

- **5-10x Faster**: Single connection vs per-file CLI calls
- **Smart Detection**: Only copies files that don't exist on the SSD
- **Full SSD Scan**: Checks all folders on the drive, not just the destination
- **Incomplete File Detection**: Identifies and replaces corrupted/partial transfers
- **HEIC/JPG Aware**: Recognizes converted files as duplicates
- **Bilingual**: Auto-detects system language (English/Spanish)
- **Interactive Selection**: Choose your disk and destination folder

### Requirements

- macOS (tested on Ventura, Sonoma, Sequoia)
- Python 3.8+
- iPhone with USB connection
- External SSD/HDD

### Installation

#### Option 1: pip (Recommended)

```bash
pip install iphone-photo-backup
```

That's it! Now you can run `ibackup` from anywhere.

#### Option 2: From Source

```bash
# Clone the repository
git clone https://github.com/jorgesoto98/iphone-photo-backup.git
cd iphone-photo-backup

# Install in development mode
pip install -e .
```

### Usage

1. Connect your iPhone via USB
2. Unlock your iPhone and tap "Trust" if prompted
3. Connect your external SSD
4. Run:

```bash
ibackup
```

5. Select your destination disk
6. Choose to create a new folder or use an existing one
7. Confirm and wait for the backup to complete

### Organizing Photos (iorganize)

Organize your existing photos into folders by year and month:

```bash
iorganize
```

**Test mode (no files moved):**
```bash
iorganize --dry-run
```

The organizer will:
1. Ask which disk to use
2. Ask which folder to organize (with navigation)
3. Ask organization mode: Year only or Year/Month
4. Show preview and ask for confirmation
5. Move files into date folders

**Result structure (Year → Month):**
```
Photos/
├── 2024/          ← Year folder
│   ├── Jan/       ← Month folders inside
│   ├── Feb/
│   └── Dec/
├── 2023/
│   ├── Jan/
│   └── ...
└── 2022/
```

### Removing Duplicates (idedup)

Find and remove duplicate files that exist elsewhere on your disk:

```bash
idedup
```

**Test mode (no files deleted):**
```bash
idedup --dry-run
```

**Verbose mode (show all copy locations):**
```bash
idedup --dry-run --verbose
```

The deduplicator will:
1. Ask which disk to use
2. Ask which folder to CLEAN (remove duplicates from)
3. Index the entire disk for existing files
4. Find files in your folder that exist elsewhere on disk
5. Show what would be deleted and ask for confirmation
6. Delete only the duplicates (originals remain safe)

**How it works:**
- Scans the entire disk to build an index of all media files
- Compares files in your selected folder against the index
- Uses filename + size + partial content hash for accurate matching
- Only deletes files that have identical copies elsewhere

### How It Works (ibackup)

1. **Indexing**: Scans the entire SSD for existing media files
2. **Listing**: Reads all files from iPhone's DCIM folder
3. **Comparing**: Identifies new files and incomplete transfers
4. **Copying**: Transfers only what's needed

### Troubleshooting

**"No iPhone found"**
- Ensure iPhone is unlocked
- Tap "Trust" on the iPhone when prompted
- Try a different USB cable/port

**"No external disk found"**
- Check if the disk is mounted in Finder
- Ensure you have write permissions

---

## Español

### Descripción

Una herramienta rápida y confiable para respaldar y organizar fotos de tu iPhone a un SSD externo en macOS. Usa `pymobiledevice3` para comunicación directa con el dispositivo - no requiere jailbreak.

**Tres comandos incluidos:**
- `ibackup` - Respaldar fotos del iPhone al SSD
- `iorganize` - Organizar fotos existentes en carpetas Año/Mes
- `idedup` - Encontrar y eliminar archivos duplicados

### Características

- **5-10x Más Rápido**: Conexión única vs llamadas CLI por archivo
- **Detección Inteligente**: Solo copia archivos que no existen en el SSD
- **Escaneo Completo**: Revisa todas las carpetas del disco, no solo el destino
- **Detecta Archivos Incompletos**: Identifica y reemplaza transferencias corruptas/parciales
- **Reconoce HEIC/JPG**: Identifica archivos convertidos como duplicados
- **Bilingüe**: Detecta automáticamente el idioma del sistema (Inglés/Español)
- **Selección Interactiva**: Elige tu disco y carpeta destino

### Requisitos

- macOS (probado en Ventura, Sonoma, Sequoia)
- Python 3.8+
- iPhone con conexión USB
- SSD/HDD externo

### Instalación

#### Opción 1: pip (Recomendado)

```bash
pip install iphone-photo-backup
```

¡Eso es todo! Ahora puedes ejecutar `ibackup` desde cualquier lugar.

#### Opción 2: Desde el Código Fuente

```bash
# Clonar el repositorio
git clone https://github.com/jorgesoto98/iphone-photo-backup.git
cd iphone-photo-backup

# Instalar en modo desarrollo
pip install -e .
```

### Uso

1. Conecta tu iPhone por USB
2. Desbloquea tu iPhone y toca "Confiar" si aparece
3. Conecta tu SSD externo
4. Ejecuta:

```bash
ibackup
```

5. Selecciona el disco destino
6. Elige crear una carpeta nueva o usar una existente
7. Confirma y espera a que termine el respaldo

### Organizar Fotos (iorganize)

Organiza tus fotos existentes en carpetas por año y mes:

```bash
iorganize
```

**Modo prueba (sin mover archivos):**
```bash
iorganize --dry-run
```

El organizador:
1. Pregunta qué disco usar
2. Pregunta qué carpeta organizar (con navegación)
3. Pregunta modo: Solo año o Año/Mes
4. Muestra vista previa y pide confirmación
5. Mueve archivos a carpetas por fecha

**Estructura resultante (Año → Mes):**
```
Fotos/
├── 2024/          ← Carpeta del año
│   ├── Ene/       ← Carpetas de mes adentro
│   ├── Feb/
│   └── Dic/
├── 2023/
│   ├── Ene/
│   └── ...
└── 2022/
```

### Eliminar Duplicados (idedup)

Encuentra y elimina archivos duplicados que existen en otro lugar del disco:

```bash
idedup
```

**Modo prueba (sin eliminar archivos):**
```bash
idedup --dry-run
```

**Modo detallado (mostrar todas las ubicaciones):**
```bash
idedup --dry-run --verbose
```

El deduplicador:
1. Pregunta qué disco usar
2. Pregunta qué carpeta LIMPIAR (eliminar duplicados de aquí)
3. Indexa todo el disco buscando archivos existentes
4. Encuentra archivos en tu carpeta que existen en otro lugar
5. Muestra qué se eliminaría y pide confirmación
6. Elimina solo los duplicados (los originales quedan seguros)

**Cómo funciona:**
- Escanea todo el disco para crear un índice de archivos multimedia
- Compara archivos de la carpeta seleccionada contra el índice
- Usa nombre + tamaño + hash parcial para comparación precisa
- Solo elimina archivos que tienen copias idénticas en otro lugar

### Cómo Funciona (ibackup)

1. **Indexado**: Escanea todo el SSD buscando archivos multimedia existentes
2. **Listado**: Lee todos los archivos de la carpeta DCIM del iPhone
3. **Comparación**: Identifica archivos nuevos y transferencias incompletas
4. **Copia**: Transfiere solo lo necesario

### Solución de Problemas

**"No se encontró ningún iPhone"**
- Asegúrate de que el iPhone esté desbloqueado
- Toca "Confiar" en el iPhone cuando aparezca
- Prueba con otro cable/puerto USB

**"No se encontró ningún disco externo"**
- Verifica que el disco esté montado en Finder
- Asegúrate de tener permisos de escritura

---

## License / Licencia

MIT License - See [LICENSE](LICENSE) file

---

## Contributing / Contribuir

Contributions are welcome! Please feel free to submit a Pull Request.

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

---

## Made by / Hecho por

<p align="center">
  <strong>IS del Norte</strong><br>
  Soluciones Tecnológicas / Technology Solutions<br>
  <a href="https://isdelnorte.com">isdelnorte.com</a>
</p>