From 2541f123bcbb69454de901f48785988df61a7d68 Mon Sep 17 00:00:00 2001 From: Roderick van Domburg Date: Fri, 9 Jul 2021 21:02:48 +0200 Subject: [PATCH 1/2] Update documentation --- COMPILING.md | 25 +++++++++++-------------- CONTRIBUTING.md | 21 ++++++++++++++------- README.md | 12 +++++++----- 3 files changed, 32 insertions(+), 26 deletions(-) diff --git a/COMPILING.md b/COMPILING.md index 8748cd0c..39ae20cc 100644 --- a/COMPILING.md +++ b/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: - -```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. +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. *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 over Rodio | `libjack-dev` | `jack-audio-connection-kit-devel` | - | -|SDL | `libsdl2-dev` | `SDL2-devel` | | -|Pipe | - | - | - | +|JACK | `libjack-dev` | `jack-audio-connection-kit-devel` | `jack` | +|JACK over Rodio | `libjack-dev` | `jack-audio-connection-kit-devel` | `jack` | +|SDL | `libsdl2-dev` | `SDL2-devel` | `sdl2` | +|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```. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3395529c..907a7c04 100644 --- a/CONTRIBUTING.md +++ b/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 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. - - 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 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, 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 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" diff --git a/README.md b/README.md index bcf73cac..f557cbc4 100644 --- a/README.md +++ b/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`._ From bd350c5aa0ebbea0769e11be79258d7087c9220b Mon Sep 17 00:00:00 2001 From: Roderick van Domburg Date: Fri, 9 Jul 2021 22:30:49 +0200 Subject: [PATCH 2/2] Remove non-working Facebook authentication --- docs/authentication.md | 18 +----------------- 1 file changed, 1 insertion(+), 17 deletions(-) diff --git a/docs/authentication.md b/docs/authentication.md index 86470161..2eeb5645 100644 --- a/docs/authentication.md +++ b/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 -`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`. - +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.