TV Launcher

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

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/
• System Controls - Built-in Restart/Shutdown/Sleep options
• Customizable Controls - Remap any keyboard key or remote button to your liking

Screenshots

Carousel view with cover art

System Menu

Key Mapper

Category Manager

2026-01-23.16-01-26.mp4

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 `` 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 0.8

• Fixed:

  • Fixed a Bug that prevented clock to update time (Windows and Linux)

• Added:

  • Auto change Wallpaper - change background with animation automatically every 5 minutes (Windows and Linux)
  • Added the ability to add .desktop and .sh files to the launcher (Linux)
  • Added the ability to choose the initial landing category.
  • Switched non portable versions to a virtual environment installation for better stability and reliability (Windows and Linux)
  • Code Refactoring - Improved performance and stability

  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

#It's highly suggested once everything is installed to run the launcher with the given .bat file
#since 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

#It's highly suggested once everything is installed to run the launcher with the given launcher.sh file
#since it will automatically activate the virtual environment and run the launcher with 1 click

#make it executable
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
• 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 v0.8 Portable.zip

# 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+Dpad up/down	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. Add Your First App

   • Click the + icon in the top-right
   • Browse for the executable
   • Insert the API Key before adding any program for auto-download to work
   • Optionally add a custom image
   • Click "Add"

2. Set Up SteamGridDB (Recommended)

   • Click the 🔑 icon
   • 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 the 🔍 icon
   • 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. Download Covers for Existing Apps

   • Click the ⬇️ download icon in the header
   • Select which apps need covers
   • Covers download automatically from SteamGridDB

5. Customize Background

   • Click the 🖼️ icon
   • Select an image file (16:9 recommended)
   • Background updates immediately

6. Auto change Wallpapers (Optional)

   • Place your image files in the wallpaper folder
   • Go to settings and activate the Auto change wallpapers
   • Now every 5 minutes your wallpapers will change in a random rotation

7. Customize Controls (Optional)

   • Press S to open Settings
   • Navigate to "🎮 Key Remapper"
   • Remap any key to your preference
   • Changes apply instantly

Using Categories

1. Press ↑ (keyboard) or D-Pad Up (gamepad) to open category selector
2. Use ←/→ or D-Pad Left/Right to switch between categories
3. Press ↓ or D-Pad Down to close and view filtered apps
4. Press C or X/Square on any app to quickly assign a category

Managing Categories:

1. Open Settings (S or Start)
2. Select "Manage Categories"
3. Add, edit, or delete categories
4. Customize icons and colors
5. Select your preferred category
6. click on the green checkmark and save
7. at launch the selected category will be the first to be shown

Using Quick Search

1. Press F (keyboard) or LB (gamepad) anywhere
2. Start typing to filter apps (Typing Mode)
3. Use ↑/↓ or D-Pad to navigate results (auto-switches to Navigation Mode)
4. Press Tab or X to manually switch modes
5. Press Enter or A to launch selected app
6. Press Esc or B to close search

Reordering Apps

Quick Toggle Method:

1. Press R (keyboard) or RB (gamepad)
2. Use ←/→ to move the app to desired position
3. Press Enter/A to confirm or Esc/B to cancel

Features:

• Gold border shows selected app
• Blue border shows target position
• Position numbers appear on each tile
• Works with both linear (≤5 apps) and circular (>5 apps) modes
• Instructions overlay appears when active

Autostart Setup

The Launcher can start at boot on both Windows and Linux

Windows Autostart

Method 1: Startup Folder (Recommended)

1. Press Win + R to open Run dialog
2. Type shell:startup and press Enter
3. Right-click your launcher .bat or .exe file → Create shortcut
4. Drag the shortcut into the Startup folder
5. Launcher will start automatically after login

💡 Tip: Right-click shortcut → Properties → Set Run: Minimized to hide console window.

Method 2: Windows Registry

1. Create a file named TVLauncher_Autostart.reg
2. Paste the following content:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run]
"TVLauncher"="\"C:\\path\\to\\launch.bat\""

3. Replace C:\\path\\to\\launch.bat with your actual path
4. Double-click the .reg file to add the registry entry
5. Launcher will start automatically on every boot

Linux Autostart

Works with any desktop environment (XFCE, GNOME, KDE, Cinnamon, MATE, etc.)

1. Create autostart directory:

mkdir -p ~/.config/autostart

2. Create autostart file:

nano ~/.config/autostart/TVLauncher.desktop

3. Add this content:

[Desktop Entry]
Type=Application
Name=TVLauncher
Comment=Automatically start the TV Launcher on login
Exec=/path/to/venv/bin/python /path/to/TvLauncher_Linux.py
Path=/path/to/
Terminal=false
X-GNOME-Autostart-enabled=true

Replace /path/to/ with actual directory

4. Make executable:

chmod +x ~/.config/autostart/TVLauncher.desktop

Launcher will now start automatically on login.

⚙️ Configuration

Configuration is stored in launcher_apps.json

Key mappings are stored separately in key_mappings.json

💡 Tip: Use the Backup feature in Settings to save your entire configuration (apps + mappings + settings).

Image Organization

Images are stored in assets/APP_NAME/banner.{png|jpg|jpeg|webp} with automatic fallback.

🛠️ Troubleshooting

Gamepad Not Detected

• Ensure pygame is installed: pip install pygame
• Connect gamepad before launching
• Launcher auto-detects gamepads every 5 seconds
• Controller connection notifications appear when detected (Windows)
• Linux: Ensure user has permission to access /dev/input/:

  sudo usermod -a -G input $USER
  # Log out and back in

Images Not Downloading

• Verify requests is installed: pip install requests
• Check SteamGridDB API key is valid
• Ensure internet connection is active
• Try the manual download button (⬇️ icon) for existing apps
• Images download in background thread (check console for errors)

App Won't Launch

• Verify executable path is correct
• Check file permissions
• Windows: Try running as administrator
• Linux: Ensure binary has execute permissions (chmod +x)

Key Remapper Issues

• If remapped keys don't work, try restarting the launcher
• Check key_mappings.json file exists
• Use "Reset to Defaults" in Key Remapper if needed
• Key mappings are automatically included in configuration backups

Program Scanner Issues

• First scan may take 1-2 minutes
• Results are cached in scanner_cache_*.json
• Click refresh button (↻) to force rescan
• Windows: Ensure pywin32 is installed for icon extraction

Scaling Issues

• Launcher auto-scales to your resolution
• Base resolution: 1920x1080
• All UI elements scale proportionally

Linux-Specific Issues

Missing Qt Platform Plugin:

# Ubuntu/Debian:
sudo apt-get install qt6-qpa-plugins

# Fedora:
sudo dnf install qt6-qtbase-gui

Missing Qt Multimedia (Sound Effects Not Working): If the launcher won't start or sound effects don't work, you may need Qt Multimedia packages:

# Debian / Ubuntu / Mint:
sudo apt install python3-pyqt6.qtmultimedia

# Fedora:
sudo dnf install python3-qt6-qtmultimedia

# Arch:
sudo pacman -S python-pyqt6-multimedia

Permission Denied:

chmod +x TvLauncher_Linux.py

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• SteamGridDB - For providing game artwork API
• PyQt6 - For the UI framework
• pygame - For gamepad support
• Community contributors and testers

Known Issues

• Windows: Some executables may need administrator privileges
• All: Background images should be high resolution (1920x1080+) for best results

📧 Contact

For issues, questions, or suggestions, please open an issue on GitHub.

---

⭐ Star this repo if you find it useful!

Made with ❤️ by Darkvinx88