Foobar2000/Описание синтаксиса форматирования заголовков

Предопределённые поля

Некоторые поля, доступные как %имя%, предопределены другими значениями, чтобы сделать написание скриптов форматирования заголовка более удобным.

Метаданные

%album artist%

Определёно как $if3($meta(album artist),$meta(artist),$meta(composer),$meta(performer))..

%album%

Определёно как $if3($meta(album),$meta(venue)).

%artist%

Определёно как $if3($meta(artist),$meta(album artist),$meta(composer),$meta(performer)).

%disc%

Возвращает номер диска. Номер берётся из тега discnumber; если этот тег не существует, номер берётся из тега disc. Если оба тега не прописаны, поле не определено.

Эквивалентно предопределённому полю %discnumber%

%discnumber%

Возвращает номер диска. Номер берётся из тега discnumber; если этот тег не существует, номер берётся из тега disc. Если оба тега не прописаны, поле не определено.

Эквивалентно предопределённому полю %disc%

%track artist%

Определёно как $meta(artist), если $meta(album artist) отлично от $meta(artist), иначе это поле пусто.

%title%

Определёно как $if2($meta(title),%_filename%). Возвращает тэг title , если он присутствует, иначе возвращает имя файла, без расширения.

%track%

Возвращает номер трека, дополненный слева нулями до двух цифр. Номер трека берётся из тега tracknumber; если этот тег не существует, номер берётся из тега track. Если оба тега не прописаны, поле не определено.

Эквивалентно предопределённому полю %tracknumber%.

%tracknumber%

Возвращает номер трека, дополненный слева нулями до двух цифр. Номер трека берётся из тега tracknumber; если этот тег не существует, номер берётся из тега track. Если оба тега не прописаны, поле не определено.

Эквивалентно предопределённому полю %track%.

Техническая информация

%bitrate%

Определёно как $if2($info(bitrate_dynamic),$info(bitrate)). Возвращает текущий битрейт, если это возможно, иначе - средний битрейт. Если ни то, ни другое не определено, ничего не возвращается.

%channels%

Определёно как $channels(). Возвращает число каналов в виде текста; возвращает "mono" и "stereo" вместо "1" и "2".

%filesize%

Определёно как %_filesize%. Возвращает размер файла в байтах.

%samplerate%

Определёно как $info(samplerate). Возвращает частоту дискретизации в Гц.

%codec%

Определёно как $codec().

Специальные поля

%playlist_number%

Определёно как $num(%_playlist_number%,$len(%_playlist_total%)). Возвращает позицию трека (индекс) в плейлисте. Первый трек имеет индекс 1. Индекс дополняется слева нулями до такого же числа цифр, как и у индекса последнего трека.

Управление потоком выполнения

Функции в этом разделе могут быть использованы для зависимого от условий выполнения выражений.

[...] (условный раздел)

Вычисляет выражение между [ и ]. Если оно истинно, возвращаются его строковое значение и логическое значение истина. Иначе возвращаются пустая строка и ложь.

Пример: [%artist%] возвратит значение тэга artist, если оно существует. Иначе ничего не возвратится, в то время, как %artist% возвратил бы "?".

$if(условие,тогда)

Если условие вычисляется как истина, возвращается значение вычисленной части тогда. Иначе возвращается ложь.

$if(условие,тогда,иначе)

Если условие вычисляется как истина, возвращается значение вычисленной части тогда. В ином случае возвращается значение вычисленной части иначе.

$if2(a,иначе)

Подобно $if(a,a,иначе) за исключением того, что a вычисляется однократно.

$if3(a1,a2,...,aN,иначе)

Вычисляет аргументы a1...aN, пока не будет найден первый, вычисляемый как истина. Если это произошло, возвращается значение этого аргумента. В иных случаях возвращается значение вычисленной части иначе.

$ifgreater(n1,n2,тогда,иначе)

Сравнивает целые числа n1 и n2, если n1 больше, чем n2, возвращается значение вычисленной части тогда. В иных случаях возвращается значение вычисленной части иначе.

$iflonger(s1,s2,тогда,иначе)

Сравнивает длины строк s1 и s2, если s1 длиннее, чем s2, возвращается значение вычисленной части тогда. В иных случаях возвращается значение вычисленной части иначе.

