# PhotoBridge
Export your photos from a local directory to Apple Photos.
## Rationale
This simple script was mostly built for my own personal use case. However, if you find it useful, feel free to use it! The
reason it exists is summarised below:
**Situation**:
You use iCloud photos, but you also use another service which synchronises photos to a local directory
(such as NextCloud Photos, Immich, etc.).
**Problem**:
You sometimes take or add photos on a device which cannot synchronise with iCloud Photos (Android, Linux, etc.). Problem is,
these photos do not make it to your iCloud Photos library.
**What you need**:
You need a program which can scan your non-iCloud photos directory and upload any new photos to your iCloud library.
**What PhotoBridge does**:
PhotoBridge scans the contents of a local directory and identifies new files (i.e. your new photos or images). It then adds
those images to an Album in your iCloud Photos library.
# Disclaimer
Although every care has been taken when developing PhotoBridge, there are two **important** things you should be aware of:
1. PhotoBridge is a simple utility I created for myself. I've released it to the public since others might find it useful, however,
I've only tested this on my system. In the **highly unlikely** event that PhotoBridge destroys your wedding photos, the selfie
you took with Bono, or the video of baby's first steps, don't come crying to me. You should **ALWAYS** have a backup!
2. Unfortunately, the way that Apple Photos is built makes it quite difficult to interact with it programmatically.
This means that, at any point, Apple may decide to change how Photos works, or disable programmatic interation
entirely. This means that PhotoBridge can stop working without any prior notice!
Due to the above:
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
## Requirements
- PhotoBridge *only* runs on macOS systems. It uses AppleScript to interact directly with Apple Photos.
- PhotoBridge performs *one-way* synchronisation. It will upload new photos in a directory to iCloud Photos. Other solutions
already exist which synchronise iCloud Photos to third-party services, such as the NextCloud app, the Immich app etc.
- PhotoBridge has only been tested in conjunction with NextCloud Photos (because that's how I use it). **In theory**, it should
also work with any folder-based photo service, but your mileage may vary.
## What It Does
The best way to understand what PhotoBridge does is via example. So, we'll use the following example for this section:
- This is Bob:
- Bob is in Apple's walled garden. He has an iPhone, a Mac and an iCloud subscription. However, Bob also has some non-Apple stuff.
So, he's installed the NextCloud app on his iPhone.
- When Bob takes a photo on his iPhone, iCloud takes care of synchronising it to his other Apple devices. On the other hand,
the NextCloud app synchronises it to his non-Apple devices. Bob can see his photo regardless of which device he's using -
this is good!
- There is, however, a problem. Due to Apple's restrictive practices, the NextCloud app on Bob's iPhone only does *one-way sync*.
This means photos are uploaded from his iCloud photo library to NextCloud, but not the other way round; whihc means that
when Bob takes a photo on his Android phone, it doesn't make it back to his iCloud photo library. He can only use his non-Apple
devices to view that photo. This is bad 😢.
- Mama Bob didn't raise no fool, so Bob installs PhotoBridge on his Mac. He tells PhotoBridge where the NextCloud app on his Mac
stores his NextCloud photos. PhotoBridge then scans this folder and builds a database. On every subsequent scan, PhotoBridge
identifies new photos, and adds them to Bob's photo library in the desktop Apple Photos app. iCloud will then synchronise these
to the cloud, and they'll make their way to Bob's iPhone.
- Now, when Bob takes a photo with his Android phone, or adds a photo to his NextCloud library on a non-Apple device, it will be
synchronised to all of his devices. Huzzah!
## Installing
The easiest way to install PhotoBridge is via [pipx](https://github.com/pypa/pipx#readme). If you don't have pipx installed,
you can easily install it via [HomeBrew](https://brew.sh):
```shell
brew install pipx
pipx ensurepath
```
Once that's done, run the following command to install PhotoBridge. This will install a ```photobridge``` command on your
system.
```shell
pipx install "git+https://github.com/keithvassallomt/photobridge.git"
```
## Usage
```
photobridge [-h] [--photos-folder PHOTOS_FOLDER] [--reset-database] [--dry-run] [--save-current-state]
```
Let's assume that, on your Mac, NextCloud is storing your photos in ```/Users/Bob/NextCloud/Photos```. Let's also assume that
prior to using PhotoBridge, you were manually synchronising your NextCloud photos to your iCloud library.
The first thing you'll need to do is let PhotoBridge build its database of your existing photos. Otherwise, when you run
PhotoBridge, it will re-upload all your NextCloud photos to iCloud, and that's probably not what you want. So, run this:
```shell
photobridge --photos-folder /Users/Bob/NextCloud/Photos --save-current-state
```
This has now built the PhotoBridge database. Any photos added to the folder **from this point onwards** will be synchronised to
Apple Photos when you run PhotoBridge.
When you want to synchronise your photos, run PhotoBridge as follows:
```shell
photobridge --photos-folder /Users/Bob/NextCloud/Photos
```
## Super-Important Point
Since PhotoBridge relies on the photo's file name for synchornisation, you need to ensure that any app on your devices which is
synchronising to your non-Apple cloud (such as NextCloud, Immich, etc.) is **preserving the original filenames used by iCloud***.
Most apps allow you to do this.
In NextCloud, for example:
**More** > **Settings** > **Advanced** > **Change filename mask** > **Maintain original filename**.
## Options
The CLI has a few basic options you may find useful:
| Option | Description |
|:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ```-h``` | Display the usage instructions. |
| ```--save-current-state``` | Save the current folder state. Very useful the first time you run PhotoBridge so existing photos aren't re-uploaded. Use with ```--photos-folder```. |
| ```--reset-database``` | Reset the internal database so all 'known' photos are forgotten. Useful if you screw something up! |
| ```--photos-folder``` | Add the path to where your non-Apple (e.g. NextCloud) photos are stored. This is the folder which will be synchronised with Apple Photos. |
| ```--dry-run``` | Use this to simulate a synchronisation without actually moving any data. Useful to confirm what PhotoBridge would do with your photos. Use with ```--photos-folder```. |
| ```--log-level``` | Set the log level. One of 'debug', 'info', 'warning', 'critical'. Defaults to 'info' |
## See Also
Happy with PhotoBridge? How about also synchronising your Apple Reminders and Notes to non-Apple devices? Check out [TaskBridge](https://taskbridge.app).
Raw data
{
"_id": null,
"home_page": "https://github.com/keithvassallomt/photobridge",
"name": "photobridge",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.13",
"maintainer_email": null,
"keywords": "sync, photo sync, cloud photos",
"author": "Keith Vassallo",
"author_email": "keith@vassallo.cloud",
"download_url": "https://files.pythonhosted.org/packages/fa/92/1a7f532dfa11ff081ecae5b9d2983bd170a80c42a63d12cfc4e62e8ae917/photobridge-0.1.1.tar.gz",
"platform": null,
"description": "# PhotoBridge\n\nExport your photos from a local directory to Apple Photos. \n\n## Rationale\n\nThis simple script was mostly built for my own personal use case. However, if you find it useful, feel free to use it! The \nreason it exists is summarised below:\n\n**Situation**: \nYou use iCloud photos, but you also use another service which synchronises photos to a local directory \n(such as NextCloud Photos, Immich, etc.). \n\n**Problem**: \nYou sometimes take or add photos on a device which cannot synchronise with iCloud Photos (Android, Linux, etc.). Problem is, \nthese photos do not make it to your iCloud Photos library.\n\n**What you need**: \nYou need a program which can scan your non-iCloud photos directory and upload any new photos to your iCloud library.\n\n**What PhotoBridge does**: \nPhotoBridge scans the contents of a local directory and identifies new files (i.e. your new photos or images). It then adds \nthose images to an Album in your iCloud Photos library. \n\n# Disclaimer\n\nAlthough every care has been taken when developing PhotoBridge, there are two **important** things you should be aware of:\n\n1. PhotoBridge is a simple utility I created for myself. I've released it to the public since others might find it useful, however,\n I've only tested this on my system. In the **highly unlikely** event that PhotoBridge destroys your wedding photos, the selfie \n you took with Bono, or the video of baby's first steps, don't come crying to me. You should **ALWAYS** have a backup!\n2. Unfortunately, the way that Apple Photos is built makes it quite difficult to interact with it programmatically.\n This means that, at any point, Apple may decide to change how Photos works, or disable programmatic interation\n entirely. This means that PhotoBridge can stop working without any prior notice!\n\nDue to the above:\n\nTHE SOFTWARE IS PROVIDED \u201cAS IS\u201d, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO\nTHE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS\nOR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n## Requirements\n\n- PhotoBridge *only* runs on macOS systems. It uses AppleScript to interact directly with Apple Photos.\n- PhotoBridge performs *one-way* synchronisation. It will upload new photos in a directory to iCloud Photos. Other solutions \nalready exist which synchronise iCloud Photos to third-party services, such as the NextCloud app, the Immich app etc.\n- PhotoBridge has only been tested in conjunction with NextCloud Photos (because that's how I use it). **In theory**, it should\nalso work with any folder-based photo service, but your mileage may vary.\n\n## What It Does\n\nThe best way to understand what PhotoBridge does is via example. So, we'll use the following example for this section:\n\n- This is Bob:\n\n\n\n- Bob is in Apple's walled garden. He has an iPhone, a Mac and an iCloud subscription. However, Bob also has some non-Apple stuff. \nSo, he's installed the NextCloud app on his iPhone. \n\n\n\n- When Bob takes a photo on his iPhone, iCloud takes care of synchronising it to his other Apple devices. On the other hand,\nthe NextCloud app synchronises it to his non-Apple devices. Bob can see his photo regardless of which device he's using - \nthis is good!\n\n\n\n- There is, however, a problem. Due to Apple's restrictive practices, the NextCloud app on Bob's iPhone only does *one-way sync*. \nThis means photos are uploaded from his iCloud photo library to NextCloud, but not the other way round; whihc means that \nwhen Bob takes a photo on his Android phone, it doesn't make it back to his iCloud photo library. He can only use his non-Apple \ndevices to view that photo. This is bad \ud83d\ude22.\n\n\n\n- Mama Bob didn't raise no fool, so Bob installs PhotoBridge on his Mac. He tells PhotoBridge where the NextCloud app on his Mac \nstores his NextCloud photos. PhotoBridge then scans this folder and builds a database. On every subsequent scan, PhotoBridge \nidentifies new photos, and adds them to Bob's photo library in the desktop Apple Photos app. iCloud will then synchronise these\nto the cloud, and they'll make their way to Bob's iPhone.\n\n\n\n- Now, when Bob takes a photo with his Android phone, or adds a photo to his NextCloud library on a non-Apple device, it will be \nsynchronised to all of his devices. Huzzah!\n\n\n\n## Installing\n\nThe easiest way to install PhotoBridge is via [pipx](https://github.com/pypa/pipx#readme). If you don't have pipx installed,\nyou can easily install it via [HomeBrew](https://brew.sh):\n\n```shell\nbrew install pipx\npipx ensurepath\n```\n\nOnce that's done, run the following command to install PhotoBridge. This will install a ```photobridge``` command on your\nsystem.\n\n```shell\npipx install \"git+https://github.com/keithvassallomt/photobridge.git\"\n```\n\n## Usage\n\n```\nphotobridge [-h] [--photos-folder PHOTOS_FOLDER] [--reset-database] [--dry-run] [--save-current-state]\n```\n\nLet's assume that, on your Mac, NextCloud is storing your photos in ```/Users/Bob/NextCloud/Photos```. Let's also assume that \nprior to using PhotoBridge, you were manually synchronising your NextCloud photos to your iCloud library.\n\nThe first thing you'll need to do is let PhotoBridge build its database of your existing photos. Otherwise, when you run \nPhotoBridge, it will re-upload all your NextCloud photos to iCloud, and that's probably not what you want. So, run this:\n\n```shell\nphotobridge --photos-folder /Users/Bob/NextCloud/Photos --save-current-state \n```\n\nThis has now built the PhotoBridge database. Any photos added to the folder **from this point onwards** will be synchronised to \nApple Photos when you run PhotoBridge. \n\nWhen you want to synchronise your photos, run PhotoBridge as follows:\n\n```shell\nphotobridge --photos-folder /Users/Bob/NextCloud/Photos\n```\n\n## Super-Important Point\n\nSince PhotoBridge relies on the photo's file name for synchornisation, you need to ensure that any app on your devices which is \nsynchronising to your non-Apple cloud (such as NextCloud, Immich, etc.) is **preserving the original filenames used by iCloud***. \nMost apps allow you to do this. \n\nIn NextCloud, for example:\n\n**More** > **Settings** > **Advanced** > **Change filename mask** > **Maintain original filename**.\n\n\n\n\n## Options\n\nThe CLI has a few basic options you may find useful:\n\n| Option | Description | \n|:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ```-h``` | Display the usage instructions. |\n| ```--save-current-state``` | Save the current folder state. Very useful the first time you run PhotoBridge so existing photos aren't re-uploaded. Use with ```--photos-folder```. |\n| ```--reset-database``` | Reset the internal database so all 'known' photos are forgotten. Useful if you screw something up! |\n| ```--photos-folder``` | Add the path to where your non-Apple (e.g. NextCloud) photos are stored. This is the folder which will be synchronised with Apple Photos. |\n| ```--dry-run``` | Use this to simulate a synchronisation without actually moving any data. Useful to confirm what PhotoBridge would do with your photos. Use with ```--photos-folder```. |\n| ```--log-level``` | Set the log level. One of 'debug', 'info', 'warning', 'critical'. Defaults to 'info' |\n\n## See Also\n\nHappy with PhotoBridge? How about also synchronising your Apple Reminders and Notes to non-Apple devices? Check out [TaskBridge](https://taskbridge.app).",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Export photos from a local folder to Apple Photos.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/keithvassallomt/photobridge",
"Repository": "https://github.com/keithvassallomt/photobridge"
},
"split_keywords": [
"sync",
" photo sync",
" cloud photos"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f1073cb90fe854eae3f7c21e4a102d6daf208d8f8c89514dbdd44089694dfa5f",
"md5": "c95de96408673783918b169eebc73832",
"sha256": "2b2567eb36c00685225603513cb153fc42857f2c4a2bf0301c228ed9bf84b221"
},
"downloads": -1,
"filename": "photobridge-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c95de96408673783918b169eebc73832",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.13",
"size": 23182,
"upload_time": "2025-02-05T12:19:13",
"upload_time_iso_8601": "2025-02-05T12:19:13.634088Z",
"url": "https://files.pythonhosted.org/packages/f1/07/3cb90fe854eae3f7c21e4a102d6daf208d8f8c89514dbdd44089694dfa5f/photobridge-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fa921a7f532dfa11ff081ecae5b9d2983bd170a80c42a63d12cfc4e62e8ae917",
"md5": "2929911aa96fdaeb657ee99f6317be1c",
"sha256": "ebff59390585865ed186b3c4257401b8a5fdf013a16e44097d54e8cd18bbc81c"
},
"downloads": -1,
"filename": "photobridge-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "2929911aa96fdaeb657ee99f6317be1c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.13",
"size": 27784,
"upload_time": "2025-02-05T12:19:16",
"upload_time_iso_8601": "2025-02-05T12:19:16.474988Z",
"url": "https://files.pythonhosted.org/packages/fa/92/1a7f532dfa11ff081ecae5b9d2983bd170a80c42a63d12cfc4e62e8ae917/photobridge-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-05 12:19:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "keithvassallomt",
"github_project": "photobridge",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "photobridge"
}
JSON
