https://docs.rs/pleezer

pleezer

⚠️ IMPORTANT: Deezer Connect Deprecation Notice

Deezer has officially deprecated Deezer Connect as announced at https://en.deezercommunity.com/product-updates/say-goodbye-to-deezer-connect-80661. It is unknown how long pleezer will continue to work.

Currently, Deezer Connect functionality remains available on:

• iOS: When "Remote Control" is enabled under Deezer Lab settings
• Android: By using an older APK version

Users should be aware that this functionality may stop working at any time as Deezer continues to phase out Deezer Connect support.

---

pleezer turns your computer into a Deezer Connect streaming device that you can control from your phone, just like a Chromecast or smart speaker. Perfect for home audio setups, DIY projects, and custom integrations.

Important: A paid Deezer subscription is required. Free accounts will not work with pleezer.

Quick Start

Using moOde Audio Player (Raspberry Pi)

The easiest way to use pleezer on a Raspberry Pi is through moOde audio player:

1. Install moOde on your Raspberry Pi
2. Enable pleezer in moOde's user interface
3. Configure your Deezer account
4. Control from your phone!

Manual Installation

1. Install pleezer:

   cargo install pleezer
   

2. Create a secrets.toml file with your Deezer login:

   email = "your-email@example.com"
   password = "your-password"
   

3. Run pleezer:

   pleezer
   

4. Control from your phone:
   • Open the Deezer app
   • Tap the speaker icon (bottom-left)
   • Select "Deezer Connect"
   • Choose your pleezer device
   • Start playing!

Need help? Check out Troubleshooting or join our Discussions.

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:

• Respects artists' rights and opposes piracy
• Only supports legitimate streaming through Deezer Connect
• Properly reports playback for artist monetization
• Does not include decryption keys in the code

Key Features

• Stream music in formats from MP3 to lossless FLAC (depending on your subscription)
• Access your full Deezer library: songs, podcasts, radio, mixes, and Flow
• High-quality audio processing:
  • High-quality dithering with Shibata noise shaping
  • Volume-aware dither scaling
  • Smart volume normalization
• Connect to standard audio outputs, or use JACK (Linux) or ASIO (Windows)
• Automate with hook scripts and external controls
• Run reliably with stateless operation and proper signal handling

Basic Usage

The audio quality setting in your Deezer app controls the streaming quality to pleezer:

1. In the Deezer mobile app, go to Settings > Audio
2. Under "Google Cast", select your preferred quality:
   • Basic Quality (64 kbps MP3)
   • Standard Quality (128 kbps MP3)
   • High Quality (320 kbps MP3)
   • High Fidelity (FLAC, up to 1411 kbps)

Notes:

• Radio streams use their best available quality up to your selected setting
• Podcasts always stream in their original quality
• Your subscription level determines available quality options

When using Deezer Connect, your phone's battery may drain faster than usual. This is normal - the Deezer app needs to maintain constant communication with pleezer for remote control.

Common Configuration

Audio Output

By default, pleezer uses your system's default audio output. To use a specific device:

1. List available devices:

   pleezer -d "?"
   

2. Select a device:

   pleezer -d "device-name"
   

Common examples:

pleezer -d "Built-in Output"              # Use built-in audio
pleezer -d "USB DAC"                      # Use USB audio device
pleezer -d "JACK|cpal_audio_out"          # Connect to JACK (Linux)
pleezer -d "ASIO|USB Audio Interface"     # Use ASIO device (Windows)

Volume Control

Set initial volume level (0-100):

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

Enable volume normalization:

pleezer --normalize-volume

Custom Name

Change how pleezer appears in the Deezer app:

pleezer --name "Living Room"

Authentication

Using Email and Password (Recommended)

Create a secrets.toml file containing:

email = "your-email@example.com"
password = "your-password"

By default, pleezer looks for this file in the current directory. Use -s to specify a different location:

pleezer -s /path/to/secrets.toml

Using ARL (Alternative)

If you prefer not to store your password, you can use a temporary Authentication Reference Link (ARL):