$ifequal(a,b,тогда,иначе)

Сравнивает значения целых чисел a и b, если они равны, возвращается значение тогда. В иных случаях возвращается значение иначе.

$select(n,a1,...,aN)

Если значение n находится между 1 и N, возвращается вычисленное значение an. Иначе возвращается ложь.

Арифметические функции

Функции в этом разделе могут быть использованы для арифметических операций над целыми числами. Строка будет автоматически преобразована в число и наоборот. Преобразуется наиболее длинная начальная часть строки, которая может быть интерпретирована как число. Ведущие пробелы игнорируются.

Пример: "c3po" -> 0, " -12" -> -12, но "- 12" ->0.

$add(a,b)

Складывает a и b.

Можно использовать с произвольным количеством аргументов. $add(a,b,...) аналогично $add($add(a,b),...).

$div(a,b)

Делит a на b. Если b вычисляется как ноль, возвращается a.

Можно использовать с произвольным количеством аргументов. $div(a,b,...) аналогично $div($div(a,b),...).

$greater(a,b)

Возвращает истина, если a больше, чем b, иначе возвращает ложь.

$max(a,b)

Возвращает максимальное из a и b.

Можно использовать с произвольным количеством аргументов. $max(a,b,...) аналогично $max($max(a,b),...).

$min(a,b)

Возвращает минимальное из a и b.

Можно использовать с произвольным количеством аргументов. $min(a,b,...) аналогично $min($min(a,b),...).

$mod(a,b)

Вычисляет остаток от деления a на b. Результат имеет тот же знак, что и a. Если b вычисляется как ноль, возвращается a.

Можно использовать с произвольным количеством аргументов. $mod(a,b,...) аналогично $mod($mod(a,b),...).

$mul(a,b)

Умножает a на b.

Можно использовать с произвольным количеством аргументов. $mul(a,b,...) аналогично $mul($mul(a,b),...).

$muldiv(a,b,c)

Умножает a на b, затем делит на c. Результат округляется до ближайшего целого.

$rand()

Генерирует случайное число в диапазоне от 0 до 2³²-1.

$sub(a,b)

Вычитает b из a.

Можно использовать с произвольным количеством аргументов. $sub(a,b,...) аналогично $sub($sub(a,b),...).

Логические функции

Функции в этом разделе могут быть использованы для работы с логическими значениями (истина и ложь), не имеющих явного представления в скриптах форматирования заголовка. Эти функции не возвращают строку или числовое значение. Их можно использовать для задания более сложных условий в $if и подобных ей функциях.

$and(...)

Логическое И произвольного числа элементов. Возвращает истина тогда и только тогда, когда все аргументы вычисляются как истина.

Пример: $and(x,y) равно истина, если как x, так и y равны истина. В иных случаях функция возвратит ложь.

$or(...)

Логическое ИЛИ произвольного числа элементов. Возвращает истина, когда хотя бы один аргумент вычисляется как истина.

Пример: $or(x,y) равно истина, если x или y, или одновременно x и y равны истина. В иных случаях функция возвратит ложь.

$not(x)

Логическое НЕ. Возвращает ложь, если x равно истина, иначе возвращает истина.

$xor(...)

Логическое ИСКЛЮЧАЮЩЕЕ ИЛИ произвольного числа элементов. Возвращает истина, когда нечётное количество аргументов вычисляется как истина.

Пример: $xor(x,y) равно истина, если x или y, но не одновременно x и y, равны истина. В иных случаях функция возвратит ложь.

Функции работы с цветом

$blend(цвет1,цвет2,часть,всего)

Возвращает цвет, являющийся переходным между цвет1 и цвет2. Если часть меньше или равно нулю, возвращается цвет1. Если часть больше или равно всего, возвращается цвет2. В иных случаях возвращается смешанный цвет, являющийся на часть цвет1 и на всего-часть цвет2. Смешивание производится в цветовом пространстве RGB.

$rgb()

Сбрасывает цвет текста к принятому по умолчанию.

$rgb(r,g,b)

Устанавливает цвет текста. r, g и b - соответственно красная, зелёная и синяя составляющие цвета невыделенного текста. Цвет выделенного текста устанавливается инверсным.

