# Pompa: a guide

Pompa (the Personal Organizer Music Player Archive) is Pop Boll's free and open music player. Think of
Winamp with its queue turned on its side: what is playing sits at the top left, and what comes next
lines up beside it, left to right. It keeps one library, the **Pompas Grass Library** (the PGL), and
it never changes your files: a title you fix, an assessment or a hidden flag lives in the library, not in
the file.

Pompa runs on popboll.com today. On your own computer, and on a Bolltridge cart when it is out of its dock,
it comes later.

## On popboll.com

Open **POMPA** from the menu bar at the top of any popboll.com page (it's in the footer too), and sign in.
It's also beside your device's player, and at `popboll.com/pompa`. There, your
library is your Pop Boll's own songs and the corpus recordings your tier lets you hear (CORPUS
recordings need Basic Square, as they do on the device page). Your band's songs play through the band's
own instruments.

## On your computer (coming later)

Pompa for your own computer isn't out yet: it comes later, as a download. This is how it will work.
You'll need Python 3.10 or newer. From the folder that holds Pompa:

```bash
pompa/pompa ~/Music
```

Your browser opens at `http://127.0.0.1:8737/`. Pompa indexes every MP3, FLAC, Ogg, Opus, WAV, AIFF,
M4A, MIDI and tracker module (MOD, S3M, XM, IT and Pop Boll's `.pxs`) file in the folders you give it, looks again every 15 minutes, and keeps its library in
`~/.pompa` (`--data` puts it elsewhere). Add or forget folders later in SETTINGS.

- **MIDI** plays in the page through a small built-in synth. If `fluidsynth` and a General MIDI
  soundfont are installed, Pompa renders MIDI to audio instead, which sounds much better.
- **Tracker modules** play in the page through libopenmpt, the OpenMPT project's own player (BSD-3-Clause), in the
  chiptune3 wrapper (MIT). Both ship with Pompa and load only when a module first plays. Now Playing shows the
  module's own title and message. A `.pxs` exported from Pop Boll plays like any IT module.
- **Play on the computer itself**, not in the page: `pompa/pompa --play-here ~/Music` (needs `ffplay`,
  `mpv`, `afplay` or `paplay`, and `fluidsynth` for MIDI).
- **Only you can reach it.** It answers on your own machine only. `--lan` lets a phone on your network
  in, once it has opened the link with the access key Pompa prints.

## The three views

- **Now Playing**: the controls on top (previous, play or pause, next, stop, the position, the
  volume), your **16 Music Notes** for what is playing, SHARE and SETTINGS. Below them, the playing track
  at the top left and the queue beside it. Each card can play now, move earlier or later, or leave the
  queue. SAVE AS PLAYLIST keeps the queue; when a track ends it leaves the queue for your history, and
  PREVIOUS brings it back.
- **Playlists**: two panes. The playlist you are editing is on top and your library below. `Tab`
  switches pane, `Insert` or `+` adds, `Delete` removes, `Alt` + arrows move, `F2` renames, `F7` makes a
  new one, `Enter` plays.
- **Library**: search, filter by artist, album, genre, key, tempo, assessment, kind and more, and sort. Pick
  entries, then PLAY NOW, PLAY NEXT, APPEND, ADD to a playlist, or HIDE. Hidden is like a game you have
  hidden in a game library: still there, out of the way. "Only hidden" shows them again. DETAILS shows
  everything Pompa read from a file and lets you correct it; your corrections can always be undone.

The keys `1`, `2` and `3` are the Pop Boll's three buttons: 1 plays or pauses (hold: stop), 2 goes back
(hold: share), 3 goes on.

## Your Popmix

Mark one playlist as your **Popmix** (POPMIX in the Playlists view). On popboll.com it appears at
`popboll.com/p/<your pillname>/popmix` while your Pop Boll is public, and nowhere while it is private.
Visitors see every title, and can play your band's songs and the corpus recordings they may hear
themselves; your own files stay yours. On a computer, turn on "Public" in SETTINGS and your Popmix is at
`/popmix` (titles only) and `/popmix.m3u`.

## Music from elsewhere

In SETTINGS, under Remote sources, add:

- **one file** by its address, including a Plex track link;
- **a folder** as a Remote Playlist: a WebDAV folder (Nextcloud, a NAS), a plain web folder listing, or a
  folder with a `MANIFEST.tsv` (as the [hosting guide](hosting-your-own-corpus.md) describes).

On a computer, a user name and password stay in your own library and go only to that server. On
popboll.com your browser plays remote music straight from where it lives, so add addresses your browser
can open by itself; popboll.com stores no passwords and never passes your music through its servers.

## Skins

SETTINGS lists the skins: **Grass** (the default), **Cassette** and **Terminal**. A skin changes shapes,
type, layout and pixel art, never colours of its own: it takes its colours from your palette, so every
skin works with every palette. To make one, with Pompa on your own computer (when it comes), write a small JSON file (the format is
`pompa.skin/1`; `pompa/pompa skin schema` prints it) and run `pompa/pompa --skin my-skin.json ~/Music`:
the page follows your edits as you save. `pompa/pompa skin check my-skin.json` tells you what is wrong
with a file. Put finished skins in `~/.pompa/pompa/skins/`.

## Taking your library with you

With Pompa on your own computer (when it comes), `pompa/pompa export --part own > my-library.json` writes everything about your own files (what you
assessed, hid, edited and put in playlists, keyed by each file's fingerprint) without any password. The
Pop Boll locker will use the same manifest: cheap backup for your music library, which we do not look
at or profile.

Pompa is open source under the Apache License 2.0; its source comes out with the computer version, later. Its hummingbird logo is adapted from the photograph
[Rufous Sabrewing](https://commons.wikimedia.org/wiki/File:Rufous_Sabrewing_JCB.jpg) by Joseph C Boone and is
under that photograph's licence, [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
