Trigger 
Describe Configuration Reference
Every knob in one place: the CLI flag, the ConversionOptions property it sets, the REST form
field, the default, and when to change it. Nothing here is invented — each row maps to a real option
in DynDyn.Pdf.Core/ConversionOptions.cs, DynDyn.Pdf.Cli/ConvertCommand.cs, or DynDyn.Pdf.Web.
- CLI takes all configuration as command-line flags — there is no config file.
- Library callers set
ConversionOptions(immutablerecord). - Web maps a subset of form fields onto
ConversionOptions(see the REST table).
Core conversion options
| CLI flag | ConversionOptions |
REST field | Default | Values / range | Guidance |
|---|---|---|---|---|---|
-o, --output <dir> |
OutputDirectory |
— (server-managed) | input's directory | any writable dir | Where output lands |
-f, --format <v> |
(writer choice) | format |
single (CLI) / viewer (REST) |
single, pages, viewer |
single=one file; pages=folder+assets; viewer=single-file app w/ TOC + zoom |
-e, --engine <v> |
(converter choice) | engine |
managed |
managed, native |
managed=clip-aware, real Bézier fonts (default); native=rasterized page render |
--dpi <n> |
Dpi |
dpi |
120 |
18–600 | CSS pixel scale = dpi/72. Higher = sharper raster backgrounds, larger output |
-p, --pages <range> |
Pages |
pages |
all | 1-5,8,10- |
1-based; applies to every doc in a batch |
--line-grouping <v> |
LineGrouping |
lineGrouping |
always |
always, auto, never |
always=merge into justified lines (best selection); auto=merge only where pixel-accurate; never=every word at its exact position (most pixel-faithful, choppiest selection) |
--no-line-grouping |
LineGrouping = Never |
— | off | flag | Alias for --line-grouping never |
--background <v> |
Background |
background |
svg |
svg, raster, none |
svg=crisp vector; raster=native raster render (correct occlusion/transparency, text stays live HTML); none=text only |
--no-background |
Background = None |
— | off | flag | Alias for --background none |
--raster-fallback <v> |
RasterFallback |
rasterFallback |
auto |
never, auto, always |
Substitute a native raster background where the vector one can't composite; text stays live. auto=only pages the engine flags; no-op if no rasterizer |
--semantic-tags |
SemanticStructure |
semanticTags |
off (false) |
flag | Emit <h1-6>/<p>/<ul>/<li>/<table>… + <sub>/<sup> from a tagged PDF via display:contents (positions unchanged). No effect on untagged PDFs |
--detect-decorative |
DetectDecorative |
detectDecorative |
off (false) |
flag | Detect running headers/footers and page numbers and emit them as non-selectable decorative text. Text stays live HTML; pixels unchanged |
--extract-styles |
ExtractStyles |
extractStyles |
off (false) |
flag | Deduplicate repeated style declarations into short generated CSS classes. Off = byte-identical output |
--jpeg-quality <n> |
JpegQuality |
jpegQuality |
85 |
1–100 | Quality for opaque background images (alpha images use PNG regardless); clamped 1–100 server-side |
--raw-ttf |
FontEmbedding = RawTtf |
rawTtf |
off (Woff1) |
flag | Embed raw TrueType instead of WOFF 1.0. Larger output; a font-debugging aid |
--password <value> |
Password |
password |
none | string | User password for an encrypted PDF. Managed engine only (--engine managed) |
--parallelism <n> |
MaxDegreeOfParallelism |
— | all cores | ≥1 |
Managed post-processing threads within one document (native extraction is single-threaded). In batch, derived from --jobs when unset |
--fail-on <v> |
(CLI-only exit-code gate) | — | none |
none, loss, any |
Exit code 5 when the conversion completes but degrades fidelity. none=never (default, unchanged behavior); loss=any WarningSeverity.Loss warning (content dropped entirely); any=any warning, including Info-level cosmetic ones. Per document in batch mode; a hard document failure still returns 1 in preference to 5 |
--timeout <seconds> |
(CLI-only) | — (server-wide ConversionTimeoutSeconds) |
0 (disabled) |
≥0 |
Hard per-document conversion timeout in seconds. On expiry the conversion is cancelled and exit code 7 is returned. Batch mode gives each document its own budget |
Library-only options (no CLI flag / REST field)
ConversionOptions |
Default | Values | Guidance |
|---|---|---|---|
MaxImageDimension |
4096 |
device px per axis | Cap for resampled background images; lower it to shrink output at some fidelity cost |
Deterministic |
false |
bool |
Fixes font timestamps and ordering for byte-reproducible output (golden tests, regulated archival) |
LineGroupingOptions |
tuned | see below | Tolerances for grouping words into lines (CSS px) |
LineGroupingOptions (only relevant when LineGrouping != Never):
| Property | Default | Meaning |
|---|---|---|
VerticalToleranceFactor |
3 |
A word joins a line when |top delta| ≤ max(2, fontSize / factor) |
HorizontalJoinTolerance |
10 |
Max horizontal gap (px) between a line's right edge and the next word |
FontSizeTolerance |
2 |
Max font-size difference (px) for words to share a line |
Batch options
Set via --jobs/--parallelism on the CLI, or BatchOptions in the library. Batch mode engages
automatically when more than one input PDF resolves.
| CLI flag | BatchOptions |
Default | Guidance |
|---|---|---|---|
-j, --jobs <n> |
MaxConcurrentDocuments |
max(1, cores / 2) |
How many PDFs convert at once. The ~1.35x throughput lever (needs Server GC). Ignored for a single input |
--parallelism <n> |
PerDocumentParallelism |
null → max(1, cores / jobs) |
Per-document internal threads; derived so jobs × per-doc never oversubscribes the CPU |
Verbosity (CLI)
-v, --verbosity <level> (default normal) maps to a log level:
| Level | Log level |
|---|---|
quiet |
none |
minimal |
warning |
normal |
information |
detailed |
debug |
diagnostic |
trace |
A live progress line is shown when verbosity ≤ normal and stdout is a TTY (not redirected).
Exit codes (CLI)
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Conversion failed (or, in batch, at least one document failed — successes are still written) |
2 |
Invalid arguments (bad --dpi, --jpeg-quality, or --pages range) |
3 |
Input not found (no PDF matched the inputs) |
4 |
A native-only feature (--engine native or --background raster) was requested but the native rendering library is unavailable for this RID |
5 |
The conversion completed and produced output, but --fail-on (default none, so this never fires unless requested) was tripped — loss: a WarningSeverity.Loss warning (content dropped entirely); any: any warning. Distinct from 1 so a harness can tell "produced output but lost fidelity" from "produced nothing" |
6 |
The PDF is password-protected and no password (or the wrong one) was supplied via --password |
7 |
The conversion was aborted by --timeout (or the Web job manager's default per-document timeout) |
8 |
The PDF is encrypted with a security handler this engine does not implement (e.g. /Adobe.PubSec public-key/certificate encryption). Distinct from a missing/wrong --password: no password can ever unlock this class of document |
--raster-fallback never triggers code 4: when the native rendering library is unavailable it degrades to the vector
background with a warning rather than failing.
Code 5 is opt-in via --fail-on; a script that doesn't pass the flag sees identical exit-code
behavior to before this option existed (always 0 on a completed conversion). In batch mode, a
hard document failure (code 1) takes priority over a --fail-on trip (code 5) when both occur
across the batch.
Web service host settings
The Web service reads standard ASP.NET Core host configuration plus its own DynDynPdf section
(appsettings.json, environment variables as DynDynPdf__Setting, or the command line); per-request
form fields above still drive the conversion itself. Full table and "why" for each value:
deployment.md.
| Setting | Source | Default |
|---|---|---|
| Listen URL(s) | ASPNETCORE_URLS / --urls |
http://localhost:5000 |
| Environment | ASPNETCORE_ENVIRONMENT |
Production |
DynDynPdf:ApiKeys |
config | empty (loopback-only unless AllowAnonymous) |
DynDynPdf:AllowAnonymous |
config | false |
DynDynPdf:MaxConcurrentConversions |
config | 0 (auto, derived from cores + memory) |
DynDynPdf:MaxLiveJobs |
config | 200 (new uploads past this get 503) |
DynDynPdf:JobTtlMinutes |
config | 30 |
DynDynPdf:CleanupIntervalSeconds |
config | 60 |
DynDynPdf:RateLimitRequestsPerMinute |
config | 120 |
DynDynPdf:MaxUploadBytes |
config | 1 GB |
DynDynPdf:ConversionTimeoutSeconds |
config | 600 (0/negative disables) |
DynDynPdf:MaxPagesPerJob |
config | 0 (unlimited) |
| DPI clamp | server-side | 18–600 |
| Job scratch root | Path.GetTempPath() |
%TEMP%/dyndyn-pdf-web |
Native library override (all surfaces)
| Env var | Effect |
|---|---|
DYNDYN_PDF_NATIVE_LIB |
Point at a specific native library file or directory to override the NuGet-restored binary (pinned/patched builds). Otherwise the correct binary for the build/publish RID is restored and used automatically |