pleezer

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.

Project Status

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.

Table of Contents

• Features
• Installation
• Usage
  • Command-Line Arguments
  • Environment Variables
  • Proxy Configuration
  • Hook Scripts
  • Stateless Configuration
  • Configuring the Secrets File
• Troubleshooting
• Setting Up Your Build Environment
• Contributing
• Support My Work
• Related Projects
• License
• Important Information
  • Important Disclaimer
  • Deezer Terms of Service
  • Security
• Contacting the Author

Features

Supported Features

• Playback Controls:
  • Queue management with shuffle and repeat modes
  • Gapless playback for seamless transitions
• High-Quality Audio: Stream in basic, HQ, or lossless formats depending on your Deezer subscription.
• Volume Controls:
  • Logarithmic volume scaling for natural-feeling volume control
  • Volume normalization to maintain consistent levels across tracks
  • Configurable initial volume level with automatic fallback to client control
• Content Support:
  • Flow and Mixes: Access personalized playlists and mixes tailored to your preferences
  • User MP3s: Play your uploaded MP3 files alongside streamed content
  • Playback Reporting: Contribute to accurate artist monetization metrics
• Audio Backends:
  • JACK backend for audio routing between applications (Linux only)
  • ASIO backend for low-latency audio with direct hardware access (Windows only)
• Connection Options:
  • Authentication via Deezer email/password or ARL token
  • HTTPS proxy support using system environment variables

Planned Features

• Live radio and podcast integration
• Device registration

Installation

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:

1. 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 or C:\Users\<YourUsername>\.cargo\bin\ on Windows.

2. Build the Latest Development Version

   If you want the latest development version, follow these steps:

   1. Clone the repository:

      git clone https://github.com/your-repo/pleezer.git
      cd pleezer
      

   2. Build the project:

      cargo build --release
      

      This command compiles the project and produces the binary in the target/release/ directory.

   3. (Optional) Install the built version system-wide:

      cargo install --path .
      

      This installs the binary into ~/.cargo/bin/ on Unix-like systems or C:\Users\<YourUsername>\.cargo\bin\ on Windows.

Usage

pleezer acts as a remote playback device that can be controlled from the Deezer mobile app using Deezer Connect. Note that Deezer Connect only works from mobile devices - you cannot control pleezer from desktop apps or the web player.

Following the official Deezer Connect instructions, here's how to control pleezer from your mobile device:

1. Open the Deezer app on your mobile device
2. Tap the loudspeaker icon in the bottom-left corner (Audio Options)
3. Select Deezer Connect to view available devices
4. Choose the device named with either your specified name (-n option) or the system hostname

Your music will then play through pleezer while being controlled from your mobile device.

Note: The device running pleezer must:

• Be connected to the internet
• Use the same Deezer account as your mobile device

Battery Usage: When using Deezer Connect, you may notice increased battery drain on your mobile device. This is normal and happens because the Deezer app maintains constant network communication with the player device - sending commands and receiving status updates. This continuous communication is necessary for remote control functionality but does consume more power than local playback.

Command-Line Arguments

• -n or --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"
  

• --device-type: Set how the device identifies itself to Deezer clients. Affects how the device appears in Deezer apps. Options are: web (default), mobile, tablet, or desktop. Example:

  pleezer --device-type mobile
  

