Metadata-Version: 2.4
Name: cisap
Version: 0.3.0
Summary: A terminal audio player for local files and Navidrome servers
Author-email: Kasra Madadipouya <kasra@madadipouya.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/kasramp/CISAP
Project-URL: Repository, https://github.com/kasramp/CISAP
Project-URL: Issues, https://github.com/kasramp/CISAP/issues
Keywords: audio,music,player,navidrome,subsonic,mpv,tui,textual,cli
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: POSIX :: BSD :: OpenBSD
Classifier: Operating System :: POSIX :: BSD :: FreeBSD
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=8.2
Requires-Dist: mpv>=1.0.7
Requires-Dist: mutagen>=1.47
Dynamic: license-file

# CISAP

CISAP Is Simple Audio Player: a terminal audio player for local files, playlists, network streams and [Navidrome](https://www.navidrome.org) servers. Started in 2012 as a C program, now Python with Textual and libmpv.

<p align="center">
<img src="https://raw.githubusercontent.com/kasramp/CISAP/HEAD/docs/screenshot.png" alt="CISAP"/>
</p>

## Requirements

- Linux, OpenBSD or FreeBSD (see [Notes](#notes))
- Python 3.11+
- mpv / libmpv from your OS (CISAP decodes audio with it)

## Installation

### Quick install (recommended)

Install mpv and pipx for your OS, then CISAP:

```
$ pacman -S mpv python-pipx           # Arch
$ apt install libmpv2 pipx            # Debian 12+, Ubuntu 24.04+
$ pkg_add mpv py3-pipx                # OpenBSD
$ pkg install mpv py311-pipx          # FreeBSD
$ pipx install cisap
```

Or with pip:

```
$ pip install cisap
```

Then run:

```
$ cisap
```

### From source

```
$ git clone https://github.com/kasramp/CISAP
$ cd CISAP
$ python -m venv .venv && source .venv/bin/activate
$ pip install .
$ cisap
```

## First run

`cisap abc.mp3` starts playing at once. `cisap` alone restores the queue saved at the last quit (`~/.local/state/cisap/queue.m3u`) with the cursor on the last-played song and waits for `Space`; the first time it starts empty: press `o` to browse local files or `n` for Navidrome. The theme and your Navidrome servers are saved in `~/.config/cisap/config.toml` (mode 600).

## Usage

```
cisap [--shuffle] [--loop N] [PATH|DIR|FILE.m3u|URL ...]
cisap --help | --version | --man | --install-man
```

All arguments go into one queue, in order, and the first starts playing. A directory adds its audio files recursively, an `.m3u` adds its entries and an `http(s)://` URL is streamed. `--shuffle` shuffles the items given (not a restored queue), `--loop N` plays the queue N times (`-1` forever).

| Key                       | Action                                              |
|---------------------------|-----------------------------------------------------|
| `>` `l` / `<` `h`         | Next / previous track                               |
| `+` / `-`                 | Volume up / down                                    |
| `m`                       | Mute                                                |
| `[` / `]`                 | Pan left / right                                    |
| `p`                       | Centre pan                                          |
| `{` / `}`                 | Slower / faster, tape style                         |
| `f`                       | Reset speed                                         |
| `←` / `→`                 | Seek -/+10 s                                        |
| `↓` / `↑`                 | Seek -/+1 min                                       |
| `Shift+↓` / `Shift+↑`     | Seek -/+10 min (PgDn / PgUp in v0.2)                |
| `Space`                   | Pause / continue; when stopped, play the selected entry |
| `q`, `Ctrl+C`             | Quit                                                |
| `1`-`7`                   | Toggle effects                                      |
| `o`                       | Local file browser                                  |
| `n`                       | Navidrome browser                                   |
| `s` / `r`                 | Shuffle / repeat (off, all, one)                    |
| `S`                       | Save the queue as `.m3u`                            |
| `C`                       | Clear the queue                                     |
| `Del`                     | Remove the selected entry                           |
| `J` / `K`                 | Move the selected entry down / up                   |
| `j` / `k`, `Enter`        | Move in the queue / play the selected entry         |
| `g` / `G`, `PgUp` / `PgDn`| Queue top / bottom, page up / down                  |
| `/`                       | Search the queue: Enter next match, Esc closes      |
| `.`                       | Jump to the playing entry (the cursor follows playback while it is on it) |
| `t`                       | Theme picker                                        |
| `?`                       | Help screen                                         |
| `Esc`                     | Close the open browser or dialog; never quits       |

### Local files

Press `o` for the file browser.

| Key (in the browser)      | Action                                              |
|---------------------------|-----------------------------------------------------|
| `Enter`                   | Open a folder / add a file (an `.m3u` adds its entries) |
| `Space`                   | Mark / unmark                                       |
| `a`                       | Add the marked entries, or the highlighted file or folder (recursively) |
| `A`                       | Add every folder (recursively) and audio file in the current folder; playlists are skipped |
| `Backspace`               | Go up                                               |
| `Esc`                     | Close the browser                                   |

### Navidrome

Press `n`, add a server (name, URL, user, password; it is tested before it is saved) and open it. A URL without a scheme tries `https://` first, then `http://`.

| Key (in the browser)      | Action                                              |
|---------------------------|-----------------------------------------------------|
| `Enter`, `Backspace`      | Open / go up (Enter on a song plays it; on an album's `▶ Play album` row plays the album) |
| `a`                       | Add the song, album or artist to the queue          |
| `d`                       | Download the song, album or artist (asks first when more than one album is involved) |
| `A` / `D`                 | Add / download every artist (`D` asks first)        |
| `/`                       | Search                                              |

Songs stream from the server. Downloads go to `~/Music/Navidrome/<server>/<song path from the server>`; files already there are skipped.

Saved playlists (`S`, default folder `~/Music/Playlists/`) are extended m3u files. A downloaded song is saved as its local path, any other Navidrome song as `navidrome://<server name>/<song id>`, so no address or password is ever written to a playlist. Other players will not understand those lines.

## Man pages

```
$ cisap --man              # read cisap(1) without installing it
$ cisap --install-man      # install cisap(1) and cisap.conf(5) system-wide
```

## History

- **v0.1** (2012-2014): C on FMOD Ex 4.40. Branches `master` and `v0.1`.
- **v0.2** (2016-2018): C++ on FMOD 1.07 and ncurses, lyrics, man page, shuffle. Branch `v0.2(testing-c++)`. [Screenshot of v0.2](https://user-images.githubusercontent.com/4501120/47316270-046bdd00-d647-11e8-8bfb-491ac37cdb91.png).
- **v0.3** (2026): Python, Textual and libmpv, so it runs on Linux, OpenBSD and FreeBSD. Navidrome added, effects 1-7 restored, lyrics removed. The old keys keep their meaning, except the 10 min seek.

The old `--playlist FILE` and `--stream URL` options are still accepted.

## Notes

- Linux is what CISAP is developed and tested on. OpenBSD and FreeBSD support comes from documentation (the packages above and the BSD `man` tools); it has not been tested on real BSD machines yet.
- Lyrics (`w`) were removed in v0.3.
- The 10 min seek keys moved to `Shift+↓` / `Shift+↑` because `PgUp` / `PgDn` now page the queue.

## Contact

- kasra@madadipouya.com

## License

CISAP is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

CISAP is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.  <http://www.gnu.org/licenses/>

Author(s):

© 2012-2026 Kasra Madadipouya <kasra@madadipouya.com>
