pdfHarmony Users Guide

Introduction

pdfHarmony is a key resource for performing process quality control in mission-critical applications. The software analyzes PDF files, identifies and repairs corrupt/malformed PDF files

Leveraging Adobe Systems’s own PDF Library, pdfHarmony offers positive identification in high-volume settings of any PDF page that stops Adobe Reader®, as well as recovery and repair of many otherwise broken PDF files.

Adobe Acrobat can open the vast majority of PDFs, and so can pdfHarmony. For these files, pdfHarmony optimizes the file structure, reduces the file size without affecting page content, and returns an authentic Adobe PDF file, fully compliant with ISO 32000, the international standard for PDF.

 

Technical Introduction

pdfHarmony leverages Adobe’s PDF library to run a series of processes that convert PDFs to Adobe PDF. These processes include:

• detecting and reporting damaged or malformed PDFs that can’t be opened with Adobe Acrobat or Reader
• detecting and reporting page rendering errors
• repairing and saving PDFs
• consolidates identical fonts, font subsets, and XObjects to reduce file size without altering objects on the page
• converting input PDFs into authentic Adobe PDFs
• downsampling and recompressing images and subsetting fonts with the enhanced optimizer, while keeping the document's tags, metadata and attachments
• converting PDFs to PDF/A, at any conformance level from PDF/A-1 to PDF/A-4
• reporting where a file's space goes, and estimating what image recompression would save
• ensuring PDFs are ISO 32000 compliant

pdfHarmony operates on recursive folders, watched folders, or from the command line. It sets document information fields and generates XMP metadata with or without modifying the creation date. In addition, pdfHarmony sets PDF open options that control page and layout modes, including open actions, toolbar, menu and bookmark states.

Results are captured in a log file and may be summarized in an HTML or XML report.

 

User Guide Conventions

This User Guide uses certain styles of text to indicate different things throughout the documentation. The following is a description of these styles:

• Command Line user input:

pdfHarmony -p -optimize -o c:\Appligent\pdfHarmony\output.pdf c:\Appligent\pdfHarmony\input.pdf

• Cross Reference to other locations in the documentation: Command Line Option Reference

• Code snippets: begin_message

Introduction

pdfHarmony is an application that brings a new sense of security and reliability to electronic document workflows because it can identify “broken” files and pages just like Adobe® Acrobat®. If Adobe Acrobat can resolve the problem, then so can pdfHarmony.

Memory Requirements

Minimum free memory available to run the application: 512 MBytes

Windows Installation

Windows installation is handled by the installer and does not require any special handling.

Unix Installation

Setting environmental variables ( macOS and Linux )

pdfHarmony needs a few environmental variables to be set. If you run pdfHarmony from the pdfharmony script created during installation, the script sets them for you. If you run pdfharmonyapp directly, you must set them yourself. The Appligent home directory is the same on macOS and Linux; the library-path variable differs between the two, as shown below. Once pdfHarmony is installed, you can see exactly what to set by looking at the pdfharmony script the installer created.

Setting the Appligent home directory ( macOS and Linux )

The environmental variable that stores the location of the Appligent home directory is APPLIGENT_HOME. The default location for the Appligent home directory is /usr/local/appligent. The Appligent home directory contains the library files and resources needed to run pdfHarmony. It also contains license information for pdfHarmony.

Example

export APPLIGENT_HOME=/usr/local/appligent

Setting the APDFL library path ( macOS )

On macOS the APDFL libraries are frameworks, so both DYLD_FRAMEWORK_PATH and DYLD_LIBRARY_PATH must include the APDFL library path. It is located in a subdirectory of the APPLIGENT_HOME directory, and should be set to ${APPLIGENT_HOME}/APDFLX.X.X/Libs.

Example

export DYLD_FRAMEWORK_PATH=${APPLIGENT_HOME}/APDFLX.X.X/Libs:${DYLD_FRAMEWORK_PATH}
export DYLD_LIBRARY_PATH=${APPLIGENT_HOME}/APDFLX.X.X/Libs:${DYLD_LIBRARY_PATH}

