CLIFT Terminal VJ Software

you can discover the software here : https://www.youtube.com/watch?v=zBFGvL8qifg (playing with a generative python/foxdot based evil server :) )!

CLIFT 0.1 is in developpement terminal-based VJ software for live visual performances using ASCII art. Features 190 visual scenes, dual-deck mixing, effects, and WebSocket integration for live coding overlays. It's made by Crash Server (https://crashserver.fr) and released under MIT License. Feel free to improve and fix if you're interested.

Best used with Cool Retro Term or some other terminal. Even better with GPU support. Have fun :)

If you want to support : https://coff.ee/crashserver

Features

190 Visual Scenes - Organized in 19 categories with 10 scenes each
Dual-Deck Mixing - Professional A/B deck system with crossfader
15 Post-Processing Effects - Real-time visual effects
Audio Reactive - Real-time audio visualization with PipeWire
Ableton Link Support - Sync with other music software
WebSocket Integration - Live coding overlay support
BPM Sync - Automatic beat detection and synchronization
Preset System - Save and load your favorite configurations

System Requirements

Dependencies

ncurses - Terminal graphics library
libwebsockets - WebSocket server functionality
PipeWire (optional) - For audio input and visualization
Ableton Link SDK (optional) - For music synchronization
GCC/G++ - C/C++ compiler

Supported Platforms

Linux (Primary platform)
macOS (With modifications)
Any Unix-like system with ncurses support

Installation

Quick Install (Linux)

# Clone or extract CLIFT
cd clift_terminal

# Install dependencies (Ubuntu/Debian)
sudo apt update
sudo apt install build-essential libncurses5-dev libncursesw5-dev libwebsockets-dev

# Install PipeWire support (optional but recommended)
sudo apt install libpipewire-0.3-dev libspa-0.2-dev

# Build CLIFT
cd scripts
chmod +x *.sh
./build_with_pipewire.sh

# Run CLIFT
../clift

Manual Build

# Basic build (no audio)
cd scripts
./build.sh

# Build with PipeWire audio support
./build_with_pipewire.sh

# Build with custom options
make -f ../src/clift_engine.c -o ../clift -lncurses -lwebsockets

Audio Setup (PipeWire)

For audio-reactive scenes, you need to connect an audio source:

# Auto-connect default audio
./connect_audio.sh

# List available audio sources
pw-link --input

# Manual connection (replace SOURCE_NAME)
pw-link "SOURCE_NAME:monitor_FL" "clift:input_FL"
pw-link "SOURCE_NAME:monitor_FR" "clift:input_FR"

Basic Usage

Starting CLIFT

# Normal mode with UI
./clift

# Fullscreen mode (hide UI)
./clift --fullscreen

# Show help
./clift --help

Essential Controls

Space - Switch between Deck A and Deck B
0-9 - Select scene within current category
←/→ - Navigate between scene categories
f - Toggle fullscreen mode
q - Quit application

Scene Navigation

CLIFT has 190 scenes organized in 19 categories (0-18):

Use number keys 0-9 to select scenes within the current category
Use arrow keys ←/→ to change categories
Scene numbering: Category × 10 + Scene (e.g., Category 5, Scene 3 = Scene 53)

Advanced Features

Dual-Deck Mixing

CLIFT features a professional dual-deck system:

Deck A - Left deck (default active)
Deck B - Right deck
Crossfader - Blend between decks
Tab - Enter crossfader edit mode
Space - Switch active deck

Effects System

15 real-time post-processing effects:

e - Cycle through effects
E (Shift+e) - Reverse cycle effects
Effects apply to the final mixed output

WebSocket Integration

Enable live coding overlays and external control:

# In CLIFT, press 'w' to start WebSocket server
# Server runs on localhost:8080

WebSocket JSON Protocol:

{
  "player": 0,           // 0 or 1 for deck selection
  "code": "print('hello')",  // Code to display
  "executed": "hello",   // Execution result
  "active": true         // Show/hide overlay
}

Audio Reactive Scenes

Special audio-reactive scenes (requires PipeWire):

Scene 0 - Audio Bars (spectrum analyzer)
Scenes 180-189 - Audio-reactive category
Real-time 64-band spectrum analysis
Beat detection and BPM sync

Ableton Link Synchronization

