photein 0.0.1 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e24eda13e60ea0e81a7ac8005f43f9e9a6bf3f04a48893cab7c10f89fd2021a
-  data.tar.gz: 7bca13e3736b841bc6ef20f246f3fc6db4c812a31b4204cd0af5399ade995a61
+  metadata.gz: 5404ec50b0c5a57144fea72eff5639ca90a19a46be319cb8ee634d9f67291617
+  data.tar.gz: bce672716a27ea28f9d4203e1858affa8793a11b5ca94e3642c6d86399969680
 SHA512:
-  metadata.gz: ed7adb5d47bb15496c5c9a30fe9ac54c616b43cc2dace96d611431005496efb5460d374544fa62a95a68abf249150f2983af5338a76080dfebe938bd6448e4e2
-  data.tar.gz: c17406ac9266527a2d0d85dc61bbc5eeadc90bae17f8ab94885e0616d7d8e06aa400f71b795d2b5c5504853f11c75e76f0a54b5d8d893fdde3f3469860193d83
+  metadata.gz: f11aba53e3bcdef67a150a549da7c16c45e0350b4bbdcfb4f1d1ce4c0fd778185845ef4719857e9eea4b1c15894578ae4e1b361952da3961c77fb1b0cc56c0bb
+  data.tar.gz: 2967ccf17b7d7631325ff9b18e445b052a52db8ddec3043cc0b4b15945b0b0c0bba52f0862044f554067950b578447235771abd1d97103346492ba6de821029a

data/README.md

@@ -1,115 +1,138 @@
 Ph📸tein
 ========
 
-Import/rename photos & videos from one directory to another.
-
-Why?
-----
-
-* The major cloud photo services (iCloud, Google Photos) are great but not FOSS. 
-
-  (My digital photo/video library belongs to me,
-  but if I don’t control the pipeline for viewing/managing it,
-  then does it really?)
-
-* 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.
+A no-nonsense way to organize your personal photo library.
 
 What does it do?
 ----------------
 
-Suppose your digital camera creates files with names like `R0017839.JPG`.
-Photein will...
-
-* 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
-
-#### Supported media formats
+Photein manages 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:
 
-* .jpg
-* .dng
-* .heic
-* .png
-* .mp4
-* .mov
+```sh
+# Before                                # After
+
+~                                       ~
+├── Downloads                           ├── Downloads
+│   ├── 1619593208911.jpeg              └── Pictures
+│   ├── DCIM                                ├── 2020
+│   │   └── 2021_03_26                      │   ├── 2020-08-01_113129.heic
+│   │       ├── R0014285.MOV                │   └── 2020-05-20_160209.png
+│   │       ├── R0014286.DNG                └── 2021
+│   │       ├── R0014286.JPG                    ├── 2021-02-12_081933a.jpg
+│   │       ├── R0014287.DNG                    ├── 2021-02-12_081933b.jpg
+│   │       └── R0014287.JPG                    ├── 2021-02-12_081939.mp4
+│   ├── IMG_20210212_081933_001.jpg             ├── 2021-03-26_161245.mp4
+│   ├── IMG_20210212_081933_002.jpg             ├── 2021-03-26_161518.dng
+│   ├── IMG_8953.HEIC                           ├── 2021-03-26_161518.jpg
+│   ├── Screenshot_20200520_160209.png          ├── 2021-03-26_170304.dng
+│   └── VID_20210212_081939.mp4                 ├── 2021-03-26_170304.jpg
+└── Pictures                                    └── 2021-04-28_000008.jpg
+```
 
-### So how do I use it?
+Photein generates these folders & filenames
+based on metadata timestamps, filename timestamps, or file creation times.
 
-#### 📷 Auto-import from a digital camera (Linux)
+> ⚠️ **Note**
+>
+> If you use a photo management app that decides
+> where and how your photos should be stored on disk
+> (looking at you, Apple Photos 👀), Photein is not for you.
 
-Customize the provided [sample systemd service][]
-to mount, import from, and unmount your camera
-whenever you plug it in via USB.
+It can also optimize photos and videos for reduced file size.
 
-```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
-```
+What _doesn’t_ it do?
+---------------------
 
-> 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.
+On its own, Photein is **not** an alternative
+to cloud photo services like Google Photos or iCloud—but
+in combination with other software, it can be.
 