1. Visit Deezer login callback
2. Log in to your account
3. Copy the ARL from the button (the part after deezer://autolog/)
4. Create a secrets.toml file containing:

   arl = "your-arl"
   

Note: ARLs expire periodically. Email/password authentication is more reliable for long-term use.

Hook Scripts

Hook scripts let you automate actions when events occur (like tracks changing or playback starting). Use the --hook option to specify your script:

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

Your script receives event information through environment variables. Example script:

#!/bin/bash
case "$EVENT" in
"track_changed")
    # Safely print track info by escaping special characters
    echo "Now playing: $(printf %q "$TITLE") by $(printf %q "$ARTIST")"

    # Run longer operations in background to avoid delays
    update_home_automation "$(printf %q "$TITLE")" "$(printf %q "$ARTIST")" &
    ;;
"connected")
    echo "Connected as: $(printf %q "$USER_NAME")"
    ;;
esac

Important:

• Keep scripts quick and simple
• Run time-consuming operations in the background
• Always use printf %q to safely escape variables

Available Events

Playback Events

playing - When playback starts

• TRACK_ID: ID of the playing track

paused - When playback pauses

• No additional variables

track_changed - When the track changes

• TRACK_TYPE: "song", "episode", or "livestream"
• TRACK_ID: Content ID
• TITLE: Track/episode title (not set for radio)
• ARTIST: Artist/podcast/station name
• ALBUM_TITLE: Album name (songs only)
• COVER_ID: Artwork ID
• DURATION: Length in seconds (not set for radio)
• FORMAT: Input format and bitrate (e.g., "MP3 320K", "FLAC 1.234M")
• DECODER: Output format (e.g., "PCM 16 bit 44.1 kHz, Stereo")

Connection Events

connected - When a controller connects

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

disconnected - When a controller disconnects

• No additional variables

Cover Art URLs

Use the COVER_ID to construct artwork URLs:

For songs and radio:

https://cdn-images.dzcdn.net/images/cover/{cover_id}/{size}x{size}.{format}

For podcasts:

https://cdn-images.dzcdn.net/images/talk/{cover_id}/{size}x{size}.{format}

Where:

• {size}: Image size in pixels (up to 1920)
• {format}: jpg (smaller) or png (higher quality)

Example: 500x500.jpg is Deezer's default size

Advanced Configuration

Audio Device Selection

The -d option accepts detailed device specifications:

[<host>][|<device>][|<sample rate>][|<sample format>]

All parts are optional and case-insensitive:

• Skip any part using |
• Omit trailing parts entirely

Sample formats:

• i16: 16-bit integer (most compatible)
• i32: 32-bit integer (better for volume control)
• f32: 32-bit float (best quality)

Examples by platform:

Linux (ALSA):

pleezer -d "ALSA|Yggdrasil+"                # Named device with default configuration
pleezer -d "ALSA|Yggdrasil+|44100|i32"      # Named device with sampling rate and format

Using ALSA Virtual Devices: If you are installing from crates, then virtual devices like _audioout or camilladsp are currently not directly enumerable. To use virtual devices, either:

• build from source
• route the default device to your virtual device by adding a configuration to one of:
  • ~/.asoundrc (user-specific)
  • /etc/asound.conf (system-wide)
  • /etc/alsa/conf.d/default.conf (system-wide, recommended)

pcm.!default {
    type plug
    slave.pcm "_audioout"
}

ctl.!default {
    type hw
    card 0
}

Then run pleezer with either no -d option or -d "ALSA|default":

pleezer                                     # Uses system default
pleezer -d "ALSA|default"                   # Explicitly use default

Linux (JACK) - requires --features jack:

pleezer -d "JACK|pleezer_out"               # Custom client name

macOS:

pleezer -d "CoreAudio|DAC|44100|f32"        # DAC with format
pleezer -d "|External Speakers"             # Just device name

Windows (WASAPI):

pleezer -d "WASAPI|Speakers|44100"          # With sample rate
pleezer -d "||48000"                        # Just sample rate

Windows (ASIO) - requires --features asio:

pleezer -d "ASIO|USB Interface"             # ASIO device

Notes:

• Music plays at 44.1 kHz
• Podcasts/radio may use other rates (e.g., 48 kHz)
• Resampling happens automatically when needed
• 32-bit formats (i32/f32) recommended with volume normalization
• 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

