Twitterpunch is designed to work with PhotoBooth and OS X Folder Actions. When this script is called with the name of an image file, it will post the image to Twitter, along with a message randomly chosen from a list and a specified hashtag.

If you call the script with the --stream argument instead, it will listen for tweets to that hashtag and download them to a specified directory. If the tweet came from another user, Twitterpunch will speak it aloud.

Typically, you'll run one copy on an OSX laptop with PhotoBooth, and a separate copy on another machine (either Windows or OSX) for the viewer. You can also use a mobile device as a remote control, if you like. This will allow the user to enter a custom message for each photo that gets tweeted out, if they'd like.

Configure the program via the ~/.twitterpunch/config.yaml YAML file. This file should look similar to the example below.

---
:twitter:                               # twitter configuration
  :consumer_key: <consumer key>
  :consumer_secret: <consumer secret>
  :access_token: <access token>
  :access_token_secret: <access secret>
:messages:                              # list of messages to attach
- Hello there                           # to outgoing tweets
- I'm a posting fool
- minimally viable product
:hashtag: Twitterpunch                  # The hashtag to post and listen to
:handle: Twitterpunch                   # The twitter username to post as
:photodir: ~/Pictures/twitterpunch/     # Where to save downloaded images
:logfile: ~/.twitterpunch/activity.log  # Where to save logs
:viewer:                                # Use the built-in slideshow viewer
  :count: 5                             # How many images to have onscreen at once
:remote:
  :timeout: 45                          # How long the button should remain disabled for
  :apptitle: dslrBooth                  # The photo booth application title
  :hotkey: space                        # Which hotkey to send to trigger a photo

1. Generate a skeleton configuration file
   • twitterpunch --configure
2. Edit the configuration file as needed. You'll be prompted with the path.
   • If you have your own Twitter application credentials, you're welcome to use them.
3. Authorize the application with the Twitter API.
   • twitterpunch --authorize

1. Start PhotoBooth at least once to generate its library.
2. Install the Twitterpunch Folder Action
   • twitterpunch --install
   • It may claim that it could not be attached, fear not.
3. Profit!
   • and by that, I mean take some shots with PhotoBooth!

Note: if the folder action doesn't seem to work and photos aren't posted to Twitter, here are some troubleshooting steps to take:

1. Run Twitterpunch by hand with photos as arguments. This may help you isolate configuration or authorization issues.
   • twitterpunch foo.jpg
2. Correct the path in the workflow.
   • which twitterpunch
   • Edit the Twitterpunch folder action to include that path.

Configure the remote web app using the :remote hash in config.yaml. You can usually find the title of the app using system_profiler -detailLevel full SPApplicationsDataType and grepping for the name or path to the .app.

In this example, the title is dslrBooth.

[ben@ganymede] ~ $ system_profiler -detailLevel full SPApplicationsDataType | grep -B8 dslrBooth.app
    dslrBooth:

      Version: 2.9
      Obtained from: Identified Developer
      Last Modified: 10/14/17, 9:50 PM
      Kind: Intel
      64-Bit (Intel): Yes
      Signed by: Developer ID Application: Hope Pictures LLC (MZR5GHAQX4), Developer ID Certification Authority, Apple Root CA
      Location: /Applications/dslrBooth.app

1. Run the app with twitterpunch --remote
2. Browse to the app with http://{address}:8080
3. [optional] If on an iOS device, add to your homescreen
   • This will give you "app behaviour", such as full screen, and a nice icon

1. Make sure the folder action is installed properly
   1. Use the Finder to navigate to ~/Pictures/
   2. Right click on the Photo Booth Library icon and choose Show Package Contents.
   3. Right click on the Pictures folder and choose Services > Folder Actions Setup
   4. Make sure that the Twitterpunch action is attached.
2. Install the folder action
   1. Open the resources folder of this gem.
      • Likely to be found in /Library/Ruby/Gems/{version}/gems/twitterpunch-#{version}/resources/.
   2. Double click on the Twitterpunch folder action and install it.
      • It may claim that it could not be attached, fear not.

Configure the program you are using for your photo shoot to call Twitterpunch each time it snaps a photo. Pass the name of the new photo as a command line argument. Alternatively, you could batch them, as Twitterpunch can accept multiple files at once.

[ben@ganymede] ~ $ twitterpunch photo.jpg [photo2.jpg photo3.jpg photo4.jpg]

You can manually install the Folder Action, or you can follow the automated install process after tweaking the workflow slightly.

1. Identify where the app stores the resulting image files.
2. Edit the Twitterpunch folder action to include that path.
3. Follow the steps above to install the Folder Action.

Twitterpunch will run on OS X or Windows equally well. Simply configure it on the computer that will act as the Twitter display and then run in streaming mode.

[ben@ganymede] ~ $ twitterpunch --stream

There are two modes that Twitterpunch can operate in.

1. If a :hashtag is defined then all images tweeted to the configured hashtag will be displayed in the slideshow.
2. Otherwise, Twitterpunch will stream the :handle Twitter user's stream and display all images either posted by that user or addressed to that user. With protected tweets, you can have rudimentary access control.

In either mode, tweets that come from any other user will also be spoken aloud.

If you don't want to use the built-in slideshow viewer, you can disable it by removing the :viewer key from your ~/.twitterpunch/config.yaml config file. Twitterpunch will then simply download the tweeted images and save them into the :photodir directory. You can then use anything you like to view them.

There are currently two decent viewing options I am aware of.

• Windows background image:
  • Configure the Windows background to randomly cycle through photos in a directory.
  • Hide desktop icons.
  • Hide the taskbar.
  • Disable screensaver and power savings.
  • Drawbacks: You're using Windows and you have to install Ruby & RubyGems manually.
• OS X screensaver:
  • Choose one of the sexy screensavers and configure it to show photos from the :photodir
  • Set screensaver to a super short timeout.
  • Disable power savings.
  • Drawbacks: The screensaver doesn't reload dynamically, so I have to kick it and you'll see it reloading each time a new tweet comes in.

• It currently requires manual setup for Folder Actions.
• Rubygame is kind of a pain to set up.

• Author: Ben Ford
• Email: binford2k@gmail.com
• Twitter: @binford2k
• IRC (Freenode): binford2k