From 1d96d39af7fcfa43944e4956a6602b144471319d Mon Sep 17 00:00:00 2001 From: Mbucari <37587114+Mbucari@users.noreply.github.com> Date: Fri, 3 Feb 2023 14:10:36 -0700 Subject: [PATCH] Add Naming Template Documentation --- Documentation/Advanced.md | 8 +-- Documentation/NamingTemplates.md | 107 +++++++++++++++++++++++++++++++ README.md | 2 +- 3 files changed, 109 insertions(+), 8 deletions(-) create mode 100644 Documentation/NamingTemplates.md diff --git a/Documentation/Advanced.md b/Documentation/Advanced.md index 28ca18ac..6188cdcd 100644 --- a/Documentation/Advanced.md +++ b/Documentation/Advanced.md @@ -9,7 +9,7 @@ - [Files and folders](#files-and-folders) - [Settings](#settings) -- [Custom File Naming](#custom-file-naming) +- [Custom File Naming](NamingTemplates.md) - [Command Line Interface](#command-line-interface) @@ -28,12 +28,6 @@ To make upgrades and reinstalls easier, Libation separates all of its responsibi * Allow Libation to fix up audiobook metadata. After decrypting a title, Libation attempts to fix details like chapters and cover art. Some power users and/or control freaks prefer to manage this themselves. By unchecking this setting, Libation will only decrypt the book and will leave metadata as-is, warts and all. -### Custom File Naming - -In Settings, on the Download/Decrypt tab, you can specify the format in which you want your files to be named. As you edit these templates, a live example will be shown. Parameters are listed for folders, files, and files split by chapter including an explanation of what each naming option means. For instance: you can use template ` - <ch# 0> of <ch count> - <ch title>` to create the file `A Study in Scarlet - 04 of 10 - A Flight for Life.m4b`. - -These templates apply to GUI and CLI. - ### Command Line Interface Libationcli.exe allows limited access to Libation's functionalities as a CLI. diff --git a/Documentation/NamingTemplates.md b/Documentation/NamingTemplates.md new file mode 100644 index 00000000..02e93017 --- /dev/null +++ b/Documentation/NamingTemplates.md @@ -0,0 +1,107 @@ +# Naming Templates +File and Folder names can be customized using Libation's built-in tag template naming engine. To edit how folder and file names are created, go to Settings \> Download/Decrypt and edit the naming templates. If you're splitting your audiobook into multiple files by chapter, you can also use a custom template to set each chapter's title metadata tag by editing the template in Settings \> Audio File Options. + +These templates apply to both GUI and CLI. + +# Table of Contents + +- [Template Tags](#template-tags) + - [Property Tags](#property-tags) + - [Conditional Tags](#conditional-tags) +- [Tag Formatters](#tag-formatters) + - [Text Formatters](#text-formatters) + - [Integer Formatters](#integer-formatters) + - [Date Formatters](#date-formatters) + + +# Template Tags + +These are the naming template tags currently supported by Libation. + +## Property Tags +These tags will be replaced in the template with the audiobook's values. + +|Tag|Description|Type| +|-|-|-| +|\<id\>|Audible book ID (ASIN)|Text| +|\<title\>|Full title|Text| +|\<title short\>|Title. Stop at first colon|Text| +|\<author\>|Author(s)|Text| +|\<first author\>|First author|Text| +|\<narrator\>|Narrator(s)|Text| +|\<first narrator\>|First narrator|Text| +|\<series\>|Name of series|Text| +|\<series#\>|Number order in series|Text| +|\<bitrate\>|File's original bitrate (Kbps)|Integer| +|\<samplerate\>|File's original audio sample rate|Integer| +|\<channels\>|Number of audio channels|Integer| +|\<account\>|Audible account of this book|Text| +|\<locale\>|Region/country|Text| +|\<year\>|Year published|Integer| +|\<language\>|Book's language|Text| +|\<language short\>|Book's language abbreviated. Eg: ENG|Text| +|\<file date\>|File creation date/time.|DateTime| +|\<pub date\>|Audiobook publication date|DateTime| +|\<date added\>|Date the book added to your Audible account|DateTime| +|\<ch count\>|Number of chapters **†**|Integer| +|\<ch title\>|Chapter title **†**|Text| +|\<ch#\>|Chapter number **†**|Integer| +|\<ch# 0\>|Chapter number with leading zeros **†**|Integer| + +**†** Only valid for Chapter Filename and Chapter Tile Metadata + +To change how these properties are displayed, [read about custom formatters](#tag-formatters) + +## Conditional Tags +Anything between the opening tag (`<tagname->`) and closing tag (`<-tagname>`) will only appear in the name if the condition evaluates to true. + +|Tag|Description|Type| +|-|-|-| +|\<if series-\>...\<-if series\>|Only include if part of a book series or podcast|Conditional| +|\<if podcast-\>...\<-if podcast\>|Only include if part of a podcast|Conditional| +|\<if bookseries-\>...\<-if bookseries\>|Only include if part of a book series|Conditional| + +For example, <if podcast-\>\<series\>\<-if podcast\> will evaluate to the podcast's series name if the file is a podcast. For audiobooks that are not podcasts, that tag will be blank. + +You can invert the condition (instead of displaying the text when the condition is true, display the text when it is false) by playing a '!' symbol before the opening tag name. + +As an example, this folder template will place all Liberated podcasts into a "Podcasts" folder and all liberated books (not podcasts) into a "Books" folder. + +\<if podcast-\>Podcasts<-if podcast\>\<!if podcast-\>Books\<-if podcast\>\\\<title\> + + +# Tag Formatters +**Text**, **Integer**, and **DateTime** tags can be optionally formatted using format text in square brackets after the tag name. Below is a list of supported formatters for each tag type. + +## Text Formatters +|Formatter|Description|Example Usage|Example Result| +|-|-|-|-| +|L|Converts text to lowercase|\<title[L]\>|a study in scarlet꞉ a sherlock holmes novel| +|U|Converts text to uppercase|\<title short[U]\>|A STUDY IN SCARLET| + +## Integer Formatters +|Formatter|Description|Example Usage|Example Result| +|-|-|-|-| +|# (a number)|Zero-pads the number|\<bitrate[4]\><br>\<series#[3]\><br>\<samplerate[6]\>|0128<br>001<br>044100| + +**Text**, **Integer**, and **DateTime** tags can be optionally formatted using format text in square brackets after the tag name. Below is a list of supported formatters for each tag type. + +## Date Formatters +Form more standard formatters, [see this guide from Microsoft](https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings). +### Standard DateTime Formatters +|Formatter|Description|Example Usage|Example Result| +|-|-|-|-| +|s|Sortable date/time pattern.|\<file date[s]\>|2023-02-14T13:45:30| +|Y|Year month pattern.|\<file date[Y]\>|February 2023| + +### Custom DateTime Formatters +You can use custom formatters to construct customized DateTime string. For more custom formatters and examples, [see this guide from Microsoft](https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings). +|Formatter|Description|Example Usage|Example Result| +|-|-|-|-| +|yyyy|4-digit year|\<file date[yyyy]\>|2023| +|yy|2-digit year|\<file date[yy]\>|23| +|MM|2-digit month|\<file date[MM]\>|02| +|dd|2-digit day of the month|\<file date[yyyy-MM-dd]\>|2023-02-14| +|HH<br>mm|The hour, using a 24-hour clock from 00 to 23<br>The minute, from 00 through 59.|\<file date[HH:mm]\>|14:45| + + diff --git a/README.md b/README.md index 2cdd8819..524a031f 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ - [Advanced](Documentation/Advanced.md) - [Files and folders](Documentation/Advanced.md#files-and-folders) - [Settings](Documentation/Advanced.md#settings) - - [Custom File Naming](Documentation/Advanced.md#custom-file-naming) + - [Custom File Naming](Documentation/NamingTemplates.md) - [Command Line Interface](Documentation/Advanced.md#command-line-interface) - [Docker](Documentation/Docker.md)