ASCII Art Converter
Setup
Before first use, run the environment setup (idempotent, <1s after first run):
bash {{SKILL_DIR}}/scripts/setup.sh
Input Detection
- File path → check extension:
.jpg/.jpeg/.png/.webp/.bmp/.tiff → image, .mp4/.webm/.avi/.mov/.mkv → video, .gif → check if animated (video) or static (image)
- Pasted/attached image → save IMMEDIATELY before doing anything else. Run:
{{SKILL_DIR}}/scripts/.venv/bin/python {{SKILL_DIR}}/scripts/save_image.py --clipboard
This grabs the image from the system clipboard (still there after paste), saves to ascii/tmp/ with a timestamped name, and prints the saved path to stdout. Use that output path as --input.
If --clipboard fails (no image in clipboard), fall back to asking: "Please provide the file path (e.g. ~/Downloads/photo.jpg)." You can also pass a known file path directly: save_image.py <path>.
Do NOT proceed to options until you have a valid file path on disk.
- Plain text (no file, or file doesn't exist) → text (FIGlet banner)
- Nothing provided → ask what they want to convert
Options Prompt
Parse the user's message for pre-specified options. Then prompt for unspecified options using AskUserQuestion.
- "defaults" or "just do it" → skip prompting, use all defaults
- "random" or "surprise me" → skip prompting, use
--random
- All options specified → skip prompting
Use questions array (max 4 per call, 3 options per question). List ALL choices with numbers in the question text. Top 3 as selectable options — user can type any number/name in free-text. No "Other" option. Default as option 1.
Image/video — ask in two rounds:
- Round 1 (4 questions): Style → Color → Export → Background
- Round 2 (only if export is
interactive or tsx): Mouse Mode → Animation
Text: Font → Color → Export → Background (single round).
Image/video options
| Option |
Choices |
Default |
| Style |
classic, braille, block, edge, dot-cross, halftone, particles, retro-art, terminal |
classic |
| Color |
grayscale, original, matrix, amber, custom (hex/named) |
grayscale |
| Ratio |
original, 16:9, 4:3, 1:1, 3:4, 9:16 |
original |
| Background |
dark, light, transparent |
dark |
| Dither |
none, floyd-steinberg, bayer, atkinson |
none |
| Font size |
6-30 px |
14 |
| Export |
png, html, svg, txt, md, clipboard, interactive, tsx |
auto (image→png, video→gif) |
| Mouse mode |
push, attract |
push |
| Animation |
none, noise-field, intervals, beam-sweep, glitch, crt |
none |
Mouse mode and animation only apply to interactive/tsx exports. Only ask when export is interactive or tsx. Don't ask for --hover-strength, --area-size, or --spread — use defaults.
Text options
| Option |
Choices |
Default |
| Font |
standard, doom, banner, slant, big, small, block, lean, mini, script, shadow, speed, ansi_shadow, ansi_regular |
standard |
| Color |
grayscale, original, matrix, amber, custom |
grayscale |
| Background |
dark, light, transparent |
dark |
| Export |
terminal (stdout), txt, md, png, html, svg, clipboard |
terminal |
Interactive/tsx exports require image or video input — text is not supported.
Disambiguation
- "block" as a style = Unicode block elements (█▓▒░) for images
- "block" as a font = block-letter FIGlet font for text
- For block-style text art, use
--font ansi_shadow or --font block
- Custom colors: hex (
#ff6600) or named (coral, skyblue). Translate creative descriptions to hex.
Running the Conversion
{{SKILL_DIR}}/scripts/.venv/bin/python {{SKILL_DIR}}/scripts/convert.py \
--input "<input>" \
--type <text|image|video> \
--style <style> \
--color <color> \
--background <background> \
--export <format> \
[--dither <algorithm>] \
[--ratio <ratio>] \
[--font-size <pixels>] \
[--cols <number>] \
[--font <font_name>] \
[--custom-color "<hex>"] \
[--mouse-mode <push|attract>] \
[--animation <preset>] \
[--invert] [--random] \
[--fps <number>] \
[--filename <custom_name>]
Output
All files save to an ascii/ folder in the current working directory (created automatically).
- Text (terminal): prints to stdout + auto-copies to clipboard. Show in a code block.
- File exports (png, html, svg, txt, md, gif): show the file path. Use Read tool to display images inline.
- Interactive HTML: show the file path. Suggest:
open <path> to view in browser.
- React TSX: show the file path. Show usage:
import { AsciiArt } from './<filename>'
- Never preview in terminal for image/video/interactive exports.
Error Handling
- Video fails: likely missing ffmpeg or opencv. Suggest:
pip install opencv-python-headless
- Image fails: check file exists and is a valid image format
- Interactive/tsx + text: prints error — interactive requires image/video input
Follow-up
After showing the result, offer to: try a different style/color, adjust settings, export in another format, or try random mode. Remember the previous input path for re-runs.
1---2name: ascii-art3description: Converts text, images, or video to ASCII art with multiple styles and export formats. Use when the user asks to create ASCII art, convert images/videos to text art, or mentions ascii-art, braille art, or block art.4---56# ASCII Art Converter78## Setup910Before first use, run the environment setup (idempotent, <1s after first run):1112```bash13bash {{SKILL_DIR}}/scripts/setup.sh14```1516## Input Detection17181. **File path** → check extension: `.jpg/.jpeg/.png/.webp/.bmp/.tiff` → **image**, `.mp4/.webm/.avi/.mov/.mkv` → **video**, `.gif` → check if animated (video) or static (image)192. **Pasted/attached image** → **save IMMEDIATELY** before doing anything else. Run:20 ```bash21 {{SKILL_DIR}}/scripts/.venv/bin/python {{SKILL_DIR}}/scripts/save_image.py --clipboard22 ```23 This grabs the image from the system clipboard (still there after paste), saves to `ascii/tmp/` with a timestamped name, and prints the saved path to stdout. Use that output path as `--input`.24 If `--clipboard` fails (no image in clipboard), fall back to asking: "Please provide the file path (e.g. `~/Downloads/photo.jpg`)." You can also pass a known file path directly: `save_image.py <path>`.25 **Do NOT proceed to options until you have a valid file path on disk.**263. **Plain text** (no file, or file doesn't exist) → **text** (FIGlet banner)274. **Nothing provided** → ask what they want to convert2829## Options Prompt3031Parse the user's message for pre-specified options. Then prompt for **unspecified options** using `AskUserQuestion`.3233- "defaults" or "just do it" → skip prompting, use all defaults34- "random" or "surprise me" → skip prompting, use `--random`35- All options specified → skip prompting3637Use `questions` array (max 4 per call, 3 options per question). List ALL choices with numbers in the `question` text. Top 3 as selectable options — user can type any number/name in free-text. No "Other" option. Default as option 1.3839**Image/video** — ask in two rounds:401. **Round 1** (4 questions): Style → Color → Export → Background412. **Round 2** (only if export is `interactive` or `tsx`): Mouse Mode → Animation4243**Text**: Font → Color → Export → Background (single round).4445### Image/video options4647| Option | Choices | Default |48|--------|---------|---------|49| Style | classic, braille, block, edge, dot-cross, halftone, particles, retro-art, terminal | classic |50| Color | grayscale, original, matrix, amber, custom (hex/named) | grayscale |51| Ratio | original, 16:9, 4:3, 1:1, 3:4, 9:16 | original |52| Background | dark, light, transparent | dark |53| Dither | none, floyd-steinberg, bayer, atkinson | none |54| Font size | 6-30 px | 14 |55| Export | png, html, svg, txt, md, clipboard, interactive, tsx | auto (image→png, video→gif) |56| Mouse mode | push, attract | push |57| Animation | none, noise-field, intervals, beam-sweep, glitch, crt | none |5859Mouse mode and animation only apply to interactive/tsx exports. Only ask when export is `interactive` or `tsx`. Don't ask for `--hover-strength`, `--area-size`, or `--spread` — use defaults.6061### Text options6263| Option | Choices | Default |64|--------|---------|---------|65| Font | standard, doom, banner, slant, big, small, block, lean, mini, script, shadow, speed, ansi_shadow, ansi_regular | standard |66| Color | grayscale, original, matrix, amber, custom | grayscale |67| Background | dark, light, transparent | dark |68| Export | terminal (stdout), txt, md, png, html, svg, clipboard | terminal |6970Interactive/tsx exports require image or video input — text is not supported.7172### Disambiguation7374- "block" as a **style** = Unicode block elements (█▓▒░) for images75- "block" as a **font** = block-letter FIGlet font for text76- For block-style text art, use `--font ansi_shadow` or `--font block`77- Custom colors: hex (`#ff6600`) or named (`coral`, `skyblue`). Translate creative descriptions to hex.7879## Running the Conversion8081```bash82{{SKILL_DIR}}/scripts/.venv/bin/python {{SKILL_DIR}}/scripts/convert.py \83 --input "<input>" \84 --type <text|image|video> \85 --style <style> \86 --color <color> \87 --background <background> \88 --export <format> \89 [--dither <algorithm>] \90 [--ratio <ratio>] \91 [--font-size <pixels>] \92 [--cols <number>] \93 [--font <font_name>] \94 [--custom-color "<hex>"] \95 [--mouse-mode <push|attract>] \96 [--animation <preset>] \97 [--invert] [--random] \98 [--fps <number>] \99 [--filename <custom_name>]100```101102## Output103104All files save to an `ascii/` folder in the current working directory (created automatically).105106- **Text (terminal)**: prints to stdout + auto-copies to clipboard. Show in a code block.107- **File exports (png, html, svg, txt, md, gif)**: show the file path. Use Read tool to display images inline.108- **Interactive HTML**: show the file path. Suggest: `open <path>` to view in browser.109- **React TSX**: show the file path. Show usage: `import { AsciiArt } from './<filename>'`110- **Never preview in terminal** for image/video/interactive exports.111112## Error Handling113114- **Video fails**: likely missing ffmpeg or opencv. Suggest: `pip install opencv-python-headless`115- **Image fails**: check file exists and is a valid image format116- **Interactive/tsx + text**: prints error — interactive requires image/video input117118## Follow-up119120After showing the result, offer to: try a different style/color, adjust settings, export in another format, or try random mode. Remember the previous input path for re-runs.
neethanwu