$rgb(r1,g1,b1,r2,g2,b2)

Устанавливает цвет текста. r1, g1 и b1 - соответственно красная, зелёная и синяя составляющие цвета невыделенного текста. r2, g2 и b2 - соответственно красная, зелёная и синяя составляющие цвета выделенного текста.

$transition(строка,цвет1,цвет2)

Вставляет цветовые коды в строка так, что первый символ имеет цвет1, последний - цвет2, и промежуточные символы имеют переходные цвета. Смешивание производится в цветовом пространстве RGB. Обратите внимание, что цветовые коды являются дополнительными символами, которые также будут обработаны строковыми функциями. Например, если вам нужно усечь строку, это необходимо сделать до применения $transition().

Информация о проигрываемой композиции

Следующие функции и поля применимы в скриптах, используемых для текущей проигрываемой композиции, например в скриптах для строки статуса строки, заголовка окна и команды копирования.

Специальные поля

%_time_elapsed%

Возвращает время, прошедшее с начала проигрывания.

%_time_remaining%

Возвращает время, оставшееся до конца проигрывания песни.

%_time_total%

Возвращает общую длительность песни.

%_time_elapsed_seconds%

Возвращает время, прошедшее с начала проигрывания, в секундах.

%_time_remaining_seconds%

Возвращает время, оставшееся до конца проигрывания, в секундах.

%_time_total_seconds%

Возвращает общую длительность песни в секундах.

%_ispaused%

Возвращает "1", если проигрывание приостановлено (на паузе) и пустую строку в ином случае.

Информация о плейлисте

Следующие функции и поля применимы в скриптах для плейлиста.

Специальные поля

%isplaying%

Возвращает "1", если файл в текущий момент проигрывается и пустую строку в ином случае.

Старая версия %_isplaying% остаётся допустимой.

%_ispausing%

Возвращает "1", если проигрывание приостановлено, в ином случае возвращает пустую строку.

%_playlist_number%

Возвращает индекс элемента в плейлисте. Первый элемент имеет индекс 1.

Смотрите также %playlist_number%.

%_playlist_total%

Возвращает количество элементов в плейлисте.

%playlist_name%

Возвращает имя плейлиста, в котором содержится элемент.

Старая версия %_playlist_name% остаётся допустимой.

Строковые функции

Функции из этого раздела используются для операций над символьными строками.

$abbr(x)

Возвращает аббревиатуру x.

$abbr(x,длина)

Возвращает аббревиатуру x, если x длиннее, чем длина символов, в ином случае возвращает x.

$ansi(x)

Приводит x к системной кодовой странице и возвращает получившееся значение. Символы, не присутствующие в системной кодовой странице будут удалены/заменены. Полезно при массовом переименования файлов для обеспечения совместимости с программами, не понимающими юникод.

$caps(x)

Делает первую букву каждого слова в x прописной, остальные буквы - строчными.

$caps2(x)

Делает первую букву каждого слова в x прописной, остальные буквы оставляет в неизменном виде.

$char(x)

Вставляет юникодный символ с кодом x.

$crc32(a)

Вычисляет численное значение CRC32 строки a. Предназначена для использования при задании цветов в скриптах.

$crlf()

Вставляет маркер конца строки (возврат каретки, перевод строки). Может использоваться для вывода нескольких строк, например, во всплывающей подсказке иконки в системном трее.

$cut(a,длина)

Возвращает первые длина символов, начиная слева a.

$directory(x)

Извлекает имя каталога из файлового пути x.

$directory(x,n)

Извлекает имя каталога уровня n (отсчитывая с последнего) из файлового пути x.

$ext(x)

Извлекает расширение файла из x (который должен быть именем файла или путём).

$filename(x)

Извлекает имя файла из полного пути.

$fix_eol(x)

Если x содержит маркер конца строки (CR-LF), этот маркер и весь текст после него заменяется строкой "(...)". В ином случае x возвращается неизменённым.

$fix_eol(x,индикатор)

Если x содержит маркер конца строки (CR-LF), этот маркер и весь текст после него заменяется строкой индикатор. В ином случае x возвращается неизменённым.

$hex(n)

Приводит целое число n к шестнадцатиричной системе счисления.

$hex(n,длина)

