Metadata-Version: 2.4
Name: pympristui
Version: 1.0.7
Summary: TUI MPRIS2 Control
Home-page: https://github.com/apocalyptech/pympristui
Author: CJ Kucera
Author-email: cj@apocalyptech.com
License: zlib/libpng
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: zlib/libpng License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
License-File: COPYING.txt
Requires-Dist: dbus-python>=1.4.0,~=1.4
Requires-Dist: mpris2>=1.0.2,~=1.0
Requires-Dist: urwid>=3.0.3,~=3.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# pympristui (TUI MPRIS2 Control)

This is a tiny little Python script to act as a TUI (Terminal User Interface)
to an [MPRIS2](https://specifications.freedesktop.org/mpris-spec/latest/)-enabled
media player.  MPRIS is a [D-Bus](https://dbus.freedesktop.org/doc/dbus-specification.html)-based
interface which many Linux-based media players support, which allows external
applications to control some aspects of media playback.  This is most often
used to provide little audio applets for desktop environments, or to allow
web-based control of a media player.  This app is intended to provide some
basic controls when (for instance) SSHed in to a machine that's running an
MPRIS-compatible media player.

![App Screenshot](https://raw.githubusercontent.com/apocalyptech/pympristui/master/screenshot.png)

This app has been tested in Python 3.9+, and requires:
 - [dbus-python](https://pypi.org/project/dbus-python/) (tested on 1.2.16)
 - [mpris2](https://pypi.org/project/mpris2/) (tested on 1.0.2)
 - [urwid](https://pypi.org/project/urwid/) (tested on 2.1.2)

It attempts to connect to the [Audacious](https://audacious-media-player.org/)
Media Player by default; to connect to another app instead, you'll have to specify
a commandline arg.

# Installation

I'd recommend using a [virtual environment](https://docs.python.org/3/library/venv.html)
to run the app.  Change to a directory where you want to store your venv,
and create/activate it with:

    $ python -m venv mpris2
    $ . mpris2/bin/activate

You should have an `(mpris2)` prefix on your shell prompt to indicate the
venv is active.  Obviously feel free to name it whatever you like.

### pip Installation

At this point, you can just install using:

    $ pip install pympristui

A `pympristui.py` script should now be available on your `$PATH`.

### Manual Installation

Otherwise, check out the project from git, or download and uncompress an
archive from github.  Then, switch over to this project's dir and install
dependencies, either through:

    $ pip install -r requirements.txt

or by hand:

    $ pip install dbus-python mpris2 urwid

Then run it direct from the CLI (or copy the script anywhere you like):

    $ ./pympristui.py

# Usage

It's a very basic app.  By default it tries to find an MPRIS interface for
the media player Audacious.  If that's not found (or if that's not what you
want to use), you can use the `-p`/`--program` arg to specify another string
to search for.  The string matching here is extremely basic; it'll just pick
the first advertised interface name which matches the string you specify.  If
the specified string isn't found (or if Audacious isn't running, when no `-p`
has been specified), you'll get a list of all available MPRIS interfaces found
on your system, on the commandline, with output like:

    Available Player URIs:
     - org.mpris.MediaPlayer2.firefox.instance319681
     - org.mpris.MediaPlayer2.audacious

To use that `-p`/`--program` argument to connect to that Firefox instance, for
instance:

    $ ./pympristui.py -p firefox
    $ ./pympristui.py --program firefox

Using `instance319681` or even `319681` would also match that Firefox instance.

Once it's started, the app just provides the simple controls pause/play/stop,
next/previous track, and seeking, along with the basic information about what's
being played currently.  It only accepts keyboard input, with the following
keybinds:

 - `space` - play/pause
 - `n` - next track
 - `p` - previous track
 - `<` - Seek 10 seconds back
 - `>` - Seek 10 seconds forward
 - `s` - stop
 - `q` - quit

Note that the "quit" key only quits the control app itself; the actual app
playing audio will continue to run as usual.

# Limitations/TODO

 - I'd originally intended to provide support for MPRIS2's
   [TrackList](https://specifications.freedesktop.org/mpris-spec/latest/Track_List_Interface.html)
   interface, but it turns out the Audacious [doesn't provide that](https://redmine.audacious-media-player.org/issues/106),
   so I didn't look into it any further.  As such, control in the app is limited
   to play/pause/stop, next, and prev.  There's no tracklist visibility, or ability
   to hop around with any control other than next/prev.
 - I didn't implement volume control.
 - The onscreen text just updates every second, so there'll often be a noticeable
   (though brief) lag between hitting a command and having the info update onscreen.
   The commands should be executed immediately, though.
 - This has only been tested against Audacious.  If other MPRIS servers behave
   differently (like maybe not including a total track time or something), this
   might have problems.

# License

All code in this project is licensed under the
[zlib/libpng license](https://opensource.org/licenses/Zlib).  A copy is
provided in [COPYING.txt](COPYING.txt).

# Changelog

**v1.0.7** - February 1, 2026
 - Updated requirements to more recent versions of dbus-python and urwid.
   The urwid update in particular is necessary for Python 3.14 compat.
   (No actual code changes to pympristui, though.)

**v1.0.6** - March 9, 2022
 - More user-friendly messages when no MPRIS players can be found
 - More user-friendly message when DBus error is encountered
 - Added `-V`/`--version` argument

**v1.0.5** - June 15, 2021
 - Bah, one more case where missing MPRIS tags would crash the app

**v1.0.4** - June 9, 2021
 - Fixed a couple more cases where missing MPRIS tags would crash the app

**v1.0.3** - May 7, 2021
 - Fixed handling of cases where some tags (such as album) aren't present

**v1.0.2** - March 3, 2021
 - Added forward/reverse seeking

**v1.0.1** - February 26, 2021
 - Use blue coloration for `Paused` notification
 - Include version number in app header
 - Fix up `--help` output a bit

**v1.0.0** - February 24, 2021
 - Initial release