Audio Processing

Volume Normalization

Enable volume normalization for consistent levels:

pleezer --normalize-volume

The normalizer provides intelligent gain adjustment to reach Deezer's target level (-15 dB LUFS):

• For negative gain (loud tracks): Simple attenuation of average signal level
• For positive gain (quiet tracks): Dynamic limiting to prevent clipping while preserving dynamics

This approach ensures:

• No clipping when boosting quiet tracks
• No unnecessary processing on tracks that only need attenuation
• Maximum dynamic range preservation

Loudness Compensation

Enable psychoacoustic loudness compensation:

pleezer --loudness

Compensates for how human hearing perceives different frequencies, especially at lower volumes:

• Applies frequency-dependent gain based on ISO 226:2013 research
• Maintains tonal balance across volume levels
• Particularly beneficial for quiet listening
• Automatically scales with volume setting

The compensation effect:

• Strong at low volumes where hearing sensitivity varies most
• Gradually reduces as volume increases

Dithering

pleezer improves audio quality through:

• High-quality triangular (TPDF) dithering
• Volume-aware dither scaling to preserve dynamic range
• Automatic adjustment based on content and playback settings

The dithering process:

• Applies when requantizing audio for your DAC
• Adapts to volume changes to maintain quality

Configure dithering based on your DAC's measured performance:

# Example for DAC with THD+N of -118 dB:
pleezer --dither-bits 19.3

# Disable dithering entirely:
pleezer --dither-bits 0

Calculate optimal dither bits from DAC specifications:

• For THD+N in dB: (-dB - 1.76) / 6.02 Example: THD+N of -118 dB → 19.3 bits
• For THD+N as percentage: (-20 * log10(percentage) - 1.76) / 6.02 Example: THD+N of 0.0002% → 18.6 bits
• Use 0 to disable dithering

Noise Shaping

pleezer uses psychoacoustic noise shaping to optimize audio quality:

• Pushes quantization noise into less audible frequencies
• Uses modern Shibata coefficients for optimal noise distribution
• Provides several noise shaping levels:
  • Level 0: No shaping (plain TPDF dither) - safest, recommended for podcasts
  • Level 1: Very mild shaping (~5 dB ultrasonic rise)
  • Level 2: Mild shaping (~8 dB rise) - recommended default for most music
  • Level 3: Moderate shaping (~12 dB rise) - can benefit classical/jazz/ambient
  • Level 4-7: Not recommended - excessive ultrasonic energy that may stress audio equipment

Configure noise shaping:

# Use noise shaping level 2 (recommended default)
pleezer --noise-shaping 2

# Use level 0 for podcasts (safest)
pleezer --noise-shaping 0

Recommendations by content type:

• Podcasts: Level 0 (pure dither, no shaping)
• Most music (rock, pop, metal, EDM): Level 1-2
• Classical, jazz, ambient: Level 2-3
• Vintage/lo-fi material: Level 0 or 1

Memory Usage

Control RAM usage for audio buffering:

pleezer --max-ram 64  # Use up to 64MB RAM

Approximate sizing:

• MP3 (320 kbps): ~15MB per 5-minute track
• FLAC: ~30-50MB per 5-minute track

Double these amounts to handle current and preloaded tracks:

• --max-ram 30 for MP3
• --max-ram 100 for FLAC

If a track exceeds the limit or --max-ram isn't set, temporary files are used instead.

Connection Control

Prevent other devices from taking control:

pleezer --no-interruptions

Specify network interface:

pleezer --bind 192.168.1.2     # Specific IPv4 interface
pleezer --bind ::1             # IPv6 loopback

Environment Variables

All options can be set with environment variables using the prefix PLEEZER_ and SCREAMING_SNAKE_CASE:

# Set in environment
export PLEEZER_NAME="Living Room"
export PLEEZER_NO_INTERRUPTIONS=true
export PLEEZER_INITIAL_VOLUME=50

# Override with arguments
pleezer --name "Kitchen"  # Takes precedence

Proxy Support

Set proxy for all connections using the HTTPS_PROXY environment variable:

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

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

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