Sync with other music software:

Automatic network discovery
BPM synchronization
Start/stop sync
Beat and phase alignment

Complete Scene Reference

Keyboard Controls Reference

Navigation

0-9 - Select scene within current category
←/→ - Change scene category
Space - Switch between Deck A and Deck B

Display

f - Toggle fullscreen mode
h - Toggle help display
i - Toggle info display

Effects

e - Next effect
E (Shift+e) - Previous effect
r - Reset effect

Mixing

Tab - Enter crossfader edit mode
+/- - Adjust crossfader (in edit mode)
Enter - Confirm crossfader setting

System

w - Toggle WebSocket server
a - Toggle audio input
l - Toggle Ableton Link
s - Save current state
Ctrl+S - Save preset
Ctrl+L - Load preset
q - Quit application

Scene Parameters

1-8 - Adjust scene parameters (when in parameter mode)
p - Enter parameter edit mode

Testing and Debugging

WebSocket Testing

# Test WebSocket connectivity
cd tests
python3 test_websocket.py

# Simple connection test
python3 simple_websocket_test.py

# Debug WebSocket issues
python3 debug_websocket.py

# Web interface test
# Open websocket_test.html in browser

Ableton Link Testing

# Test Link connectivity
python3 test_ableton_link.py

# Requires: pip install python-abletonlink

Debugging Crashes

# Run with GDB for crash analysis
python3 test_segfault.py

# Or manually:
gdb ./clift
run
bt  # on crash

Troubleshooting

Audio Issues

No Audio Reactive Scenes: Install PipeWire development packages
No Audio Input: Run ./connect_audio.sh or check PipeWire connections
Audio Latency: Adjust PipeWire buffer settings

WebSocket Issues

Connection Refused: Check if port 8080 is available
Firewall Blocking: Open port 8080 for local connections
Browser CORS: Serve test files from local HTTP server

Build Issues

Missing ncurses: Install libncurses5-dev
Missing WebSockets: Install libwebsockets-dev
C++ Compilation: Ensure g++ is installed for Link support

Performance Issues

Slow Rendering: Reduce terminal size or disable effects
High CPU Usage: Lower frame rate or disable audio features
Memory Leaks: Report issues with valgrind output

License

CLIFT IS RELEASED UNDER MIT LICENSE

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contributing

feel free to fork or contact [email protected]

Credits

Created by Crash Server || 2025 >> crashserver.fr

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
docs		docs
scripts		scripts
src		src
tests		tests
INSTALLATION.md		INSTALLATION.md
README.md		README.md
clift		clift

CrashServer/clift_terminal

Folders and files

Latest commit

History

Repository files navigation

CLIFT Terminal VJ Software

Features

System Requirements

Dependencies

Supported Platforms

Installation

Quick Install (Linux)

Manual Build

Audio Setup (PipeWire)

Basic Usage

Starting CLIFT

Essential Controls

Scene Navigation

Advanced Features

Dual-Deck Mixing

Effects System

WebSocket Integration

Audio Reactive Scenes

Ableton Link Synchronization

Complete Scene Reference

Category 0: Basic Scenes (0-9)

Category 1: Geometric Scenes (10-19)

Category 2: Organic Scenes (20-29)

Category 3: Text/Code Scenes (30-39)

Category 4: Abstract Scenes (40-49)

Category 5: Infinite Tunnels (50-59)

Category 6: Nature Scenes (60-69)

Category 7: Explosions (70-79)

Category 8: Cities (80-89)

Category 9: Freestyle (90-99)

Category 10: Human (100-109)

Category 11: Warfare (110-119)

Category 12: Revolution & Eyes (120-129)

Category 13: Film Noir (130-139)

Category 14: Escher 3D Illusions (140-149)

Category 15: Ikeda-Inspired (150-159)

Category 16: Giger-Inspired (160-169)

Category 17: Revolt (170-179)

Category 18: Audio Reactive (180-189)

Keyboard Controls Reference

Navigation

Display

Effects

Mixing

System

Scene Parameters

Testing and Debugging

WebSocket Testing

Ableton Link Testing

Debugging Crashes

Troubleshooting

Audio Issues

WebSocket Issues

Build Issues

Performance Issues

License

Contributing

Credits

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages