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.

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:
- Songs: Stream regular music tracks and your uploaded MP3s
- Podcasts: Listen to your favorite shows with direct streaming
- Livestreams: Tune in to live radio stations and broadcasts
- 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

Device registration
RAM-backed storage

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:

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

Important: A paid Deezer subscription is required to use pleezer. The player will not appear as an available device in the Deezer app if you're using a Deezer Free account.

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:

Open the Deezer app on your mobile device
Tap the loudspeaker icon in the bottom-left corner (Audio Options)
Select Deezer Connect to view available devices
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. The variables differ based on content type:

Variable	Music	Podcast	Radio
`TRACK_TYPE`	`song`	`episode`	`livestream`
`TRACK_ID`	Song ID	Episode ID	Livestream ID
`TITLE`	Song title	Episode title	(not set)
`ARTIST`	Artist name	Podcast title	Station name
`ALBUM_TITLE`	Album title	(not set)	(not set)
`COVER_ID`	Album art	Podcast art	Station logo
`DURATION`	Song duration (seconds)	Episode duration (seconds)	(not set)
`FORMAT`	Audio format and bitrate	Audio format and bitrate	Audio format and bitrate

The FORMAT value shows the audio configuration (e.g., "MP3 320K" for constant bitrate, or "FLAC 1.234M" for variable bitrate).

The COVER_ID can be used to construct image URLs:

https://e-cdns-images.dzcdn.net/images/cover/{cover_id}/{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.


#### `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
Note: The script must properly escape received values to prevent command injection when using them in shell commands. In bash, `printf %q` provides safe escaping:

```bash
#!/bin/bash
# example-hook.sh
echo "Event: $EVENT"
case "$EVENT" in
"track_changed")
    # Use printf %q to prevent command injection when using values in commands
    echo "Track changed: $(printf %q "$TITLE") by $(printf %q "$ARTIST")"
    ;;
"connected")
    echo "Connected as: $(printf %q "$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.

Signal Handling

On Unix systems, pleezer responds to system signals:

SIGTERM: Gracefully stops playback and shuts down
SIGHUP: Reloads configuration and restarts the client
Ctrl-C (SIGINT): Gracefully stops playback and shuts down (all platforms)

Windows systems only support Ctrl-C for graceful shutdown.

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:

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 after deezer://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.

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

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 the latest version of Rust using rustup. Follow the instructions on the rustup website for the most current setup commands.

Install Git (optional for the development version):

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

macOS

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.

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

Windows

Set up a build environment by installing Visual Studio with the required components, following the instructions on the Visual Studio official site.
Install the latest version of Rust using rustup. Follow the instructions on the rustup website for the most current setup commands.
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.

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.

Install the Steinberg ASIO SDK
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

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.

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.

Name		Name	Last commit message	Last commit date
Latest commit History 297 Commits
.github		.github
src		src
tests/fixtures		tests/fixtures
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
build.rs		build.rs
secrets.toml.example		secrets.toml.example

License

roderickvd/pleezer

Folders and files

Latest commit

History

Repository files navigation

pleezer

Project Status

Table of Contents

Features

Supported Features

Planned Features

Installation

Usage

Command-Line Arguments

Environment Variables

Proxy Configuration

Hook Scripts

playing

paused

track_changed

Stateless Configuration

Signal Handling

Configuring the Secrets File

Troubleshooting

Building pleezer

Setting Up Your Build Environment

Linux

macOS

Windows

Advanced Audio Backends

JACK Backend (Linux only)

ASIO Backend (Windows only)

Contributing

How to Contribute

Support My Work

Related Projects

License

Non-Commercial Use

Commercial Use

Important Information

Important Disclaimer

Deezer Terms of Service

Security

Contacting the Author

About

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases 10

Sponsor this project

Languages

`playing`

`paused`

`track_changed`