TV Launcher

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

Features

• 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
• Mouse/Touch Support - Navigate with mouse or touch controls
• 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
• Streaming Video Wallpapers - Projectivy Overflight-style animated backgrounds, streamed directly (no permanent download)
• Movable Launcher Layout - The carousel can now be shifted vertically to leave room for video wallpapers
• Auto-hiding Bottom Bar - The system button bar (Restart/Sleep/Shutdown/Close) stays hidden off-screen at rest and slides in only when you navigate down to it

Screenshots

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

Video Wallpapers

TV Launcher supports animated, streaming video wallpapers in the style of Projectivy Overflight.

• Source: Videos are streamed from the official Projectivy Overflight JSON catalogue (a custom catalogue URL can also be set)
• No permanent download: videos are streamed live, requires an active internet connection
• Configurable via dialog: Settings → Video Wallpaper lets you set:
  • Video quality (1080p, 1080p HDR, 4K, 4K HDR, or automatic/adaptive)
  • Rotation interval (change video every N minutes)
  • Mute/audio toggle
  • Category filters (leave empty to include all categories)
  • Custom catalogue URL, with a one-click "restore default" option
  • Catalogue refresh and link validation, plus a "Test/Try video" button to preview instantly
• Vertical layout shift: with video wallpapers enabled, the launcher carousel can be moved vertically to leave clean space for the video, similar to Projectivy Launcher on Android TV
• Auto-hiding button bar: the system button bar (Restart/Sleep/Shutdown/Close) stays hidden at rest and slides into view only when navigated to, maximizing the visible video area

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

Dependencies

Python, maybe libmpv

• 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
• python-mpv - Video wallpaper playback (requires libmpv installed at system level on Linux; bundled on Windows)

Installation

git clone ...

# linux
pip install -r requirements.txt

# windows
pip install -r requirements_win.txt

python TvLauncher_[X/Windows/Linux].py

Configuration

Configuration files in %APPDATA%\Roaming\TVLauncher on Windows and in ~/.config/TVLauncher on Linux

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

8. 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)

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

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

Video Wallpaper Not Working / mpv not available:

sudo apt install libmpv2   # or libmpv1 on older Ubuntu/Mint versions
sudo dnf install mpv-libs  # Fedora
sudo pacman -S mpv         # Arch

Check the console for the specific error shown in the Video Wallpaper dialog status label — it usually indicates the missing library directly.

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

📝 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
• Projectivy Launcher - Inspiration for the vertical layout and video wallpaper concept
• Overflight - For the video wallpaper catalogue this feature streams from
• mpv / libmpv - Powers video wallpaper playback.
• The bundled mpv-2.dll (Windows) is distributed under the LGPLv2.1+ license;
• Community contributors and testers