Setting the APDFL library path ( Linux )

On Linux the APDFL library path must be added to the LD_LIBRARY_PATH variable. It is located in a subdirectory of the APPLIGENT_HOME directory, and should be set to ${APPLIGENT_HOME}/APDFLX.X.X/Libs.

Example

export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${APPLIGENT_HOME}/APDFLX.X.X/Libs

Supported Platforms

Windows: 64-bit (Intel)
macOS: Apple Silicon
Linux: 64-bit (Intel)

Introduction

This chapter tells you what you need to know to get started with pdfHarmony…

you will learn:

• The basic structure of  pdfHarmony commands
• How to get product information about your installation of pdfHarmony

 

pdfHarmony Command Basics

All pdfHarmony commands that you run from the command line start with the pdfharmony command name. The command name is followed by one or more options, which begin with a dash. Commands that you use to obtain information about a PDF document must also include an input file specification. For example, the following command instructs pdfHarmony to optimize the PDF file:

$pdfharmony -optimize -o pathname\output.pdf  pathname\myfile.pdf

 

Displaying the Product Version Number

It is a good idea to test your installation of pdfHarmony by displaying the product version number. You will also need this number if you ever contact Appligent’s Customer Support with a question.

Command

$pdfharmony -v

Result

The following listing is typical of the output you would receive. In addition to the product version number, it contains the release date and registration number.  It also indicates that the registration number is valid.

Typical listing produced by -v option

# Copyright XXXX by Appligent, Inc.  http://www.appligent.com
# Written by Mark Gavin
# Version X.X, Build Date XXXX, Library Version X.X.X
# Serial Number XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
# License is valid.

 

Displaying Product Usage Information

If you have a question about the command syntax or a command option, you can get help by displaying product usage information.

Command

$pdfharmony -h

Typical listing produced by -h or -help option

Usage: pdfHarmony [options] inPDFFile1 [inPDFFile2 ...]
  …
  -verifyonly              : Verify Only, search for corrupt files without creating any new files
  -o <string>              : Output directory name or PDF filename
  …
  -optimize2               : Use the enhanced optimizer
  …
# pdfHarmony Version 3.0.2, Build Date …, Library Version …

The listing continues through every option. The Quick Reference at the start of this guide lists them, and the pdfHarmony Command Line Option Reference describes each one with an example.

Using Command-line Options

Command-line options are used in all Appligent Document Solutions server applications. The tables below shows command-line options for pdfHarmony. The following is an example of command syntax for pdfHarmony:

pdfharmony [options] inPDFFile1 [inPDFFile2]

Document Save and Optimize Options