-[sample systemd service]: blob/master/examples/share/systemd/user/photein-dcim.service
-[rbenv]: https://github.com/rbenv/rbenv
+If you want to:
 
-#### 📱 Auto-import from an Android phone
+* import photos from your phone as soon as you take them
+* import photos from a digital camera / SD card as soon as you plug it in
+* mirror a low-res copy of your entire photo library to your Android phone
 
-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.
+check out Photein’s sister utility [Xferase][],
+or try the [automation guides][] below.
 
-[Syncthing]: https://syncthing.net/
+[Xferase]: https://github.com/rlue/xferase
+[automation guides]: #automation-guides
 
 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.6+
+* [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
 -----
 
 ```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
+
+Using Photein + systemd, you can:
+
+* [📷➡️🖥️ Set up auto-import from a digital camera](guides/auto-import-digital-camera.md)
+
+But for more complex tasks, like:
+
+* 📱➡️🖥️ Setting up auto-import from an Android phone
+* 📱🔄🖥️ Mirroring your library across multiple devices
+
+check out the documentation for [Xferase][],
+an always-on background service based on Photein.
+
+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 `rspec` itself.
+> 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,10 +41,14 @@ 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)
-        Optipng.optimize(tempfile, level: 4) unless Photein::Config.dry_run
+        Photein::Logger.info "optimizing #{path}"
+        begin
+          Optipng.optimize(tempfile, level: 4) unless Photein::Config.dry_run
+        rescue Errno::ENOENT
+          Photein::Logger.error('optipng is required to compress PNG images')
+          raise
+        end
       end
     end
 
@@ -52,10 +56,20 @@ module Photein
 
     def image
       @image ||= MiniMagick::Image.open(path)
+    rescue MiniMagick::Invalid => e
+      Photein::Logger.error(<<~MSG) if e.message.match?(/You must have ImageMagick/)
+        ImageMagick is required to manipulate image files
+      MSG
+      raise
     end
 
     def metadata_stamp
       MiniExiftool.new(path.to_s).date_time_original
+    rescue MiniExiftool::Error => e
+      Photein::Logger.error(<<~MSG) if e.message.match?(/exiftool: not found/)
+        exiftool is required to read timestamp metadata
+      MSG
+      raise
     end
 
     # NOTE: This may be largely unnecessary:

data/lib/photein/media_file.rb

@@ -20,6 +20,7 @@ module Photein
     end
 
     def import
+      return if corrupted?
       return if Photein::Config.interactive && denied_by_user?
       return if Photein::Config.safe && in_use?
       return if Photein::Config.optimize_for && non_optimizable_format?
@@ -44,6 +45,12 @@ module Photein
 
     private
 
+    def corrupted?(result = false)
+      return result.tap do |r|
+        Photein::Logger.error("#{path.basename}: cannot import corrupted file") if r
+      end
+    end
+
     def denied_by_user?
       $stdout.printf "Import #{path}? [y/N]"
       (STDIN.getch.downcase != 'y').tap { $stdout.puts }

data/lib/photein/version.rb

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

data/lib/photein/video.rb

@@ -53,13 +53,23 @@ module Photein
 
     private
 
+    def corrupted?
+      super(video.bitrate.nil?)
+    end
+
     def video
       @video ||= FFMPEG::Movie.new(path.to_s)
+    rescue Errno::ENOENT
+      Photein::Logger.error('ffmpeg is required to manipulate video files')
+      raise
     end
 
     def metadata_stamp
       # video timestamps are typically UTC
       MediaInfo.from(path.to_s).general.encoded_date&.getlocal
+    rescue MediaInfo::EnvironmentError
+      Photein::Logger.error('mediainfo is required to read timestamp metadata')
+      raise
     end
 
     # NOTE: This may be largely unnecessary:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: photein
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.6
 platform: ruby
 authors:
 - Ryan Lue
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-05-20 00:00:00.000000000 Z
+date: 2021-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mediainfo
@@ -53,33 +53,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '4.11'
 - !ruby/object:Gem::Dependency
-  name: optipng
+  name: nokogiri
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '1.11'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '1.11'
 - !ruby/object:Gem::Dependency
-  name: nokogiri
+  name: optipng
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: streamio-ffmpeg
   requirement: !ruby/object:Gem::Requirement
@@ -95,19 +95,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: pry-remote
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.14'
+        version: '0.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.14'
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement