Update README (#430)

jpochyla · Jun 6, 2023 · c839fab · c839fab
1 parent 56fae74
commit c839fab
Showing 1 changed file with 65 additions and 47 deletions.
diff --git a/README.md b/README.md
@@ -1,59 +1,74 @@
 # Psst
 
-Fast Spotify client with native GUI, without Electron, built in Rust. Very early in development, lacking in features, stability, and general user experience. It is being tested only on Mac so far, but aims for full Windows and Linux support. Contributions welcome!
+A fast Spotify client with a native GUI written in Rust, without Electron.
+Psst is still very early in development, lacking in features, stability, and general user experience.
+It's fully cross-platform, supporting Windows, Linux, and macOS.
+Contributions are welcome!
 
-**Note:** Spotify Premium account is required.
+**Note:** A Spotify Premium account is required.
 
 [![Build](https://github.com/jpochyla/psst/actions/workflows/build.yml/badge.svg)](https://github.com/jpochyla/psst/actions)
 
 ![Screenshot](./psst-gui/assets/screenshot.png)
 
-##### Pre-built binaries
 
-GitHub Actions automatically runs when new commits are pushed to `master`. To download prebuilt binaries for x86_64 macOS, Windows or Ubuntu, [go to the newest successfully built action](https://nightly.link/jpochyla/psst/workflows/build/master).
+## Download
+
+GitHub Actions automatically creates builds when new commits are pushed to the `master` branch.
+You can download the prebuilt binaries for x86_64 Windows, Linux (Ubuntu), and macOS.
 
 | Platform |
 |----------|
 | [Windows](https://nightly.link/jpochyla/psst/workflows/build/master/Psst.exe.zip) |
 | [Linux (Ubuntu)](https://nightly.link/jpochyla/psst/workflows/build/master/psst-gui.zip) |
-| [MacOS](https://nightly.link/jpochyla/psst/workflows/build/master/Psst-x64.dmg.zip) |
 | [Debian Package](https://nightly.link/jpochyla/psst/workflows/build/master/psst-deb.zip) |
+| [MacOS](https://nightly.link/jpochyla/psst/workflows/build/master/Psst-x64.dmg.zip) |
+
+Unofficial builds of Psst are also available through the [AUR](https://aur.archlinux.org/packages/psst-git) and [Homebrew](https://formulae.brew.sh/cask/psst).
+
+
+## Building
+
+On all platforms, the **latest [Rust](https://rustup.rs/) stable** (at least 1.65.0) is required.
+For platform-specific requirements, see the dropdowns below.
 
-##### Linux
+<details>
+<summary>Linux</summary>
 
-Our user-interface library, Druid, has two possible backends to choose from on Linux: GTK and pure X11, with Wayland backend in the works. The default linux backend is GTK. Before building on Linux, make sure the required dependencies are installed. 
+Our user-interface library, Druid, has two possible backends on Linux: GTK and pure X11, with a Wayland backend in the works.
+The default Linux backend is GTK.
+Before building on Linux, make sure the required dependencies are installed.
 
-Debian/Ubuntu:
+#### Debian/Ubuntu:
 
 ```shell
 sudo apt-get install libssl-dev libgtk-3-dev libcairo2-dev libasound2-dev
 ```
 
-RHEL/Fedora:
+#### RHEL/Fedora:
 
 ```shell
 sudo dnf install openssl-devel gtk3-devel cairo-devel alsa-lib-devel
 ```
+</details>
 
-##### BSD (WIP)
+<details>
+<summary>OpenBSD (WIP)</summary>
 
-**Note:** BSD isn't fully supported yet, and you may encounter issues.
-
-Similar to Linux, Druid defaults to GTK while providing an X11 backend as well.
+OpenBSD support is still a WIP, and things will likely not function as intended.
+Similar to Linux, Druid defaults to GTK while also providing a pure X11 backend.
 Furthermore, bindgen must be able to find LLVM through the expected environment variable.
 Only OpenBSD/amd64 has been tested so far.
 
-OpenBSD:
 ```shell
 doas pkg_add gtk+3 cairo llvm
 export LIBCLANG_PATH=/usr/local/lib
 ```
 
 In case rustc(1) fails building bigger crates
 ```shell
-memory allocation of 2880 bytes failed
+memory allocation of xxxx bytes failed
 error: could not compile `gtk`
-
 Caused by:
   process didn't exit successfully: `rustc --crate-name gtk [...]` (signal: 6, SIGABRT: process abort signal)
 warning: build failed, waiting for other jobs to finish...
@@ -63,50 +78,47 @@ try increasing your user's maximum heap size:
 ulimit -d $(( 2 * `ulimit -d` ))
 ```
 
-##### Building
+</details>
 
-On all platforms, the **latest Rust stable** (at least 1.54.0) is needed.
+---
 
-Development build:
+#### Build from Source:
 ```shell
-git submodule update --recursive --init
 cargo build
+# Append `--release` for a release build.
 ```
 
-Release build:
+#### Run from Source:
 ```shell
-git submodule update --recursive --init
-cd psst-gui
-cargo build --release
-# Use `cargo install cargo-bundle` and `cargo bundle --release` for building the installation bundle (i.e. macOS .app)
+cargo run --bin psst-gui
+# Append `--release` for a release build.
 ```
 
-##### Running and configuration
-
+#### Build Installation Bundle (i.e., macOS .app):
 ```shell
-cd psst-gui
-cargo run
-# Use `cargo run --release` for the release build.
+cargo install cargo-bundle
+cargo bundle --release
 ```
 
-##### Roadmap
+
+## Roadmap
 
 - [x] Vorbis track playback
 - [x] Browsing saved albums and tracks
 - [x] Save / unsave albums and tracks
 - [x] Browsing followed playlists
-- [x] Search for artist, albums, and tracks
+- [x] Search for artists, albums, and tracks
 - [x] Podcast support
 - [x] Media keys control
-- [x] Open Spotify links through search bar
+- [x] Open Spotify links through the search bar
 - [x] Audio volume control
 - [x] Audio loudness normalization
 - [x] Genre playlists and "For You" content
 - [x] Dark theme
 - [ ] Resilience to network errors (automatically retry timed-out requests)
 - [ ] Managing playlists
-    - Follow / unfollow
-    - Add / remove track
+    - Follow/unfollow
+    - Add/remove tracks
     - Reorder tracks
     - Rename playlist
     - Playlist folders
@@ -115,7 +127,7 @@ cargo run
     - Pause after disconnecting headphones
     - Transfer playback after connecting headphones
 - [ ] Better caching
-    - Cache as much as possibly of WebAPI responses
+    - Cache as many WebAPI responses as possible
     - Visualize cache utilization
         - Total cache usage in the config dialog
         - Show time origin of cached data, allow to refresh
@@ -124,35 +136,41 @@ cargo run
 - [ ] Reporting played tracks to Spotify servers
 - [ ] OS-specific application bundles
 - UI
-    - [ ] Rethink current design, consider a two-pane layout
+    - [ ] Rethink the current design, consider a two-pane layout
         - Left pane for browsing
         - Right pane for current playback
     - [ ] Detect light/dark OS theme
-    - [ ] Robust error states, ideally with retry button
+    - [ ] Robust error states, ideally with a retry button
     - [ ] Correct playback highlight
-        - Highlight now-playing track only in the correct album / playlist
+        - Highlight now-playing track only in the correct album/playlist
         - Keep highlighted track in viewport
     - [ ] Paging or virtualized lists for albums and tracks
     - [ ] Grid for albums and artists
     - [ ] Robust active/inactive menu visualization
-    - [ ] Save last route, volume, playback state
+    - [ ] Save playback state
 
-##### Development
 
-Contributions are very welcome! Project structure:
+## Development
+
+Contributions are very welcome!  
+Here's the basic project structure:
 
 - `/psst-core` - Core library, takes care of Spotify TCP session, audio file retrieval, decoding, audio output, playback queue, etc.
 - `/psst-gui` - GUI application built with [Druid](https://github.com/linebender/druid)
-- `/psst-cli` - Example CLI that plays a track.  Credentials need to be configured in the code.
+- `/psst-cli` - Example CLI that plays a track.  Credentials must be configured in the code.
 - `/psst-protocol` - Internal Protobuf definitions used for Spotify communication.
 
-##### Privacy Policy
 
-Psst connects only to the official Spotify servers, and does not call home. Cache of various things is stored locally, and can be deleted at any time. User credentials are not stored at all (re-usable authentication token from Spotify is used instead).
+## Privacy Policy
+
+Psst connects only to the official Spotify servers and does not call home.
+Caches of various things are stored locally and can be deleted anytime.
+User credentials are not stored at all; instead, a re-usable authentication token from Spotify is used.
+
 
-##### Thanks
+## Thanks
 
-This project would not exist without:
+This project would not exist without the following:
 
 - Big thank you to [`librespot`](https://github.com/librespot-org/librespot), the Open Source Spotify client library for Rust.  Most of `psst-core` is directly inspired by the ideas and code of `librespot`, although with a few differences:
     - Spotify Connect (remote control) is not supported yet.