Merge pull request #822 from roderickvd/update-documentation

Update documentation

COMPILING.md

@@ -5,20 +5,15 @@
 In order to compile librespot, you will first need to set up a suitable Rust build environment, with the necessary dependencies installed. You will need to have a C compiler, Rust, and the development libraries for the audio backend(s) you want installed. These instructions will walk you through setting up a simple build environment.
 
 ### Install Rust
-The easiest, and recommended way to get Rust is to use [rustup](https://rustup.rs). On Unix/MacOS You can install `rustup` with this command:
+The easiest, and recommended way to get Rust is to use [rustup](https://rustup.rs). Once that’s installed, Rust's standard tools should be set up and ready to use.
-
-```bash
-curl https://sh.rustup.rs -sSf | sh
-```
-
-Follow any prompts it gives you to install Rust. Once that’s done, Rust's standard tools should be setup and ready to use.
 
 *Note: The current minimum required Rust version at the time of writing is 1.48, you can find the current minimum version specified in the `.github/workflow/test.yml` file.*
 
 #### Additional Rust tools - `rustfmt`
-To ensure a consistent codebase, we utilise [`rustfmt`](https://github.com/rust-lang/rustfmt), which is installed by default with `rustup` these days, else it can be installed manually with:
+To ensure a consistent codebase, we utilise [`rustfmt`](https://github.com/rust-lang/rustfmt) and [`clippy`](https://github.com/rust-lang/rust-clippy), which are installed by default with `rustup` these days, else they can be installed manually with:
 ```bash
 rustup component add rustfmt
+rustup component add clippy
 ```
 Using `rustfmt` is not optional, as our CI checks against this repo's rules.
 
@@ -43,12 +38,13 @@ Depending on the chosen backend, specific development libraries are required.
 |--------------------|------------------------------|-----------------------------------|-------------|
 |Rodio (default)     | `libasound2-dev`             | `alsa-lib-devel`                  |             |
 |ALSA                | `libasound2-dev, pkg-config` | `alsa-lib-devel`                  |             |
+|GStreamer | `gstreamer1.0-plugins-base libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-good libgstreamer-plugins-good1.0-dev` | `gstreamer1 gstreamer1-devel gstreamer1-plugins-base-devel gstreamer1-plugins-good` | `gstreamer gst-devtools gst-plugins-base gst-plugins-good` |
 |PortAudio           | `portaudio19-dev`            | `portaudio-devel`                 | `portaudio` |
 |PulseAudio          | `libpulse-dev`               | `pulseaudio-libs-devel`           |             |
-|JACK                | `libjack-dev`                | `jack-audio-connection-kit-devel` |             |
+|JACK                | `libjack-dev`                | `jack-audio-connection-kit-devel` |  `jack`     |
-|JACK over Rodio     | `libjack-dev`                | `jack-audio-connection-kit-devel` |  -          |
+|JACK over Rodio     | `libjack-dev`                | `jack-audio-connection-kit-devel` |  `jack`     |
-|SDL                 | `libsdl2-dev`                | `SDL2-devel`                      |             |
+|SDL                 | `libsdl2-dev`                | `SDL2-devel`                      |  `sdl2`     |
-|Pipe                |  -                           |  -                                |  -          |
+|Pipe & subprocess   |  -                           |  -                                |  -          |
 
 ###### For example, to build an ALSA based backend, you would need to run the following to install the required dependencies:
 
@@ -68,7 +64,6 @@ The recommended method is to first fork the repo, so that you have a copy that y
 
 ```bash
 git clone git@github.com:YOURUSERNAME/librespot.git
-cd librespot
 ```
 
 ## Compiling & Running
@@ -109,7 +104,9 @@ cargo build --no-default-features --features "alsa-backend"
 Assuming you just compiled a ```debug``` build, you can run librespot with the following command:
 
 ```bash
-./target/debug/librespot -n Librespot
+./target/debug/librespot
 ```
 
 There are various runtime options, documented in the wiki, and visible by running librespot with the ```-h``` argument.
+
+Note that debug builds may cause buffer underruns and choppy audio when dithering is enabled (which it is by default). You can disable dithering with ```--dither none```.

CONTRIBUTING.md

@@ -8,10 +8,12 @@ If you have encountered a bug, please report it, as we rely on user reports to f
 
 Please also make sure that your issues are helpful. To ensure that your issue is helpful, please read over this brief checklist to avoid the more common pitfalls:
 
-	- Please take a moment to search/read previous similar issues to ensure you aren’t posting a duplicate. Duplicates will be closed immediately.
+- Please take a moment to search/read previous similar issues to ensure you aren’t posting a duplicate. Duplicates will be closed immediately.
-	- Please include a clear description of what the issue is. Issues with descriptions such as ‘It hangs after 40 minutes’ will be closed immediately.
+- Please include a clear description of what the issue is. Issues with descriptions such as ‘It hangs after 40 minutes’ will be closed immediately.
-	- Please include, where possible, steps to reproduce the bug, along with any other material that is related to the bug. For example, if librespot consistently crashes when you try to play a song, please include the Spotify URI of that song. This can be immensely helpful in quickly pinpointing and resolving issues.
+- Please include, where possible, steps to reproduce the bug, along with any other material that is related to the bug. For example, if librespot consistently crashes when you try to play a song, please include the Spotify URI of that song. This can be immensely helpful in quickly pinpointing and resolving issues.
-	- Lastly, and perhaps most importantly, please include a backtrace where possible. Recent versions of librespot should produce these automatically when it crashes, and print them to the console, but in some cases, you may need to run ‘export RUST_BACKTRACE=full’ before running librespot to enable backtraces.
+- Please be alert and respond to questions asked by any project members. Stale issues will be closed.
+- When your issue concerns audio playback, please first make sure that your audio system is set up correctly and can play audio from other applications. This project aims to provide correct audio backends, not to provide Linux support to end users.
+- Lastly, and perhaps most importantly, please include a backtrace where possible. Recent versions of librespot should produce these automatically when it crashes, and print them to the console, but in some cases, you may need to run ‘export RUST_BACKTRACE=full’ before running librespot to enable backtraces.
 
 ## Contributing Code
 
@@ -33,16 +35,21 @@ Unless your changes are negligible, please add an entry in the "Unreleased" sect
 
 Make sure that the code is correctly formatted by running:
 ```bash
-cargo +stable fmt --all
+cargo fmt --all
 ```
 
-This command runs the previously installed stable version of ```rustfmt```, a code formatting tool that will automatically correct any formatting that you have used that does not conform with the librespot code style. Once that command has run, you will need to rebuild the project:
+This command runs ```rustfmt```, a code formatting tool that will automatically correct any formatting that you have used that does not conform with the librespot code style. Once that command has run, you will need to rebuild the project:
 
 ```bash
 cargo build
 ```
 
-Once it has built, and you have confirmed there are no warnings or errors, you should commit your changes.
+Once it has built, check for common code mistakes by running:
+```bash
+cargo clippy
+```
+
+Once you have confirmed there are no warnings or errors, you should commit your changes.
 
 ```bash
 git commit -a -m "My fancy fix"

README.md

@@ -2,17 +2,17 @@
 [![Gitter chat](https://badges.gitter.im/librespot-org/librespot.png)](https://gitter.im/librespot-org/spotify-connect-resources)
 [![Crates.io](https://img.shields.io/crates/v/librespot.svg)](https://crates.io/crates/librespot)
 
-Current maintainer is [@awiouy](https://github.com/awiouy) folks.
+Current maintainers are [listed on GitHub](https://github.com/orgs/librespot-org/people).
 
 # librespot
 *librespot* is an open source client library for Spotify. It enables applications to use Spotify's service to control and play music via various backends, and to act as a Spotify Connect receiver. It is an alternative to the official and [now deprecated](https://pyspotify.mopidy.com/en/latest/#libspotify-s-deprecation) closed-source `libspotify`. Additionally, it will provide extra features which are not available in the official library.
 
-_Note: librespot only works with Spotify Premium. This will remain the case for the foreseeable future, as we are unlikely to work on implementing the features such as limited skips and adverts that would be required to make librespot compliant with free accounts._
+_Note: librespot only works with Spotify Premium. This will remain the case. We will not any support features to make librespot compatible with free accounts, such as limited skips and adverts._
 
 ## Quick start
 We're available on [crates.io](https://crates.io/crates/librespot) as the _librespot_ package. Simply run `cargo install librespot` to install librespot on your system. Check the wiki for more info and possible [usage options](https://github.com/librespot-org/librespot/wiki/Options).
 
-After installation, you can run librespot from the CLI using a command such as `librespot -n "Librespot Speaker" -b 160` to create a speaker called _Librespot Speaker_ serving 160kbps audio.
+After installation, you can run librespot from the CLI using a command such as `librespot -n "Librespot Speaker" -b 160` to create a speaker called _Librespot Speaker_ serving 160 kbps audio.
 
 ## This fork
 As the origin by [plietar](https://github.com/plietar/) is no longer actively maintained, this organisation and repository have been set up so that the project may be maintained and upgraded in the future.
@@ -53,12 +53,14 @@ librespot currently offers the following selection of [audio backends](https://g
 ```
 Rodio (default)
 ALSA
+GStreamer
 PortAudio
 PulseAudio
 JACK
 JACK over Rodio
 SDL
 Pipe
+Subprocess
 ```
 Please check the corresponding [compiling entry](https://github.com/librespot-org/librespot/wiki/Compiling#general-dependencies) for backend specific dependencies.
 
@@ -84,9 +86,9 @@ The above is a minimal example. Here is a more fully fledged one:
 ```shell
 target/release/librespot -n "Librespot" -b 320 -c ./cache --enable-volume-normalisation --initial-volume 75 --device-type avr
 ```
-The above command will create a receiver named ```Librespot```, with bitrate set to 320kbps, initial volume at 75%, with volume normalisation enabled, and the device displayed in the app as an Audio/Video Receiver. A folder named ```cache``` will be created/used in the current directory, and be used to cache audio data and credentials.
+The above command will create a receiver named ```Librespot```, with bitrate set to 320 kbps, initial volume at 75%, with volume normalisation enabled, and the device displayed in the app as an Audio/Video Receiver. A folder named ```cache``` will be created/used in the current directory, and be used to cache audio data and credentials.
 
-A full list of runtime options are available [here](https://github.com/librespot-org/librespot/wiki/Options)
+A full list of runtime options is available [here](https://github.com/librespot-org/librespot/wiki/Options).
 
 _Please Note: When using the cache feature, an authentication blob is stored for your account in the cache directory. For security purposes, we recommend that you set directory permissions on the cache directory to `700`._
 

docs/authentication.md

@@ -57,20 +57,4 @@ login_data = AES192-DECRYPT(key, data)
 ```
 
 ## Facebook based Authentication
-The client starts an HTTPS server, and makes the user visit
+Facebook authentication is currently broken due to Spotify changing the authentication flow. The details of how the new flow works are detailed in https://github.com/librespot-org/librespot/issues/244 and will be implemented at some point in the future.
-`https://login.spotify.com/login-facebook-sso/?csrf=CSRF&port=PORT`
-in their browser, where CSRF is a random token, and PORT is the HTTPS server's port.
-
-This will redirect to Facebook, where the user must login and authorize Spotify, and
-finally make a GET request to
-`https://login.spotilocal.com:PORT/login/facebook_login_sso.json?csrf=CSRF&access_token=TOKEN`,
-where PORT and CSRF are the same as sent earlier, and TOKEN is the facebook authentication token.
-
-Since `login.spotilocal.com` resolves the 127.0.0.1, the request is received by the client.
-
-The client must then contact Facebook's API at
-`https://graph.facebook.com/me?fields=id&access_token=TOKEN`
-in order to retrieve the user's Facebook ID.
-
-The Facebook ID is the `username`, the TOKEN the `auth_data`, and `auth_type` is set to `AUTHENTICATION_FACEBOOK_TOKEN`.
-