Folder Format Tokens

Narratorr uses token-based templates to name audiobook folders and files in your library. Configure these in Settings under the File Naming section (it sits just below Library on the General settings page).

Presets

If you’d rather not hand-write templates, the File Naming section includes a Preset dropdown with four built-in format pairs. Selecting one populates both the folder and file format fields; editing either field afterward switches the dropdown to Custom.

Preset	Folder Format	File Format
Standard	{author}/{title}	{author} - {title}
Detailed	{author}/{series}/{seriesPosition:00? - }{title}	{author} - {series? - }{seriesPosition:00? - }{title} {- ?trackNumber:000}
Audiobookshelf	{author}/{series?/}{title}	{title}
Plex	{author}/{series?/}{year? - }{title}	{title}{ - pt?trackNumber:00}
Last, First	{authorLastFirst}/{titleSort}	{authorLastFirst} - {titleSort}

Tokens

Token	Description	Example Value
{author}	Author name	Terry Goodkind
{authorLastFirst}	Author as Last, First	Goodkind, Terry
{title}	Book title	Wizards First Rule
{titleSort}	Title without leading articles	Wizards First Rule
{series}	Series name	The Sword of Truth
{seriesPosition}	Position in series	01
{year}	Publication year	1994
{narrator}	Narrator name	Sam Tsoukalas
{narratorLastFirst}	Narrator as Last, First	Tsoukalas, Sam
{edition}	Edition label when a book has more than one recording — see Multiple Editions	Full Cast
{trackNumber}	Chapter/track number (file format only)	01
{trackTotal}	Total tracks (file format only)	47
{partName}	Part or volume name (file format only)	Book 1

Modifiers

Tokens support modifiers that control formatting:

Zero-Pad: {token:00}

Pads numeric values with leading zeros to the specified width.

Expression	Input	Output
{seriesPosition:00}	1	01
{seriesPosition:000}	1	001
{trackNumber:00}	3	03
{year:00}	1994	1994 (already wider than 2)

Only applies to numeric token values. Non-numeric values are left as-is.

Conditional Suffix: {token?text}

Appends text only if the token has a value. If the token is empty or missing, the entire expression (including the suffix) is omitted.

Expression	Has Value	No Value
{series? - }	The Sword of Truth -	(nothing)

To wrap a value in parentheses (e.g. a year), use the prefix + suffix form below — {(?year?)} — rather than two separate conditional tokens.

Conditional Prefix: {text?token}

Prepends text only if the token has a value. As with the suffix form, the entire expression (including the prefix) is omitted when the token is empty or missing.

Expression	Has Value	No Value
{ - pt?trackNumber:00}	- pt01	(nothing)
{Book ?seriesPosition}	Book 1	(nothing)

Disambiguation: if the text before ? is a known token name, the expression is treated as a conditional suffix ({token?text}); otherwise it’s treated as a conditional prefix ({text?token}).

Prefix + Suffix: {pre?token?suf}

Wraps the token’s value with both a prefix and a suffix, omitting the whole expression when the token has no value.

Expression	Has Value	No Value
{(?year?)}	(1994)	(nothing)

Combined: {token:00?text}

Both modifiers can be used together — zero-pad first, then conditional suffix.

Expression	Input	Output
{seriesPosition:00? - }	1	01 -
{seriesPosition:00? - }	(empty)	(nothing)

Examples

Folder Format

Simple — {author}/{title}

Terry Goodkind/Wizards First Rule

With series — {author}/{series?/}{title}

Terry Goodkind/The Sword of Truth/Wizards First Rule

With series position — {author}/{series? - }{seriesPosition:00? - }{title}

Terry Goodkind/The Sword of Truth - 01 - Wizards First Rule

If no series: Terry Goodkind/Wizards First Rule

With year — {author}/{title} ({year})

Terry Goodkind/Wizards First Rule (1994)

File Format

Simple — {author} - {title}

Terry Goodkind - Wizards First Rule.m4b

With track number — {trackNumber:00} - {title}

01 - Wizards First Rule.m4b
02 - Wizards First Rule.m4b

Defaults

Setting	Default
Folder Format	{author}/{title}
File Format	{author} - {title}

Behavior Notes

Separator and Case

Two settings in the File Naming section reshape every resolved token value before it’s placed into the path:

Setting	Options	Default
Separator	Space, Period, Underscore, Dash	Space
Case	Default, lowercase, UPPERCASE, Title Case	Default

These apply to every non-numeric token value at render time, so they affect your folder and file names regardless of which template you use. For example, choosing the Period separator turns Brandon Sanderson into Brandon.Sanderson and collapses the comma in Last, First formats. The Case setting transforms casing in the same way — lowercase, UPPERCASE, or Title Case — while Default leaves the original casing untouched.

Empty folder segments are skipped

If a token resolves to nothing (e.g., a book has no series), the entire folder segment is removed from the path — you don’t end up with empty directories or double slashes.

For example, with the template {author}/{series}/{title} and a book that has no series:

// Expected: the series folder is simply omitted
Terry Goodkind/Wizards First Rule

This means you don’t need any special conditional syntax to handle missing values in folder segments. Just include {series} as its own segment and it’ll disappear when there’s no series. If you want series info combined with the title in the same segment, use the conditional suffix modifier instead: {series? - }.

Character sanitization

Illegal filesystem characters (< > : " / \ | ? * and control characters) are stripped from each path segment. Leading/trailing whitespace is trimmed, and consecutive spaces are collapsed to a single space. For example, if a colon is stripped from Author: Name, the resulting double space is automatically collapsed to Author Name.

The {edition} token and multiple editions

When you keep more than one recording of a book (a full-cast and an unabridged, say), narratorr distinguishes them with an edition label on the book folder. This happens automatically — when a second recording needs its own folder, (<edition>) is appended to the book folder even if your template contains no {edition} token:

Brandon Sanderson/The Stormlight Archive/01 - The Way of Kings
Brandon Sanderson/The Stormlight Archive/01 - The Way of Kings (Full Cast)

Add the {edition} token to your folder format to control where the label appears instead of letting it auto-append. When the token is present, narratorr renders the label in place and suppresses the automatic suffix (so it never appears twice). The token renders nothing for a book with a single recording, so it’s safe to add library-wide:

{author}/{series}/{seriesPosition:00? - }{title} ({edition})

Unlike other tokens, the folder {edition} label is written verbatim — the Separator and Case settings never reshape it, so it stays a stable on-disk identifier. The token is available in file formats too, where it is styled by Separator/Case like any other token. See Multiple Editions for how narratorr decides what counts as a separate recording.

Validation

Narratorr validates your format template when you save. Invalid tokens are flagged. The preview below the format field shows how a sample book would be named with your current template.