photein 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e24eda13e60ea0e81a7ac8005f43f9e9a6bf3f04a48893cab7c10f89fd2021a
-  data.tar.gz: 7bca13e3736b841bc6ef20f246f3fc6db4c812a31b4204cd0af5399ade995a61
+  metadata.gz: 8358c084cdf56bab539d9f429706a606cb346b33e7832e056054b2a4ead67e08
+  data.tar.gz: c9e77f835d2ba2d39a3edb08e5fc6973a1871b82c52a823e3bf15a446c263f80
 SHA512:
-  metadata.gz: ed7adb5d47bb15496c5c9a30fe9ac54c616b43cc2dace96d611431005496efb5460d374544fa62a95a68abf249150f2983af5338a76080dfebe938bd6448e4e2
-  data.tar.gz: c17406ac9266527a2d0d85dc61bbc5eeadc90bae17f8ab94885e0616d7d8e06aa400f71b795d2b5c5504853f11c75e76f0a54b5d8d893fdde3f3469860193d83
+  metadata.gz: '08be8726129d9b2c2ffcfe4f9ba206db82619c6b6cd1f8f50339d7390988a3c224c9ecb69da7dedc6edfee5e0c479f6ea4119551af75716039e55eda4635cdc7'
+  data.tar.gz: a91a5a3be62081f8a25333f323a1ed98f2e34421134878679d5af8f3fce674c8e7ef8e1a299d4caa3afd9364af38fbe6ef8136045bfe15ac614afd9cf4d2f9ba

data/README.md

@@ -1,115 +1,157 @@
 Ph📸tein
 ========
 
-Import/rename photos & videos from one directory to another.
+All your photos under one roof.
 
-Why?
-----
+What does it do?
+----------------
 
-* The major cloud photo services (iCloud, Google Photos) are great but not FOSS. 
+This repo provides two related programs: `photein` and `xferase`.
 
-  (My digital photo/video library belongs to me,
-  but if I don’t control the pipeline for viewing/managing it,
-  then does it really?)
+### Photein
 
-* Importing photos from many sources
-  (📱 cell phone / 📷 digital camera / 💬 chat app)
-  into one library with as few manual steps as possible
-  is not simple, especially on Linux.
+Photein is a CLI utility for managing your photos **at the filesystem level**.
+It won’t let you browse or edit your photos,
+but it will give them a uniform folder structure and filenames,
+no matter where they come from:
 
-What does it do?
-----------------
+```sh
+# Before                                # After
+
+~/Pictures                              ~/Pictures
+└── _inbox                              ├── _inbox
+    ├── 1619593208911.jpeg              ├── 2020
+    ├── DCIM                            │   ├── 2020-08-01_113129.heic
+    │   └── 2021_03_26                  │   └── 2020-05-20_160209.png
+    │       ├── R0014285.MOV            └── 2021
+    │       ├── R0014286.DNG                ├── 2021-02-12_081933a.jpg
+    │       ├── R0014286.JPG                ├── 2021-02-12_081933b.jpg
+    │       ├── R0014287.DNG                ├── 2021-02-12_081939.mp4
+    │       └── R0014287.JPG                ├── 2021-03-26_161245.mp4
+    ├── IMG_20210212_081933_001.jpg         ├── 2021-03-26_161518.dng
+    ├── IMG_20210212_081933_002.jpg         ├── 2021-03-26_161518.jpg
+    ├── IMG_8953.HEIC                       ├── 2021-03-26_170304.dng
+    ├── Screenshot_20200520_160209.png      ├── 2021-03-26_170304.jpg
+    └── VID_20210212_081939.mp4             └── 2021-04-28_000008.jpg
+```
 
-Suppose your digital camera creates files with names like `R0017839.JPG`.
-Photein will...
+> ⚠️ **Note**
+>
+> If you use a photo management app that decides
+> where and how your photos should be stored on your system (like Apple Photos), 
+> Photein is not for you.
 
-* look for a timestamp in...
-  * EXIF metadata
-  * filename
-  * file birthtime
-* rename files by that timestamp (`YYYY-mm-dd_HHMMSS.jpg`)
-* handle conflicts for identical timestamps (`YYYY-mm-dd_HHMMSSa.jpg`, `YYYY-mm-dd_HHMMSSb.jpg`...)
-* sort files into subdirectories by year (`YYYY/YYYY-mm-dd_HHMMSS.jpg`)
-* optionally, optimize media for reduced filesize
+### Xferase
 
-#### Supported media formats
+Xferase is a background service built on top of photein.
+It watches a directory of your choosing,
+and whenever any files are placed there,
+it automatically imports them into your photo library.
 
-* .jpg
-* .dng
-* .heic
-* .png
-* .mp4
-* .mov
+It creates and manages two parallel copies of your library
+(one original/hi-res, one optimized for web)
+and ensures that when you delete a photo from one,
+it is automatically removed from the other.
 
-### So how do I use it?
+When combined with other software,
+Xferase can be used as a self-hosted / DIY alternative
+to cloud photo services like Google Photos or iCloud.
 
-#### 📷 Auto-import from a digital camera (Linux)
+Why?
+----
 
-Customize the provided [sample systemd service][]
-to mount, import from, and unmount your camera
-whenever you plug it in via USB.
+I could not find any existing software product that:
 
