Содержание

Справка по функциям и полям, используемым в скриптах Foobar2000 (TAGZ)

Справка по функциям и полям, используемым в скриптах Foobar2000 (TAGZ)

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

Ревизия 1.1

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

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

Метаданные

%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%

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

%track artist%

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

%title%

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

%track%

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

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

%tracknumber%

Эквивалентно предопределённому полю %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, пока не будет найден первый, вычисляемый как истина. Если это произошло, возвращается значение этого аргумента. В иных случаях возвращается значение вычисленной части иначе.

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

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

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

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

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

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

$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().

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

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

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

%playback_time%

Возвращает время, прошедшее с начала проигрывания в формате [ЧЧ:]ММ:СС.

%playback_time_seconds%

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

%playback_time_remaining%

Возвращает время, оставшееся до конца проигрывания песни, в фомате [ЧЧ:]ММ:СС. Прошлое название: %_time_remaining%

%playback_time_remaining_seconds%

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

%length%

Возвращает длительность песни в виде часов, минут, секунд. Прошлое название: %_time_total%

%length_ex%

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

%length_seconds%

Возвращает длительность песни в секундах. Прошлое название: %_time_total_seconds%

%length_seconds_fp%

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

%length_samples%

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

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

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

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

%isplaying%

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

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

%ispaused%

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

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

%list_index%

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

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

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

%list_total%

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

Старая версия %_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)

$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-го тега с именем имя (для первого тега n=0).

Пример: $meta(artist,1) → «She»

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

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

Пример: $meta_sep(artist,' + ') → «He + She + It»

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

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

Пример: $meta_sep(artist,', ',' and ') → «He, She and It»

$meta_test(...)

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

Пример: $meta_test(artist,title) → 1

$meta_num(имя)

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

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

$tracknumber()

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

$tracknumber(n)

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

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

$info(имя)

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

Для удобства доступен еще и псевдоним %__name%.

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

Информационный список полей. Некоторые из них зависят от запрашиваемого типа медиа файла.

Общие

Поле	Описание
codec	Кодек (например, MP3)
codec_profile	Профиль (например, CBR)
samplerate	Частота дискредитации, в герцах (например, 44100)
bitrate	Битрейт, в килобитах в секунду (например, 320)
tool	Утилита, с помощью которой создан файл (например, LAME3.97)
encoding	Тип кодирования (например, lossy)
channels	Количество каналов (например, 2 [для стерео])
bitspersample	Битов на семпл (например, 16)
tagtype	Тип тегов, разделенный список тегов (например, id3v2\|apev2)
cue_embedded	Наличие внедренного Cuesheet (например, нет [может быть пустым!])
md5	MD5-хэш файла, если определяется контейнером (например, 1E24A910D91EF09A8CF403C9B6963961)

Другие

Поле	Описание
ENC_DELAY	LAME MP3 значение enc_delay (например, 576)
ENC_PADDING	LAME MP3 значение enc_padding (например, 1536)
MP3_ACCURATE_LENGTH	mp3_accurate_length (частный заголовок LAME)? (например, да)
MP3_STEREO_MODE	Стерео режим в MP3 (например: mono, stereo, joint stereo)
VERSION	Версия утилиты (например, 3.99)
FLAGS	Флаги утилиты (например, 22)

$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. Эти поля также доступны посредством %_имя%; обратите внимание на дополнительный знак подчёркивания. Такой синтаксис использовался в старой версии Foobar2000 0.8x. Теперь можно просто использовать следующие имена полей:

%filename%

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

%filename_ext%

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

%directoryname%

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

%path%

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

%path_raw%

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

%subsong%

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

$extra(foobar2000_version)

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

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

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

Пример:

код	результат
$put(foo,bar)$char(10) $get(foo)$char(10) $get(Foo)$char(10) $puts(foo,2000)$char(10) $get(foo)$char(10)	bar bar bar 2000

$get(имя)

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

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

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

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

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

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

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

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

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

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

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

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

Columns UI

~~DISCUSSION~~