ttfx-js

Terminal text effects in your terminal, with zero setup. It started as TerminalTextEffects, a Python library for animating text; was ported to Rust as ttfx — a single ~2 MB static binary that starts in half a millisecond; and this package ships that binary prebuilt for Linux, macOS and Windows, so npm users get everything with no Rust, no Python, no compiler:

echo "hello" | npx ttfx-js decrypt

All 37 effects ride inside each binary — the JS here only picks the file for your OS/CPU and hands it your terminal, so speed, rendering and exit codes are identical to the native build.

Credit

Every effect, the animation engine and the command-line interface are the work of TerminalTextEffects by ChrisBuilds, via the ttfx Rust port (Windows support from this fork). This repository only packages their prebuilt binaries for npm — see THIRD-PARTY-NOTICES for the full attribution. If you like the effects, star the original.

Installation

npx ttfx-js decrypt            # no install at all, runs once (pipe text in)
npm i ttfx-js                  # local to a project, then npx ttfx-js ...
npm i -g ttfx-js               # global, adds the ttfx command everywhere

No postinstall build, no peer dependencies. The platform binary (~1 MB download) arrives as an optional dependency npm selects automatically.

Usage

<producer> | ttfx [terminal options] <effect> [effect options]

A few to try (same in PowerShell, cmd and bash):

echo "hello" | npx ttfx-js decrypt
echo "hello" | npx ttfx-js beams
git log --oneline -10 | npx ttfx-js matrix
echo "surprise me" | npx ttfx-js --random-effect
npx ttfx-js decrypt --help    # options for one effect

After a global install two commands exist and do the same thing — ttfx (matches the upstream docs) and ttfx-js (matches the package name):

echo "hello" | ttfx beams
echo "hello" | ttfx decrypt
git log --oneline -10 | ttfx matrix
echo "surprise me" | ttfx --random-effect
# ...or replace ttfx with ttfx-js in any of the above

npx ttfx-js --help prints all 37 effects and the terminal options:

Terminal text effects (Rust port of terminaltexteffects)

Usage: ttfx [OPTIONS] [COMMAND]

Commands:
  beams            Create beams which travel over the canvas illuminating the characters behind them
  binarypath       Binary representations of each character move towards the home coordinate of the character
  blackhole        Characters are consumed by a black hole and explode outwards
  bouncyballs      Characters are bouncy balls falling from the top of the canvas
  bubbles          Characters are formed into bubbles that float down and pop
  burn             Burns vertically in the canvas
  colorshift       Display a gradient that shifts colors across the terminal
  crumble          Characters lose color and crumble into dust, vacuumed up, and reformed
  decrypt          Display a movie style decryption effect
  ...
  waves            Waves travel across the terminal leaving behind the characters
  wipe             Wipes the text across the terminal to reveal characters

Options:
      --frame-rate <FRAME_RATE>  [default: 60]
      --canvas-width <CANVAS_WIDTH>  [default: -1]
      --canvas-height <CANVAS_HEIGHT>  [default: -1]
      --anchor-canvas <ANCHOR_CANVAS>  [default: sw]
      --anchor-text <ANCHOR_TEXT>  [default: sw]
      --seed <SEED>              Seed for the random number generator (deterministic within ttfx)
  -R, --random-effect            Run a random effect
  -h, --help                     Print help

(The binary prints its own name in Usage: — ttfx after a global install.)

API (ttfx-node)

For CLI builders (chalk-style): npm i ttfx-node, then

import { play, getFrames, listEffects } from 'ttfx-node';

await play('Deploy complete', 'decrypt');                 // animates in your terminal
const frames = getFrames('hi', 'beams', { seed: 1 });    // pure ANSI strings
const tuned = getFrames('hi', 'decrypt', {
  seed: 1, effectArgs: ['--typing-speed', '5'],           // any effect option, CLI-validated
});

play hides/restores the cursor, paces at frameRate, prints plain final text under NO_COLOR/non-TTY, and rejects with code INTERRUPTED on Ctrl-C after restoring the cursor. getFrames is sync and deterministic per seed; terminal size is never read, so output is machine-independent.

Sync guarantee: CI asserts CLI --parity-dump and getFrames byte-identical for the same input/seed (native/sync-gate.mjs, per OS) — a release fails if the API ever renders differently from the CLI. Both ship from the same engine tag (see .ttfx-ref and versions.json).

License

MIT — see LICENSE. The shipped binaries stay under their own MIT terms from TTE and ttfx, reproduced in THIRD-PARTY-NOTICES.