TV Launcher

A sleek, console-style application launcher for Windows and Linux with gamepad support, automatic image fetching, and powerful organization features.

<p align="center"> <img src="https://img.shields.io/badge/Platform-Windows%20%7C%20Linux-0078D4?style=for-the-badge&logo=windows&logoColor=white" alt="Platform"> <img src="https://img.shields.io/badge/Python-3.8+-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python"> <img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License"> </p> <img width="1920" height="1080" alt="Screenshot (338)" src="https://github.com/user-attachments/assets/4bb5d45b-ef80-4481-beb4-28fc2ac89485" />

Features

Beautiful Interface

• Full-screen TV-Mode - Console-style carousel with smooth animations
• System Menu - Press S or Start button to access the system Menu
• Responsive Scaling - Automatically adapts to any screen resolution (from 720p to 4K+)
• Gamepad Support - Navigate with Xbox/PlayStation controllers or keyboard/Bluetooth TV Remotes
• Automatic Image Downloads - Fetches 16:9 cover art from SteamGridDB
• Smart Program Scanner - Automatically detects installed applications with proper icon extraction
• Quick Search Widget - Instant app filtering with F/LB
• Drag & Drop Reordering - Reorganize apps with R/RB
• System Controls - Built-in Restart/Shutdown/Sleep options
• Customizable Controls - Remap any keyboard key or remote button to your liking

Screenshots

<img width="1920" height="1080" alt="Screenshot (339)" src="https://github.com/user-attachments/assets/b9c74376-fc18-4be8-8c99-639de0777a43" />

System Menu

<img width="1920" height="1080" alt="Screenshot (340)" src="https://github.com/user-attachments/assets/b77ce772-d9d2-48a4-bfe9-f3e8632b71dc" />

Key Mapper and battery Widget

<img width="1920" height="1080" alt="Screenshot (314)" src="https://github.com/user-attachments/assets/616d08f4-c1c3-45a7-8e8e-6981a002348c" />

Category Manager

https://github.com/user-attachments/assets/09108e93-de59-4919-a60f-eb129cec89bc

In motion

Input Support

• Gamepad Compatible - Xbox, PlayStation, or any standard controller
• Keyboard Navigation - Full keyboard support
• TV Remote Support - Works with Bluetooth TV remotes
• Fully Customizable - Remap any key or button in Settings → Key Remapper
• Auto-detection - Automatically detects connected gamepads with visual notifications

Smart Organization

• Category System

  • Organize apps into categories (Games, Media, Programs, Other)
  • Press Up/D-Pad Up to open category selector
  • Navigate categories with Left/Right or D-Pad
  • Quick category assignment with C (keyboard) or X/Square (controller)

• Category Manager - Customize categories in Settings

  • Add, edit, or delete categories
  • Choose custom icons and colors
  • Select the default category shown on launch

• Quick Search - Press F or LB to instantly search your apps

  • Live filtering as you type
  • Alphabetically sorted results
  • Keyboard and gamepad support

• Drag & Drop Reordering - Press R or RB to rearrange apps

  • Press Enter/A to activate reorder mode
  • Visual position indicators
  • Supports both linear and circular navigation

• Smart Program Scanner - Automatically detects installed applications

  • Cached results for instant loading
  • Proper icon extraction from executables
  • Alphabetically sorted display

• Edit & Delete - Manage your app library easily

Automatic Image Management

• SteamGridDB Integration - Auto-downloads 16:9 cover art
• Manual Download Button - Download covers for existing apps at any time
• Smart Auto-download Logic - Automatically fetches images when adding apps
• Local Image Support - Use your own custom images

System Controls

• Settings Menu Comprehensive configuration panel with:
  • Visual toggles for all settings
  • Backup/Restore configuration
  • Soft Reset (keeps apps) vs Full Reset options
  • Direct GitHub update checker
  • Category Manager for organizing apps
• Quick Actions - Restart, Sleep, Shutdown, or Close launcher

New in Version 1.2

• Changed

  • Configuration files (launcher_apps.json, key_mappings.json, scanner_cache.json) and tile images are now stored in the user folder %APPDATA%\Roaming\TVLauncher on
    Windows and ~/.config/TVLauncher on Linux, keeping user data separate from the application files and ensuring it survives updates.
  • Existing configurations are automatically migrated on first launch — no action required
  • Missing app covers are automatically re-downloaded at startup

• Added

  • A toast notification now appears in the bottom-right corner when a new update is available; a persistent banner also appears in the Settings menu until the
    update is installed. (Windows and Linux)
  • A new Config Files shortcut in the Settings menu opens the configuration folder directly for quick access. (Windows and Linux)

  Requirements

• Operating System: Windows 10/11 or Linux (Ubuntu 20.04+, Fedora, Arch, etc.)

• Python: 3.8 or higher

Dependencies

• PyQt6 - UI framework
• psutil - Process management
• pygame - Gamepad support
• requests- Automatic image downloads
• pycaw (Windows only) - Windows core audio control
• pywin32 (Windows only) - Shortcut scanning and icon extraction

Installation

1. Clone the Repository (branch 1 for Windows,branch 2 for Linux)

git clone https://github.com/Darkvinx88/TvLauncher.git
cd TvLauncher

2. Create Virtual Environment and Install Dependencies

Windows:

#Create Virtual environment:
python -m venv venv

#Activate Virtual environment:
venv\Scripts\activate

#Install dependencies:
pip install -r requirements.txt

#Run the launcher
python TvLauncher_Windows.py

#Alternatively you can just run the installer.bat and let it do everything for you
#(creates a virtual environment,activates it,installs dependencies)
#Once everything is installed simply run the launcher with the given TVLauncher.bat file
#it will automatically activate the virtual environment and run the launcher with 1 click

Linux:

# Create virtual environment:
python3 -m venv venv

# Activate virtual environment:
source venv/bin/activate

# Install dependencies:
pip install -r requirements.txt

# Run the launcher 
python3 TvLauncher_Linux.py

#Alternatively you can just run the Installer.sh and let it do everything for you
#(creates a virtual environment,activates it,installs dependencies)
#Once everything is installed simply run the launcher with the given Launcher.sh file
#it will automatically activate the virtual environment and run the launcher with 1 click

#sh files are already executable but if they are not just do
chmod +x installer.sh
./installer.sh

chmod +x launcher.sh
./launcher.sh

#you can also edit the given .desktop so you are able to run the launcher no matter where it is placed.

Windows Portable Mode

The Windows version is fully portable - simply press the .exe to start the launcher. You can move the entire folder anywhere.

Linux Portable Mode

This version includes everything needed:

• Python runtime
• Environment and launcher.sh have launching permissions already baked in
• All Python packages (PyQt6, pygame, requests, etc.)
• Qt6 with XCB/Wayland support (if in trouble sudo apt install libxcb)

Just extract and run:

# Extract
TVLauncher Linux v1.2 Portable.tar.gz

# Run
./launcher.sh

or edit the .desktop file

Controls

Default Keyboard Controls

| Key | Action | |-----|--------| | ← → | Navigate carousel | | ↑ ↓ | Navigate menus / system controls | | Enter | Launch app | | F | Open Quick Search | | R | Toggle Reorder Mode | | S | Open Settings Menu | | E | Edit current app | | C | Quick Category Assignment | | Delete | Remove current app | | Tab | Switch search mode (when searching) | | Esc | Exit launcher / Cancel / Close search |

Default Gamepad Controls

| Button | Action | |--------|--------| | D-Pad / Left Stick | Navigate | | D-Pad Up | Open category selector | | A/Cross | Launch app / Confirm | | B/Circle | Back / Cancel | | X/Square | Quick Category editor | | Y/Triangle | Delete app | | LB/L1 | Open Quick Search | | RB/R1 | Toggle Reorder Mode | | start | Open Settings Menu | | LT\L2+Dpad ↑/↓ | Volume up/down |

Customizing Controls All controls can be remapped! Here's how:

• Open Settings - Press S or Start button
• Navigate to Advanced section
• Select "🎮 Key Remapper"
• Choose an action to remap
• Press "Change" button
• Press any key or button on your remote/keyboard
• Confirm or cancel
• Save and Close when done
• Works with any keyboard key or TV remote button

Quick Start Guide

First Time Setup

1. Open settings Menu with s or start

2. Set Up SteamGridDB (Recommended)

   • Click "API Key"
   • Get a free API key from SteamGridDB
   • Paste it in the dialog
   • The launcher will now auto-download 16:9 cover art

3. Scan Installed Programs

   • Click "Scan Programs"
   • Wait for the scan to complete (may take a minute on first run)
   • Results are cached for instant loading next time
   • Select programs to add
   • Click "Add Selected"
   • Images download automatically in background

4. Add App Manually

   • Click "Add app"
   • Browse for the executable
   • Optionally add a custom image
   • Click "Add"

5. Download Covers for Existing Apps

   • Click "Download Covers"
   • Covers download automatically from SteamGridDB

6. Customize Background

   • Click "Set Background"
   • Select an image file (16:9 recommended)
   • Background updates immediately

7. Auto change Wallpapers (Optional)

   • Place