Приводит целое число n к шестнадцатиричной системе счисления с длина цифрами, дополняет слева нулями при необходимости.

$insert(a,b,n)

Вставляет b в a после символа, находящегося в позиции n.

$left(a,длина)

Возвращает первые длина символов, считая слева a.

$len(a)

Возвращает длину строки a в символах.

$len2(a)

Возвращает длину строки a в символах, учитывая правила обработки двухбайтовых (double-width) символов (двухбайтовый символ считается за два).

$longer(a,b)

Возвращает истина, если строка a длиннее строки b, в ином случае возвращает ложь.

$lower(a)

Приводит a к нижнему регистру.

$longest(a,...)

Возвращает длиннейший из аргументов. Можно использовать с произвольным количеством строк.

$num(n,длина)

Дополняет (при необходимости) нулями слева до длина цифр число n в десятичной системе счисления.

$pad(x,длина)

Дополняет x слева пробелами до длина символов.

$pad_right(x,длина)

Дополняет x справа пробелами до длина символов.

$pad(x,длина,символ)

Дополняет x слева символом символ до длина символов.

$pad_right(x,длина,символ)

Дополняет x справа символом символ до длина символов.

$padcut(x,длина)

Возвращает первые длина сиволов с начала x, если x длиннее длина символов. В ином случае дополняет x справа пробелами до длина символов.

$padcut_right(x,длина)

Возвращает первые длина сиволов с начала x, если x длиннее длина символов. В ином случае дополняет x слева пробелами до длина символов.

$progress(позиция,диапазон,длина,a,b)

Создаёт полоску прогресса (progress bar): позиция определяет текущую позицию, диапазон - граничное значение, длина - длину полоски прогресса в символах, a и b определяют символы, из которых строится полоска прогресса.

Пример: $progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'#','=') выдаст "====#===============", где символ # движется в соответствии со временем проигрывания песни.

$progress2(позиция,диапазон,длина,a,b)

Создаёт полоску прогресса (progress bar): позиция определяет текущую позицию, диапазон - граничное значение, длина - длину полоски прогресса в символах, a и b определяют символы, из которых строится полоска прогресса. Отличается от $progress видом результирующей полоски.

$repeat(a,n)

Возвращает n копий a. Обратите внимание, что a вычисляется однажды перед использованием значения, так что $repeat не может быть использовано в роли цикла.

$replace(a,b,c)

Заменяет все вхождения строки b в строке a строкой c.

Можно использовать с произвольным количеством аргументов. Обратите внимание, что $replace(a,b1,c1,b2,c2) возвращает значение, отличное от $replace($replace(a,b1,c1),b2,c2).

Пример: $replace(ab,a,b,b,c) -> "bc", $replace($replace(ab,a,b),b,c) -> "cc"

$right(a,длина)

Возвращает первые длина символов с конца a.

$roman(n)

Приводит целое число n к записи римскими цифрами.

$rot13(a)

Производит ROT13 преобразование строки a.

Пример: $rot13('foobar2000') -> "sbbone2000".

$shortest()

Возвращает самый короткий из своих аргументов. Можно использовать с произвольным количеством аргументов.

$strchr(s,c)

Ищет первое вхождение символа c строке s.

Пример: $strchr(abca,a) -> 1

$strrchr(s,c)

Ищет последнее вхождение символа c в строке s.

Пример: $strrchr(abca,a) -> 4

$strstr(s1,s2)

Ищет первое вхождение строки s2 в строке s1.

$strcmp(s1,s2)

Выполняет регистрозависимое сравнение строк s1 и s2.

$stricmp(s1,s2)

Выполняет регистронезависимое сравнение строк s1 и s2.

$substr(s,m,n)

Возвращает подстроку строки s, начиная с m-го символа т заканчивая n-ым символом.

$trim(s)

Удаляет ведущие и завершающие пробелы из строки s.

$tab()

Вставляет один символ табуляции.

$tab(n)

Вставляет n символов табуляции.

$upper(s)

Приводит строку s к верхнему регистру.

Информация о треке

Метаданные

$meta(имя)

Возвращает значение тега с именем имя. Если существуют несколько тегов с этим именем, они объединяются с использованием "," в качестве разделителя.

