## Справочник синтаксиса

### Основные значения

Синтаксис | Описание
--- | ---
%title% | Название трека. Если тег "title" отсутствует, используется имя файла.
%artist% | Исполнитель. Проверяется след. теги в таком порядке: "artist", "album artist", "composer", "performer".
%album artist% | Исполнитель альбома. Проверяется след. теги в таком порядке: "album artist", "artist", "composer", "performer". Разница от %artist% в том, что %album artist% используется как общий исполнитель для всего альбома, тогда как %artist% отдельно для каждого трека. Примечание переводчика: у многих начинающих пользователей возникают проблемы с сортировкой в сборниках из-за неправильного использования этого поля. В большинстве случаев нужно просто указать "VA" или "Various Artist".
%track artist% | Исполнитель трека. Присутствует только в случае, если %album artist% отличается от %artist% для конкретного трека. Пример: %album artist% - %title%[ '//' %track artist%] – в этом случае, последняя часть будет отображена только если тег %track artist% присутствует.
%album% | Название альбома. Проверяется след. теги в таком порядке: "album", "venue".
%date% | Год выпуска альбома. Используется аналогичный тег.
%genre% | Жанр альбома. Используется аналогичный тег.
%tracknumber% | Двузначный порядковый номер трека в альбоме. Используется аналогичный тег.
%totaltracks% | Общее количество треков в альбоме. Используется аналогичный тег.
%discnumber% | Номер диска. Используется тег "discnumber" или "disc".
%totaldiscs% | Общее количество дисков альбома. Используется аналогичный тег.
%codec% | Название кодека используемого для декодирования трека. В случае отсутствия используется расширение файла.
%codec_profile% | Дополнительная информация о настройках декодирования. Не всегда доступно.
%filename% | Имя файла без пути к каталогу и расширения.
%filename_ext% | Название файла, включая расширение, но исключая путь к каталогу.
%directoryname% | Название каталога в котором расположен файл.
%path% | Полный путь к файлу. Учтите, что для сортировки нужно использовать %path_sort%.
%subsong% | Позиция трека. Используется в форматах, которые поддерживают несколько дорожек в пределах одного физического файла (например, cuesheet).
%path_sort% | Путь к файлу. Используется в сортировке для сохранения порядка индексов внутри файла; точное значение возвращается не определено, так что не стоит на него полагаться.
%length% | Длина трека в формате [ЧЧ:]ММ:СС.
%length_seconds% | Длина трека в секундах, в формате целого числа.
%bitrate% | Битрейт трека в килобитах на секунду включая динамический VBR-битрейт для текущего трека.
%channels% | Количество каналов в треке (моно / стерео / и т.д.).
%samplerate% | Частота дискретизации (частота семплирования) в Гц.
%replaygain_track_gain%, %replaygain_album_gain%, %replaygain_track_peak%, %replaygain_album_peak% | Информация о ReplayGain.
%filesize% | Размер файла в байтах.
%filesize_natural% | Размер файла, автоматически отформатированный в соответствующих единицах, таких как мегабайты или килобайты.
%last_modified% | Время последнего изменения файла в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС.

Кроме приведенных выше, есть и другие значения, например, %field% — <имя тега> и %__field% — <тех.инфо.> для переназначения технической информации и обеспечении обратной совместимости.

### Контекстно-зависимые

Синтаксис | Описание
--- | ---
%list_index% | Позиция элемента в списке, которому он принадлежит. Используется в плейлисте, списках элементов обрабатываемых Мasstagger, File Operations и т.п. Начинается с нулей, количество которых зависит от максимального индекса в списке.
%list_total% | Общее количество элементов в списке. Используется в плейлисте, списках элементов обрабатываемых Мasstagger, File Operations и т.п.
%isplaying% | Присутствует, если например, текущий трек в плейлисте воспроизводится и отсутствует в противном случае. Подразумевает использование с $if().
%ispaused% | Присутствует, если например, текущий трек в плейлисте приостановлен и отсутствует в противном случае. Подразумевает использование с $if().
%playback_time% | Текущее время воспроизведения в формате [ЧЧ:]MM:СС. Доступно только там, где разрешен вывод динамических значений, например, строка состояния.
%playback_time_seconds% | Текущее время воспроизведения в секундах, в формате целого числа. Доступно только там, где разрешен вывод динамических значений, например, строка состояния.
%playback_time_remaining% | Оставшееся время воспроизведения в формате [ЧЧ:]MM:СС. Доступно только там, где разрешен вывод динамических значений, например, строка состояния. Недоступно, если продолжительность проигрываемой композиции не известна.
%playback_time_remaining_seconds% | Оставшееся время воспроизведения в секундах, в формате целого числа. Доступно только там, где разрешен вывод динамических значений, например, строка состояния. Недоступно, если продолжительность проигрываемой композиции не известна.
%queue_index% | Позиция текущего трека в очереди проигрывания. Доступно только в плейлисте. Если трек занесен в очередь несколько раз, учитывается только первая позиция.
%queue_indexes% | Список позиций текущего трека в очереди проигрывания. Доступно только в плейлисте.
%queue_total% | Общее количество треков в очереди воспроизведения. По техническим причинам доступно только для треков в очереди.

