Troubleshooting¶

Common issues and solutions.

GUI Application Issues¶

App Won't Launch¶

Cause: macOS security settings or missing dependencies.

Solutions:

Check macOS version - Requires macOS 12.0 (Monterey) or later
Allow in Security Settings:
Go to System Settings > Privacy & Security
Scroll to "App was blocked from opening"
Click Open Anyway

Reset quarantine attribute:

xattr -d com.apple.quarantine /Applications/Video\ Converter.app

"Video Converter" is Damaged (Gatekeeper Error)¶

Cause: App not signed or quarantine flag set.

Solution:

xattr -cr /Applications/Video\ Converter.app

Photos Library Access Denied¶

Cause: App doesn't have Photos permission.

Solution: 1. Open System Settings > Privacy & Security > Photos 2. Enable Video Converter in the list 3. Restart Video Converter

Tip

If Video Converter doesn't appear in the list, launch the app and try accessing the Photos tab first.

GUI Appears Frozen¶

Cause: Large batch conversion or memory pressure.

Solutions:

Wait a moment - UI may be updating
Reduce concurrent conversions in Settings (try 1)
Check Activity Monitor for memory usage
Force quit and restart:
```
killall "Video Converter"
```

Menubar Icon Not Appearing¶

Cause: Menubar disabled or system resources.

Solutions:

Check Settings > Notification Settings > Show in Menubar
Restart the application
Check if menubar is full (use Bartender or similar)

Drag and Drop Not Working¶

Cause: Permission or file type issue.

Solutions:

Ensure file is a supported format (.mp4, .mov, .avi, .mkv, .m4v)
Check System Settings > Privacy & Security > Files and Folders
Grant Video Converter access to your files

Queue Stuck in "Converting" State¶

Cause: FFmpeg process hung or crashed.

Solutions:

Click Cancel All in Queue tab
Check for FFmpeg processes:
```
ps aux | grep ffmpeg
killall ffmpeg
```
Restart Video Converter

Window Too Small or Off-Screen¶

Cause: Saved window position is invalid.

Solution: Reset window position:

defaults delete com.video-converter.app NSWindow.Frame

Installation Issues¶

"FFmpeg not found"¶

Solution:

brew install ffmpeg

"ExifTool not found"¶

Solution:

brew install exiftool

"osxphotos import error"¶

Solution:

pip install --upgrade osxphotos

Photos Library Issues¶

"Photos library access denied"¶

Cause: Terminal doesn't have Photos access permission.

Solution: 1. Open System Preferences > Privacy & Security > Photos 2. Enable access for your terminal application 3. Restart the terminal

"No videos found in Photos library"¶

Causes: - Photos library might be empty - Videos are iCloud-only

Solution:

# Check library status
video-converter scan --mode photos --verbose

# Include iCloud videos (will download)
video-converter run --mode photos --download-icloud

Conversion Issues¶

"Conversion fails with VideoToolbox error"¶

Cause: Hardware encoder initialization failed.

Solution:

# Try software encoder
video-converter convert input.mp4 output.mp4 --encoder software

"Output file is larger than input"¶

Cause: Source video is already highly compressed.

Solution:

# Increase quality setting (reduce file size)
video-converter convert input.mp4 output.mp4 --quality 55

"Conversion is very slow"¶

Cause: Using software encoder or system is under load.

Solutions:

# Ensure hardware encoder is used
video-converter convert input.mp4 output.mp4 --encoder hardware

# Reduce concurrent conversions
video-converter run --mode photos --concurrent 1

Metadata Issues¶

"GPS coordinates lost after conversion"¶

Cause: ExifTool couldn't copy GPS data.

Solution:

# Verify ExifTool is installed
exiftool -ver

# Re-apply metadata manually
exiftool -tagsFromFile original.mp4 "-GPS*" converted.mp4

"Creation date changed"¶

Solution:

# Sync timestamps manually
touch -r original.mp4 converted.mp4

Performance Issues¶

"High memory usage"¶

Solution:

# Reduce concurrent conversions
video-converter run --mode photos --concurrent 1

"System becomes unresponsive"¶

Solutions:

# Use nice to lower priority
nice -n 10 video-converter run --mode photos

# Limit concurrent operations
video-converter run --mode photos --concurrent 1

Getting Help¶

If issues persist:

Check logs: ~/.local/share/video_converter/logs/
Run with verbose output: video-converter --verbose
Open an issue