PulseTTY

A terminal-based music visualiser that reacts to audio input (MP3, Mic or System Audio), and visualises the frequencies in the terminal. It has different modes, including bars, waveform, and a spectrogram.

Download it from crates.io!

https://github.com/user-attachments/assets/aa3cc2b5-8ee6-43da-a3c1-d243f209e7d4

Bars Mode	Lines Mode	Spectrum Analyser

Features

• Runs as a CLI in the terminal
• Real-time audio visualisation, driven by audio input
• Supports multiple input modes:
  • System audio loopback (default)
  • MP3/Audio file playback
  • Microphone Input
• Multiple rendering modes (bars, line, spectrogram, or VU)
• Lightweight ASCII/Unicode terminal rendering
• Dynamically detects and fits to terminal size

Installation

Currently, PulseTTY only supports Windows environments, due to underlying audio pipeline structuring relying upon WASAPI. You can install it in a few different ways.

Via Cargo (recommended)

You must first have Rust and Cargo installed. You can find their installation instructions here.

Now run: (case-sensitive)

cargo install PulseTTY

This will globally install PulseTTY as a binary, allowing you to run it from any directory with pulsetty.

Build From Source (for development)

You must first have Rust and Cargo installed. You can find their installation instructions here.

Now run:

git clone https://github.com/MadAvidCoder/PulseTTY.git
cd PulseTTY
cargo build --release

This will create an executable binary, which you can run with:

./target/release/pulsetty

Usage

For a more detailed reference of all supported arguments, run pulsetty --help.

When run with no arguments, PulseTTY will display the bars rendering mode, using system audio, captured from the default output device. Use q or Esc to exit from the interface.

To select a specific output device, supply the --device <INDEX> option, with either its index or name. These can be obtained using the --list-devices option. To use an input device, use --mic or -m. A specific input device can be selected by supplying a parameter (-m 0 or -m "Microphone Array"), which can be found by running --list-mics. To play from a file, supply the filename as an argument. (pulsetty "path/to/a_song.mp3")

To preset a render mode, supply the --mode <MODE> option, with bars, line, spectrogram or vu. During runtime, you can cycle through modes by pressing m. You can also adjust input gain, with -/+ and 0, for compatability with quiet input sources.

Troubleshooting

• If your terminal emulator doesn't support Unicode or ANSI Colour codes, you can use the --ascii or --no-colour flags to ensure compatibility. These can also be toggled with a and c while running.
• If PulseTTY fails to detect the height/width of the terminal, they can be overridden with -c <N> and -H <ROWS. You can also use the --compact flag to reduce size on smaller screens.
• If the rendering is lagging, try raising the frame delay, with --frame-ms <MS>. The default is 15ms.
• If detecting a default audio capture fails, run --list-devices or --list-mics and provide the index of an active device.

Tech Stack

• Rust
• clap (for CLI parsing)
• crossterm (terminal rendering + input handling)
• rustfft (FFT Transforms)
• symphonia (file decoding)
• wasapi (Windows live audio capture)

Licence

PulseTTY is licensed under the MIT Licence.

You are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of this software. You must include the original copyright and license notice in any copies or substantial portions of the project.

There is no warranty. PulseTTY is provided “as is”, without warranty of any kind. Use at your own risk.