### Плагин статистики

Синтаксис | Описание
--- | ---
%first_played% | Дата и время, когда трек был проигран первый раз.
%last_played% | Дата и время, когда трек был проигран последний раз.
%play_count% | Сколько раз трек был проигран.
%played_per_day% | Сколько раз в день трек был проигран, расчёт ведется на основе данных, когда был проигранный трек первый и последний раз, и сколько раз.
%added% | Дата и время, когда трек был добавлен в библиотеку.
%rating% | Рейтинг трека, от 1 до 5.
%rating_stars% | Рейтинг трека, в формате до пяти звёзд.
%rating_stars_fixed% | Рейтинг трека, в формате пять звёзд.

### Функции

Синтаксис | Описание | Пример
--- | --- | ---
$abbr(X) | Возвращает аббревиатуру X. | $abbr(%album%)
$abbr(X,Y) | Возвращает аббревиатуру X, если X больше, чем Y-символов, иначе – оставляет как есть. | $abbr(%album%,5)
$ansi(X) | Возвращает X со всеми символами, которых нет в текущей кодировке, заменяя отсутствующие значения похожими. Полезно при работе с другими программами, которые не поддерживают юникод. | $ansi(%title%), $ansi(%filename%)
$ascii(X) | Возвращает X со всеми не-ASCII символами, заменяя отсутствующие значения ASCII-похожими. Полезно при работе с другими программами, которые не поддерживают юникод. | $ascii(%title%), $ascii(%filename%)
$lower(X), $upper(X) | Преобразовывает X к верхнему или нижнему регистру. | $upper(%title%)
$num(X,Y) | Отображает X как число начинающиеся нулями, количество которых определяет Y (полезно для номера трека и т.д.). | $num(%tracknumber%,3)
$caps(X) | Преобразовывает первую букву в каждом слове X в верхний регистр, а все остальные буквы в нижний. Пример: "blah BLAH" в "Blah Blah". | $caps(%title%)
$caps2(X) | Тоже что и $caps(X), но не затрагивает заглавные буквы. Пример: "blah BLAH" в "Blah BLAH". | $caps2(%title%)
$if(X,Y,Z) | Если X содержит хотя бы одно значение, выполняет/отображает Y, иначе – Z. | $if(%artist%,%artist%,unknown artist)
$if2(X,Y) | Тоже что и $if(X,X,Y). |
$if3(X,Y,Z,..) | Возвращает первый из параметров, который содержит хотя бы одно значение. |
$ifgreater(A,B,C,D) | Если число А больше, чем число B, выполняет/отображает С, иначе – D. |
$iflonger(A,B,C,D) | Если в строке A больше символов чем в B, выполняет/отображает С, иначе – D. |
$ifequal(A,B,C,D) | Если число А равно числу B, выполняет/отображает С, иначе – D. |
$longest(A,B,C,….) | Сравнивает длину А, B, C,... и возвращает самую длинную. | $longest(%title%,%filename%)
$len(X) | Возвращает длину строки X в символах. |
$pad(X,Y), $pad_right(X,Y) | Дополняет Х пробелами, количество которых определяет Y. |
$pad(X,Y,Z), $pad_right(X,Y,Z) | Дополняет Х символом Z, количество которого определяет Y. |
$cut(X,Y) | Усекает X до Y-символов. |
$padcut(X,Y), $padcut_right(X,Y) | Дополняет Х до Y-символов, и усекает до Y если X больше. |
$insert(A,B,N) | Вставляет строку B в строку А после N-символов. |
$add(X,Y), $sub(X,Y), $mul(X,Y), $div(X,Y), $mod(X,Y), $min(X,Y), $max(X,Y) | Различные математические операции. |
$left(X,Y) | Возвращает первые Y символов строки X. |
$right(X,Y) | Возвращает последние Y символов строки X. |
$and(X,Y), $or(X,Y), $xor(X,Y), $not(X) | Различные логические операции для использования с $if(). |
$fix_eol(x), $fix_eol(x,y) | Усекает многострочный вывод добавляя " (...)" (вариант 1) или Y (вариант 2) в конец. |
$meta(X) | Возвращает значение тега X. | $meta(artist)
$meta_sep(X,Y), $meta_sep(X,Y,Z) | Возвращает значение тега X с произвольными разделителями для нескольких значений. | $meta(artist,', ',' and ') -> “artist1, artist2 and artist3”
$meta_num(X) | Возвращает число текущего значения тега X.
$info(X) | Возвращает техническую инфо. тега X. | $info(bitrate)
$char(X) | Вставляет юникодный символ №Х. | $char(9674)
$strcmp(X,Y) | Возвращает "1", если строки X и Y идентичны, иначе – пустую строку; предназначен для использования с $if(). |
$stricmp(X,Y) | Не регистрозависимый вариант $strcmp(X,Y). |
$directory(X), $directory(X,N) | Извлекает имя каталога (по %path%) файла Х, опционально может брать на N-каталог выше. | $directory(%path%,2)
$directory_path(X) | Полный путь к каталогу файла Х. | $directory_path(%path%)
$greater(X,Y) | Сравнивает два целых числа; для использования с $if() и другими логичесими операторами. |
$longer(X,Y) | Сравнивает две строки; для использования с $if() и другими логичесими операторами. |
$strchr(X,Y) | Находит первое вхождение символа Y в строке X. |
$strrchr(X,Y) | Находит последнее вхождение символа Y в строке X. |
$strstr(X,Y) | Находит первое вхождение строки Y в строке X. |
$select(N,A,B,C,….) | Отображает A,B,C,... в N-строк. |
$repeat(X,N) | Повторяет X N-раз. |
$replace(A,B,C) | Заменяет все вхождения строки B в строку А строкой C. |
$ext(X) | Извлекает расширения файла из пути или имени файла. | $ext(%path%)
$substr(A,B,C) | Возвращает подстроку строки А, начиная с B-го символа и заканчивается в C-тым. | $substr(blah,1,2) -> “bl”
$trim(A) | Отсекает пробелы в начале\конце А. | $trim(%title%)
$tab() | Символ табуляции; аналогично $char(9). См. подробное описание в разделе Другое. | $tab()
$stripprefix(X) | Удаляет префикс "А" и "The" из X. | $stripprefix(%artist%) -> “The Prodigy” becomes “Prodigy”
$stripprefix(X,prefix1,prefix2,…) | Удаляет произвольный префикс из X. | $stripprefix(%artist%,a,the) -> “The Prodigy” becomes “Prodigy”
$swapprefix(X) | Переносит префикс "А" и "The" в конец Х. | $swapprefix(%artist%) -> “The Prodigy” becomes “Prodigy, The”
$swapprefix(X,prefix1,prefix2,…) | Переносит произвольный префикс в конец Х. | $swapprefix(%artist%,a,the) -> “The Prodigy” becomes “Prodigy, The”

