Initial commit

README.md

@@ -0,0 +1,56 @@
+# 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`).