Tensionix ENDERU
GitHub28 repositoriesDaily Tech3 subscribersaudion.devthe product shelfRSSrelease feed
← All notesProjects

Audion Office Image Optimizer

Portable Python utility for working with embedded raster images inside Microsoft Office OOXML documents:

  • DOCX
  • PPTX

The project is focused on practical processing of Office files without breaking package structure, visible object geometry, or the general document layout.

What the project does

Audion Office Image Optimizer opens Office OOXML packages, scans embedded raster image parts, and rewrites them in a controlled way.

Current project goals:

  • reduce oversized Office files;
  • preserve visible layout geometry;
  • keep OOXML package integrity;
  • provide a portable runtime for end users;
  • support both optimization workflows and color-profile normalization workflows.

Current build

The current project already includes:

  • embedded Python runtime;
  • local launchers in English and Russian;
  • fzf launcher mode;
  • optional GUI file picker;
  • desktop GUI with clear resolution choices, shared JPEG quality, and source/destination folder pickers;
  • release/licensing structure inherited from the portable template;
  • GitHub release documentation stored inside the project itself.

CLI command reference

Run commands from the portable project root:

runtime\python.exe -m app --help
runtime\python.exe -m app scan "input\file.pptx"
runtime\python.exe -m app batch "input\file.pptx" --mode hard --preset presentation
runtime\python.exe -m app batch "input\file.pptx" --mode hard --preset custom --max-width 2560 --max-height 1440 --max-megapixels 3.7 --jpeg-quality 85
runtime\python.exe -m app fit-size "input\file.pptx" --target-mb 20
runtime\python.exe -m app extract-media "input\file.pptx"

The same modes are available through the launchers:

  • launcher_project.cmd - English CLI/fzf launcher;
  • launcher_project_ru.cmd - Russian CLI/fzf launcher;
  • launcher_project_picker.cmd - English launcher with GUI file picker;
  • launcher_project_picker_ru.cmd - Russian launcher with GUI file picker.
  • launcher_gui.cmd - desktop GUI shell over the same CLI.

The GUI is intentionally focused on automatic workflows and diagnostics. Console-interactive paths such as SAFE ASK remain available in CLI/TUI for expert use, but they are not the primary GUI workflow.

In the GUI, every operation uses the shared Workbench. Source can be one DOCX/PPTX file or a folder, while Target is the results folder. Operation screens do not duplicate I/O path fields; Reset restores the project input and output routes.

Canonical Workbench labels

The address rows are Source and Target. The action labels are identical across Audion NiceGUI projects: Source, Add file..., Target, Reset, Delete, and List.

CLI commands work on one selected DOCX or PPTX document at a time. GUI operations can process the file or folder selected in the Workbench. The source document is not overwritten. Output is written into output\ or the selected Target folder as:

  • filename.optimized.docx
  • filename.optimized.pptx

scan

Read-only analysis of embedded images. This command does not modify the Office package and is the safest first diagnostic step.

runtime\python.exe -m app scan "input\file.pptx"

