Skip to content

Releases: Longbatman09/MetaInject

Initial Release v.0.0.1

20 Jun 17:34
@Longbatman09 Longbatman09
v.0.0.1
0d038a0
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Initial Release v.0.0.1 Latest
Latest

MetaInject v.0.0.1

Overview

Metadata Injector is a lightweight, pure Python CLI tool that automates the process of stamping sequential numeric IDs directly into the metadata of PDF, PNG, and JPG files. It is designed for anyone who needs a simple, reliable way to track and identify a batch of files without renaming them or altering their visual content.

What It Does

The tool scans a designated Input/ folder and assigns each supported file a unique zero-based integer ID — starting from 0 for the first file and incrementing for every new file added. This ID is written directly into the file's internal metadata using pure Python libraries, meaning no external tools, binaries, or runtimes are required.

Every injection is recorded in a central CSV file called ID_RECS.csv, which acts as the project's persistent registry. The CSV stores the original filename alongside its assigned ID, creating a permanent, human-readable index of all processed files.

How the ID Is Stored

The ID is embedded differently depending on the file type:

  • JPG / JPEG — Written into the ImageDescription EXIF field using Pillow and piexif
  • PNG — Written into a tEXt metadata chunk with the key ImageDescription using Pillow
  • PDF — Written into the /Keywords field of the PDF Info dictionary using pypdf

In all cases, the value is stored in the format ID:<number> (e.g. ID:0, ID:14), making it easy to read with any standard metadata viewer or programmatically with the same libraries.

File Registry — ID_RECS.csv

ID_RECS.csv is the source of truth for the entire project. It is automatically created on the first run and appended to on every subsequent run. It contains two columns:

Column Description
actual_name The original filename as found in Input/
assigned_id The zero-based integer ID injected into that file

Files are never re-processed. If a filename already exists in the CSV, the tool skips it and moves on. This makes the tool safe to run repeatedly as new files are added to the Input/ folder.

Components

The project is made up of four Python scripts and one Windows batch launcher:

test.py — Injection Engine

The core script. Scans Input/, filters for supported file types, checks the CSV for existing records, injects the next available ID into each new file, and appends the result to ID_RECS.csv. Prints a [OK], [SKIP], or [FAIL] status line for every file it encounters.

open.py — File Opener

Accepts an integer ID as a command-line argument, looks it up in ID_RECS.csv, and opens the corresponding file from Input/ using the operating system's default application. Works on Windows, macOS, and Linux. Prints a descriptive [ERROR] message and exits cleanly if the ID does not exist or the file is missing on disk.

show.py — Record Viewer

Reads ID_RECS.csv and prints all records as a neatly formatted table in the terminal, sorted by ID in ascending order. Column widths auto-adjust to the longest filename in the dataset. Handles missing or empty CSV files gracefully with an informational message.

run.bat — Windows Menu Launcher

A double-clickable Windows batch file that wraps all three scripts behind a numbered menu. Users choose an option, the corresponding script runs, and the menu reappears automatically after each action. No need to open a terminal or remember script names.

Dependencies

The tool relies on three lightweight, widely-used Python libraries:

Library Purpose
Pillow Reading and writing JPG and PNG files
piexif Reading and writing EXIF metadata in JPG files
pypdf Reading and writing PDF metadata

All other functionality uses the Python standard library only (os, sys, csv, platform, pathlib). No external binaries, no Perl runtime, no ExifTool installation required.

Install with:

pip install Pillow piexif pypdf

Project Structure

project-root/
│
├── run.bat                  # Windows menu launcher
├── test.py                  # Metadata injection script
├── open.py                  # File opener by ID
├── show.py                  # ID record viewer
├── ID_RECS.csv              # Auto-generated file registry
│
└── Input/                   # Place files here before running
    └── (supported: .jpg, .jpeg, .png, .pdf)

Typical Workflow

  1. Drop PDF, PNG, or JPG files into the Input/ folder
  2. Double-click run.bat and select option 1 to scan and inject IDs
  3. Select option 3 to view all assigned IDs in the terminal
  4. Select option 2 and enter an ID number to open that file instantly
  5. Add more files to Input/ at any time and re-run option 1 — only new files are processed

Design Principles

  • Non-destructive — Only metadata is modified. File content, appearance, and filename remain completely unchanged.
  • Idempotent — Running the tool multiple times on the same folder produces the same result. Already-processed files are always skipped.
  • Zero external dependencies — No ExifTool, no Perl, no system-level installs beyond standard Python packages.
  • Transparent — Every action is printed to the terminal with a clear status prefix ([OK], [SKIP], [FAIL], [ERROR], [OPEN]).
  • Portable — Works on any machine with Python 3 installed. open.py detects the operating system automatically.
Assets 2
Loading