├── LICENSE ├── README.md ├── pyproject.toml ├── setup.py ├── terminal-bg-cava.gif ├── terminal-bg-lavat.gif ├── terminal-bg.conf └── terminal_bg ├── __init__.py ├── config.py ├── main.py └── terminal_window.py /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 DaarcyDev 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Terminal-bg 2 | 3 | Python script that turns your terminal into a transparent, live desktop background using GTK, VTE, and GtkLayerShell, giving you the ability to run terminal animations as wallpaper. 4 | 5 | 6 | ## Preview 7 | ### cava 8 | ![terminal-bg running cava](terminal-bg-cava.gif) 9 | 10 | ### lavat 11 | ![terminal-bg running lavat](terminal-bg-lavat.gif) 12 | 13 | ## Disclaimer 14 | 15 | I’m just a junior developer who loves Linux. This project was built with help from ChatGPT—apologies if anything is broken or doesn’t work correctly. Use at your own risk! 16 | 17 | --- 18 | 19 | ## Features 20 | 21 | - **Transparent terminal background**: Run any CLI program as your live wallpaper. 22 | - **Configurable appearance**: Adjust opacity and RGBA background color via a simple config file. 23 | - **Automatic config creation**: First launch auto-generates `~/.config/terminal-bg/terminal-bg.conf` with sane defaults. 24 | - **Custom script & monitor support**: Override the default command and target monitor at runtime. 25 | - **Lightweight & responsive**: Built on GTK3 + VTE with GtkLayerShell for smooth, accurate layering. 26 | - **Multi‑monitor friendly**: Choose which display to use for your animated background. 27 | 28 | --- 29 | 30 | ## Requirements 31 | 32 | - **Python 3.6+** 33 | - **Python GObject Introspection** bindings for: 34 | - GTK3 (`python3-gi`, `gir1.2-gtk-3.0`) 35 | - VTE (`gir1.2-vte-2.91`) 36 | - GtkLayerShell (`gir1.2-gtk-layer-shell-0.1`) 37 | - A compositing window manager or desktop environment that supports true transparency. 38 | 39 | 40 | ## Installation 41 | 42 | The recommended way to install **terminal‑bg** is using `pipx`. This makes the `terminal-bg` command available globally while keeping its dependencies isolated in its own virtual environment. 43 | 44 | ### Using `pipx` (Recommended) 45 | 46 | `pipx` installs Python CLI applications into isolated environments and makes them globally available without polluting your system Python or requiring you to manually activate a virtualenv. 47 | 48 | #### Install `pipx` (if you haven’t already) 49 | 50 | The best way to install `pipx` on Linux is via your distribution’s package manager: 51 | 52 | - **Ubuntu / Debian** 53 | ```bash 54 | sudo apt update 55 | sudo apt install pipx 56 | pipx ensurepath 57 | sudo pipx ensurepath --global # optional, enables `--global` flag 58 | 59 | - **Fedora** 60 | ```bash 61 | sudo dnf install pipx 62 | pipx ensurepath 63 | sudo pipx ensurepath --global # optional 64 | 65 | - **Arch Linux** 66 | ```bash 67 | sudo pacman -S python-pipx 68 | pipx ensurepath 69 | sudo pipx ensurepath --global # optional 70 | 71 | - **Other distros (via pip)** 72 | ```bash 73 | python3 -m pip install --user pipx 74 | python3 -m pipx ensurepath 75 | sudo pipx ensurepath --global # optional 76 | 77 | After installing, restart your shell or run source ~/.bashrc (or equivalent) so that the pipx command is on your PATH. 78 | 79 | ### Install terminal‑bg 80 | - **From Github** 81 | ```bash 82 | pipx install git+https://github.com/DaarcyDev/terminal-bg.git 83 | 84 | - **From a local clone** 85 | ```bash 86 | git clone https://github.com/DaarcyDev/terminal-bg.git 87 | cd terminal-bg 88 | pipx install . 89 | 90 | ## Usage 91 | Once installed, you can launch your animated terminal background with: 92 | 93 | 94 | terminal-bg [OPTIONS] 95 | 96 | 97 | For example: 98 | 99 | # Run 'cava' on monitor 1 100 | terminal-bg --script cava --monitor 1 101 | 102 | # Run 'lavat' on monitor 0 103 | terminal-bg --script 'lavat -c red -R 1' --monitor 1 104 | 105 | 106 | --- 107 | 108 | ## Autostart (Run on system startup) 109 | 110 | If you want terminal-bg to launch automatically when your system starts (for example, with a window manager like bspwm, i3, or Hyprland), you can add one of the following lines to your autostart configuration file: 111 | 112 | - For bspwm: edit ~/.config/bspwm/bspwmrc 113 | 114 | - For i3: edit ~/.config/i3/config 115 | 116 | - For Hyprland: edit ~/.config/hypr/hyprland.conf 117 | 118 | Try them in this order until one works for your setup: 119 | 120 | 1. **If the binary is in your PATH (installed via pipx):** 121 | ```bash 122 | exec-once = terminal-bg --script 'cava' --monitor 1 123 | 124 | 2. **If the command is not found, try with the full path:** 125 | ```bash 126 | exec-once = /home/your-username/.local/bin/terminal-bg --script 'cava' --monitor 1 127 | 128 | 3. **If it starts too early before the session is fully ready, try with a delay:** 129 | ```bash 130 | exec-once = bash -c "sleep 10 && /home/your-username/.local/bin/terminal-bg --script 'cava' --monitor 2" 131 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = ["setuptools"] 3 | build-backend = "setuptools.build_meta" 4 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | from setuptools import setup, find_packages 2 | 3 | setup( 4 | name='terminal-bg', 5 | version='0.1', 6 | packages=find_packages(), 7 | include_package_data=True, 8 | install_requires=[ 9 | 'pygobject', 10 | ], 11 | entry_points={ 12 | 'console_scripts': [ 13 | 'terminal-bg=terminal_bg.main:main', 14 | ], 15 | }, 16 | ) 17 | -------------------------------------------------------------------------------- /terminal-bg-cava.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/DaarcyDev/terminal-bg/1652908b907b5a3c5aa13b645feee8722f7f9652/terminal-bg-cava.gif -------------------------------------------------------------------------------- /terminal-bg-lavat.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/DaarcyDev/terminal-bg/1652908b907b5a3c5aa13b645feee8722f7f9652/terminal-bg-lavat.gif -------------------------------------------------------------------------------- /terminal-bg.conf: -------------------------------------------------------------------------------- 1 | [Appearance] 2 | opacity = 0.8 3 | background_color = rgba(0,0,0,0.6) 4 | 5 | [Behavior] 6 | default_command = cava 7 | default_monitor = 0 8 | -------------------------------------------------------------------------------- /terminal_bg/__init__.py: -------------------------------------------------------------------------------- 1 | 2 | """ 3 | terminal-bg: Ejecuta una terminal transparente como fondo de pantalla en Linux. 4 | """ 5 | 6 | __version__ = "0.1.0" 7 | 8 | from .main import main 9 | 10 | __all__ = ["main", "__version__"] -------------------------------------------------------------------------------- /terminal_bg/config.py: -------------------------------------------------------------------------------- 1 | import configparser 2 | import os 3 | 4 | DEFAULT_CONFIG = { 5 | "Appearance": { 6 | "opacity": "0.8", 7 | "background_color": "rgba(0,0,0,0)" 8 | }, 9 | "Behavior": { 10 | "default_command": "cava", 11 | "default_monitor": "0" 12 | } 13 | } 14 | 15 | CONFIG_PATH = os.path.expanduser("~/.config/terminal-bg/terminal-bg.conf") 16 | 17 | def load_config(): 18 | config = configparser.ConfigParser() 19 | config.read_dict(DEFAULT_CONFIG) 20 | 21 | if os.path.exists(CONFIG_PATH): 22 | config.read(CONFIG_PATH) 23 | return config 24 | -------------------------------------------------------------------------------- /terminal_bg/main.py: -------------------------------------------------------------------------------- 1 | import sys 2 | import signal 3 | import argparse 4 | import os 5 | import configparser 6 | 7 | # Primero, comprobamos que las librerías GI estén instaladas 8 | def check_gi_dependencies(): 9 | try: 10 | import gi 11 | gi.require_version('Gtk', '3.0') 12 | gi.require_version('Vte', '2.91') 13 | gi.require_version('GtkLayerShell', '0.1') 14 | from gi.repository import Gtk, Vte, GtkLayerShell 15 | except (ImportError, ValueError): 16 | sys.stderr.write( 17 | "❌ No se han encontrado las dependencias necesarias para ejecutar terminal‑bg:\n" 18 | " • python-gobject (Gtk)\n" 19 | " • gir1.2-vte-2.91 (Vte)\n" 20 | " • gir1.2-gtk-layer-shell-0.1 (GtkLayerShell)\n\n" 21 | "En Arch Linux:\n" 22 | " sudo pacman -S python-gobject vte3 gtk-layer-shell\n\n" 23 | "En Debian/Ubuntu:\n" 24 | " sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-vte-2.91 gir1.2-gtk-layer-shell-0.1\n\n" 25 | "Luego vuelve a ejecutar el comando.\n" 26 | ) 27 | sys.exit(1) 28 | 29 | check_gi_dependencies() 30 | 31 | # Ahora que sabemos que existirá, importamos lo que necesitamos de GI 32 | from .config import load_config, DEFAULT_CONFIG, CONFIG_PATH 33 | from .terminal_window import TerminalBackground 34 | from gi.repository import Gtk 35 | 36 | def ensure_config_exists(): 37 | """ 38 | Crea el directorio y el archivo de configuración con los valores por defecto 39 | si no existen.. 40 | """ 41 | config_dir = os.path.dirname(CONFIG_PATH) 42 | os.makedirs(config_dir, exist_ok=True) 43 | 44 | if not os.path.exists(CONFIG_PATH): 45 | parser = configparser.ConfigParser() 46 | parser.read_dict(DEFAULT_CONFIG) 47 | with open(CONFIG_PATH, 'w') as f: 48 | parser.write(f) 49 | print(f"[+] Archivo de configuración creado en {CONFIG_PATH}") 50 | 51 | def main(): 52 | # 1) Asegurarnos de que exista la config 53 | ensure_config_exists() 54 | 55 | # 2) Cargar configuración (mezcla de DEFAULTS + ~/.config/terminal-bg/terminal-bg.conf) 56 | config = load_config() 57 | 58 | # 3) Parsear argumentos de línea de comando 59 | parser = argparse.ArgumentParser(description="Terminal como fondo de pantalla") 60 | parser.add_argument('--script', type=str, help='Script a ejecutar en la terminal') 61 | parser.add_argument('--monitor', type=int, help='Monitor donde mostrar (no implementado)') 62 | args = parser.parse_args() 63 | 64 | # 4) Elegir comando & parámetros 65 | command = args.script if args.script else config['Behavior']['default_command'] 66 | monitor = args.monitor if args.monitor is not None else int(config['Behavior']['default_monitor']) 67 | opacity = config['Appearance']['opacity'] 68 | bg_color = config['Appearance']['background_color'] 69 | 70 | # 5) Crear la ventana y arrancar GTK 71 | win = TerminalBackground(command, opacity, bg_color, monitor) 72 | win.connect("destroy", Gtk.main_quit) 73 | 74 | # 6) Manejador de Ctrl+C para cerrar sin traceback 75 | signal.signal(signal.SIGINT, lambda *a: Gtk.main_quit()) 76 | try: 77 | Gtk.main() 78 | except KeyboardInterrupt: 79 | Gtk.main_quit() 80 | sys.exit(0) 81 | 82 | if __name__ == '__main__': 83 | main() 84 | -------------------------------------------------------------------------------- /terminal_bg/terminal_window.py: -------------------------------------------------------------------------------- 1 | import os 2 | import cairo 3 | import gi 4 | import sys 5 | gi.require_version('Gtk', '3.0') 6 | gi.require_version('Vte', '2.91') 7 | gi.require_version('GtkLayerShell', '0.1') 8 | from gi.repository import Gtk, Vte, GLib, Gdk, GtkLayerShell 9 | 10 | class TerminalBackground(Gtk.Window): 11 | def __init__(self, command, opacity, background_color, monitor): 12 | super().__init__(title="TerminalBackground") 13 | 14 | GtkLayerShell.init_for_window(self) 15 | GtkLayerShell.set_layer(self, GtkLayerShell.Layer.BACKGROUND) 16 | GtkLayerShell.set_namespace(self, "terminal-background") 17 | 18 | # Obtener monitor por índice 19 | display = Gdk.Display.get_default() 20 | monitor_obj = display.get_monitor(monitor) 21 | 22 | if monitor_obj is None: 23 | print(f"❌ Monitor {monitor} no encontrado.") 24 | sys.exit(1) 25 | 26 | GtkLayerShell.set_monitor(self, monitor_obj) 27 | 28 | 29 | for edge in [GtkLayerShell.Edge.TOP, GtkLayerShell.Edge.BOTTOM, 30 | GtkLayerShell.Edge.LEFT, GtkLayerShell.Edge.RIGHT]: 31 | GtkLayerShell.set_anchor(self, edge, True) 32 | 33 | self.set_app_paintable(True) 34 | screen = self.get_screen() 35 | visual = screen.get_rgba_visual() 36 | if visual: 37 | self.set_visual(visual) 38 | self.set_decorated(False) 39 | 40 | self.terminal = Vte.Terminal() 41 | self.terminal.set_opacity(float(opacity)) 42 | 43 | color = Gdk.RGBA() 44 | color.parse(background_color) 45 | self.terminal.set_color_background(color) 46 | self.terminal.set_clear_background(True) 47 | 48 | self.terminal.spawn_async( 49 | Vte.PtyFlags.DEFAULT, 50 | os.environ['HOME'], 51 | ["bash", "-lc", command], 52 | None, GLib.SpawnFlags.DO_NOT_REAP_CHILD, 53 | None, None, -1, None, None 54 | ) 55 | 56 | box = Gtk.Box() 57 | box.pack_start(self.terminal, True, True, 0) 58 | self.add(box) 59 | 60 | self.connect("draw", self.on_draw) 61 | self.show_all() 62 | 63 | def on_draw(self, widget, cr): 64 | cr.set_operator(cairo.OPERATOR_CLEAR) 65 | cr.paint() 66 | cr.set_operator(cairo.OPERATOR_OVER) 67 | return False 68 | --------------------------------------------------------------------------------