Option	Description	Example
-verifyonly	Verify only; search for corrupt files without creating new files.	pdfharmony -p -verifyonly input.pdf
-verifypage	Verify page drawing.	pdfharmony -verifypage -verifyonly input.pdf
-rewritepage	Rewrite page contents to cleanup at the page content level.  This option rebuilds the entire contents of the page eliminating many types of malformed content.	pdfharmony -rewritepage -o output.pdf input.pdf
-removerotation	Remove rotation from all pages	pdfharmony -removerotation -o output.pdf input.pdf
-retaincreator	Retain original document creator	pdfharmony -retaincreator -o output.pdf input.pdf
-optimize	Combine -flate, -rascii, -nolzw, -optxobj, -optcontent and -optfonts.	pdfharmony -optimize -o output.pdf input.pdf
-optimize2	Use the enhanced optimizer: downsample and recompress images, subset fonts and remove duplicate objects. It keeps the document's tags, XMP metadata, document information, page labels, output intents, named destinations and attachments, and removes comments (notes, highlights and other markup). See Enhanced Optimizer Options below.	pdfharmony -optimize2 -o output.pdf input.pdf
-nocomp	Do not compress using Object Streams; compatible with all versions of Acrobat.*	pdfharmony -p -nocomp -verifyonly
-comp	Compress using Object Streams; compatible with Acrobat 6 and later.*	pdfharmony -p -comp -o output.pdf input.pdf
-cstruct	Compress logical structure.* *: -nocomp, -comp and -cstruct are mutually exclusive; these options can all be off, but only one can be used at a time.	pdfharmony -cstruct -o output.pdf input.pdf
-iso32000	Set file for ISO 32000 compliance (PDF 1.7).	pdfharmony -iso32000 -o output.pdf input.pdf
-flate	Encode non-encoded streams using Flate compression.	pdfharmony -flate -o output.pdf input.pdf
-rascii	Remove ASCII85 filters from all streams.	pdfharmony -rascii -o output.pdf input.pdf
-nolzw	Replace LZW encoded streams with Flate encodings.	pdfharmony -nolzw -o output.pdf input.pdf
-optxobj	Merge identical XObjects and Images.	pdfharmony -optxobj -o output.pdf input.pdf
-optcontent	Optimize common sequences in page content.	pdfharmony -optcontent -o output.pdf input.pdf
-optfonts	Merge identical font descriptors and encodings.	pdfharmony -optfonts -o output.pdf input.pdf
-xreadonly	Suppresses the generation of padding in the XMP metadata.	pdfharmony -xreadonly -o output.pdf input.pdf
-xpadding <int>	XMP metadata padding bytes. Default is 2048.	pdfharmony -xpadding 3045 -o output.pdf input.pdf
-w	Save the output as a linearized file.	pdfharmony -w -o output.pdf input.pdf
-wauto	Auto-detect linearized and save linearized; otherwise, save as normal.	pdfharmony -wauto -o output.pdf input.pdf
-wforms	Extends “w” and “wauto” to linearize Acrobat forms. Default is to not linearize forms. Requires -w or -wauto.	pdfharmony -wforms -o output.pdf input.pdf
-nomod	Retain current file modification date.	pdfharmony -w -nomod -o output.pdf input.pdf
-nosign	Ignore digital signatures. Default is to incrementally save files with digital signatures.	pdfharmony -optimize -nosign -o output.pdf input.pdf

Enhanced Optimizer Options

These options tune -optimize2. Images above the target resolution are downsampled to it and recompressed with the method chosen for their kind. Without -optdpi, only color images are downsampled, to 96 dpi; with -optdpi, color, grayscale and black-and-white images all are.

Option	Description	Example
-optdpi <int>	Target image resolution in dpi. Default is 96.	pdfharmony -optimize2 -optdpi 150 -o output.pdf input.pdf
-optquality <string>	Image quality: minimum | low | medium | high | maximum. Default is low.	pdfharmony -optimize2 -optquality medium -o output.pdf input.pdf
-optcolor <string>	Method for color images: jpeg | jp2k (JPEG 2000) | flate | same (keep the current method). Default is jpeg.	pdfharmony -optimize2 -optcolor jp2k -o output.pdf input.pdf
-optgray <string>	Method for grayscale images: jpeg | jp2k | flate | same. Default is jpeg.	pdfharmony -optimize2 -optgray flate -o output.pdf input.pdf
-optbw <string>	Method for black-and-white images: jbig (JBIG2) | ccittg4 | ccittg3 | flate | same. Default is jbig.	pdfharmony -optimize2 -optbw ccittg4 -o output.pdf input.pdf

Note: A method name pdfHarmony does not recognize is not reported as an error; the default is used instead, so check the spelling.

PDF/A Conversion Options

-pdfa converts each document to PDF/A, the ISO standard for long-term archiving. pdfHarmony embeds the fonts and adds an output intent with an ICC color profile, so the output is often larger than the input.

Option	Description	Example
-pdfa [level]	Convert the document to PDF/A. With no level, the output is PDF/A-1b. Append c to any level for a CMYK output intent (U.S. Web Coated (SWOP) v2) instead of RGB (sRGB IEC61966-2.1).	pdfharmony -pdfa 2b -o output.pdf input.pdf pdfharmony -pdfa 2bc -o output.pdf input.pdf

PDF/A Conformance Levels

