Metadata-Version: 2.4
Name: ytmx
Version: 1.0.1
Summary: A full-featured YouTube Music TUI client for the terminal
Project-URL: Homepage, https://github.com/Villoh/ytmx
Project-URL: Repository, https://github.com/Villoh/ytmx
Project-URL: Bug Tracker, https://github.com/Villoh/ytmx/issues
Project-URL: Changelog, https://github.com/Villoh/ytmx/blob/master/CHANGELOG.md
Author-email: Villoh <mikelvillotatic@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: mpv,music-player,terminal,textual,tui,youtube-music
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: click>=8.1.0
Requires-Dist: pillow>=10.0
Requires-Dist: pynput>=1.7.6; sys_platform == 'win32'
Requires-Dist: pyobjc-framework-mediaplayer>=11.0; sys_platform == 'darwin'
Requires-Dist: pyobjc-framework-quartz>=11.0; sys_platform == 'darwin'
Requires-Dist: python-mpv>=1.0.0
Requires-Dist: textual<8.0,>=7.0
Requires-Dist: yt-dlp>=2025.1.0
Requires-Dist: ytmusicapi>=1.11.0
Provides-Extra: dev
Requires-Dist: anyascii>=0.3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: discord
Requires-Dist: pypresence>=4.3.0; extra == 'discord'
Provides-Extra: images
Provides-Extra: lastfm
Requires-Dist: pylast>=5.0.0; extra == 'lastfm'
Provides-Extra: mpris
Requires-Dist: dbus-next>=0.2.3; extra == 'mpris'
Provides-Extra: spotify
Requires-Dist: spotifyscraper>=2.0.0; extra == 'spotify'
Requires-Dist: spotipy>=2.24.0; extra == 'spotify'
Requires-Dist: thefuzz>=0.22.0; extra == 'spotify'
Provides-Extra: transliteration
Requires-Dist: anyascii>=0.3.0; extra == 'transliteration'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/logo.png" alt="ytmx" />
</p>

<p align="center">
  A full-featured YouTube Music TUI client for the terminal.<br/>
  Browse your library, search, queue tracks, and control playback — all with vim-style keybindings.
</p>

<p align="center">
  <a href="https://pypi.org/project/ytmx/"><img src="https://img.shields.io/pypi/v/ytmx?style=for-the-badge&logo=pypi&color=ff0000&labelColor=0f0f0f&logoColor=ff4e45" alt="PyPI"></a>
  <a href="https://pypi.org/project/ytmx/"><img src="https://img.shields.io/pypi/pyversions/ytmx?style=for-the-badge&logo=python&color=ff0000&labelColor=0f0f0f&logoColor=ff4e45" alt="Python"></a>
  <a href="https://github.com/Villoh/ytmx/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Villoh/ytmx/ci.yml?style=for-the-badge&logo=githubactions&labelColor=0f0f0f&logoColor=ff4e45" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/Villoh/ytmx?style=for-the-badge&color=ff0000&labelColor=0f0f0f" alt="License"></a>

</p>

<p align="center">
  <a href="#what-is-it">What is it?</a> · <a href="#quick-start">Quick start</a> · <a href="#features">Features</a> · <a href="#documentation">Documentation</a> · <a href="CONTRIBUTING.md">Contributing</a> · <a href="CHANGELOG.md">Changelog</a> · <a href="#credits">Credits</a>
</p>

---

## What is it?

ytmx is a terminal-based YouTube Music client. It gives you a full-featured music experience — library browsing, search, queues, synced lyrics, playlists — entirely from the keyboard, without opening a browser. It runs on Linux, macOS, and Windows.

It is a hard fork of [ytm-player](https://github.com/peternaame-boop/ytm-player), extended with features the original project does not intend to support.

## Quick start

```bash
pip install ytmx
ytmx setup   # authenticate with your YouTube Music account
ytmx         # launch the TUI
```

> **System dependency:** [`mpv`](https://mpv.io/) must be installed — see [Installation](docs/installation.md) for platform-specific instructions.

## Documentation

- [Installation](docs/installation.md) — all platforms (Linux, macOS, Windows, NixOS, AUR)
- [Configuration](docs/configuration.md) — `config.toml`, custom themes
- [Keybindings](docs/keybindings.md) — keyboard and mouse reference
- [CLI reference](docs/cli.md) — headless commands and IPC control
- [Spotify import](docs/spotify-import.md) — import playlists from Spotify
- [Troubleshooting](docs/troubleshooting.md)

## Features

- Full playback control via mpv — gapless audio, stream prefetching, shuffle, repeat
- Synced lyrics with LRCLIB.net fallback and ASCII transliteration toggle
- 8 pages — Library, Search, Browse, Context, Queue, Liked Songs, Recently Played, Help
- Vim-style navigation with multi-key sequences and count prefixes
- Custom themes via `~/.config/ytmx/themes/`
- Session resume — queue, volume, shuffle/repeat, theme persist across restarts
- MPRIS/D-Bus (Linux), Now Playing (macOS), media keys (Windows)
- Discord Rich Presence, Last.fm scrobbling
- Spotify playlist import, offline downloads, audio caching
- IPC control — drive the TUI from another terminal or script

## Credits

ytmx is a hard fork of [ytm-player](https://github.com/peternaame-boop/ytm-player) by [peternaame-boop](https://github.com/peternaame-boop).
Built on top of [Textual](https://textual.textualize.io/), [ytmusicapi](https://github.com/sigma67/ytmusicapi), [yt-dlp](https://github.com/yt-dlp/yt-dlp), and [python-mpv](https://github.com/jaseg/python-mpv).

## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md).

## Security vulnerabilities

See [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE)
