pleezer is an open-source, headless streaming player built around the Deezer Connect protocol. "Headless" means it runs without a graphical interface, making it ideal for DIY setups, server-based systems, or custom integrations where flexibility is key.
pleezer is a new project and is actively being developed. We welcome contributions and feedback from the community. For more details, see the Contributing section.
- Features
- Installation
- Usage
- Troubleshooting
- Setting Up Your Build Environment
- Contributing
- Support My Work
- Related Projects
- License
- Important Information
- Contacting the Author
- High-Quality Audio: Stream in basic, HQ, or lossless formats depending on your Deezer subscription.
- Gapless Playback: Enjoy seamless transitions between tracks.
- Flow and Mixes: Access personalized playlists and mixes tailored to your preferences.
- Playback Reporting: Contribute to accurate artist monetization metrics.
- User MP3 Support: Play your uploaded MP3 files alongside streamed content.
- Authentication Options: Log in via Deezer email/password or ARL token.
- Volume Normalization: Maintain consistent volume across all tracks while preventing clipping or distortion.
- Proxy Support: Connect through HTTPS proxies using system environment variables.
- Shuffle support
- Live radio and podcast integration
- Advanced audio outputs: ASIO, JACK
- Device registration
Before installing pleezer, ensure your system has the necessary build environment set up. Refer to the Setting Up Your Build Environment section for instructions.
pleezer can be installed in one of two ways:
-
Install the Latest Stable Version
You can install the latest stable release of pleezer directly from crates.io using Cargo:
cargo install pleezer
This command downloads, compiles, and installs the latest release version of pleezer. The binary will be placed in
~/.cargo/bin/on Unix-like systems orC:\Users\<YourUsername>\.cargo\bin\on Windows. -
Build the Latest Development Version
If you want the latest development version, follow these steps:
-
Clone the repository:
git clone https://github.com/your-repo/pleezer.git cd pleezer -
Build the project:
cargo build --release
This command compiles the project and produces the binary in the
target/release/directory. -
(Optional) Install the built version system-wide:
cargo install --path .This installs the binary into
~/.cargo/bin/on Unix-like systems orC:\Users\<YourUsername>\.cargo\bin\on Windows.
-
Once pleezer is launched, it will wait for a connection from another Deezer client. Here's how to connect and use pleezer with your mobile device or other Deezer clients:
- Open the Deezer app on your mobile device or another Deezer client.
- Tap the loudspeaker icon, usually found in the bottom-left corner, to access the Audio Output section.
- Select Deezer Connect to view a list of available devices.
- Choose the device named with either the name you specified using the
-noption or the default system hostname.
Your music will start playing on the selected device.
Note: To discover and connect to the pleezer device, ensure it is connected with the same Deezer account and that pleezer is online.
-
-nor--name: Set the player's name as it appears to Deezer clients. By default, it uses the system hostname. Example:pleezer --name "My Deezer Player" -
-dor--device: Select the output device. Use?to list available devices. If omitted, the system default output device is used. Examples:# List available devices pleezer -d "?" # Use a specific device, formatted as: # "[<host>][:<device>][:<sample rate>][:<sample format>]" (case-insensitive) # # All fields are optional: # - If you don't specify a host, it will use the system default host. # - If you don't specify a device, it will use the host default device. # - If you don't specify a sample rate, it will use the device default sample rate. # - If you don't specify a sample format, it will use the device default sample format. pleezer -d "CoreAudio" pleezer -d "CoreAudio:Yggdrasil+" pleezer -d "CoreAudio:Yggdrasil+:44100" pleezer -d "CoreAudio:Yggdrasil+:44100:f32" # Some more advanced examples, showing you can omit fields as long as you include the colons: pleezer -d ":yggdrasil+" # The Yggdrasil+ device (case-insensitive) pleezer -d "::44100" # The first device to support 44100 Hz
Deezer streams audio at 44100 Hz exclusively. Sampling rates other than 44100 Hz are not recommended and provided for compatibility only. Resampling is done using linear interpolation.
-
--no-interruptions: Prevent other clients from taking over the connection after pleezer has connected. By default, interruptions are allowed. Example:pleezer --no-interruptions
-
-qor--quiet: Suppresses all output except warnings and errors. Example:pleezer -q
-
-vor--verbose: Enables debug logging. Use-vvfor trace logging. The--quietand--verboseoptions are mutually exclusive. Examples:pleezer -v # Debug logging pleezer -vv # Trace logging
-
--eavesdrop: Listen to the Deezer Connect websocket without participating. This is useful for development purposes and requires verbose or probably trace logging (-vor-vv). Example:pleezer --eavesdrop -vv
Note: This option provides only partial insight into client communications. While some messages are echoed across all websockets belonging to a user, most messages are sent on separate websockets specific to each client. For complete traffic analysis, monitoring of all websockets would be required.
-
-sor--secrets: Specify the secrets configuration file. Defaults tosecrets.toml. Example:pleezer -s /path/to/secrets.toml
-
-hor--help: Display help information about command-line options and exit. Example:pleezer -h
-
--version: Show pleezer version and build information, then exit. Example:pleezer --version
All command-line options can be set using environment variables by prefixing PLEEZER_ to the option name in SCREAMING_SNAKE_CASE. For example:
# Using environment variables
export PLEEZER_NAME="Living Room"
export PLEEZER_NO_INTERRUPTIONS=true
# Command-line arguments override environment variables
pleezer --name "Kitchen" # Will use "Kitchen" insteadCommand-line arguments take precedence over environment variables if both are set.
pleezer supports proxy connections through the HTTPS_PROXY environment variable. he value must include either the http:// or https:// schema prefix.
Examples:
# Linux/macOS
export HTTPS_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="https://proxy.example.com:8080"
# Windows (Command Prompt)
set HTTPS_PROXY=https://proxy.company.com:8080
# Windows (PowerShell)
$env:HTTPS_PROXY="https://proxy.company.com:8080"The proxy settings will be automatically detected and used for all Deezer Connect connections.
pleezer operates statelessly and loads user settings, such as normalization and audio quality, when it connects. To apply changes, disconnect and reconnect. This limitation is due to the Deezer Connect protocol.
Command-line options handle settings that cannot be managed statelessly.
For authentication, pleezer requires a secrets.toml file containing either:
- email and password: Your Deezer account email address and password, or
- arl: The Authentication Reference Link for your Deezer account. If present, this will override the email and password authentication. ARLs expire over time, so using email and password authentication is preferred for long-term access.
In addition to the authentication keys, the secrets.toml file can also include the following optional key:
- bf_secret (optional): The secret for computing the track decryption key. If not provided, pleezer will attempt to extract it from Deezer's public resources. Providing this secret is optional and pleezer does not include it to prevent piracy.
Important: Keep your secrets.toml file secure and private. Do not share it, as it contains sensitive information that can give unauthorized access to your Deezer account.
To obtain the ARL:
- Visit Deezer login callback and log in.
- Copy the Authentication Reference Link (ARL) from the button shown. The ARL link will look like
deezer://autolog/.... You only need the part afterdeezer://autolog/(i.e.,...). - Keep this link confidential as it grants full access to your account.
Here are examples of a secrets.toml file:
Using email and password for authentication:
email = "[email protected]"
password = "your-password"Using ARL for authentication (with optional bf_secret):
arl = "your-arl"
bf_secret = "your-bf-secret"You can start with the secrets.toml.example file provided in the repository as a template.
If you encounter any issues while using pleezer, visit our GitHub Discussions for help and advice. You can also post your issue there to get help from the community.
pleezer is supported on Linux and macOS with full compatibility. Windows support is tier two, meaning it is not fully tested and complete compatibility is not guaranteed. Contributions to enhance Windows support are welcome.
Before building pleezer, make sure your system is set up with a build environment.
- Install the necessary build tools and dependencies:
- On Debian/Ubuntu:
sudo apt-get update sudo apt-get install build-essential libasound2-dev pkgconf
- On Fedora:
sudo dnf groupinstall 'Development Tools' sudo dnf install alsa-lib-devel
-
Install Git (optional for the development version):
sudo apt-get install git # On Debian/Ubuntu sudo dnf install git # On Fedora
-
Install the latest version of Rust using rustup. Follow the instructions on the rustup website for the most current setup commands.
- Install the necessary build tools:
- Install Xcode from the App Store. Then install the Xcode Command Line Tools by running:
xcode-select --install
-
Install Rust using rustup. Follow the instructions on the rustup website for the most current setup commands.
-
Install Git and Homebrew (optional for the development version):
- Install Homebrew by following the instructions at Homebrew's official site.
- Use Homebrew to install Git:
brew install git
-
Install the latest version of Rust using rustup. Follow the instructions on the rustup website for the most current setup commands.
-
Set up a build environment by installing Visual Studio with the required components, following the instructions on the Visual Studio official site.
-
Install Git (optional for the development version):
- Download and install Git from the official site.
We appreciate and encourage contributions to pleezer! Whether you're fixing bugs, adding features, or improving documentation, your involvement is valuable.
-
Submit Issues: Submit issues for bugs or feature requests by reporting an issue. Include detailed debug logs and be responsive to follow-up questions and testing. Inactive issues may be closed. This is not a general help forum; issues should focus on pleezer itself, not your system configuration.
-
Create Pull Requests: To contribute code changes or improvements, submit a pull request. Follow the coding standards in the Contributing Guidelines.
-
Participate in Discussions: Engage in GitHub discussions to offer feedback, stay informed, and collaborate with the community.
For more details on contributing, refer to the Contributing Guidelines.
If you appreciate the effort and dedication put into pleezer and other open-source projects, consider supporting my work through GitHub Sponsorships. Your contributions help me continue developing and improving software, and they make a meaningful difference in the sustainability of these projects.
Become a sponsor today at github.com/sponsors/roderickvd. Thank you for your support!
There are several projects that have influenced pleezer. Here are a few:
- librespot: An open-source client library for Spotify with support for Spotify Connect.
- lms-deezer: A plugin for Logitech Media Server to stream music from Deezer.
pleezer is licensed under the Sustainable Use License. This license promotes fair use and sustainable development of open-source software while preventing unregulated commercial exploitation.
You may use, modify, and distribute pleezer freely for non-commercial purposes. This includes integrating it into other software or hardware as long as these offerings are available at no cost to users.
If you intend to use pleezer in a commercial context—such as incorporating it into paid software or hardware products, or any offering that requires payment—you must obtain a separate commercial license. Commercial use includes:
- Bundling pleezer with software or hardware that requires payment to unlock features or access.
- Distributing pleezer as part of a paid product or service.
For example, pleezer can be included in free software or hardware, but if it is part of a product or service that charges for access or additional features, a commercial license is required.
This approach addresses challenges seen with projects like librespot, which, despite widespread use, has seen limited contributions. By requiring commercial users to obtain a separate license, we aim to promote fair contributions and support the ongoing development of pleezer.
pleezer is an independent project and is not affiliated with, endorsed by, or created by Deezer. It is developed to provide a streaming player that is fully compatible with the Deezer Connect protocol.
pleezer does not and will not support saving or extracting music files for offline use. This project is committed to respecting artists' rights and strongly opposes piracy. Users must not use pleezer to infringe on intellectual property rights.
When using pleezer, you must comply with Deezer's Terms of Service. This includes, but is not limited to:
- Using the software only for permitted purposes, such as personal or family use.
- Avoiding any activities that violate Deezer's policies or terms.
It is your responsibility to thoroughly understand and adhere to Deezer's Terms of Service while using pleezer.
For information on how security is handled, including how to report vulnerabilities, please refer to the Security Policy.
For general inquiries, please use GitHub Issues or GitHub Discussions. For commercial licensing or to report security vulnerabilities, you may contact me directly via email. Please avoid using email for general support or feature requests.