PECOMATO(1)

📦
version 0.0.15 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

✨ pecomato — a portable picture-embedded metadata processor ✨

okay bestie, welcome to pecomato, part of the General Commands Manual, section 1. this is the girl who reads your photos' secrets. 💅

🌸 NAME 🌸

pecomato — a portable picture-embedded metadata processor

🦋 SYNOPSIS 🦋

pecomato [OPTION...] OP [EXPR] FILE [FILE...]

pecomato [OPTION...] OP [EXPR] @FILE

so real talk, the OP EXPR form of this? it only matters for the OP mode dump-value, okay, keep that in mind.

and @file is the cutest little trick — you hand it a file, and it reads a list of files from that file. exactly one filename per line, and no escaping anything, bestie, the filenames get taken as-is. no cap. 🫶

💖 DESCRIPTION 💖

pecomato is literally built to display any kind of information embedded in picture files, and also to check it, filter it, extract it, remove it, add it, and fix it. like, it's a whole metadata processor. it's giving multitask queen. 👑

here's what it can read, format-wise:

  • JPEG/JFIF
  • Adobe PSD and FFO
  • raw IPTC

and the metadata formats it knows about: JFIF, IPTC, Exif, Adobe and Fotostation. and more file and metadata formats might get supported later, like TIFF, etc. the future is bright. ✨

one of its big main-character goals is checking whether parsed metadata is even valid, and optionally checking strict compliance to the official standards. and on the other hand, it wants to give you ways to fix broken or non-compliant chunks, plus general basic functions for manipulating the metadata.

go say hi to the program homepage at http://www.mollux.org/projects/pecomato/. and if something's broken, report issues at https://www.mollux.org/services/bugzilla/. thank you for your service. 🎀

🎀 OPTIONS 🎀

general options

  • -v, --version — show the version number, then exit
  • -h, --help — show this usage help, then exit
  • --list — list all the supported embedded data structures
  • -l, --log-level NUM — define the verbosity (the possible values are down below, keep scrolling)
  • -c, --check-compliance — do full checks to test the strict validity and compliance of structures against the official formats

filtering and extracting options

  • -b, --backup — create backup files of files that get (re)written, if necessary
  • -d, --target-dir DIRNAME — the target directory for every file it writes
  • -f, --fix — fix metadata inconsistencies when possible

extracting options

  • -x, --extract TYPE — extract and save metadata to a standalone file (the list of metadata types you can extract is further down)
  • -t, --ext EXTENSION — pick what filename extension to use when writing out extracted metadata (default: .iptc)
  • -a, --append-ext — append the extension to the original filename when saving extracted metadata (default behaviour: replace the original file extension)

filtering options

  • -i, --include EXPR — a filter expression describing the datasets to keep
  • -i, --include @FILE — or a file containing a list of datasets to keep; every other dataset gets filtered out. if you don't use this, all datasets get kept
  • -e, --exclude EXPR — a filter expression describing the datasets to filter out
  • -e, --exclude @FILE — a file containing a list of datasets to filter out; all the other datasets get kept. if you don't use this, all datasets get kept
  • --edit EXPR — a filter edit expression describing the datasets to add
  • --edit @FILE — or a file containing a list of datasets to add. datasets won't get inserted if that would break compliance with the standards
  • --test — don't override the original file, create a *.rewrite file instead. this option only affects rewriting of source files

dump options

  • -w, --wrap NUM — max column for wrapping (num must be in range [8-1024]). default is to dump unwrapped

🌈 POSSIBLE OPS 🌈

  • check — just check the embedded data structures
  • dump — show embedded data (headers only)
  • dump-full — show all embedded data (values included, we're nosy now)
  • dump-value — show the requested value (headers only)
  • filter — filter embedded data (see -i, -e and --edit)

🧚 DUMP-VALUE EXPRESSIONS 🧚

IPTC.<record>

same thing as the filter include/exclude expression, which is, like, literally right below. 👇

⭐ FILTER INCLUDE/EXCLUDE EXPRESSIONS ⭐

IPTC.<record>

where <record> can be either of these:

  • all: *
  • hexadecimal unary: 0xhhhh
  • hexadecimal range: 0xhhhh-0xhhhh
  • decimal unary: nnn:nnn
  • decimal ranges: nnn:nnn-nnn
  • decimal ranges: nnn:*

examples, bestie:

IPTC.0x0219
IPTC.0x0300-0x0364
IPTC.3:0-100

💜 FILTER EDIT EXPRESSIONS 💜

IPTC.<record>=<type>:<value>

where <record> can be either of these:

  • hexadecimal unary: 0xhhhh
  • decimal unary: nnn:nnn

where <type> can be either of these:

  • hex
  • text

and <value> is:

  • hex: [a-zA-Z0-9] pairs
  • text: any char (even widechars) on the line is taken as text, until a newline is found

examples:

IPTC.0x0200=hex:0002
IPTC.0x0219=text:this is a keyword

🍓 SUPPORTED METADATA FOR EXTRACTION 🍓

  • iptc — IPTC datasets

🔥 POSSIBLE LOG LEVELS 🔥

  • 0 — quiet, no output at all
  • 1 — error messages only (default)
  • 2 — warning and error messages
  • 3 — informative, warning and error messages
  • 4 — all messages, including the debug ones

👑 SUPPORTED INPUT FILES 👑

  • JPEG files (commonly .jpeg, .jpg, .jpe, .jfif, .jif)
  • Adobe Photoshop files (commonly .psd, .pdd, .ffo)
  • FotoStation files (commonly .fdp, .ipt)
  • standalone IPTC metadata (commonly .iptc)

💀 EXIT CODES 💀

  • 0 — normal exit
  • 1 — usage error
  • 2 — asynchronous signal termination
  • 3 — normal exit, with warning(s)
  • 4 — normal exit, with error(s)
  • 5 — fatal error encountered
fr fr, exit codes are how you and your scripts talk to each other. don't ignore them, they're trying to communicate. 😭

🌸 EXAMPLES 🌸

Check metadata structures of a JPEG file, only report errors:

$ pecomato check file.jpg

🫶 AUTHOR 🫶

Written by Tristan Chabredier "wwp" <subscript@free.fr>. iconic behaviour, honestly.

Copyright (C) 2005-2007 Tristan Chabredier.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

okay that's the whole thing, and yes, every last detail is still in there because we don't do half-finished here. 💅 this page lives in the General Commands Manual, section 1, for pecomato — that's the version-of-record vibe, straight from the source, no filler. now go check some JPEGs, bestie, you've got this. 🦋✨

📦 where this page comes from