Metadata-Version: 2.4
Name: tuatara
Version: 0.6.2
Summary: Tuatara is a text-mode music player.
License: GPL-3.0-or-later
License-File: LICENSE.txt
Keywords: music,media,player
Author: Bill Nottingham
Author-email: notting@splat.cc
Requires-Python: >=3.11,<3.15
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Classifier: Topic :: Multimedia :: Sound/Audio :: Players :: MP3
Requires-Dist: blessed (>=1.21.0,<2.0.0)
Requires-Dist: m3u8 (>=6.0.0,<7.0.0)
Requires-Dist: pillow (>=11.3.0,<12.0.0)
Requires-Dist: pygobject (>=3.46.0,<4.0.0)
Requires-Dist: urllib3 (>=2.1.0,<3.0.0)
Project-URL: Repository, https://github.com/wenottingham/tuatara
Description-Content-Type: text/markdown


tuatara
=======

tuatara is a text-mode music player, written in Python.

# Description

tuatara plays local music files. It can play single files, or play
an entire music library.

## Features

- Simple keyboard controls
- Shuffle mode
- Basic playlist support via .m3u files
- Integrated cover art display
- Dynamic background color
- Visualization support

tuatara is not intended for interactive browsing of your library;
tell it what to play, and it plays it.

## Screenshot

![Screenshot](https://github.com/wenottingham/tuatara/raw/main/assets/screenshot.png)

# Usage

To start with tuatara, just pass a file, directory of music files, or a URL
on the commandline.

Example:
```
tuatara /path/to/my/music/library /path/to/some/other/files
```

You can pass multiple files or directories to play on the command line.

## Controls

tuatara is controlled by the keyboard. Basic keys are:

- Space bar: toggle Play/Pause
- 'p', PageUp: Previous track
- 'n', PageDown: Next track
- 'm': Toggle mute
- 'h', '?': Show full keybindings
- 'q': Quit

Controls are not case-sensitive.

For more comprehensive documentation on features, usage, controls, and
configuration, see the [manual](https://github.com/wenottingham/tuatara/blob/main/MANUAL.md).

# Requirements and installation

System requirements:
- Python >= 3.11
- GStreamer (with appropriate plugins)
- GObject-introspection

Python requirements:
- PyGObject
- Pillow
- urllib3
- m3u8
- blessed

tuatara can be installed from [PyPI](https://pypi.org/project/tuatara/), or
from the [Releases](https://github.com/wenottingham/tuatara/releases) page on GitHub.

To install from Pypi, run:
```
pip install tuatara
```

tuatara is only tested on Linux. macOS or Windows may theoretically work.

# Development

When submitting changes:
- Please add tests in tests/ if it is a testable change
- Ensure code passes both lint and formatting with `ruff` (https://docs.astral.sh/ruff/)

# License & Credits

tuatara is licensed under the GPL, version 3.0 or later.

Python ASCII art implementation inspired and cribbed from
[ascii-wizard](https://pypi.org/project/ascii-wizard/) and
[artem](https://docs.rs/artem/latest/artem/index.html).

# Why 'tuatara'?

The tuatara is a reptile, native to New Zealand. It is the sole surviving
member of the Rhynchocephalia order; its lineage split from modern snakes
and lizards well over 200 million years ago.

Hence, despite existing to this day, it appears to be a relic of a far bygone
era. Much like this software.