Level	Conformance	Requirements
1b	PDF/A-1b (ISO 19005-1)	Visual appearance. The default.
1a	PDF/A-1a	Requires a tagged document.
2b, 2u	PDF/A-2b, PDF/A-2u (ISO 19005-2)	Visual appearance; u adds text that maps to Unicode. Attached files must themselves be PDF/A.
2a	PDF/A-2a	Requires a tagged document. Attached files must be PDF/A.
3b, 3u	PDF/A-3b, PDF/A-3u (ISO 19005-3)	As PDF/A-2, but attached files may be of any type.
3a	PDF/A-3a	Requires a tagged document. Attached files may be of any type.
4, 4e	PDF/A-4, PDF/A-4e (ISO 19005-4)	4e is the engineering conformance level.
4f	PDF/A-4f	Requires a document with at least one attached file.

Image Recompression Options

-imagecompress recompresses the images in a document at their current resolution. To reduce resolution as well, use -downsample to give a target DPI, or use -optimize2 with -optdpi.

Option	Description	Example
-imagecompress <string>	Recompress images: jpeg | flate | jpeg2000 | auto. With auto, pdfHarmony chooses for each image: images that are already JPEG or JPEG 2000 are kept as they are, continuous-tone images are compressed with JPEG, and everything else with Flate.	pdfharmony -imagecompress auto -o output.pdf input.pdf
-jpegquality <int>	JPEG quality, from 1 to 100. Default is 85. Also used by -testrun.	pdfharmony -imagecompress jpeg -jpegquality 70 -o output.pdf input.pdf
-downsample <int>	Reduce the resolution of images drawn above this DPI to the target, then recompress. pdfHarmony reads each image's rendered resolution from the pages, so only images actually over the target are changed.	pdfharmony -downsample 150 -o output.pdf input.pdf

Document Analysis Options

These options report on a document without changing it; no output file is written.

Option	Description	Example
-analyze	Report how the file's space is used: images, content streams, fonts, metadata and structure, followed by the fonts, the images by compression filter, and the document information.	pdfharmony -analyze input.pdf
-analyzejson	Write the -analyze report as JSON.	pdfharmony -analyze -analyzejson input.pdf
-testrun	Try image compression strategies (keep, JPEG at quality 85 and 50, Flate, and auto) on sample pages, and estimate the size of the whole document under each. The recommended strategy is marked with *.	pdfharmony -testrun input.pdf
-testpages <int>	Number of sample pages for -testrun. Default is 10.	pdfharmony -testrun -testpages 5 input.pdf

A typical -analyze report:

=== PDF Analysis: input.pdf ===
File size: 298.3 KB (305503 bytes)
Pages: 35    PDF version: 1.6    Linearized: No

--- Space Breakdown ---
  Images:                102.7 KB  (34.4%)    3 unique images
  Content streams:        69.9 KB  (23.4%)
  Fonts:                  66.3 KB  (22.2%)    3 fonts
  Metadata:                3.9 KB  (1.3%)
  Structure/overhead:     55.5 KB  (18.6%)

Document Metadata Options

Option	Description	Example
-title <string>	Document title.	pdfharmony -title “This is the title” -o output.pdf input.pdf
-author <string>	Author of the document.	pdfharmony -author “John Doe” -o output.pdf input.pdf
-subject <string>	Subject of the document.	pdfharmony -subject Test -o output.pdf input.pdf
-keyword <string>	Keywords associated with the document, separated by commas.	pdfharmony -keyword Value1,Value2 -o output.pdf input.pdf
-addinfo	Add the new information to any existing in the file.	pdfharmony -addinfo -author “Jane Smith” -o output.pdf input.pdf
-custom <string>	Custom document information. For example, in -custom “name,value”, name and value are separated by a comma. This option may be repeated.	pdfharmony -custom “Field1,Value1” -custom “Field2,Value2” -o output.pdf input.pdf

Document Open and Layout Options

