Skip to content
kōan
Contents

Start

Server

Library

Playback

Automation

Reference

Protocol

Format strings

fb2k-compatible format string engine used by organize and library display formatting.

Syntax

Three constructs: fields, conditionals, and functions. Everything else is literal text (including / for directory separators).

Fields: %field name%

Replaced with the track's metadata value. If the field doesn't exist, it evaluates to empty string.

%artist% - %title%
→ Aphex Twin - Windowlicker

Available fields:

Field Example
%title% Windowlicker
%artist% Aphex Twin
%album artist% Aphex Twin
%album% Windowlicker EP
%date% 1999 (the original release date where one is tagged, as the library dates albums)
%tracknumber% 01 (zero-padded)
%discnumber% 1
%codec% FLAC
%genre% Electronic

Conditionals: [...]

Content inside brackets is only included if all fields within it have values. If any field is missing, the entire block is omitted.

%artist%[ - %album%]
→ Aphex Twin - Windowlicker EP   (album exists)
→ Aphex Twin                     (no album tag)

Nest them for finer control:

%artist%[ (%date%)][ - %album%]
→ Aphex Twin (1999) - Windowlicker EP   (date + album)
→ Aphex Twin - Windowlicker EP          (no date)
→ Aphex Twin (1999)                     (no album)
→ Aphex Twin                            (neither)

Functions: $function(args)

Transform values. Arguments are comma-separated. Fields can be used as arguments.

$upper(%artist%)
→ APHEX TWIN

$if(%date%,%date%,Unknown)
→ 1999       (date exists)
→ Unknown    (no date)

Quoted literals: '...'