The report shows:

  • package type: docx, pptx, or unknown;
  • detected word/media/* or ppt/media/* image parts;
  • actual image format reported by Pillow;
  • width, height, and transparency;
  • image part size inside the Office package;
  • estimated decoded raster size;
  • whether the format is supported by current modes;
  • the recommendation for the selected optimization policy;
  • format summary and the largest image parts;
  • recommendation summary.

Typical uses:

  • inspect why a file is large;
  • count PNG/JPEG/SVG/WMF/EMF assets;
  • preview what batch would change;
  • safely check a file before processing.

ask

Interactive mode for one document.

runtime\python.exe -m app ask "input\file.pptx" --mode safe --preset presentation
runtime\python.exe -m app ask "input\file.pptx" --mode hard --preset presentation

Arguments:

  • --mode safe - interactive processing for existing JPEG parts;
  • --mode hard - currently a report-first alpha path without interactive write-back;
  • --preset fhd - 1920x1080 limit;
  • --preset qhd - 2560x1440 limit;
  • --preset uhd - 3840x2160 limit.
  • --preset office - ordinary documents and email attachments;
  • --preset presentation - balanced slide quality and size;
  • --preset quality - quality matters more than size reduction;
  • --preset custom - manual limits through --max-width, --max-height, --max-megapixels, and --jpeg-quality.

SAFE ASK asks what to do with each JPEG:

  • keep - leave it unchanged;
  • recompress - re-save JPEG with the current quality default;
  • resize - resize to the selected preset;
  • resize+recompress - resize and re-save;
  • skip - skip this part.

After choosing an action, the same action can be applied to similar JPEGs in the document. Non-JPEG parts are skipped in safe mode.

HARD ASK in the current build is an interactively launched report. It prints recommendations but does not write changes. Use batch --mode hard for automatic hard processing.

batch

Automatic processing of one document using project rules.

runtime\python.exe -m app batch "input\file.pptx" --mode safe --preset presentation
runtime\python.exe -m app batch "input\file.pptx" --mode hard --preset presentation
runtime\python.exe -m app batch "input\file.pptx" --mode hard --preset custom --max-width 2560 --max-height 1440 --max-megapixels 3.7 --jpeg-quality 85

SAFE BATCH:

  • works only with jpg and jpeg;
  • resizes JPEGs that exceed the selected preset;
  • re-saves changed JPEGs;
  • preserves existing media part paths;
  • leaves PNG/GIF/BMP/TIFF/SVG/WMF/EMF unchanged.

HARD BATCH:

  • works with jpg, jpeg, png, gif, bmp, tif, and tiff;
  • resizes and re-saves oversized JPEGs;
  • converts supported non-JPEG raster parts to JPEG;
  • resizes oversized non-JPEG raster parts before JPEG conversion;
  • skips tiny visual assets only when the internal pixel policy says they are safe to skip;
  • does not use encoded KB size as the main skip reason, because a tiny PNG file can decode into a huge raster;
  • detects SVG/WMF/EMF but skips them.

When a raster part is converted, its package path may change, for example ppt/media/image42.png -> ppt/media/image42.jpg. The command updates internal relationship targets and content types inside the OOXML package.

fit-size

Automatically fit a document under a target size in MB.

runtime\python.exe -m app fit-size "input\file.pptx" --target-mb 20

fit-size always uses forced HARD JPG: it first lowers quality to 75, then lowers resolution down to 1920x1080, then uses quality 65, then tries 1600x900 and 1280x720 as the lower bound. Portrait images automatically receive rotated limits, for example 1920x1080 becomes 1080x1920.

normalize-srgb

Normalize all supported embedded raster images to sRGB through Pillow CMS.

runtime\python.exe -m app normalize-srgb "input\file.pptx"
runtime\python.exe -m app normalize-srgb "input\file.pptx" --embed-icc

Profile:

  • config/icc/sRGB2014.icc

Behavior:

  • uses an embedded ICC profile when present;
  • treats images without a profile as sRGB;
  • saves transparent images as PNG to preserve alpha;
  • saves opaque images as JPEG;
  • --embed-icc embeds the target sRGB ICC profile into saved image parts;
  • without --embed-icc, output stays compact.

Useful for:

  • documents assembled from mixed image sources;
  • display/RGB workflows;
  • stabilizing color profile handling before export.

normalize-cmyk

Normalize all supported embedded raster images to CMYK through Pillow CMS.

runtime\python.exe -m app normalize-cmyk "input\file.pptx"
runtime\python.exe -m app normalize-cmyk "input\file.pptx" --embed-icc

Profiles:

  • source fallback: config/icc/sRGB2014.icc;
  • target: config/icc/Photoshop5DefaultCMYK.icc.

Behavior:

  • uses embedded ICC profiles when present;
  • treats images without a profile through the sRGB fallback;
  • flattens transparency onto a white background before CMYK conversion;
  • saves output as JPEG;
  • does not embed the CMYK ICC profile by default, to avoid document bloat;
  • --embed-icc enables the heavier profile-embedding path.

Useful for:

  • print-oriented review;
  • predictable CMYK conversion;
  • diagnosing documents before handoff to a print workflow.

extract-media

Extract embedded Office media files from word/media/* or ppt/media/* into:

  • output\<document-name>\
runtime\python.exe -m app extract-media "input\file.pptx"

This command does not modify the source Office file. It is useful for inspecting all embedded raster/vector media parts directly.

GUI naming model

The GUI describes optimization through a clear maximum-resolution choice:

  • Standard resolutions:
  • 1920x1080 - ordinary document.
  • 2560x1440 - presentations.
  • 3840x2160 - print / archive.
  • JPEG quality - shared compression control for all GUI modes, default 82.
  • Custom size - manual width/height for stronger or non-standard compression.
  • Fit to size - a separate operation with an MB target and automatic HARD JPG selection.

Standard resolutions always run as HARD. Custom size mode exposes width/height spinners, SAFE / HARD, and the tiny-PNG rule, which defaults to 400x400.

Internal CLI names such as SAFE, HARD, FHD, QHD, UHD, office, presentation, quality, and custom remain available in scripts.

Command smoke test

Baseline smoke set for a portable build:

runtime\python.exe -m app --help
runtime\python.exe -m app scan "input\file.pptx"
runtime\python.exe -m app ask "input\file.pptx" --mode hard --preset presentation
runtime\python.exe -m app batch "input\file.pptx" --mode safe --preset presentation
runtime\python.exe -m app batch "input\file.pptx" --mode hard --preset presentation
runtime\python.exe -m app batch "input\file.pptx" --mode hard --preset custom --max-width 2560 --max-height 1440 --max-megapixels 3.7 --jpeg-quality 85
runtime\python.exe -m app fit-size "input\file.pptx" --target-mb 20
runtime\python.exe -m app normalize-srgb "input\file.pptx"
runtime\python.exe -m app normalize-srgb "input\file.pptx" --embed-icc
runtime\python.exe -m app normalize-cmyk "input\file.pptx"
runtime\python.exe -m app normalize-cmyk "input\file.pptx" --embed-icc

SAFE ASK smoke needs a document with at least one JPEG because the command asks interactive questions for JPEG parts.

After write commands, check that:

  • a file appears in output\;
  • the source file remains unchanged;
  • output\*.optimized.pptx or output\*.optimized.docx opens as a ZIP/OOXML package;
  • a follow-up scan on the optimized file reports no errors;
  • SVG/WMF/EMF parts remain skipped when present in the source.

Optimization logic

SAFE

Works only with existing JPEG image parts.

Main idea:

  • safer write-back path;
  • lower structural risk;
  • preserve media part paths whenever possible.

HARD

Works with supported raster formats and may convert non-JPEG raster images to JPEG.

Main idea:

  • stronger size reduction;
  • broader real-world coverage for Office documents full of PNG/GIF/BMP/TIFF assets.

Supported raster formats

Supported for scanning

  • JPG
  • JPEG
  • PNG
  • GIF
  • BMP
  • TIF
  • TIFF

Detected but intentionally skipped

  • EMF
  • WMF
  • SVG

Presets

User-facing GUI optimization choices:

  • Standard resolutions:
  • 1920x1080 - ordinary document;
  • 2560x1440 - presentations;
  • 3840x2160 - print / archive.
  • JPEG quality - default 82, lower values compress more.
  • Custom size - manual width/height.
  • Fit to size - a separate MB target with automatic HARD JPG attempts.

Standard resolutions run as HARD. Custom size mode can choose SAFE / HARD and override the tiny-PNG 400x400 limit.

Compatible technical presets are still supported:

  • fhd = 1920x1080;
  • qhd = 2560x1440;
  • uhd = 3840x2160.

CLI custom exposes:

  • --max-width;
  • --max-height;
  • --max-megapixels;
  • --jpeg-quality;
  • --min-skip-width;
  • --min-skip-height;
  • --min-skip-megapixels.

ICC profiles and config

Project config lives in:

  • config/defaults.json

ICC profiles currently used by the normalization commands:

  • config/icc/sRGB2014.icc
  • config/icc/Photoshop5DefaultCMYK.icc

Output behavior

The project does not overwrite the source Office file by default.

Output naming:

  • filename.optimized.docx
  • filename.optimized.pptx

Launchers

The main launchers now live directly in the project root:

  • launcher_project.cmd
  • launcher_project_picker.cmd
  • launcher_project_ru.cmd
  • launcher_project_picker_ru.cmd

Service entry points remain English-only:

  • builder_main.cmd
  • launcher_tools.cmd

Project structure

Audion Office Image Optimizer/
  config/
  GitHub/
  input/
  output/
  logs/
  install/
  runtime/
  system_core/
    app/
  wheelhouse/
  launcher_project.cmd
  launcher_project_picker.cmd
  launcher_project_ru.cmd
  launcher_project_picker_ru.cmd
  builder_main.cmd

What is already working

The current build already works for:

  • package scanning;
  • safe JPEG processing;
  • hard raster processing;
  • sRGB normalization;
  • CMYK normalization;
  • launcher-based execution from the project root;
  • portable embedded-Python execution without a system-wide Python install.

Current limitations

Important current limitations:

  • HARD ASK should still be treated as experimental;
  • vector formats are detected but not converted;
  • CLI commands operate on one selected Office file; GUI operations can process a picked source folder;
  • some normalization paths may rewrite image parts to a different raster container when required by the target profile/output path.

This project is useful when you need to:

  • shrink bloated Office files;
  • normalize embedded image color profiles;
  • standardize mixed image content before print/export workflows;
  • avoid manual extract-edit-reinsert cycles for Office packages.

Disclaimer

This is still an alpha-stage engineering tool. Keep original files and test on copies before using it in critical production workflows.

Edited 08.28.2026