Option	Description	Example
-pageMode <string>	Set the document’s page mode (DontCare | UseNone | UseThumbs | UseBookmarks | Fullscreen | UseOC | UseAttachments).	pdfharmony -pageMode UseBookmarks -o output.pdf input.pdf
-layout <string>	Set the document’s layout (single | oneColumn | twoColLeft | twoColRight | twoPageLeft | twoPageRight).	pdfharmony -layout single -o output.pdf input.pdf
-openAction <string>	Set the document’s Open Action (FitPage | FitWidth | FitHeight | FitBoundingBox).	pdfharmony -openAction FitHeight -o output.pdf input.pdf
-openToPage <int>	Open the document to the given page number.	pdfharmony -openToPage 3 -o output.pdf input.pdf
-hideToolbar	Hide the toolbar upon opening the document.	pdfharmony -hideToolbar -o output.pdf input.pdf
-hideMenubar	Hide the menubar upon opening the document.	pdfharmony -hideMenubar -o output.pdf input.pdf
-hideWinUI	Hide scrollbars and other controls upon opening the document.	pdfharmony -hideWinUI -o output.pdf input.pdf
-fitWin	Resize the window to the initial page.	pdfharmony -fitWin -o output.pdf input.pdf
-centerWin	Center the window on the screen.	pdfharmony -centerWin -o output.pdf input.pdf
-showTitle	Display the document title in the Windows title bar.	pdfharmony -showTitle -o output.pdf input.pdf
-LeftToRight	Left-to-right reading order used to determine relative position of pages for side-by-side display.	pdfharmony -LeftToRight -o output.pdf input.pdf
-RightToLeft	Right-to-left reading order; includes vertical writing systems like Chinese, Japanese and Korean.	pdfharmony -RightToLeft -o output.pdf input.pdf

Bookmarks, Annotations and Form Fields Options

Option	Description	Example
-openBookmarks	Open all bookmarks.	pdfharmony -openBookmarks -o output.pdf input.pdf
-closeBookmarks	Close all bookmarks.	pdfharmony -closeBookmarks -o output.pdf input.pdf
-openLevel <int>	Open all bookmarks up to and including the specified level.	pdfharmony -openLevel 2 -o output.pdf input.pdf
-removeBookmarks	Remove all bookmarks.	pdfharmony -removeBookmarks -o output.pdf input.pdf
-removeAnnots	Remove all annotations including notes, highlights, form fields, etc.	pdfharmony -removeAnnots -o output.pdf input.pdf
-removeFields	Remove all form fields.	pdfharmony -removeFields -o output.pdf input.pdf

Watched Folders Options

Option	Description	Example
-watch <string>	Path to watched folder base directory.	pdfharmony -optimize -watch OutDir
-watchin <string>	Path to input watched folder. Optional.	pdfharmony -w -watch OutDir -watchin OutDir\NewDir
-watchout <string>	Path to output of watched folder. Optional. **The command line to the right will create a sub-folder beneath OutDir called NewOutDir. This is the directory where the output files will be placed once processed.	pdfharmony -w -watch OutDir -watchout OutDir\NewOutDir

General Options

Option	Description	Example
-l <string>	Write progress information to log file.	pdfharmony -l logfile.txt -optimize -o output.pdf input.pdf
-p	Write progress information to the log file and/or stdout.	pdfharmony -p -title “this is a test” -author “Jane Smith” -o output.pdf input.pdf
-r <string>	Pass  registration number to pdfHarmony.	pdfharmony -r XXXX-XXXX-XXXX-XXXX-XXXX-XXXX -p -optimize -o output.pdf input.pdf
-v	Display version information.	pdfharmony -v
-h or -help	Display usage information.	pdfharmony -h or pdfharmony -help
-html <string>	Output results to an HTML file. See an example report.	pdfharmony -html Report.html -verifyonly input.pdf
-htmlurl <string>	Specify path to server hosting HTML support files.
-xml <file>	Output results to an XML file: for each input file, its assessment and whether it passed.	pdfharmony -xml Report.xml -verifyonly input.pdf
-options <file>	Read more command line options from a text file. Write the options as you would on the command line, on one line or several, and quote values that contain spaces. Every word in the file is read as an option or a file name, so the file cannot contain comments.	pdfharmony -options settings.txt -o output.pdf input.pdf
-pref <file>	Read command line options from an XML preferences file. The file can be produced by -writepref. Options given on the command line take precedence over those read from the file.	pdfharmony -pref settings.xml -o output.pdf input.pdf
-writepref <file>	Write the options from this command to a new XML preferences file, which can be read back later with -pref.	pdfharmony -optimize2 -optquality high -writepref settings.xml -o output.pdf input.pdf
-o <string>	Output directory name or PDF filename.	pdfharmony -openToPage 5 -o output.pdf input.pdf
-d <string>	Owner password to open the document.	pdfharmony -d Ownerpass -subject “Test File” -o output.pdf input.pdf

