streamterm

Real-time display capture rendered as braille ASCII art directly in your terminal, with 24-bit color.
Report Bug · Request Feature

About The Project

streamterm captures your primary display in real time and streams it into your terminal as Unicode braille characters with full 24-bit color. Every terminal cell covers a 2x4 pixel block, mapped to one of the 256 braille characters in the U+2800–U+28FF range, giving an effective resolution of twice the terminal width by four times its height.

(Back to top)

Built With

• 
• 
• 
• 

(Back to top)

Getting Started

To run streamterm locally, follow the steps below.

Prerequisites

• Rust 1.80+

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  source ~/.cargo/env

• [Linux only] - X11 headers required by scrap:

  sudo apt install libx11-dev libxext-dev libxcb1-dev

  [!NOTE] macOS and Windows ship the required native APIs, no extra system packages needed.

Installation

1. Clone the repository:

   git clone https://github.com/NgodingCik/streamterm.git

2. Move into the project directory:

   cd streamterm

3. Build the release binary:

   cargo build --release

4. Run it:

   # Linux / macOS
   ./target/release/streamterm
   
   # Windows
   target\release\streamterm.exe

Tip

Maximize your terminal and use a small font size before launching, the larger the terminal grid, the higher the effective render resolution.

(Back to top)

How It Works

Each frame goes through four stages:

1. Capture: scrap grabs the primary display as a raw BGRA byte buffer.
2. Scale: nearest-neighbor lookup tables map every braille sub-pixel to a source coordinate without division inside the inner loop.
3. Render: rayon processes rows in parallel; each cell samples 8 sub-pixels, computes BT.601 luminance, classifies pixels into foreground/background, picks the matching braille character, and writes ANSI 24-bit color escapes only when the color actually changes.
4. Output: the resulting byte buffer is flushed to stdout in one shot via BufWriter.

Press Ctrl+C to exit cleanly.

(Back to top)

Contributing

Contributions of any kind are welcome.

1. Fork the repository
2. Create an isolated branch for your change (git checkout -b feature/YourFeature)
3. Commit your changes (git commit -m 'feat: add YourFeature')
4. Push to your fork (git push origin feature/YourFeature)
5. Open a Pull Request

Important

Run cargo clippy -- -D warnings and cargo test before opening a Pull Request. PRs that introduce new warnings will not be merged.

(Back to top)

License

Distributed under the GNU General Public License v3.0. See LICENSE for details.

(Back to top)

Contact

Project link: https://github.com/NgodingCik/streamterm Discord server: https://discord.ngodingcik.my.id

(Back to top)

Acknowledgments

• scrap: cross-platform screen capture
• rayon: data parallelism
• crossterm: cross-platform terminal control
• Unicode Braille Patterns: U+2800-U+28FF

(Back to top)