github-mirrors/librespot
1
0
Fork 0
mirror of https://github.com/librespot-org/librespot.git synced 2024-09-19 16:08:30 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update documentation

Browse source
This commit is contained in:
Roderick van Domburg 2021-07-09 21:02:48 +02:00
parent 68bec41e08
commit 2541f123bc
No known key found for this signature in database
GPG key ID: FE2585E713F9F30A
3 changed files with 32 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
COMPILING.md
View file

@ -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```.

21
CONTRIBUTING.md
View file

@ -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"

12
README.md
View file

@ -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`._