Notes on options

If -hideWinUI is on the command line, then pageMode is ignored.

If you are running pdfHarmony on a file that contains form fields and you want the output to be linearized, you must have both -wforms and -w on the command line. Running with -w alone does not linearize output files that contain active form fields.

The -html reporting option cannot be used with watched folders.

-analyze, -analyzejson and -testrun only report. They never write a PDF, as if -verifyonly were on the command line.

-optimize2 removes comments (notes, highlights and other markup). Use -optimize to keep them.

A note on using -p and -l <logfile> together

As outlined in the above sections the -p option gives you progress messages on your screen and the -l <logfile> option writes error messages to a file if errors occur. The table below provides more detail on using these options alone or together.

l	p	errors	Result
			Nothing will be written to the screen or to the log file you specify
			Progress message will be written to the screen and pdfHarmony.log
			Progress messages will be written to the screen and to the log file you specify
			A pdfHarmony.log file will be created with the errors in your working directory
			Errors will be written to the log file you specify
			Errors will be written to pdfHarmony.log and your screen
			Both progress and error messages will be written to the screen and to the log file you specify

Therefore, -l <logfile> used on its own will only go into action if there are errors. With -p and -l <logfile> combined, you will get a text file with full details on pdfHarmony operations whether there are errors or not.

Sample pdfHarmony Commands

To optimize a PDF file:

pdfharmony -p -optimize -o output.pdf input.pdf

To optimize multiple files:

pdfharmony -p -optimize -o OutputDir input.pdf input2.pdf

To set document properties:

pdfharmony -p -subject pdfHarmony -author "Jane Smith" -title "Testing pdfHarmony" -o output2.pdf input.pdf

To shrink an image-heavy PDF while keeping its tags and metadata:

pdfharmony -p -optimize2 -optdpi 150 -optquality medium -o output.pdf input.pdf

To convert a PDF to PDF/A-2b:

pdfharmony -p -pdfa 2b -o output.pdf input.pdf

To see where a file's space goes before optimizing it:

pdfharmony -analyze input.pdf

Introduction

pdfHarmony is a command-line application. If you are used to the Microsoft Windows  operating system, you may not be familiar with running command-line tools. This section shows you all you need to get started.

• Windows tells you how to use pdfHarmony on Windows.
  Note: You can refer to the Getting Started With Command Line Applications for additional information on using command-line applications.

Windows

To run pdfHarmony in Windows, you need to open a Command Prompt window.

In Windows :

• Click Start, type cmd, and press Enter

The Command Prompt window opens.

Some basic commands

At the command prompt, you type each command, and press the Enter key to execute it. You can use the mouse to select text to copy or cut to the clipboard, but you cannot position the cursor with it. The command line is completely keyboard driven. Navigation keys are shown below:

Key	Action
Backspace	Delete previous character
Right arrow	Move right one character
Left arrow	Move left one character
Up arrow	Recall previous command
Tab	File or directory name auto complete
Enter	Execute command

In addition to running programs, you have many commands to navigate and maintain the system. Two important ones are cd and dir.

Changing directories

Use the cd command to change directories. For example, to change to the directory that pdfHarmony is located in, type:

C:\>cd \Appligent\pdfHarmony\

