TermiCam

README

TermiCam

A real-time ASCII camera for your terminal.

TermiCam is a Go TUI application that reads camera frames through FFmpeg and renders them as ASCII art in your terminal. It supports Linux, macOS, and Windows camera capture through platform-specific FFmpeg backends.

---

Requirements

• Go to build the app.
• FFmpeg for camera capture. ffmpeg must be available in your PATH.
• A terminal with enough space to render the camera view.

Platform-specific requirements:

• Linux: install v4l2-ctl from v4l-utils.
• macOS: grant camera permission to the terminal app you use to run TermiCam.
• Windows: use an FFmpeg build with DirectShow support. Most common Windows FFmpeg builds include this.

---

Installation

Pre-compiled Binaries (Recommended)

If you do not have Go installed, you can download a pre-compiled binary for your operating system and architecture directly from the GitHub Releases page.

Linux & macOS

1. Download the archive for your system (e.g., termicam_Darwin_x86_64.tar.gz or termicam_Linux_arm64.tar.gz).

2. Extract the archive and make the binary executable:

   tar -xzf termicam_*.tar.gz
   chmod +x termicam
   

3. (Optional) Move it to your local path to run it from anywhere:

   sudo mv termicam /usr/local/bin/
   

[!TIP] macOS Users: Because the binary is not signed/notarized by Apple, you may see a "Developer Cannot Be Verified" warning on the first run. To allow execution, you can run: xattr -d com.apple.quarantine termicam

Windows

1. Download the .zip archive for your architecture (e.g., termicam_Windows_x86_64.zip).
2. Extract the folder.
3. Run termicam.exe from PowerShell or Command Prompt, or add the folder to your System Environment variables (PATH) to run it globally.

Via Go

If you have Go installed on your machine, you can install TermiCam directly to your $GOPATH/bin:

go install github.com/Megge06/TermiCam/cmd/termicam@latest

---

Local Setup

Clone the repository:

git clone https://github.com/Megge06/TermiCam.git
cd TermiCam

Install Go dependencies:

go mod download

Run the app from source:

go run ./cmd/termicam

Build a local binary:

go build -o termicam ./cmd/termicam

Run the built binary on Linux or macOS:

./termicam

On Windows, build and run from PowerShell:

go build -o termicam.exe ./cmd/termicam
.\termicam.exe

---

Installing Platform Dependencies

macOS

Install FFmpeg:

brew install ffmpeg

When you first run TermiCam, macOS may ask for camera access. Allow access for the terminal application you are using, such as Terminal, iTerm2, or VS Code.

If camera access was previously denied, update it in System Settings > Privacy & Security > Camera.

Linux

Install FFmpeg and v4l-utils.

Debian or Ubuntu:

sudo apt update
sudo apt install ffmpeg v4l-utils

Fedora:

sudo dnf install ffmpeg v4l-utils

Arch Linux:

sudo pacman -S ffmpeg v4l-utils

Confirm that cameras are visible:

v4l2-ctl --list-devices

Windows

Install Go and FFmpeg with winget from PowerShell:

winget install --id GoLang.Go -e
winget install --id Gyan.FFmpeg -e

Restart PowerShell after installation so the updated PATH is loaded.

Confirm FFmpeg is available:

ffmpeg -version

Confirm DirectShow can see video devices:

ffmpeg -hide_banner -f dshow -list_devices true -i dummy

TermiCam uses FFmpeg's DirectShow input on Windows. If no camera appears, check Windows camera privacy settings and make sure desktop apps are allowed to access the camera.

---

Usage

Start the app:

go run ./cmd/termicam

The app starts on a settings screen. Configure the display options, proceed to device selection, choose a camera, and press Enter to start the ASCII camera view.

---

Keyboard Shortcuts

Settings Screen

• Up / Down (j / k): Move between configuration items.
• Space / Left / Right: Toggle settings or activate the Target FPS input field.
• Enter: Save settings and proceed to device selection.
• Esc (while editing FPS): Cancel editing and restore previous value.

Device Selection

• Up / Down: Navigate the list of detected video devices.
• /: Enter search mode to filter devices by name or path.
• Space: Check/uncheck a device.
• Enter: Connect to the selected/checked device and start the camera stream.
• Esc / Backspace: Return to the Settings screen.

Camera View

• h: Toggle the HUD sidebar on and off for a minimal, full-screen ASCII display.
• Esc / Backspace: Stop the session and return to the Device Selection screen.
• q / Ctrl+C: Terminate the application immediately.

---

Development Commands

Run package checks:

go test ./...

Format Go files:

gofmt -w .

Build for the current platform:

go build -o termicam ./cmd/termicam

---

Troubleshooting

ffmpeg Not Found

Make sure FFmpeg is installed and available in your PATH:

ffmpeg -version

No Camera Devices Found

Check that your operating system can see the camera first.

Linux:

v4l2-ctl --list-devices

macOS:

ffmpeg -hide_banner -f avfoundation -list_devices true -i ""

Windows:

ffmpeg -hide_banner -f dshow -list_devices true -i dummy

Permission Errors

• macOS: allow camera access for your terminal in System Settings.
• Windows: allow camera access for desktop apps in Camera privacy settings.
• Linux: make sure your user has permission to access /dev/video* devices.

Slow Rendering

Try lowering the target FPS in the settings screen or use a smaller terminal window. TermiCam caps capture scaling to reduce CPU load, but color output and detailed palettes can still be heavier in large terminals.

---

Project Structure

• cmd/termicam/main.go: application entry point.
• internal/tui/: Bubble Tea model, update loop, views, and styling.
• internal/video/: platform-specific camera discovery and FFmpeg capture sessions.
• internal/ascii/: RGB24 frame to ASCII conversion.

---

Built With

• Bubble Tea - A powerful little TUI framework, used to power TermiCam's interface.
• Lip Gloss - Style definitions for nice terminal layouts, used for styling and rendering in the TUI.
• FFmpeg - A complete, cross-platform solution to record, convert and stream audio and video, used for getting a stream of the camera video.

Acknowledgments

• Algorithm Inspiration: The core image-to-ASCII conversion logic, character mapping, and 8-bit color scaling in this project were heavily inspired by the fantastic ascii-image-converter by Zoraiz Hassan.