-```sh
-$ mkdir -p ~/.local/share/systemd/user
-$ curl https://raw.githubusercontent.com/rlue/photein/master/examples/share/systemd/user/photein-dcim.service -o ~/.local/share/systemd/user/photein-dcim.service
-$ systemctl --user daemon-reload
-$ systemctl --user enable photein-dcim.service
-```
+1. imports photos from many sources\* with **no mouse or keyboard interaction**
 
-> Note: The provided systemd service makes the following
-> assumptions:
->
-> * Your device’s label is `RICOH_GR`. 
->   (Use `systemctl --all --full -t device`
->   to determine the label of your USB device.)
-> * You use [rbenv][] to manage your system’s Ruby environment.
->
-> Adjust accordingly.
+   \*_e.g.,_ 📱 cell phone / 📷 digital camera / 💬 chat app download
 
-[sample systemd service]: blob/master/examples/share/systemd/user/photein-dcim.service
-[rbenv]: https://github.com/rbenv/rbenv
+2. enforces a clean, consistent, **user-visible directory & filename scheme**
 
-#### 📱 Auto-import from an Android phone
+   (I want to be able to access my photos from the file manager,
+   find them in an “Open...” dialog,
+   or sync them to other devices with tools like Dropbox or Syncthing.)
 
-Use [Syncthing][] to sync photos from your phone to a staging directory on
-your computer. Then, run photein in a cron job to import those photos into
-your library on a daily basis.
+3. comes with **no recurring subscription fee**—or better yet, is FOSS
 
-[Syncthing]: https://syncthing.net/
+   (My digital photo/video library belongs to me,
+   but if I don’t control the pipeline for viewing/managing it,
+   then does it really?)
+
+4. works with Linux
+
+> ⚠️ **Note**
+>
+> Strictly speaking, Photein does not handle requirement #1;
+> for that, use Xferase in combination with other software,
+> such as Syncthing or systemd.
 
 Installation
 ------------
 
 ```sh
-$ git clone https://github.com/rlue/photein
-$ cd photein
-$ gem build photein.gemspec
-$ gem install photein-0.0.1.gem
+$ gem install photein
 ```
 
+### Dependencies
+
+* Ruby 2.7+
+* [ExifTool][]
+* [MediaInfo][]
+* ImageMagick (for `--optimize-for=web` option)
+* OptiPNG (for `--optimize-for=web` option)
+* ffmpeg (for `--optimize-for={web,desktop}` options)
+
+[ExifTool]: https://exiftool.org/
+[MediaInfo]: https://mediaarea.net/MediaInfo
+
 Usage
 -----
 
+### Simple import
+
 ```sh
 $ photein \
-    --source=/media/ricoh_gr/DCIM \ # pull photos & videos from here
-    --dest=/home/rlue/Pictures      # and deposit them here (in per-year subdirectories)
+    --source /media/ricoh_gr/DCIM \ # batch-import photos from here
+    --recursive \                   # including subdirectories
+    --dest /home/rlue/Pictures      # into here
 ```
 
 Use `photein --help` for a summary of all options.
 
-Dependencies
-------------
+#### Supported media formats
 
-* [ExifTool][]
-* [MediaInfo][]
-* ImageMagick (for `--optimize-for=web` option)
-* OptiPNG (for `--optimize-for=web` option)
-* ffmpeg (for `--optimize-for={web,desktop}` options)
-* lsof (for `--safe` option)
+* .jpg
+* .dng
+* .heic
+* .png
+* .mp4
+* .mov
 
-[ExifTool]: https://exiftool.org/
-[MediaInfo]: https://mediaarea.net/MediaInfo
+### Automation guides
+
+* [📷➡️🖥️ Set up auto-import from a digital camera](doc/auto-import-digital-camera.md)
+* [📱➡️🖥️ Set up auto-import from an Android phone](doc/auto-import-android-phone.md)
+* [📱🔄🖥️ Mirror your library across multiple devices](doc/mirroring-a-library-on-multiple-devices.md)
+
+Development
+-----------
+
+Contributions welcome.
+
+> ⚠️ **Warning**
+>
+> The RSpec test suite contains no unit tests.
+> It solely tests `photein` as a CLI utility, or in other words,
+> it defines expectations against the effects of `system('photein <args>')`.
+>
+> Because `Kernel#system` runs the given command in a subprocess, 
+> it prints to a different stdout than
+> native Ruby code in a normal RSpec example.
+> This makes test failures cumbersome to debug,
+> because `puts` statements never appear in the test output,
+> and `binding.pry` will cause the test to appear to hang
+> as it waits for user input on an invisible stdin.
 
 License
 -------

data/lib/photein/image.rb

@@ -41,9 +41,8 @@ module Photein
           convert << tempfile
         end unless Photein::Config.dry_run
       when '.png'
-        return if !Optipng.available?
-
         FileUtils.cp(path, tempfile, noop: Photein::Config.dry_run)
+        Photein::Logger.info "optimizing #{path}"
         Optipng.optimize(tempfile, level: 4) unless Photein::Config.dry_run
       end
     end

data/lib/photein/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Photein
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: photein
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Ryan Lue
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-05-20 00:00:00.000000000 Z
+date: 2021-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mediainfo