The command prompt changes to:

C:\Appligent\pdfHarmony>

to show you where you are.

To move back one level, use the shortcut of two periods (..)

C:\Appligent\pdfHarmony>cd..

Don’t forget to press the Enter key after every command. You will now be in this directory:

C:\Appligent>

Move back to pdfHarmony:

C:\Appligent>cd pdfHarmony

Listing the contents of a directory

Use the dir command to list the contents of a directory:

C:\Appligent\pdfHarmony>dir

The computer responds with a listing of all the contents of the pdfHarmony directory.

If the directory contents fly by too fast to read, do this:

C:\Appligent\pdfHarmony>dir /p

The /p switch tells DOS to display one page at a time. Press the Enter key to see the next page.

To see the contents of all the subdirectories at the same time, type:

C:\Appligent\pdfHarmony>dir /s

This displays the contents of pdfHarmony and all the subdirectories under it.

Running pdfHarmony

To run pdfHarmony, type the commands on the command line as shown in other sections of this manual and press Enter.  A simple command would be:

c:\Appligent\pdfHarmony\pdfharmony [options] -o c:\Appligent\pdfHarmony\output.pdf c:\Appligent\pdfHarmony\input.pdf

Now, refer to the rest of this User Guide for details about using pdfHarmony.

Introduction

This chapter describes what you can do if you do not get the results you expect when you run pdfHarmony. This troubleshooting checklist describes common problems. It is the first place to look for a possible solution to your problem.

Reviewing the Troubleshooting Checklist

Are you trying to retrieve information from one or more encrypted files?

You must specify the -d option, followed by a User password, as in the following example. (An Owner password will not work.)

You can only specify one User password. Therefore, all of the encrypted files you include on the command line must have the same User password. If you want to retrieve information from encrypted files that have different User passwords, run a separate command for each User password.

Are you using any options that require a file name (-o, -l)?

The file name must immediately follow the option, as in the following examples:

-o C:\Appligent\pdfHarmony\samples\myoutput.pdf

-l /Appligent/pdfHarmony/mylogfile.txt

If a text string other than a file name follows the option, pdfHarmony will recognize that text string as the file name.

Did you receive an error “this file cannot be found”?

You may not have provided the correct path for all files or you may have misspelled a file or directory name.

Is each input file a PDF document?

pdfHarmony can only open PDF files. If you are using wildcards, include the .pdf suffix (for example, *.pdf) to help prevent you from accidentally attempting to open a non-PDF file.

Are you using pdfHarmony in a script?

Use full path names for all files and applications accessed from within the script. If you cannot get your script to work, make sure that you can run pdfHarmony from a command line.

Did a PDF/A conversion fail?

Each conformance level has requirements, and pdfHarmony reports the one a document does not meet:

• is missing structure tree root, unable to convert to PDFA: the a levels (1a, 2a, 3a) need a tagged document. Choose a b level, or tag the document first.
• Embedded File Attachment … is not a valid PDF: PDF/A-2 allows only PDF/A attachments. Use PDF/A-3, which allows attachments of any type.
• A /Names dictionary entry was not found in the document catalog dictionary: PDF/A-4f needs a document with at least one attached file. Choose another level.

Did comments disappear after optimizing?

-optimize2 removes comments (notes, highlights and other markup). Use -optimize to keep them.

On Windows, does -optimize2 fail with “Bad file handle” while -optimize works?

-optimize2 cannot write into a folder whose permissions grant access only through the OWNER RIGHTS entry, which some programs give the temporary folders they create. Write the output to a folder created in the usual way, for example with File Explorer or mkdir.

E-mail

You can contact support directly by sending an e-mail to support@appligent.com. Support e-mails are answered within one business day during the normal business hours listed below.  

Telephone & Fax

• Telephone: +1 610 284 4006
• Fax: +1 610 284 4233

To better serve you, please call us during our normal business hours, Monday - Friday, 8:00 am - 5:00 pm U.S. EST/EDT.

A member of our friendly, knowledgeable support staff will reply as soon as possible, generally within one business day.

