Initial version of Switch Capture Tagger

Author: ticky

.gitignore

@@ -0,0 +1 @@
+/Switch Capture Tagger.app

Readme.md

@@ -0,0 +1,31 @@
+# Switch Capture Tagger
+
+Automatically correct and update metadata in Nintendo Switch captures imported to Apple Photos
+
+## Features
+
+- Identifies and corrects the incorrect date and time metadata produced by Switch system software versions prior to 10.0.0
+- Adds Keywords for both Nintendo Switch and individual games to each capture
+- Grabs individual game names from <https://github.com/RenanGreca/Switch-Screenshots>
+
+## Usage
+
+You will need to set up an Album in Photos for Switch Capture Tagger to work from due to the slow nature of querying the Photos database.
+
+The album needs to be called "Switch Capture Tagger Scratch". A Smart Album with these parameters can help to target likely Switch captures:
+
+    Match [all ] of the following conditions:
+     [Camera Model ] [is empty         ]
+     [Lens         ] [is empty         ]
+     [Filename     ] [includes         ] [-]
+     [Filename     ] [does not include ] [ ]
+     [Filename     ] [does not include ] [n]
+     [Filename     ] [does not include ] [o]
+
+Note that this works well with target albums of around 300 files on my machine. Larger albums tend to time out when querying and I have yet to find a workaround. If your Smart Album returns a very large number of items, you may need to rename it and use a manually-managed album where you drag around 150-300 items and run Switch Capture Tagger over each group. Suggestions for how to better handle this performance problem are very welcome!
+
+The script is in `Switch Capture Tagger.js`, and can be opened in Script Editor and run from there (you'll need to select JavaScript where it very likely says AppleScript under the toolbar; Script Editor doesn't have a plain-text extension which indicates JavaScript).
+
+An easier option is to run the build script, `build.sh`, which will produce a `Switch Capture Tagger` Application.
+
+This application can be run from anywhere, and will request access to control Photos before proceeding.

Switch Capture Tagger.js

