Про 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