• -d or --device: Select the output device. Use ? to list available stereo 44.1/48 kHz output devices. If omitted, the system default output device is used. Examples:

  # List available stereo 44.1/48 kHz output devices
  pleezer -d "?"
  

  Devices are specified in the format: [<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.

  Sample formats use Rust naming conventions:

  • i16: Signed 16-bit integer (S16 in ALSA)
  • i32: Signed 32-bit integer (S32)
  • f32: 32-bit float (FLOAT)

  Examples by platform:

  Linux (ALSA):

  pleezer -d "ALSA|default:CARD=Headphones"                  # Named device
  pleezer -d "ALSA|hw:CARD=sndrpihifiberry,DEV=0|44100|i16"  # Hardware device
  

  Linux (JACK) (requires --features jack):

  pleezer -d "JACK|cpal_client_out"               # Connect as "cpal_client_out"
  

  macOS (CoreAudio):

  pleezer -d "CoreAudio"                          # System default
  pleezer -d "CoreAudio|Yggdrasil+"               # Specific device
  pleezer -d "CoreAudio|Yggdrasil+|44100"         # With sample rate
  pleezer -d "CoreAudio|Yggdrasil+|44100|f32"     # With format
  

  Windows (ASIO) (requires --features asio):

  pleezer -d "ASIO"                               # System default ASIO device
  pleezer -d "ASIO|Focusrite USB ASIO"            # Specific ASIO device
  

  Windows (WASAPI):

  pleezer -d "WASAPI"                            # System default
  pleezer -d "WASAPI|Speakers"                   # Specific device
  pleezer -d "WASAPI|Speakers|44100|f32"         # With format
  

  Shorthand syntax (any platform):

  pleezer -d "|yggdrasil+"    # Just device name (case-insensitive)
  pleezer -d "||44100"        # Just sample rate
  

  Notes:

  • 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.
  • 32-bit sample formats (i32/f32) are recommended when using volume control or normalization, as they preserve more precision in the audio output.
  • Advanced: While device enumeration shows only common configurations (44.1/48 kHz, I16/I32/F32), other sample rates (e.g., 96 kHz) and formats (e.g., U16) are supported when explicitly specified in the device string.

• --normalize-volume: Enable volume normalization to maintain consistent volume levels across tracks. This operates independently from the "Normalize audio" setting in Deezer apps. Example:

  pleezer --normalize-volume
  

• --initial-volume: Set initial volume level between 0 and 100. Remains active until a Deezer client sets volume below maximum. Example:

  pleezer --initial-volume 50  # Start at 50% volume
  

• --no-interruptions: Prevent other clients from taking over the connection after pleezer has connected. By default, interruptions are allowed. Example:

  pleezer --no-interruptions
  

• --hook: Specify a script to execute when events occur (see Hook Scripts for details). Example:

  pleezer --hook /path/to/script.sh
  

  Note: The script must be executable and have a shebang line.

• -q or --quiet: Suppresses all output except warnings and errors. Example:

  pleezer -q
  

• -v or --verbose: Enables debug logging. Use -vv for trace logging. The --quiet and --verbose options 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 (-v or -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.

• -s or --secrets: Specify the secrets configuration file. Defaults to secrets.toml. Example:

  pleezer -s /path/to/secrets.toml
  

• -h or --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
  

Environment Variables

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
export PLEEZER_INITIAL_VOLUME=50  # Set initial volume to 50%

# Command-line arguments override environment variables
pleezer --name "Kitchen"  # Will use "Kitchen" instead

Command-line arguments take precedence over environment variables if both are set.

Proxy Configuration

pleezer supports proxy connections through the HTTPS_PROXY environment variable. The value must include either the http:// or https:// schema prefix. HTTPS can be tunneled over either HTTP or HTTPS proxies.

Examples:

# Linux/macOS
export HTTPS_PROXY="http://proxy.example.com:8080"   # HTTPS over HTTP proxy
export HTTPS_PROXY="https://proxy.example.com:8080"  # HTTPS over HTTPS proxy

# Windows (Command Prompt)
set HTTPS_PROXY=https://proxy.example.com:8080

# Windows (PowerShell)
$env:HTTPS_PROXY="https://proxy.example.com:8080"

The proxy settings will be automatically detected and used for all Deezer Connect connections.

Hook Scripts

You can use the --hook option to specify a script that will be executed when certain events occur. The script receives event information through environment variables.

For all events, the EVENT variable contains the event name. Additional variables depend on the specific event:

playing

Emitted when playback starts

Variables:

• TRACK_ID: The ID of the track being played

paused

Emitted when playback is paused

No additional variables

track_changed

Emitted when the track changes

Variables:

• TRACK_ID: The ID of the track
• TITLE: The track title
• ARTIST: The main artist name
• ALBUM_TITLE: The album title
• ALBUM_COVER: The album cover ID, which can be used to construct image URLs:

  https://e-cdns-images.dzcdn.net/images/cover/{album_cover}/{resolution}x{resolution}.{format}
  

  where {resolution} is the desired resolution in pixels (up to 1920) and {format} is either jpg (smaller file size) or png (higher quality). Deezer's default is 500x500.jpg
• DURATION: Track duration in seconds

connected

Emitted when a Deezer client connects to control playback

Variables:

• USER_ID: The Deezer user ID
• USER_NAME: The Deezer username

disconnected

Emitted when the controlling Deezer client disconnects

No additional variables

Example

All string values are properly escaped for shell safety.

#!/bin/bash
# example-hook.sh
echo "Event: $EVENT"
case "$EVENT" in
  "track_changed")
    echo "Track changed: $TITLE by $ARTIST"
    ;;
  "connected")
    echo "Connected as: $USER_NAME"
    ;;