Пример: $meta(artist) -> "He, She, It"

$meta(имя,n)

Возвращает значение n-го тега с именем имя.

Пример: $meta(artist,2) -> "She"

$meta_sep(имя,разделитель)

Возвращает значение тега с именем имя. Если существуют несколько тегов с этим именем, они объединяются с использованием разделитель в качестве разделителя.

Пример: $meta_sep(artist,' + ') -> "He + She + It"

$meta_sep(имя,разделитель,последний_разделитель)

Возвращает значение тега с именем имя. Если существуют несколько тегов с этим именем, они объединяются с использованием разделитель в качестве разделителя между ними, исключая последние два значения, которые разделяются последний_разделитель.

Пример: $meta_sep(artist,', ',' and ') -> "He, She and It"

$meta_test(...)

Возвращает истина, если все теги, имена которых были переданы в качестве параметров, существуют.

Пример: $meta_test(artist,title) -> true

$meta_num(имя)

Возвращает количество тегов с именем имя.

Пример: $meta_num(artist) -> 3

$tracknumber()

Возвращает номер трека, дополненный нулями до 2 цифр.

$tracknumber(n)

Возвращает номер трека, дополненный нулями до n цифр.

Техническая информация

$info(имя)

Возвращает значение поля технической информации с именем имя.

Пример: $info(channels) -> 2

$codec()

Возвращает кодек трека. Если поле codec отсутствует, используется расширение файла.

Пример: $codec() -> "WavPack"

$channels()

Возвращает число каналов в виде текста.

Пример: $channels() -> "stereo"

%__replaygain_album_gain%

Возвращает значение ReplayGain gain альбома.

%__replaygain_album_peak%

Возвращает значение ReplayGain peak альбома.

%__replaygain_track_gain%

Возвращает значение ReplayGain gain трека.

%__replaygain_track_peak%

Возвращает значение ReplayGain peak трека.

Специальные поля

$extra(имя)

Возвращает значение специального поля с именем name. Эти поля также доступны посредством %_имя%; обратите внимание на дополнительный знак подчёркивания. Можно использовать следующие имена полей:

filename

Возвращает имя файла без имени каталога и расширения.

filename_ext

Возвращает имя файла c расширением, но без имени каталога.

directoryname

Возвращает только имя родительского каталога, но не полный путь.

path

Возвращает путь.

path_raw

Возвращает путь как URL, включая тип протокола.

subsong

Возвращает номер подкомпозиции. Номер подкомпозиции используется для отличия множества треков в одном файле, например, в cue sheet, трекерных модулях и различных форматах контейнеров.

foobar2000_version

Возвращает строку, сообщающую версию foobar2000.

length

Возвращает длину трека в формате часы, минуты, секунды.

length_ex

Возвращает длину трека в формате часы, минуты, секунды и миллисекунды.

length_seconds

Возвращает длину трека в секундах.

length_seconds_fp

Возвращает длину трека в секундах в виде числа с плавающей точкой.

length_samples

Возвращает длину трека в сэмплах.

Операции с переменными

Переменные используются для хранения строк и чисел. Они не могут хранить логические значения. Переменные отлично подходят для сохранения промежуточных результатов, которые потребуются несколько раз. Имена переменных регистронезависимы.

$get(имя)

Возвращает значение, которое было последним сохранено в переменной имя. Если переменная не определена, ничего не возвращается. Логическое значение, возвращаемое $get показывает, существует ли переменная с именем имя.

$put(имя,значение)

Сохраняет значение в переменной с именем имя и возвращает значение неизменённым.

$puts(имя,значение)

Сохраняет значение в переменной с именем имя и возвращает только логическое значение.

Поля и функции, предоставляемые компонентами для треков

В этом разделе перечисляются компоненты, которые предоставляют поля и функции, доступные в контексте любого трека.

Статистика проигрывания (playback statistics)

Поля и функции, специфичные для компонентов

В этом разделе перечисляются компоненты, предоставляющие поля и функции, доступные только в контексте самого компонента

Список альбомов (album list)

Официальный компонент списка альбомов поддерживает создание различных элементов дерева с использованием специальных команд.

Columns UI

Оригинал описания

Данный документ является переводом Foobar2000:Titleformat Reference.