KeyTune

KeyTune is a media player built with Python, wxPython, and MPV.

KeyTune 2 also includes a permission-based plugin platform, process-isolated plugin lifecycle, accessible plugin manager, verified package installer, and a GitHub-friendly marketplace workflow. See the plugin developer and marketplace guide (Português, Español).

It focuses on playlist management, folder browsing, session restore, and persistent user preferences.

Features

• Embedded MPV playback inside a wxPython window
• Tabbed playlists and a folder explorer next to the tabs (Ctrl+E)
• .m3u and .m3u8 playlist loading and saving
• Session restore for tabs, playback position, volume, and the current item
• Persistent preferences stored in settings.json
• Recent files, folders, and playlists
• Item search inside the active playlist or folder (Ctrl+F, F3, Shift+F3)
• Smart library: FTS5-backed global search across indexed playlists and folders (Ctrl+G)
• Favorites (Ctrl+D) and star ratings (Ctrl+0–Ctrl+5) for local media, shown inline in the item list
• Local playback history with all-plays, grouped, and most-played views (Ctrl+Shift+H)
• Per-file resume for podcasts, audiobooks, and other long-form media, plus a "continue listening" list (Ctrl+Shift+R)
• Smart playlists: saved rules (favorites, rating, folder, staleness, play count) rebuilt on every open
• AutoDJ sessions with a visible rolling queue, per-track state, preparation controls, multi-track planning, downbeat/section/key/vocal analysis, loudness-aware selection, phrase alignment, tempo matching, and profile-specific bass/EQ mixing
• Sleep timer with preset durations, a custom duration, or an end-of-track stop (Ctrl+Shift+D)
• Built-in equalizer presets plus custom presets
• KeyTube (Ctrl+Shift+Y): YouTube Music and YouTube in one list, with search, link-based open flows, channels, subscriptions, comments, details, library refresh, and account-synced likes/dislikes
• Online radio from the Radio Browser directory (Ctrl+Shift+N), with favorites, recents, and browsing by country, genre, and language
• Optional YouTube Music related-content autoplay (radio) when a playlist ends
• YouTube live broadcasts from a link, with audio and optional video (Ctrl+Alt+V toggles video output), automatic reconnection, and accessible status announcements
• Audio and video conversion between formats (Ctrl+Shift+K, File > Convert): audio to video, video to audio, audio to audio, and video to video, powered by FFmpeg
• Batch download and conversion: the selected list items or a whole YouTube playlist (into a folder named after it), and several local files at once, from the list's context menu
• Download of the current YouTube or YouTube Music media as audio (original, MP3, FLAC) or video with Ctrl+Shift+B, using yt-dlp, with configurable quality, sample rate, and folder in a new Download preferences tab
• Fresh per-track YouTube Music radio (Ctrl+R) with recent-playback repeat suppression
• Keyboard customization (Settings > Customize keyboard): change, remove, or restore any shortcut, with conflict checks
• Global shortcuts (Windows) for playback, volume, status, and showing or hiding the window, plus a system tray icon with minimize/close-to-tray options

Requirements

• Python 3.14
• python-mpv installed in the active Python environment
• A compatible libmpv runtime available in one of these locations:
  • a local mpv/ folder
  • the path pointed to by MPV_HOME
  • the path pointed to by MPV_DLL_DIR
  • a supported Chocolatey installation path

Installation

Python 3.14 is required for source development and is also used by the Windows release build.

1. Clone the repository.

   git clone https://github.com/Ed-Fe/KeyTune.git
   cd KeyTune

2. Install uv.

3. Install dependencies. This creates .venv with Python 3.14 and installs the exact versions pinned in uv.lock.

   uv sync

   The command also installs the optional YouTube Music and AutoDJ integrations for source-tree development. Release builds publish these components separately and the installed app downloads them only after the user enables and confirms the corresponding feature.

4. Download the MPV runtime for local development.

   uv run python scripts/download_mpv_runtime.py

   This helper downloads the latest mpv-winbuild release, extracts the folder containing libmpv-2.dll, and writes it to ./mpv/ by default. It depends on 7z or 7-Zip to unpack the .7z archive.

   If you already have a compatible runtime in another location, you can skip this step and point MPV_HOME, MPV_DLL_DIR, or a Chocolatey installation to it.

5. Run the application.

   uv run keytune

Usage

Useful project links:

• User manual
• Roadmap
• Releases
• Issues
• Discussions
• Pull requests

Windows Release

The Windows release workflow is defined in .github/workflows/release-windows.yml. It builds the app, bundles the MPV runtime, compiles the Inno Setup installer (installer/keytune.iss), and publishes KeyTune-Setup.exe plus the matching SHA256 file.

The installer supports both per-user (no admin) and per-machine installs, registers KeyTune for Windows "Default apps", and drives updates: the app downloads KeyTune-Setup.exe and runs it silently to upgrade in place, then relaunches.

For a repeatable end-to-end updater test flow, see docs/update-testing.md.

Project Structure

• src/main.py — application entry point
• src/player/app.py — wx application bootstrap
• src/player/frames/base.py — main window coordinator and mixin composition
• src/player/frames/ui.py — menus, layout, and UI bindings
• src/player/frames/commands.py — event handlers, dialogs, and shortcuts
• src/player/frames/playback.py — playback control and MPV integration
• src/player/frames/library.py — library mixin composition
• src/player/frames/library_tabs.py — tab state, selection, and ordering behavior
• src/player/frames/library_loader.py — background loading for folders and playlists
• src/player/frames/library_navigation.py — folder navigation and browser refresh flows
• src/player/frames/session.py — session capture and restore
• src/player/frames/recents.py — recent items and path helpers
• src/player/playlists/models.py — playlist state and playback order helpers
• src/player/playlists/titles.py — playlist and folder tab naming helpers
• src/player/library/media_scan.py — supported media checks and folder scanning helpers
• src/player/library/playlist_io.py — .m3u / .m3u8 load and save helpers
• src/player/library/browser.py — side panel for playlist and folder navigation
• src/player/library/search_dialog.py — item search dialog (Ctrl+F)
• src/player/frames/item_search.py — item search coordination and result navigation
• src/player/smart_library/ — smart library storage (SQLite index, favorites, ratings, history, resume, metadata cache)
• src/player/smart_library/search_dialog.py — global library search dialog (Ctrl+G)
• src/player/smart_library/history_dialog.py — playback history dialog (Ctrl+Shift+H)
• src/player/smart_library/smart_playlists.py — smart playlist rules and their query builder
• src/player/smart_library/smart_playlist_dialog.py — smart playlist manager and rule editor
• src/player/frames/smart_library/ — window behavior for the smart library
• src/player/frames/sleep_timer.py — sleep timer scheduling and countdown handling
• src/player/sleep_timer/dialog.py — sleep timer configuration dialog
• src/player/keyboard/ — shortcut catalog, customization rules, and the keyboard customization dialog
• src/player/frames/keyboard.py, global_hotkeys.py, tray.py — custom shortcuts, global hotkeys, and the system tray icon
• src/player/preferences/dialog.py — preferences UI
• src/player/preferences/models.py — persistent user settings model
• src/player/preferences/storage.py — persistent user settings storage
• src/player/session.py — session persistence
• src/player/accessibility.py — shared UI helpers

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for the recommended workflow, local setup, and validation steps.

In short:

1. Fork the repository and create a feature branch.
2. Make focused changes that match the existing architecture.
3. Run the relevant validation before opening a pull request.
4. Describe the behavior change clearly in the PR description.