Single quotes escape special characters ([, ], %, $, ,, (). Use them when you need literal brackets in output:

%album% '['%codec%']'
→ OK Computer [FLAC]

Function reference

String

Function Args Result
$lower(s) string lowercase
$upper(s) string UPPERCASE
$caps(s) string Title Case
$caps2(s) string Title Case (articles stay lowercase)
$trim(s) string strip whitespace
$left(s,n) string, count first n chars
$right(s,n) string, count last n chars
$substr(s,from,to) string, start, end substring (0-indexed)
$pad(s,n) string, width right-align (pad left with spaces)
$pad_right(s,n) string, width left-align (pad right with spaces)
$padcut(s,n) string, width right-align, truncate to width
$padcut_right(s,n) string, width left-align, truncate to width
$insert(s,sub,pos) string, substring, position insert at position
$replace(s,from,to) string, search, replacement string replace
$repeat(s,n) string, count repeat n times
$len(s) string length in bytes
$abbr(s) string first letter of each word
$stripprefix(s) string remove leading "A "/"The "
$swapprefix(s) string "The Beatles" → "Beatles, The"
$rot13(s) string ROT13 cipher
$fix_eol(s) string replace line breaks with spaces
$fix_eol(s,r) string, replacement replace line breaks with r
Function Args Result
$strchr(s,c) string, char position of first occurrence (1-indexed, "" if not found)
$strrchr(s,c) string, char position of last occurrence
$strstr(s,sub) string, substring position of substring

Comparison (boolean)

These return "1" for true, "" for false — designed for use with $if().

Function Args Result
$strcmp(a,b) string, string true if equal (case-sensitive)
$stricmp(a,b) string, string true if equal (case-insensitive)
$longer(a,b) string, string true if a is longer
$longest(a,b,...) strings returns the longest
$shortest(a,b,...) strings returns the shortest
$greater(a,b) number, number true if a > b
$not(x) value invert boolean
$and(a,b) value, value both non-empty
$or(a,b) value, value either non-empty
$xor(a,b) value, value exactly one non-empty

Logic

Function Args Result
$if(cond,then,else) test, if non-empty, if empty conditional
$if2(a,b) primary, fallback first non-empty
$if3(a,b,c,...) values... first non-empty of any
$ifequal(a,b,then,else) int, int, if equal, if not numeric equality
$ifgreater(a,b,then,else) int, int, if a>b, if not numeric comparison
$iflonger(s,n,then,else) string, length, if longer, if not length comparison
$select(n,a,b,c,...) index (1-based), values... select nth value

Numeric

Function Args Result
$num(n,digits) number, width zero-padded ($num(5,3) → 005)
$add(a,b) int, int addition
$sub(a,b) int, int subtraction
$mul(a,b) int, int multiplication
$div(a,b) int, int integer division
$mod(a,b) int, int remainder
$muldiv(a,b,c) int, int, int (a*b)/c without overflow
$max(a,b) int, int larger value
$min(a,b) int, int smaller value
$hex(n) int hexadecimal
$hex(n,digits) int, width zero-padded hex

Path

Function Args Result
$directory(path) file path parent directory name
$directory_path(path) file path full parent path
$ext(path) file path file extension
$filename(path) file path filename without extension

Special

Function Args Result
$tab() (optional count) tab character(s)
$crlf() — newline
$char(n) code point unicode character

Named patterns

Store patterns in config and reference them by name instead of typing the full format string every time.

~/.config/koan/config.toml:

[organize]
default = "standard"

[organize.patterns]
standard = "%album artist%/(%date%) %album%/%tracknumber%. %title%"
va-aware = "%album artist%/$if($stricmp(%album artist%,Various Artists),,['('$left(%date%,4)')' ])%album% '['%codec%']'/[$num(%discnumber%,2)][%tracknumber%. ][%artist% - ]%title%"
label = "$if2(%label%,%album artist%)/%album% '['%codec%']'/[$num(%discnumber%,2)][%tracknumber%. ][%artist% - ]%title%"

Organize runs from the TUI (space on a queue selection, then Organize) and from the macOS Organize sheet. Both list the patterns above and preselect the one default names; there is no koan organize subcommand.

Organize examples

Slashes in the pattern create directory structure. Both front ends preview the whole plan before anything moves.

Standard layout

%album artist%/(%date%) %album%/%tracknumber%. %title%
Aphex Twin/(1999) Windowlicker EP/01. Windowlicker.flac
Aphex Twin/(1999) Windowlicker EP/02. Nannou.flac

With disc number for multi-disc albums

%album artist%/[(%date%) ]%album%/[%discnumber%-]%tracknumber%. %title%
Tool/(2006) 10,000 Days/1-01. Vicarious.flac
Tool/(2006) 10,000 Days/2-01. Wings for Marie.flac

The [%discnumber%-] conditional means the disc prefix only appears if discnumber exists.

VA-aware layout with $stricmp

Skip the date prefix for Various Artists compilations:

%album artist%/$if($stricmp(%album artist%,Various Artists),,['('$left(%date%,4)')' ])%album% '['%codec%']'/[$num(%discnumber%,2)][%tracknumber%. ][%artist% - ]%title%
Aphex Twin/(1992) Selected Ambient Works 85-92 [FLAC]/01. Aphex Twin - Xtal.flac
Various Artists/Warp 20 Recreated [FLAC]/03. Flying Lotus - Roygbiv.flac

Label-based with $if2 fallback

$if2(%label%,%album artist%)/%album% '['%codec%']'/[$num(%discnumber%,2)][%tracknumber%. ][%artist% - ]%title%
Warp Records/Selected Ambient Works 85-92 [FLAC]/01. Aphex Twin - Xtal.flac

Uses record label if tagged, falls back to album artist.

Artist - Title flat layout

%artist% - %title%
Aphex Twin - Windowlicker.flac
Boards of Canada - Roygbiv.flac

Fallback artist with $if2

$if2(%album artist%,%artist%)/%album%/%tracknumber%. %title%

Uses album artist if available, falls back to track artist.

Genre-based structure

[%genre%/]%album artist%/%album%/%tracknumber%. %title%
Electronic/Aphex Twin/Windowlicker EP/01. Windowlicker.flac

Tracks without a genre tag skip the genre directory.

Safety

Illegal filename characters (/ \ : * ? " < > |) are replaced with _, and a file name is capped at 250 bytes, extension included. The rest of what organize guarantees is in File Organization.

fb2k compatibility

The format engine implements a subset of the foobar2000 title formatting spec: the core syntax (%fields%, [conditionals], $functions()) and the functions listed above.

Not implemented

Functions: $meta, $meta_sep, $meta_num, $meta_test, $info (multi-value), $channels, $get, $put, $puts, $progress, $progress2, $rand, $blend, $transition, $rgb, $hsl, $year, $month, $day_of_month, $date, $time, $crc32, $ansi, $ascii

Fields: %track number% (unpadded), %totaltracks%, %totaldiscs%, %samplerate%, %bitrate%, %channels%, %filename%, %filename_ext%, %directoryname%, %path%, %filesize%, %filesize_natural%, %length%, %length_seconds%, all ReplayGain fields, all playback status fields