ASCII Synthesizer

ASCII Synthesizer is a macOS-first creative utility for turning images, videos, and ordered frame folders into authentic fixed-grid ASCII art. It is local, deterministic, and does not require AI to convert media.

What It Does

• Imports still images, video files, or folders of ordered frames.
• Converts frames into a stable ASCII grid using luminance, alpha, contrast, edge direction, and background subtraction.
• Preserves the thing that makes ASCII feel real: explicit columns, rows, FPS, glyph ramps, and cell-grid fidelity.
• Provides a SwiftUI preview app with import, render, preview, export, and terminal workflow pages.
• Exports .txt, .json, .js, and self-contained .html previews.
• Includes a CLI so batch rendering can be scripted.
• Can generate Claude/Codex-friendly terminal commands, but the renderer itself is not AI-dependent.

Privacy And Security

• Conversion runs locally on macOS.
• No API keys are required.
• No network calls are used for rendering or exporting.
• Imported media stays on your machine unless you manually upload exported files somewhere else.
• The terminal companion only generates local shell commands from the settings currently visible in the app.

App Icon

The app icon is generated from scripts/make_icon.sh and packaged into a real macOS .icns file.

Requirements

• macOS 14 or newer
• Swift 6 toolchain
• ImageMagick for icon generation when packaging from source

Runtime conversion uses Apple frameworks already on macOS:

• SwiftUI
• AppKit
• AVFoundation
• CoreGraphics
• ImageIO

Install From Release Zip

After a release is built, unzip:

release/ASCII-Synthesizer-macOS-v0.1.0.zip

Then move ASCII Synthesizer.app into /Applications or open it from the unzipped folder.

Current local builds are ad-hoc signed, not Apple Developer ID notarized. On a fresh Mac, Gatekeeper may require right-clicking the app and choosing Open.

Build And Run From Source

git clone <your-repo-url>
cd "ASCII-Synthesizer"
./scripts/build_and_run.sh

The script builds the Swift package, stages a macOS .app bundle in dist/, adds the generated icon, ad-hoc signs it, and opens the app.

Package A Local Release

./scripts/package_release.sh

Outputs:

• dist/ASCII Synthesizer.app
• release/ASCII-Synthesizer-macOS-v0.1.0.zip
• release/ascii-synth

CLI

swift run ascii-synth render \
  --input /path/to/media-or-frames \
  --out /path/to/ascii-frames.js \
  --cols 104 \
  --rows 142 \
  --fps 10 \
  --frame-step 4 \
  --preset paper-print \
  --format js

Supported formats:

• txt: one ASCII frame
• json: full AsciiSequence
• js: browser-ready window.ASCII_ANIMATION_FRAMES payload
• html: self-contained animated preview

Presets

• paper-print: high fidelity for pale paper, book covers, and printed looks
• terminal: compact terminal-friendly conversion
• poster: larger high-contrast output
• dense: expanded glyph ramp for detailed art
• edge-outline: stronger structural edge rendering

Package Structure

Sources/
  AsciiSynthCore/          Shared deterministic renderer
  ascii-synth/             CLI executable
  AsciiSynthesizerApp/     SwiftUI macOS app
scripts/
  build_and_run.sh         Debug app bundle launcher
  make_icon.sh             Generates AppIcon.icns
  package_release.sh       Release app bundle + zip
docs/
  method.md                Rendering method notes
  install-codex-claude.md  Optional agent workflow install notes
skills/
  ascii-animation-pipeline Portable Codex/Claude skill

Renderer Model

The core renderer produces:

struct AsciiSequence {
    let cols: Int
    let rows: Int
    let fps: Double
    let glyphs: String
    let frames: [String]
}

Each frame is a fixed-size grid. Every cell samples the underlying media, calculates alpha/luminance/edge signal, maps that signal to glyphs, and writes the result into a stable ASCII framebuffer.

Tests

swift test

The current suite checks:

• transparent inputs stay blank
• noisy paper backgrounds do not become glyph wallpaper
• high-contrast shapes produce stable silhouettes
• edge glyphs follow contours
• frame sequences change over time

Terminal Companion

The app can open Terminal, iTerm2, Warp, or the system default terminal with the exact ascii-synth command generated from current UI settings. Claude Code and Codex workflows are optional sidecars, not conversion dependencies.

License

MIT