From a7f89769e9116554028b3742009b29011b833374 Mon Sep 17 00:00:00 2001 From: ajp_anton Date: Tue, 6 Oct 2026 19:27:57 +0000 Subject: [PATCH] Document new tools and interactive Linux workflows --- README.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 75 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index ff6925c..dd0cb97 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ Small Python scripts for organizing photo collections and preparing or encoding ## Scripts +When started without paths, the path-based tools ask for one file or directory per line until an empty line is entered. Tab completes paths on Linux, including the photo and audio output-directory fields. The repository tracks the entry-point scripts as executable, so on Linux they can also be run as `./photo_metadata.py`, `./audio_tool.py`, and so on. If a graphical session starts one without a terminal, it opens in Konsole or another supported terminal. + ### `photo_metadata.py` Interactive metadata cleanup for photo collections: @@ -12,7 +14,7 @@ Interactive metadata cleanup for photo collections: python3 photo_metadata.py path/to/file/or/directory [...] ``` -Directory inputs are scanned recursively. The script reads metadata, asks for the choices it needs, prints a preview, and only then applies changes in place after confirmation. +With no paths, the script asks for one file or directory per line until an empty line is entered. This is equivalent to supplying several command-line or dragged paths. Directory inputs are scanned recursively. The script reads metadata, asks for the choices it needs, prints a preview, and only then applies changes in place after confirmation. Current features: @@ -22,7 +24,7 @@ Current features: - optional reference-clock correction using a source photo timestamp or filename plus the correct time - keyboard-driven settings table with timezone gap filling and optional fixed timezone offsets - artist/author set, clear, or leave unchanged -- timestamp-based rename modes: adjust timestamps already in filenames, add one, or replace the stem +- optional timestamp renaming: adjust timestamps already in filenames, add one, replace the stem, or leave names unchanged - video filenames use the beginning timestamp by subtracting rounded duration from the video metadata timestamp - Sony-style video sidecars like `C0011.MP4` plus `C0011M01.XML` are moved and renamed with the video - automatic photo burst/HDR grouping per camera @@ -30,15 +32,19 @@ Current features: - inferred subsecond metadata for grouped same-second photo bursts when the group has no existing subseconds - optional capture-time inference from a safe timestamp filename, then `ModifyDate` as a fallback -The working directory is determined from the dragged items. A single dragged folder is the working directory. For multiple dragged files/folders, their last common ancestor is the working directory. Automatic burst/HDR and `.pto` group folders are created inside that working directory. +The default output directory is determined from the selected items. A single selected folder is the default. For multiple selected files/folders, their last common ancestor is used. The first settings row can replace it with an absolute path or a path relative to that default. Automatic burst/HDR and `.pto` group folders are created inside the selected output directory. -The `Organize/group` setting controls all file movement. When enabled, ungrouped files are moved into the working directory and groups are created there; when disabled, files remain in their original directories. Panorama-project grouping is also enabled from that row. +The `Organize/group` setting has three modes. **No moving** leaves files in their existing directories. **Flat** moves every selected media file into the output directory without creating groups. **Grouping** moves ungrouped files there and creates burst/HDR and optional panorama-project group directories. Space cycles the mode; burst size and `.pto` controls are available only in Grouping mode. Panorama project files use the `.pto` extension. When enabled, every media file referenced by a `.pto` file belongs to the same group. If those files already belong to burst/HDR groups, the groups are merged. `.pto` files are moved into the group folder with their referenced files, renamed from the first and last referenced media stems, and their file references are rewritten to the new relative paths. Reference-clock correction is useful when one photo shows a reliable clock. For example, if `DSC01234.JPG` has camera metadata `2026:06:02 22:10:00`, but the clock in the photo shows `22:13:25`, choose reference mode, enter `DSC01234.JPG` as the source, and enter `22:13:25` as the correct time. The script computes a `+00:03:25` shift and applies that correction to the selected files. If you omit the date in the correct time, the script chooses the date closest to the source timestamp, within 12 hours. -The settings table requires an ANSI-capable terminal because it uses arrow keys and inline editing. Use Up/Down to select a row, Left/Right to select an option, Space to toggle an option, and Enter to continue. The preview separates common changes, inferred timestamps, warnings, and file operations before asking for confirmation. +The settings table requires an ANSI-capable terminal because it uses arrow keys and inline editing. Konsole is supported. Use Up/Down to select a row, Left/Right to select an option, Space to toggle an option, and Enter to continue. The preview separates common changes, inferred timestamps, warnings, and file operations before asking for confirmation. + +Dolphin may follow its configured file-type action instead of executing Python files; in that case, use its **Run in Konsole** action or run `./photo_metadata.py` from Konsole. + +In the reference-photo field, Tab completes names from the selected photos (not videos). Ambiguous matches complete their common prefix and show possible names; continue typing to narrow the selection. ### `grouping.py` @@ -48,14 +54,33 @@ Fast manual grouping for selected files: python3 grouping.py path/to/file/or/directory [...] ``` -It does not ask questions. It recursively collects all files inside the dragged files/folders, sorts those files by name, and moves them into one folder named `[first stem]-[last stem]`. +With no arguments, it lists the supported input forms and asks for selections until an empty line is entered. For example: -Manual grouping uses the same working-directory rule as `photo_metadata.py`: +```text +Selection: /photos/DSC0010.JPG DSC0020.JPG +Selection: "/photos/Extra photo.JPG" +Selection: "/photos/Panorama A" "Panorama C" +Selection: /photos/DSC01*.JPG +Selection: /photos/DSC0021.JPG 5 +Selection: +``` + +Each line accepts one path, a wildcard pattern, two range endpoints, or a path followed by a positive integer count. Quote any path/name containing spaces. A range's second endpoint can be just a name or an absolute path, but must be in the first endpoint's directory. Both endpoints must be files or both must be directories. Selection uses case-insensitive alphabetical filename order, includes both endpoints, and skips items of the other type. Reversed endpoints work too. Invalid lines are reported and can be re-entered. + +`*` matches zero or more characters within a filename or directory name. Other wildcard syntax is treated literally. As with shell wildcards, hidden names require an explicit leading dot. Patterns are only allowed in single-path entries, never with a range endpoint or count. Matched folders are collected recursively, as with explicitly selected folders. If a pattern spans several directories, their common parent becomes its working directory. + +A count includes the starting item and selects following items of the same type in its directory: `/photos/A.jpg 5` selects five files; `/photos/FolderA 3` selects three folders. Too few remaining items is an error, not a shortened selection. A purely numeric second token is a count; use an absolute path to specify a numeric filename as a range endpoint. + +Tab completes the first endpoint from filesystem paths. For the second endpoint, it suggests only names in the first endpoint's directory, restricted to the same type (files or folders). Starting the second endpoint with `/` or `~` completes that directory first, then its matching names. Completion quotes names containing spaces. + +Interactive selections must resolve to the same working directory. For paths, ranges, and counts, this is the selected items' parent directory, even when selecting just one folder. All selections are combined into one group; overlapping selections are collected only once. With command-line or dragged paths, the original working-directory rules still apply: - one dragged folder is the working directory - multiple dragged files/folders use their last common ancestor as the working directory -- the group folder is created inside the working directory -- all collected files are flattened into that group folder + +The script recursively collects all file types from selected folders and moves the files into one flat folder named `[first stem]-[last stem]` inside the working directory. Existing group folders are reused, and filename collisions receive `-1`, `-2`, etc. Input directory structure is not preserved. + +Selected folders and their descendants are removed afterward if empty, including pre-existing empty folder trees and selections containing no files at all. Folders with remaining files are kept. The working directory is never removed. ### `view_metadata.py` @@ -96,6 +121,46 @@ If run without files, it asks for source and destination paths. If exactly two f The script copies normal metadata with ExifTool `-TagsFromFile`, while excluding file/system tags, composite tags, image dimensions, pixel dimensions, and resolution fields that should remain specific to the destination file. +### `audio_tool.py` + +Extract, remux, or encode audio from audio files and videos: + +```bash +python3 audio_tool.py path/to/file/or/directory [...] +``` + +The tool probes every selected file, warns about files without audio, and leaves those files untouched. When multi-stream inputs have the same stream layout, it offers one stream selection for those inputs; single-stream inputs always use their only stream. Different multi-stream layouts fall back to their first stream with a warning. + +The keyboard-driven settings table defaults to encoding. Use Up/Down to select a setting and Left/Right to change choices. Bitrate, quality, FLAC compression, and output directory are edited by typing; bare bitrates such as `192` are treated as `192k`, and invalid values remain open for correction. + +Choose `remux` to preserve source audio codecs, or `encode` to produce AAC, Opus, FLAC, or MP3. `Native` keeps each codec's typical audio extension. `MKA` is the broadly compatible universal option. `M4A` is offered only when every relevant codec can be stored in MP4; non-AAC/ALAC M4A combinations are allowed but flagged as less compatible with players. + +A blank output directory places each result beside its source. An absolute path collects every result there; a relative path is resolved from the displayed working directory. The working directory is the dragged directory when exactly one directory is supplied, otherwise it is the inputs' last common ancestor. Missing output directories are created when processing starts. + +The tool skips, remuxes, or re-encodes sources that already match the requested output according to the selected matching-output policy. Audio-only `.mkv` and `.mka` are treated as the same container family, as are `.mp4` and `.m4a`. Video inputs are always extracted into a new audio-only output. Existing and same-batch name collisions receive `-1`, `-2`, and so on. + +AAC presents both the built-in FFmpeg encoder and FDK AAC. FDK AAC uses the normal FFmpeg on `PATH` when it provides `libfdk_aac`. Otherwise the tool asks for an absolute path to an FDK-enabled FFmpeg, verifies it, and remembers that path in the user's Media Batch Tools settings for later runs. It never silently substitutes the built-in encoder when FDK AAC was selected. + +### `metadata_editor.py` + +Interactively inspect, edit, or remove metadata fields in one or more files: + +```bash +python3 metadata_editor.py path/to/file/or/directory [...] +``` + +The ANSI terminal table includes fields found in the selected files plus common writable fields that may be missing. Differing bulk values are shown as `(multiple values)`; selecting and changing one replaces it in every selected file. Use Up/Down to navigate, type to replace a value, Enter to confirm text, Delete to mark a field for removal, and Esc to cancel editing. + +The `GPS coordinates` row accepts decimal degrees or ASCII degrees/minutes/seconds without requiring a degree-sign key: + +```text +58.660600, 16.448300 +58 39 38.16 N, 16 26 53.88 E +58:39:38.16N, 16:26:53.88E +``` + +Negative decimal values mean south/west. N/S/E/W are accepted with either form, but contradictory values such as `-58 N` are rejected. The editor writes normalized EXIF GPS coordinate and hemisphere-reference tags. + ### `video_encode.py` Prepare, validate, encode, and remux Avisynth-edited videos: @@ -190,7 +255,7 @@ Current video scenarios copy fixture videos to temporary directories before proc - Python 3.10 or newer - ExifTool available as `exiftool` on `PATH` -- FFmpeg available as `ffmpeg` and `ffprobe` on `PATH` for `video_encode.py` +- FFmpeg available as `ffmpeg` and `ffprobe` on `PATH` for `video_encode.py` and `audio_tool.py` - MKVToolNix available as `mkvmerge` on `PATH` for VFR or frame-deletion output (Windows also checks its standard installation path) - the x264 command-line encoder available as `x264` on `PATH` for timestamp-aware x264 output - `hdr10plus_tool` available on `PATH` only when re-encoding HDR10+ video while retaining HDR