esac

Stateless Configuration

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 through the Deezer Connect protocol.

Configuring the Secrets File

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:

1. Visit Deezer login callback and log in.
2. Copy the Authentication Reference Link (ARL) from the button shown. The ARL link will look like deezer://autolog/.... You only need the part after deezer://autolog/ (i.e., ...).
3. 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 = "your-email@example.com"
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.

Troubleshooting

If you encounter any issues while using pleezer, visit our GitHub Discussions for help and advice.

Common volume-related issues:

• Volume at maximum when connecting: Use --initial-volume to set a lower starting level
• Volume variations between tracks: Enable --normalize-volume for consistent playback levels

Building pleezer

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.

Setting Up Your Build Environment

Before building pleezer, make sure your system is set up with a build environment.

Linux

1. 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
  

2. Install the latest version of Rust using rustup. Follow the instructions on the rustup website for the most current setup commands.

3. Install Git (optional for the development version):

   sudo apt-get install git  # On Debian/Ubuntu
   sudo dnf install git      # On Fedora
   

macOS

1. Install the necessary build tools:

• Install Xcode from the App Store. Then install the Xcode Command Line Tools by running:

  xcode-select --install
  

2. Install Rust using rustup. Follow the instructions on the rustup website for the most current setup commands.

Note: Git comes pre-installed on macOS, so no additional Git installation is needed.

Windows

1. Set up a build environment by installing Visual Studio with the required components, following the instructions on the Visual Studio official site.

2. Install the latest version of Rust using rustup. Follow the instructions on the rustup website for the most current setup commands.

3. Install Git (optional for the development version):

• Download and install Git from the official site.

Advanced Audio Backends

pleezer supports additional audio backends that can be enabled at compile time:

JACK Backend (Linux only)

JACK (JACK Audio Connection Kit) is a professional audio server that enables routing audio between applications. It provides flexible routing capabilities.

1. Install JACK development files:

• On Debian/Ubuntu:

  sudo apt-get install libjack-dev
  

• On Fedora:

  sudo dnf install jack-audio-connection-kit-devel
  

Then build with JACK support:

cargo build --features jack

ASIO Backend (Windows only)

ASIO (Audio Stream Input/Output) is a low-latency audio driver protocol developed by Steinberg. It bypasses the Windows audio mixer to provide direct hardware access and sub-millisecond latency.

1. Install the Steinberg ASIO SDK
2. Configure build environment following the CPAL documentation

Then build with ASIO support:

cargo build --features asio

Contributing

We appreciate and encourage contributions to pleezer! Whether you're fixing bugs, adding features, or improving documentation, your involvement is valuable.

How to Contribute

1. 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.

2. Create Pull Requests: To contribute code changes or improvements, submit a pull request. Follow the coding standards in the Contributing Guidelines.

3. 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.

Support My Work

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!

Related Projects

There are several projects that have influenced pleezer. Here are a few:

• deezer-linux: An unofficial Linux port of the native Deezer Windows application, providing offline listening capabilities.
• 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.

License

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.

Non-Commercial Use

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.

Commercial Use

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.

Important Information

Important Disclaimer

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.

Deezer Terms of Service

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.

Security

For information on how security is handled, including how to report vulnerabilities, please refer to the Security Policy.

Contacting the Author

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.