International Support

Customers from locations outside the United States, including Germany, United Kingdom, Canada and Australia can contact us directly or connect with one of our many resellers.

When contacting support please provide the following information:

• Name of the Product
• Product Version Number
• Operating System
• Your Name
• Company Name
• Your Email Address
• Your Phone Number
• Product Registration Number
• Any files to help us reproduce your problem (if needed)

New Features – pdfHarmony 3.0

• -optimize2 – the enhanced optimizer: downsamples and recompresses images (-optdpi, -optquality, -optcolor, -optgray, -optbw), subsets fonts and removes duplicates, while keeping the document's tags, metadata, page labels, output intents and attachments
• -pdfa level – PDF/A conversion at every conformance level from PDF/A-1 to PDF/A-4, with an RGB or CMYK output intent
• -imagecompress, -jpegquality and -downsample – recompress images with JPEG, JPEG 2000 or Flate (or let pdfHarmony choose for each image), and optionally reduce the resolution of images above a target DPI
• -analyze and -analyzejson – a report of where a file's space goes
• -testrun and -testpages – estimate what image recompression would save, before changing anything
• -xml – results as XML
• -options – read command line options from a text file
• -pref and -writepref – read command line options from, or write them to, an XML preferences file

New Features – pdfHarmony 2.0

-optimize – For document optimization, use -optimize. This flag will do the following

1. Encode any non-encoded streams using Flate compression
2. Remove ASCII85 filters from all streams
3. Replace LZW encoded streams with Flate encoding
4. Merge identical XObjects and images
5. Optimize common sequences in page content
6. Merge identical font descriptors and encodings
   This option will usually result in a smaller file size

-iso32000 – To create a document that is ISO 32000 complaint.  This flag set file for ISO 32000 compliance (PDF version 1.7).

–comp – To use object level compression, use the -comp flag. This flag will apply object level compression, typically reducing the file size by 2%.

-nocomp – To not use object level compression, use the -nocomp flag.  This flag will not add object level compression and will remove object level compression, if found; resulting in a document that is compatible with all versions of Acrobat

PDF files support the use of multiple types of compression simultaneously.  Object level compression is a technique developed by Adobe to reduce the size of PDF files.  Object level compression is used in addition to the other compression mechanisms used within the PDF file. Object level compression will reduce the file size typically by 2%. NOTE: This mechanism is not always understood by older versions of Acrobat or third party PDF viewers or procession tools.

-rewritepage – Rewrite page contents to cleanup at the page content level.  This feature can be used to clean PDF files at the page level

-removerotation – Remove rotation from all pages. Landscape (11 x 8.5) pages in a PDF file are often portrait (8.5 x 11) pages rotated by 90 degrees.  This flag will remove the rotation, replacing the rotated page with a true landscape (11 x 8.5) page

-retaincreator – Retain the original document creator

-nomod – Retain the original document file modification date

Known Issues

• Running digitally-signed files through pdfHarmony will modify the digital signature
• Using -nosign on a digitally-signed file is not forcing a full save on the document
• if -hideWinUI is on the command line, then pageMode is ignored
• If you are running on a file that contains form fields and you want the output file to be linearized, you must have both -wforms -w on the command line.  Running with just -w does not linearize files with active form fields
• Comma separated keyword lists are not supported.  To enter a list of keywords, use the semicolon (;) character as a separator
• The -html reporting option cannot be used with watched folders
• -optimize2 removes comments (notes, highlights and other markup); use -optimize to keep them
• PDF/A-1a output may not validate for a document whose tables use THead and TBody tags, which PDF/A-1 predates; use PDF/A-2a or later
• On Windows, -optimize2 cannot write into a folder whose permissions grant access only through the OWNER RIGHTS entry (see Troubleshooting)

To Get Help

Contact technical support by:

emailing support@appligent.com, or calling 610-284-4006

Please provide the following:

Product name and version number
Operating system
Your name, company name, email address, and phone number
Description of your question or problem

Responses are typically emailed within one business day.