# SaraTune

A music player with two modes, switched in the header:

- **Audio**: open a file or a folder and listen right away. A folder browser on the left; the
  playing file's cover, details (format, codec, bitrate, sample rate, ...) and every tag on the
  right. Nothing is saved: no library, no queue, no history. Files opened with SaraTune (e.g.
  "Open with" in a file manager, or `Main.py song.flac`) always open here.
  Keys: space play/pause, left/right seek, up/down previous/next file. The play bar can loop the
  file or carry on to the next one in the folder.
- **Music**: a library of your music folders (Songs, Albums, Artists, with search), a queue with
  shuffle and repeat, and saved playlists. The queue and position are kept between runs.

Each mode has its own player, so switching modes doesn't lose your place; starting one pauses
the other.

## Where things live

| Path | What |
| --- | --- |
| `~/.config/SaraSuite/SaraTune/Config.toml` | settings (Settings > General / Music) |
| `~/.config/SaraSuite/SaraTune/Playlists/<Name>.toml` | one file per playlist: `Name` and `Tracks` (paths, in order) |
| `~/.config/SaraSuite/SaraTune/Session.toml` | Music mode's queue, position, shuffle and repeat |
| `~/.cache/SaraSuite/SaraTune/` | the library's tag cache and cover thumbnails (safe to delete) |

On Windows: `%APPDATA%\SaraSuite\SaraTune\` and `%LOCALAPPDATA%\SaraSuite\SaraTune\`.

Playlists can be imported from and exported to `.m3u`/`.m3u8` (the buttons in the sidebar and on a
playlist's page). Like every SaraSuite program, the theme, font and title bar come from the shared
`~/.config/SaraSuite/Config.toml` unless "uses these shared settings" is off.

## Playback

Playback goes through `flet-audio` (audioplayers), which is only in Flet's **full** desktop
client; SaraTune asks for it (`FLET_DESKTOP_FLAVOR=full`). On Linux that client links against the
system's libmpv and decodes with GStreamer:

```
sudo dnf install mpv-libs
```

Without libmpv, SaraTune shows a page saying so instead of failing to start. What plays depends on
the system's codecs (GStreamer on Linux, Media Foundation on Windows); mp3, flac, ogg, opus, wav
and m4a are tested on Fedora.

Each track gets a fresh player service, and files are passed as `file://` URIs: changing an
existing service's source only works once, and plain paths break on names with `#` or `%`
(see `Player.py`).

## Running and building

- From source: `Packaging/Launch.sh [files...]` (makes `.venv` on the first run).
- Through SaraSuite: the manifest in `Packaging/SaraSuite/` is kept in sync with
  `SaraSuite/Programs/SaraTune/`.
- AppImage: `Packaging/BuildAppImage.sh` builds `dist/SaraTune-x86_64.AppImage` (same recipe as
  SaraSort's and SaraFem's; needs `appimagetool`).