$year(time) | Извлекает только год (4 цифри) из времени/даты. | $year(%last_modified%)
$month(time) | Извлекает только месяц (2 цифри) из времени/даты. | $month(%last_modified%)
$day_of_month(time) | Извлекает только день (2 цифри) из времени/даты. | $day_of_month(%last_modified%)
$date(time) | Извлекает дату (ГГГГ-ММ-ДД) из времени/даты. | $date(%last_modified%)
$time(time) | Извлекает время ([ЧЧ:]ММ:СС) из времени/даты. | $time(%last_modified%)

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

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

Синтаксис | Описание | Пример
--- | --- | ---
$put(name,text) | Объявляет переменную name как text и возвращает text. | “$put(x,blah)” sets variable x to “blah” and returns “blah”.
$puts(name,text) | Тихий вариант: тоже что и $put(name,text), но возвращает пустую строку. |
$get(name) | Возвращает значение переменной name, если такая была объявлена, иначе – пустую строку. | “$puts(x,blah)$get(x)$get(x)” returns “blahblah”

### Other

Синтаксис | Описание | Пример
--- | --- | ---
[ …. ] | Не учитывает содержание внутри квадратных скобок, если отсутствуют значения. Обычно используется для значений, которые не всегда доступны. | %artist% - [%album% / ]%title%
' (одинарная кавычка) | Позволяет использовать произвольный текст (например, %,$,[,]) в обход синтаксиса. Для того, что бы вставить двойные кавычки используйте две одинарная кавычки. |
// | Комментарий; может быть размещен только в начале новой строки. Разрешено использовать любые символы до окончания строки. |
Символ перевода строки | Игнорируется; используется чтобы сделать скрипт более читабельным. |
Символ табуляции | Используется для выравнивания текста там, где это разрешено, например, строка состояния. См. также: $tab(). | %title%$tab()%length%
Управление цветом: < > | Используется для затемнения или подсветки текста; доступно в плейлисте и строке состояния. Есть три уровня для затемнения и подсветки, которые достигаются повтором символов управления цветом. | <dim> >highlight< >>extrahighlight<<