Про ASCII-арт на хабре скорее всего знают большинство, да и писали тут о нем неоднократно, но давайте дежурно. ASCII-арт это способ рисовать обычным текстом. Вместо пикселей здесь символы, вместо графического редактора - любой текстовый редактор, а вместо программы для просотра - cat и терминал.
/\_/\ ( o.o ) > ^ <
Исторически под ASCII-артом часто понимают вообще любое текстовое искусство, даже если оно давно вышло за пределы собственно ASCII и использует Unicode, ANSI-цвета, псевдографику, Braille-символы, управляющие последовательности терминала итд. В этой статье я тоже буду использовать термин в широком смысле: изображение или анимация, которую можно хранить, редактировать и показывать как текст.
Зачем очередной формат
Лет пять назад, еще до того как у меня окончательно выветрился интерес к кастомизации вненего вида ОС, я хотел непременно прикрутить анимированное ASCII-лого своего дистрибутива в neofetch ради красивых гифок для r/unixporn.
Я уже видел примеры анимированных фетчей и по какой-то причине полагал, что для такого существует некоторый распространенный формат.
Как выяснилось, ничего такого не было (на самом деле таки было, но об этом в конце). Те примеры, которые я находил, чаще всего оказывались кастомными скриптами с захардкоженными строками с ANSI цветами и sleep между кадрами. Никакого “стандарта” не было.
Ну а раз нет, значит надо сделать. Так и появился Animated ASCII Art.
Характерным отличием 3a от plaintext файла с ANSI кодами является то, что он сохраняет форматирование и в текстовом редакторе арт выглядит также как и отрендеренная анимация что позволяет так и работать без нужды в специфическом редакторе вроде DurDraw.
Долгое время проект существовал в виде неоднозначного описания формата, минимальной реализации без особых фич и буквально пары артов ради которых сабж и создавался.
Недавно я все это наконец причесал: переписал спецификацию, довел cli-тулу до более человеческого состояния, вынес библиотеки, добавил конвертацию в разные форматы и организовал мини коллекцию ASCII анимаций с открытыми лиензиями.
Структура файла
Файл 3a состоит из блоков. Каждый блок начинается со строки с именем блока, начинающейся с @. Первый блок всегда @3a; это заголовок с метаданными. Основной блок с кадрами называется @body.
Минимальный файл без цветов и метаданных может выглядеть так:
@3a @body <=>\ ,..\\.., ' // ' | | | | '.__.~._.'
Если кадров несколько, они разделяются пустыми строками:
@3a title just an apple delay 300 loop yes @body <=>\ ,..\\.., ' // ' | | | | '.__.~._.' <=>\ ,..\\.., ' //,_.--' | / { | \_,''-. '.__.~._.' <=>\ ,..\\.., ',--,_.--' } { ,-,_,''-. '.__.~._.'
В заголовке здесь появилось несколько полей:
title- название арта;delay- задержка между кадрами в миллисекундах;loop- нужно ли зацикливать анимацию.
Если delay не указан, используется по умолчанию 50 мс. Если loop не указан, анимация считается зацикленной. То есть простые арты можно не раздувать метаданными без необходимости.
Помимо этого в заголовке можно указывать авторов, оригинального автора, ссылку на источник, лицензию, редактор, preview-кадр, теги итд. Например:
@3a title just an apple author ASCIIMoth license CC0-1.0 src https://github.com/asciimoth/openascii delay 300 loop yes preview 0 #apple #fruit #food
Комментарии в тех местах, где они разрешены, начинаются с ;; и занимают всю строку.
Цвета
Самая важная идея цветного 3a в том, что текст и цвета хранятся отдельными столбцами а не вперемешку. Вместо того чтобы вставлять ANSI коды прямо внутрь арта, рядом с каждой строкой текста пишется строка такой же длины, но состоящая из имен цветов.
@3a colors yes @body <=>\ 112228111111 ,..\\.., 111118811111 ' // ' 111991111111 | |111111111111 | |111111111111 '.__.~._.' 111111811111
Встроенные имена обозначают стандартные 4-bit ANSI цвета:
0 black 1 red 2 green 3 yellow 4 blue 5 magenta 6 cyan 7 white 8 bright black / gray 9 bright red a bright green b bright yellow c bright blue d bright magenta e bright cyan f bright white _ default (зависит от терминала)
Можно определять и свои цвета:
@3a colors yes col r fg:196 col l fg:bright-green col b fg:94
Цвет может быть ANSI-цветом по имени, 256-color кодом или RGB hex-значением. Для терминала это затем маппится в ANSI-последовательности, для SVG/PNG/GIF/WebP/MP4 — в соответствующее графическое представление.
Если цветовой канал одинаковый для всех кадров, его можно не повторять каждый раз. Для этого есть @color-pin блок, который задает однин “прикрепленный” кадр цветового канала для всей анимации. И наоборот, если текст один и тот же, а меняются только цвета, можно использовать @text-pin.
@3a title apple with pinned colors colors yes delay 300 @color-pin 112228111111 111118811111 111991111111 111111111111 111111111111 111111811111 @body <=>\ ,..\\.., ' // ' | | | | '.__.~._.' <=>\ ,..\\.., ' //,_.--' | / { | \_,''-. '.__.~._.' <=>\ ,..\\.., ',--,_.--' } { ,-,_,''-. '.__.~._.'
aaa
Основной инструмент для работы с 3a это cli утилита aaa.
На верхнем уровне у нее есть несколько групп команд:
list List builtin art gen Generate new art play Play art in terminal fetch Show system info side by side with animated logo preview Show art preview edit Editing subcommands convert Format conversion subcommands from-text Constructs art from plain text with ANSI color escape codes completions Generate shell completions
Чтобы просто проиграть .3a файл в терминале:
aaa play ./apple.3a
Если файл цветной, aaa преобразует цветовой канал в ANSI escape sequences уже на этапе вывода.
Чтобы показать preview (один из кадров; по умолчанию нулевой):
aaa preview apple.3a
Fetch, ради которого все и начиналось:
aaa fetch distro_nixos_big.3a
По умолчанию aaa пытается использовать один из уже установленных fetch-инструментов: neofetch, fastfetch, screenfetch, nitch, profetch, leaf, fetch-scm. Так что информация берется из привычного fetch-туллинга, а логотип - из 3a-файла.
Генерация и редактирование
Создать заготовку можно через gen:
aaa gen > apple.3a
Дальше файл можно открыть руками и дописать содержимое. Но часть операций можно делать через aaa edit (например из скрипта):
Установить название:
aaa edit ./apple.3a title "just an apple" > apple2.3a
Добавить тег:
aaa edit ./apple.3a tag-add apple fruit food > apple2.3a
Поменять лицензию:
aaa edit ./apple.3a license CC0-1.0 > apple2.3a
Помимо метаданных есть операции над кадрами: продублировать кадр, удалить, поменять местами, развернуть порядок кадров, вырезать диапазон, дедуплицировать повторяющиеся кадры, сдвинуть анимацию
Конвертация
Вторая большая часть функционала aaa - конвертация.
Список поддерживаемых направлений сейчас выглядит так:
to-frames ANSI-colored frames separated by blank lines to-cast asciicast v2 to-dur durdraw format to-json JSON document to-ttyrec ttyrec to-png PNG image to-gif GIF animation to-webp WebP animation to-mp4 MP4 video to-svg SVG animation to3a print art back in 3a format
Например, сделать GIF:
aaa convert apple.3a to-gif > apple.gif
Или asciinema cast:
aaa convert apple.3a to-cast > apple.cast asciinema play apple.cast
Отдельно полезна команда нормализации:
aaa convert apple.3a to3a > normalized.3a
Она читает файл и печатает его обратно в 3a-формате. Это удобно для проверки того, как файл понимается парсером, и для приведения артов к более единообразному виду.
Еще один практический сценарий - взять существующий арт с ANSI последовательностями и превратить его в 3a:
cat old-logo.txt | aaa from-text > logo.3a
вперед или назад итд.
Библиотеки
aaa построен поверх Rust-библиотеки rs3a. Она умеет читать и писать новый 3a-формат, частично читать легаси версию, редактировать арт программно и экспортировать его в SVG, asciicast v2 и плейнтекстом с ANSI кодами.
use rs3a::{Art, font::Font, CSSColorMap}; use std::fs::File; use std::io::Write; fn main() { let mut art = Art::from_file("./examples/dna.3a").unwrap(); let color_pair = "fg:black bg:yellow".parse().unwrap(); let color = art.search_or_create_color_map(color_pair); for frame in 0..art.frames() { art.print(frame, 0, 0, &format!("{}", frame), Some(Some(color))); } art.to_file("./examples/edited_dna.3a").unwrap(); let mut output = File::create("./examples/dna.svg").unwrap(); write!( output, "{}", art.to_svg_frames(&CSSColorMap::default(), &Font::default()) ).unwrap(); }
Также в наличии py3a и go3a, но они менее функциональные и по большей части только для парсинга.
OpenASCII
Последняя часть “экосистемы” - openascii. Это микро коллекция ASCII-арта (в основном моего) в 3a-формате под permissive или copyleft лицензиями c веб плеером на основе asciinema. Буду рад если что-то из этой коллекции пригодится вам в cli утилитах / ASCII играх / etc или у вас найдется чем ее пополнить.
Альтернативы
Постфактум я таки обнаружил что несколько других попыток сделать что-то похожее таки уже предпринимались, но либо решали не совсем ту же задачу, либо остались в зачаточном состоянии.
Из того, что стоит внимания - терминальный редактор ASCII анимаций DurDraw. У него имеется собственный формат (gzip’нутый json) и возможность использовать его во встроенном фетче. Тем не менее
формат имеет исключительно одну очень запутанную реализацию
документация формата противоречит de-facto реализации
Редактировть руками эту лапшу из вложенных json в обычном текстовом редакторе не многим проще чем “эталонный” плейнтекст+ANSI коды
Но все же, будь DurDraw в свое время чуть более известным и чуть менее багованным, может и не было бы 3a. Впрочем сейчас aaa поддерживает в том числе конвертацию между .3a и .dur
