Output File Rename

1. Introduction

2. Tag Reference

3. Numbering Rules

4. Rules & Limitations

5. Examples

*GUI in this document refers to Waifu2x-Extension-GUI

Introduction

Waifu2x-Extension-GUI names the output files automatically. With the Output File Rename dialog (click the Rename button to open it), you can customize the output file name.

The dialog offers three modes:

Default - keep the engines' built-in naming convention; no custom rename is applied.
Simple combination - pick elements (number, engine, scale, denoise level, image quality, source extension) to place before and/or after the file name, joined by a connector (_, space or -).
Advanced - build the file name from tags, with two separate format strings: one for when an output folder is used and one for in-place save (the file stays next to the source, including when the output folder is disabled).

The rename is applied after the file has been saved and moved to its output location. It only changes the file name (base name), the file extension is never touched.

The rename does not take effect when Keep original file name is enabled while an output folder is in use, or when Replace original file is enabled.

Tag Reference

Tag	Description
`<name>`	Base name of the source file (without the extension). Example: `CatPic.png` → `CatPic`.
`<ext>`	Extension of the source file (without the dot). Example: `CatPic.png` → `png`.
`<outext>`	Extension of the output file (without the dot).
`<scale>`	Scale ratio, such as `2x`, or the custom resolution, such as `1920x1080`, when a custom resolution is applied. Expands to an empty string in pipelines without upscaling (format conversion only, frame interpolation only, duplicate-frame removal only).
`<denoise>`	Denoise level. Expands to an empty string for engines without a denoise option (RealESRGAN, RealSR, PyTorch, Maxine) and in pipelines without upscaling.
`<engine>`	Short name of the upscaling engine: `Waifu2xNcnn`, `Waifu2xCaffe`, `Waifu2xConverter`, `SrmdNcnn`, `SrmdCuda`, `RealSR`, `RealESRGAN`, `RealCUGAN`, `Anime4K`, `Maxine`, `PyTorch`. Expands to an empty string in pipelines without an upscaling engine (format conversion only, frame interpolation only, duplicate-frame removal only).
`<number-pad>`	Sequence number within the source folder, zero-padded. The width adapts to the number of files in the group: 77 files → width 2 → `07`. See Numbering Rules.
`<number-pad3>`	Sequence number with an explicit width. Example: `<number-pad3>` → `007`.
`<number-pad3:date:desc>`	Sequence number with inline sort keys. Allowed parameters: `name`, `date`, `asc`, `desc`; the default is `name asc`.
`<date:yyyy-MM-dd>`	Modification date of the source file, formatted with Qt's native format tokens (the format string of `QDateTime::toString`). Common examples: `yyyy-MM-dd` → `2024-01-15`, `yyyyMMdd-hhmmss` → `20240115-103000`.
`<ImgQuality:separator>`	Image quality of the output image. Image files only, and it carries its own connector: `cat<ImgQuality:_>` → `cat_Q95.jpg`. Expands to an empty string for non-image files (GIF, video).

Tag names are case-insensitive: <NAME> is the same as <name>.

Numbering Rules

Sequence numbers are assigned per source folder, numbered from 1.
Numbers are assigned when processing starts, so they do not depend on the order in which files finish. A file that later fails or is skipped does not change the numbers of the other files.
Files that are skipped automatically by the resolution-based auto-skip cannot be told apart when the numbers are assigned, so they are still counted and the sequence may contain gaps.
Simple mode: the sort key comes from the dropdown (file name / modification date, ascending only).
Advanced mode: the sort key is set inline in the number-pad tag, e.g. <number-pad:date>, <number-pad3:name:asc>, <number-pad3:date:desc>. If several number-pad tags with different sort keys appear in the same format string, the first one takes effect.
The modification time used for date sorting and for <date:...> is a snapshot taken when processing starts - modifying the source file during processing does not change the expanded value.

Rules & Limitations

Tag names are case-insensitive.
Separator folding. When a tag expands to an empty string, the one separator (_, space or -) immediately adjacent on each side is folded away. Example: a_<empty>_b → a_b. Consecutive separators that you wrote yourself are preserved: img_<name>__v2 → img_CatPic__v2.
Illegal characters. The expanded file name must not contain \ / : * ? " < > |. This check also applies to the expansion result, e.g. <date:hh:mm:ss> would expand to 10:30:00, which contains : and is therefore rejected.
Do not use > inside a date format string, even inside Qt single-quoted literals - the tag is terminated at the first >, so the format string would be cut short.
The rename only changes the file name, never the extension.
If the target file name already exists, _1, _2, ... is appended automatically.
The rename is not applied when Keep original file name is enabled while an output folder is in use, or when Replace original file is enabled.
If the rename cannot be applied at runtime (for example the whole format expands to an empty name for the current pipeline, or the file is in use), the original output file name is kept, a warning is shown in the log, and the file is not marked as failed.

Examples

Source file: CatPic.png, Waifu2xNcnn engine, 2x, denoise level 1, output png.

<engine>_<name>_<scale>_<denoise> → Waifu2xNcnn_CatPic_2x_1.png
Same format with the RealESRGAN engine (no denoise option), 4x: <engine>_<name>_<scale>_<denoise> → RealESRGAN_CatPic_4x.png (the empty <denoise> folds the adjacent _).
Format conversion only (no engine, no scale, no denoise): <engine>_<name>_<scale>_<denoise> → CatPic.png (all three tags are empty, all separators fold).
cat<ImgQuality:_> → cat_Q95.jpg for images; for a GIF or a video it expands to cat.jpg.
<name>_<date:yyyy-MM-dd> → CatPic_2024-01-15.png (modification date of the source at processing start).
<number-pad>_<name> with 77 files in the folder: the 7th file → 07_CatPic.png.
<number-pad3:date:desc>_<name> → sorted by modification date, descending, width 3: 003_CatPic.png.