@@ -0,0 +1,200 @@
+/* global Application */
+(() => {
+	// Because filtering the entire Photos library is very slow,
+	// we need to use a Smart Album to speed things up.
+	//
+	// You'll need to create a Smart Album with this exact name:
+	const SMART_ALBUM_NAME = "Switch Capture Tagger Scratch";
+	// and to make sure that it has these filter settings:
+	//
+	//   Match [all ] of the following conditions:
+	//
+	//    [Camera Model ] [is empty         ]
+	//    [Lens         ] [is empty         ]
+	//    [Filename     ] [includes         ] [-]
+	//    [Filename     ] [does not include ] [ ]
+	//    [Filename     ] [does not include ] [n]
+	//    [Filename     ] [does not include ] [o]
+	//
+	// This filter is not perfect; some non-Switch items will
+	// likely show up in it. Unfortunately we can't do all the
+	// filtering we need with a Smart Album, or this would be
+	// more direct. Fundamentally, though, this finds items with
+	// no camera information (i.e. you didn't shoot this on your
+	// iPhone or any modern digital camera), excludes PNGs & MOVs,
+	// and trims out a few other things.
+	// The real business end of the filtering is done with the
+	// regular expression here:
+	const NAME_REGEX = /^(?<year>[0-9]{4})(?<month>[0-9]{2})(?<day>[0-9]{2})(?<hour>[0-9]{2})(?<minute>[0-9]{2})(?<second>[0-9]{2})[0-9]{2}-(?<titleId>[0-9A-F]{32}).(?<extension>mp4|jpg)$/;
+	// Once you've run this script, it's easy to find Switch media
+	// either by filtering on the "Nintendo Switch" keyword, or
+	// with the keywords which include the game name.
+
+	const ScriptRunner = Application.currentApplication();
+	ScriptRunner.includeStandardAdditions = true;
+	
+	Progress.completedUnitCount = 0;
+	Progress.description = "Preparing";
+	Progress.additionalDescription = `Looking for source album`;
+
+	const Photos = Application('Photos');
+	
+	// Grab the album we're after, and check we got one and only one
+	const albums = Photos.albums.whose({ name: SMART_ALBUM_NAME });
+	if (albums.length !== 1) {
+		ScriptRunner.displayAlert(
+			"Error finding Album",
+			{
+				as: 'critical',
+				message: `${albums.length > 1 ? 'Too many matching albums were' : 'No matching album was'} found.\n\nPlease make sure there is a “${SMART_ALBUM_NAME}” Smart Album which filters for items with empty Camera Model and Lens, and file names including “-” and not including “n”, “o” or “ ”.\n\nFor more information please see the script.`
+			}
+		);
+		
+		return 2;
+	}
+
+	Progress.additionalDescription = "Downloading list of Nintendo Switch title IDs";
+
+	// We pinch a mapping of title IDs to game names from the Switch-Screenshots project
+	const GAME_IDS = ((url) => JSON.parse(ScriptRunner.doShellScript(`curl -sL "${url}"`)))("https://github.com/RenanGreca/Switch-Screenshots/raw/master/game_ids.json");
+	
+	// Keep track of how many items were Switch items, and how many needed updates
+	let matchedItems = 0;
+	let updatedItems = 0;
+
+	Progress.description = "Processing Nintendo Switch captures";
+	Progress.additionalDescription = "Getting a list of captures";
+
+	// Here we whittle down the items further, because
+	// the Smart Album can't filter on dimensions or handle
+	// the _or clause we do here.
+	Array.prototype.forEach.call(
+		albums.first.mediaItems.whose({
+			width: 1280,
+			height: 720,
+			filename: {
+				_contains: '-'
+			},
+			_or: [
+				{ filename: { _endsWith: '.mp4' } },
+				{ filename: { _endsWith: '.jpg' } }
+			]
+		})
+		.id(),
+		(id, index, array) => {
+			if (index === 0) {
+				Progress.totalUnitCount = array.length;
+			}
+
+    		Progress.additionalDescription = `Analysing capture ${index + 1} of ${array.length}`
+
+			// We cannot rely on the index-based collection normally returned
+			// by filtering on mediaItems, as we manipulate properties which
+			// may affect the ordering. Instead, we grab the IDs and always
+			// look up the media item using them first.
+			const mediaItem = Photos.mediaItems.byId(id);
+
+			// We use a regular expression to check for sure if the file is a
+			// Switch screenshot or video, and to pull the information out of it.
+			const match = NAME_REGEX.exec(mediaItem.filename());
+
+			// If this is null, the file isn't a Nintendo Switch one after all; skip it!
+			if (!match) {
+				return;
+			}
+
+			matchedItems++;
+			let updated = false;
+
+			// Grab the information out of the filename.
+			const { year, month, day, hour, minute, second, titleId, extension } = match.groups;
+
+			// The Switch was released to the public in 2017, and until
+			// system update 10.0.0 on April 16th, 2020 it emitted broken
+			// date information (~Jan 1st 1970) in videos.
+			//
+			// If an item's date is before 2017, we'll let the date in
+			// the file name take precedence for our purposes.
+			if (mediaItem.date().getFullYear() < 2017) {
+				// Construct a date out of the information in the filename
+				//
+				// Note that the filename's date is in local time, so this
+				// may be inaccurate if you've been in multiple time zones
+				// with your Switch.
+				//
+				// Manually correcting the time zone if you know you've
+				// travelled is what I'd recommend!
+				mediaItem.date = new Date(year, month - 1, day, hour, minute, second);
+				updated = true;
+			}
+			
+			// Additionally, we will add some Switch-related keywords.
+			const keywords = mediaItem.keywords() || [];
+			const originalKeywords = Array.from(keywords);
+			
+			// If the game title isn't known to us, we'll add something based on the ID instead
+			const missingTitleString = `Nintendo Switch: Unknown title ID ${titleId}`;
+			
+			// Grab the game title from our list
+			const gameTitle = GAME_IDS[titleId];
+			if (gameTitle) {
+				// Add the game title to the keywords
+				const gameTitleString = `Nintendo Switch: ${gameTitle}`;
+				if (keywords.indexOf(gameTitleString) === -1) {
+					keywords.push(gameTitleString);
+				}
+
+				// Remove the missing title keyword if it's there
+				const missingTitleIndex = keywords.indexOf(missingTitleString);
+				if (missingTitleIndex !== -1) {
+					keywords.splice(missingTitleIndex, 1);
+				}
+			} else {
+				// Add the missing title string
+				if (keywords.indexOf(missingTitleString) === -1) {
+					keywords.push(missingTitleString);
+				}
+			}
+
+			// Always add the "Nintendo Switch" keyword for Switch items
+			if (keywords.indexOf('Nintendo Switch') == -1) {
+				keywords.push('Nintendo Switch');
+			}
+			
+			// Only publish keyword updates if we're changing things around
+			if (keywords.length !== originalKeywords.length || !keywords.every((item, index) => item === originalKeywords[index])) {
+				mediaItem.keywords = keywords;
+				updated = true;
+			}
+			
+			if (updated) {
+				updatedItems++;
+			}
+
+			Progress.completedUnitCount = index + 1;
+		}
+	);
+
+	Progress.description = "Finished processing Nintendo Switch captures";
+	Progress.additionalDescription = "Reporting the results to you!";
+
+	if (matchedItems == 0) {
+		ScriptRunner.displayAlert(
+			"Switch Capture Tagger",
+			{
+				as: 'critical',
+				message: `No Switch captures were found in the “${SMART_ALBUM_NAME}” Smart Album.\n\nIf you expected some, double check they weren't renamed before importing.`
+			}
+		);
+		
+		return 1;
+	} else {
+		ScriptRunner.displayAlert(
+			"Switch Capture Tagger",
+			{
+				as: 'informational',
+				message: `Of the ${matchedItems.toLocaleString()} Switch capture${matchedItems.toLocaleString === 1 ? '' : 's'} in “${SMART_ALBUM_NAME}”, ${updatedItems.toLocaleString()} needed metadata updates.`
+			}
+		);
+	}
+})();

