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/RB
System Controls - Built-in Restart/Shutdown/Sleep options
Customizable Controls - Remap any keyboard key or remote button to your liking
Parental Control System - Lock the Launcher with a PIN code

Screenshots

System Menu

Key Mapper and battery Widget

Parental Control

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.3

Added
- Full Parental Control System
  - 4-digit PIN protection stored as SHA-256 with a randomly generated per-user salt (never stored in plain text).
    Once set, user will be asked for the PIN at startup.
  - Security question & answer backup stored as SHA-256 with independent salt
  - 6 built-in security questions to choose from during setup
  - Brute-force protection: 5 failed PIN attempts trigger a 30-second lockout with a live countdown
  - Configure or Disable directly in the Settings Menu
  - Mouse,Keyboard,Remote and Game pads input supported
  - Parental Control Data is stored as a JSON in %APPDATA%\Roaming\TVLauncher on
    Windows and ~/.config/TVLauncher on Linux.
Changed
- PyQt temporarily locked to version 6.10 on Windows via requirements due to a regression
  introduced in Qt 6.11 with the Windows DWM compositor.

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)

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

2. Create Virtual Environment and Install Dependencies

Windows:

bash
#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:

bash

# 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:

bash
# 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

Open settings Menu with s or start
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
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
Add App Manually
- Click "Add app"
- Browse for the executable
- Optionally add a custom image
- Click "Add"
Download Covers for Existing Apps
- Click "Download Covers"
- Covers download automatically from SteamGridDB
Customize Background
- Click "Set Background"
- Select an image file (16:9 recommended)
- Background updates immediately
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
Setup Weather Widget (Optional)
- Press S to open Settings
- Navigate to Weather Settings
- Type your city and optional nation code (IT,GB,US etc)
- Click Save and Apply
- Weather Widget will be on top righ corner (it may take 1 second to fetch weather data)
Customize Controls (Optional)
- Press S to open Settings
- Navigate to "🎮 Key Remapper"
- Remap any key to your preference
- Changes apply instantly

Using Categories

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

Managing Categories:

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

Using Quick Search

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

Reordering Apps

Quick Toggle Method:

Press R (keyboard) or RB (gamepad)
Use ←/→ to move the app to desired position
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)

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

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

Method 2: Windows Registry

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

reg
Windows Registry Editor Version 5.00

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

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

Linux Autostart

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

Create autostart directory:

bash
mkdir -p ~/.config/autostart

Create autostart file:

bash
nano ~/.config/autostart/TVLauncher.desktop

Add this content:

ini
[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

Make executable:

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

Launcher will now start automatically on login.

Configuration

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.
A shortcut to these folders is accessible using the given button in the settings menu.

Updating

The launcher now checks for updates on startup and shows a notification in the bottom right corner which leads to the releases page of this repo.
A persistent banner will also be present in the settings menu if an update is available and disappears when the update is done.

🛠️ 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/:

bash
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:

bash
# 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:

bash
# 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:

bash
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