Troubleshooting

Common Issues

Connection Problems

Device not showing in Deezer app

• Verify you have a paid Deezer subscription
• Check that pleezer and your phone use the same Deezer account
• Ensure both devices are on the same network
• Try restarting the Deezer app

Controls not responding

• Disconnect and reconnect in the Deezer app
• If problem persists, force-quit and restart the Deezer app

Audio Issues

Maximum volume on connect

• Use --initial-volume to set a lower starting level

  pleezer --initial-volume 50
  

Volume inconsistent between tracks

• Enable volume normalization

  pleezer --normalize-volume
  

• Note: Not all tracks have normalization data

Known Limitations

• Cannot control from desktop apps or web player (Deezer Connect limitation)
• Favorites list may not work (known Deezer app issue)
• Some Pi Zero 2W users may need to disable IPv6 DNS lookups:

  # Add to /etc/resolv.conf
  options no-aaaa
  

Debug Options

For troubleshooting, enable debug logging:

pleezer -v     # Debug logging
pleezer -vv    # Trace logging (very detailed)

Suppress non-essential output:

pleezer -q     # Only show warnings and errors

Monitor protocol messages (development):

pleezer --eavesdrop -vv

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.

System Requirements

Linux

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install build-essential libasound2-dev pkgconf

# Fedora
sudo dnf groupinstall 'Development Tools'
sudo dnf install alsa-lib-devel

macOS

xcode-select --install

Windows

• Install Visual Studio with C++ support

Installing Rust

All platforms need Rust installed. Visit rustup.rs and follow the installation instructions for your system.

Installation Methods

From crates.io (Stable)

cargo install pleezer

From Source (Development)

git clone https://github.com/roderickvd/pleezer.git
cd pleezer
cargo build --release
cargo install --path .  # Optional: system-wide install

Optional Features

JACK Support (Linux)

# Debian/Ubuntu
sudo apt-get install libjack-dev

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

# Build with JACK support
cargo build --features jack

ASIO Support (Windows)

• Install Steinberg ASIO SDK
• Configure per CPAL documentation
• Build with ASIO support:

  cargo build --features asio
  

Pre-Built Installations

pleezer is available as part of these distributions:

• moOde audio player: A complete Raspberry Pi-based audiophile music player distribution

If you maintain a project, product, or distribution that includes pleezer, feel free to submit a pull request to add it to this list.

Related Projects

These projects have influenced pleezer:

• 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

Acknowledgements

This project uses:

• Shibata noise shaping coefficients from SSRC by Naoki Shibata, licensed under LGPL-2.1
• See ATTRIBUTION.md for details on third-party components

Legal Information

License

pleezer uses the Sustainable Use License, which promotes fair use and sustainable open-source development.

Personal/Non-Commercial Use

• Free to use, modify, and distribute
• Can integrate into other free software/hardware
• Must maintain free access for users

Commercial Use

Requires a commercial license when:

• Including in paid software/hardware
• Using in products with paid features
• Distributing as part of a paid service

This helps ensure fair compensation for development work and continued project maintenance.

Using pleezer with Deezer

When using pleezer, you must follow Deezer's Terms of Service:

• Use only for personal/family streaming
• Maintain a valid paid subscription
• Don't extract or save content offline
• Allow proper playback reporting for artists

Security

Reporting Issues

• Security Vulnerabilities: Email the author directly
• General Issues: Use GitHub Issues
• See Security Policy for details

Secrets File Safety

Keep your secrets.toml file secure:

• Store in a private location
• Don't share or commit to repositories
• Contains sensitive account access information

Support and Contact

Getting Help

1. Check Troubleshooting section
2. Search GitHub Issues
3. Join GitHub Discussions

Contributing

Contributions welcome! See Contributing Guidelines for:

• Submitting issues
• Creating pull requests
• Code standards
• Development setup

Supporting Development

If you find pleezer useful, consider:

• Contributing code or documentation
• Reporting issues and testing fixes
• Supporting through GitHub Sponsors

Contact

• Security Issues/Commercial Licensing: Email author directly
• Bug Reports: GitHub Issues
• General Discussion: GitHub Discussions
• Please don't use email for general support requests