build.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if ! command -v osacompile >/dev/null || ! command -v defaults >/dev/null || ! command -v plutil >/dev/null; then
+  echo "Could not find osacompile, defaults and/or plutil commands!"
+  echo "This script will only work on macOS hosts."
+  exit 1
+fi
+
+TARGET="Switch Capture Tagger.app"
+SOURCE="Switch Capture Tagger.js"
+
+# We need to resolve the current directory as an absolute path for later use
+SCRIPTDIR="$(cd "$(dirname "$0")" >/dev/null 2>&1; pwd -P)"
+
+if [[ -d "$SCRIPTDIR/$TARGET" ]]; then
+  echo "Removing existing build..."
+  rm -rf "${SCRIPTDIR:?}/$TARGET"
+fi
+
+echo "Compiling script to app..."
+
+osacompile -l JavaScript \
+  -o "$SCRIPTDIR/$TARGET" \
+  "$SCRIPTDIR/$SOURCE"
+
+echo "Writing app metadata..."
+
+PLIST="$SCRIPTDIR/$TARGET/Contents/Info.plist"
+
+function deleteInfo {
+  defaults delete "$PLIST" "$1"
+}
+
+function writeInfo {
+  defaults write "$PLIST" "$1" "$2"
+}
+
+# We *don't* use Apple Music, Calendars, Camera, Contacts, HomeKit,
+# Microphone, Photo Library API, Reminders, Siri or Administrator access
+deleteInfo NSAppleMusicUsageDescription
+deleteInfo NSCalendarsUsageDescription
+deleteInfo NSCameraUsageDescription
+deleteInfo NSContactsUsageDescription
+deleteInfo NSHomeKitUsageDescription
+deleteInfo NSMicrophoneUsageDescription
+deleteInfo NSPhotoLibraryUsageDescription
+deleteInfo NSRemindersUsageDescription
+deleteInfo NSSiriUsageDescription
+deleteInfo NSSystemAdministrationUsageDescription
+
+# Update relevant metadata
+writeInfo  NSAppleEventsUsageDescription  "Access to control Photos is necessary so Switch Capture Tagger can find Switch captures, read their names, and update their date, time and keywords"
+writeInfo  CFBundleIdentifier             "net.jessicastokes.switch-capture-tagger"
+writeInfo  CFBundleShortVersionString     "0.1.0"
+writeInfo  NSHumanReadableCopyright       "Copyright © 2020 Jessica Stokes"
+
+# For whatever reason, defaults really likes to convert to binary form,
+# for readability we convert back to xml format like most other apps use
+plutil -convert xml1 "$PLIST"
+
+# TODO: Icon?
+
+echo "Done! The app can be found at $SCRIPTDIR/$TARGET"