diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index e0c36c8c..95f9ac56 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -2,10 +2,12 @@ [Introduction](./Introduction.md) -- [Installation Instructions](./installation/README.md) - - [Installing on a Raspberry Pi](./installation/Raspberry-Pi.md) +- [Installation & Build Instructions](./installation/README.md) + - [Installing on a Raspberry Pi 32-bit/ARM32](./installation/Raspberry-Pi-32_ARM32.md) + - [Installing on a Raspberry Pi 64-bit/ARM64](./installation/Raspberry-Pi-64_ARM64.md) - [Installing on Ubuntu (from source)](./installation/Ubuntu.md) - [Cross Compiling on Ubuntu](./installation/Cross-Compiling-on-Ubuntu.md) + - [Building on Linux](./installation/Build-on-Linux.md) - [Installing with Homebrew on macOS](./installation/MacOS.md) - [Installing on FreeBSD](./installation/FreeBSD.md) - [Configuration](./config/README.md) @@ -14,4 +16,3 @@ - [Running as a Service](./config/services/README.md) - [Running as systemd service](./config/services/Systemd.md) - [Running as launchd service (MacOS)](./config/services/MacOS.md) - diff --git a/docs/src/config/services/Systemd.md b/docs/src/config/services/Systemd.md index 36bcbe7a..bd3ec578 100644 --- a/docs/src/config/services/Systemd.md +++ b/docs/src/config/services/Systemd.md @@ -17,6 +17,15 @@ Control of the daemon is handed over to systemd. The following command will star systemctl --user enable spotifyd.service --now ``` +To run the service on boot: + +```bash +sudo loginctl enable-linger +``` + +Where is the user name which starts the service, the user wich runned thw systemctl command. +The command is required to enable your user to run long-running services. Without it `systemd` would kill the `spotifyd` process as soon as you log out, and only run it when you log in. + ## As a system wide service A `systemd.service` unit file is provided to help run spotifyd as a service on systemd-based systems. The file `contrib/spotifyd.service` should be copied to: diff --git a/docs/src/installation/Build-on-Linux.md b/docs/src/installation/Build-on-Linux.md new file mode 100644 index 00000000..f87c62d3 --- /dev/null +++ b/docs/src/installation/Build-on-Linux.md @@ -0,0 +1,101 @@ +# Linux build guide + +This guide covers Debian based systems with APT packet manager. + +## Install required packages + +Depending on the distribution and environments, required packages have to be installed. + +Ubuntu Desktop (22.04 LTS): + +```bash +sudo apt install curl git build-essential pkg-config libasound2-dev portaudio19-dev libdbus-1-dev +``` + +Raspberry Pi OS (Bookworm): + +```bash +sudo apt install libasound2-dev portaudio19-dev libdbus-1-dev +``` +> **Note:** Depending on your feature flags, you can also leave packages out, e.g. +> libasound2-dev: no ALSA backend (--no-default-features) +> portaudio19-dev: No PortAudio backend + +## Uninstall the preinstalled rust compiler + +> **Note:** spotifyd may require a newer rust toolchain than the one which is delivered with your Linux system, +> we recommend to uninstall the current version if you are not sure which version you have and if it is sufficient. +> We recommend to always use the latest version and don't guarantee compatibility with older ones. + +If it was installed from apt packet manager: + +```bash +sudo apt remove rustc +``` + +If it was installed from rustup: + +```bash +rustup self uninstall +``` + +## Install the rust toolchain + +To install the latest rust toolchain, follow the installation instructions on [rustup.rs][rustup]. + +Currently it is (chose option 1): + +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +Set up evnironment variables: + +```bash +source "$HOME/.cargo/env" +``` + +## Clone the repository + +Switch to a folder where you want the sources to be downloaded, then: + +```bash +git clone https://github.com/Spotifyd/spotifyd.git +``` + +Swtich to the repository folder: + +```bash +cd spotifyd +``` + +## Building spotifyd + +If you want to build the latest release and not the latest commit, look up the (heading) of the latest release +on https://github.com/Spotifyd/spotifyd/releases or https://github.com/Spotifyd/spotifyd/tags. Then: + +```bash +git checkout tags/v0.3.5 +``` + +Replace v0.3.5 with the desired tag. + +This takes a while... + +```bash +cargo build --release +``` + +If you want it to be build with additional features like DBus and PulseAudio backend: + +```bash +cargo build --release --features dbus_mpris,pulseaudio_backend +``` + +The resulting binary will be placed in `target/release/spotifyd` + +## Running spotifyd + +You can run it using `./target/release/spotifyd` + +[rustup]: https://rustup.rs/ diff --git a/docs/src/installation/Feature-flags.md b/docs/src/installation/Feature-flags.md index 65c5366e..d8d5c705 100644 --- a/docs/src/installation/Feature-flags.md +++ b/docs/src/installation/Feature-flags.md @@ -6,12 +6,14 @@ To enable an additional audio backend, pass `_backend` as a `Spotifyd` provides the following additional functionality: -| Feature Flag | Description | -|--------------|-------------------------------------------------------------------------------------| -| dbus_keyring | Provides password authentication over the system's keyring (supports all platforms) | -| dbus_mpris | Provides multimedia key support (Linux only) | +| Feature Flag | Description | +|------------------------------|-------------------------------------------------------------------------------------| +| dbus_keyring | Provides password authentication over the system's keyring (supports all platforms) | +| dbus_mpris | Provides multimedia key support (Linux only) | +| _backend | Provides other audio backend support (Linux only) | > __Note:__ Compiling Spotifyd with all features and the pulseaudio backend on Ubuntu would result in the following command: `cargo build --release --no-default-features --features pulseaudio_backend,dbus_keyring,dbus_mpris` +> We currently support alsa, pulseaudio and portaudio as audio backends and ## Media controls diff --git a/docs/src/installation/README.md b/docs/src/installation/README.md index 8be76e42..6536adcf 100644 --- a/docs/src/installation/README.md +++ b/docs/src/installation/README.md @@ -31,6 +31,8 @@ You can also compile `Spotifyd` yourself, allowing you to make use of feature fl > __Note:__ The package names for Linux are the ones used on Debian based distributions (like Ubuntu). You will need to adapt the packages for your distribution respectively. +You can find more details about building on Linux [here](Build-on-Linux.md). + To compile the binary, run ```bash diff --git a/docs/src/installation/Raspberry-Pi-32_ARM32.md b/docs/src/installation/Raspberry-Pi-32_ARM32.md new file mode 100644 index 00000000..df7f1af8 --- /dev/null +++ b/docs/src/installation/Raspberry-Pi-32_ARM32.md @@ -0,0 +1,19 @@ +# Raspberry Pi install guide + +This guide will help you to install `spotifyd` on a Raspberry Pi and have it always running. + +## Download + +1. Download the latest ARMv6 from (use `wget`) +2. Unzip the file: `tar xzf spotifyd-linux-arm6*` +You will now see a file called `spotifyd`. You can run it with `./spotifyd --no-daemon` + +It is recommended to copy the file to usr/bin, so that everyone can run it or use it for a service: + +```bash +sudo cp ./spotifyd /usr/bin +``` + +For further configuration see [Run-on-Linux](Run-on-Linux.md) + +To run on a ARM64 only architecture, have a look at [Raspberry-Pi-64_ARM64](Raspberry-Pi-64_ARM64.md). diff --git a/docs/src/installation/Raspberry-Pi-64_ARM64.md b/docs/src/installation/Raspberry-Pi-64_ARM64.md new file mode 100644 index 00000000..d7b47b71 --- /dev/null +++ b/docs/src/installation/Raspberry-Pi-64_ARM64.md @@ -0,0 +1,37 @@ +# 64 bit Raspery OS build guide + +The ARM binaries on the download site are all 32 bit binaries, you cannot easily run them on an OS with ARM64 only architecture like Raspberry Pi OS. +Trying to run them will result in `cannot execute: required file not found`. + +To run spotifyd on a 64 bit Raspberry Pi OS, you have two possiblities. Build the 64 bit binary by yourself or add the 32 bit architecture as +an additional architecture to your 64 bit Raspberry Pi OS. + +Let's start with building the 64 bit version, as it offers you more possibilities like adding the DBus feature for controlling the service with +DBus commands. + +## Option 1: Building the 64 bit version + +See [Build-on-Linux.md](Build-on-Linux.md) + +## Option 2: Add the 32 bit architecture + +### Adding architecture and dependency packages + +These commands add the architecture and install the required packages for the architecure: + +```bash +dpkg --add-architecture armhf +sudo apt update +sudo apt install libasound2-plugins:armhf +``` + +Now you can go on with the [32-bit instructions](Raspberry-Pi-32_ARM32.md), but download the `armhf-slim.tar.gz` file instead of the armv6 file. +The other instructions are the same once you have the binary running. +Downloading other variants like full or default may require further armhf packages to be installed with the command like above: + +```bash +sudo apt install packagename:armhf +``` + +## Run +Now you can go on with the instructions in [Run-on-Linux](Run-on-Linux.md). diff --git a/docs/src/installation/Raspberry-Pi.md b/docs/src/installation/Raspberry-Pi.md deleted file mode 100644 index b241a09c..00000000 --- a/docs/src/installation/Raspberry-Pi.md +++ /dev/null @@ -1,47 +0,0 @@ -# Raspberry Pi install guide - -This guide will help you to install `spotifyd` on a Raspberry Pi and have it always running. - -## Download - -1. Download the latest ARMv6 from (use `wget`) -2. Unzip the file: `tar xzf spotifyd-linux-arm6*` -You will now see a file called `spotifyd`. You can run it with `./spotifyd --no-daemon` - -## Systemd daemon file - -Create a systemd service file and copy the [default configuration](https://github.com/Spotifyd/spotifyd/blob/master/contrib/spotifyd.service) into it. Change **ExecStart** to where you unzipped the `spotifyd` binary. - -```bash -sudo nano /etc/systemd/user/spotifyd.service -``` - -if you want to run as user instead of root or have some `Failed to get D-Bus connection: Connection refused`, you define `spotifyd.service` in your home directory: - -```bash -mkdir -p ~/.config/systemd/user/ -nano ~/.config/systemd/user/spotifyd.service -systemctl --user daemon-reload -``` - -## Configuring spotifyd - -Spotifyd comes pre-configured with defaults that should be working in most cases, but if you want to tweak it further to your needs, have a look at the [configuration section](../config/) of this book. - -## Start the service - -```bash -systemctl --user start spotifyd.service -``` - -Now see if you can find it in the normal Spotify client (Devices in right bottom corner). Retry the above steps if you can't find it. - -## Starting spotifyd at boot - -```bash -sudo loginctl enable-linger -systemctl --user enable spotifyd.service -``` - -The first command is required to enable your user to run long-running services. Without it `systemd` would kill the `spotifyd` process as soon as you log out, and only run it when you log in. -Now `spotifyd` is always running on the Pi, so you can use it as a listening device remotely! diff --git a/docs/src/installation/Run-on-Linux.md b/docs/src/installation/Run-on-Linux.md new file mode 100644 index 00000000..7eeac089 --- /dev/null +++ b/docs/src/installation/Run-on-Linux.md @@ -0,0 +1,120 @@ +# Raspberry Pi install guide + +This guide will help you to install `spotifyd` on a Linux system and have it always running. This guide requires a spotifyd executable wiht full path: /usr/bin/spotifyd. +See specific system installation guides or the [build guide](Build-on-Linux.md) how to set this up. + +## Configuring spotifyd + +Spotifyd comes pre-configured with defaults that should be working in most cases, but if you want to tweak it further to your needs, have a look at the [configuration section](../config/File.md) of this book. + +## Start spotifyd from CLI + +Simply run: + +```bash +/usr/bin/spotifyd --no-daemon +``` + +or if you want to run it in the background: + +```bash +/usr/bin/spotifyd +``` + +Without the --no-daemon argument the process forks itself into the background. + +## Start spotifyd as service / on boot + +For systemd setup see [Systemd](../config/services/Systemd.md) + +Now see if you can find it in the normal Spotify client (Devices in right bottom corner). Retry the above steps if you can't find it. + +## Starting with DBus enabled on boot + +If you have configured spotifyd to start at boot as system wider service or as user service with linger and if you have DBus enabled to listen to player changes like +track changes or if you want to control the player by other process, you need to to configure spotifyd to use the system DBus as it can't register services on the session dbus at boot. +You need to have a config file and configure to use the system dbus, see `Configuring spotifyd`, you can delete everything you don't need to use the standard values. +But you need to configure 2 values: + +```config +use_mpris = true +dbus_type = "system" +``` + +In the standard DBus config, no one is allowed to register services on the system dbus, so you need to configure it. +Create a configuration file under `/usr/share/dbus-1/system.d/`, eg. `spotifyd-dbus.conf` (must end with `.conf`). + +```bash +sudo nano /usr/share/dbus-1/system.d/spotifyd-dbus.conf +``` + +Add the following content: + +As system wide service: + +```content + + + + + + + + + + + + + + +``` + +User is the user account name with which you listen to the DBUs messages and root the account name wich runs the service. + +As user service the account name with which you run the service and with which you listen to the DBUs messages may be the same, then the config would be: + +```content + + + + + + + + + + + + +``` + +## Using other audio backends like PulseAudio +It may be usefull to not use the ALSA interface but Pulse, e.g. if several audio sources want to acces the sound card, it is likely that the sound card +doesn't support it, then you need to use the PulseAudio interface. + +Make sure spotifyd is compiled with PulseAudio support. You need to have a config file and configure 1 value: + +```config +backend = "pulseaudio" +``` + +Latest Raspberry OS versions (Bookworm) run pipewire with PulseAudio interface as default. + +## Known issues +- As user service, spotifyd crashes once at startup with Message: called 'Result::unwrap()' on an 'Err' value: DnsSdError(Os { code: 19, kind: Uncategorized, message: "No such device" }). + Be sure to configure your service file with + + ``` + [Service] + ExecStart=/usr/bin/spotifyd --no-daemon + Restart=always + RestartSec=12 + ``` + + so that it restarts after the crash. + +- As system daemon with PulseAudio backend starting the service will result in a connection refused error from PulseAudio. \ No newline at end of file diff --git a/docs/src/installation/Ubuntu.md b/docs/src/installation/Ubuntu.md deleted file mode 100644 index 93e3cdd7..00000000 --- a/docs/src/installation/Ubuntu.md +++ /dev/null @@ -1,37 +0,0 @@ -# Ubuntu install guide - -## Install the rust toolchain - -To install the latest rust toolchain, follow the installation instructions on [rustup.rs][rustup]. - -> **Note:** If you installed rust before via apt, you need to remove it before installing rustup. -> We recommend to always use the latest version and don't guarantee compatibility with older ones. - -## Install the requirements - -```bash -sudo apt install libasound2-dev libssl-dev pkg-config -``` - -## Clone the repository - -```bash -git clone https://github.com/Spotifyd/spotifyd.git -``` - -## Building spotifyd - -This takes a while... - -```bash -cd spotifyd -cargo build --release -``` - -The resulting binary will be placed in `target/release/spotifyd` - -## Running spotifyd - -You can run it using `./target/release/spotifyd` - -[rustup]: https://rustup.rs/