Skip to content
Benedikt edited this page Oct 29, 2024 · 64 revisions
Type Short Long Description Hint
Option h help Print a list of options and flags.
Option c cache Path to a directory where files will be cached. PATH
Option system-cache Path to a directory where system files (credentials, volume) will be cached. May be different from the cache option value. PATH
Option cache-size-limit Limits the size of the cache for audio files. It's possible to use suffixes like K, M or G. SIZE
Flag disable-audio-cache Disable caching of the audio data.
Flag disable-credential-cache Disable caching of credentials. Not advisable with OAuth/token authentication.
Flag q quiet Only log warning and error messages.
Option n name Device name. NAME
Option device-type Displayed device type: computer, tablet, smartphone, speaker, tv, avr (Audio/Video Receiver), stb (Set-Top Box), audiodongle, gameconsole, castaudio, castvideo, automobile, smartwatch, chromebook, carthing, homething. Defaults to speaker. TYPE
Option b bitrate Bitrate (kbps): 96, 160, 320. Defaults to 160. BITRATE
Option onevent The path to a script that gets run when one of librespot's events is triggered. PROGRAM
Flag emit-sink-events Run PROGRAM set by --onevent before sink is opened and after it is closed.
Option V version Display librespot version string.
Flag v verbose Enable verbose output PROGRAM
Flag j enable-oauth Perform interactive OAuth sign in. Ideally used alongside --cache/--system-cache options. Details
Option K oauth-port OAuth server redirect port. Use 0 to disable the server i.e. when a web browser is unavalable. Defaults to 5588. PORT
Option k access-token Spotify access-token to sign in with. Must include 'streaming' scope. A token can be obtained using librespot-oauth or Spotify's OAuth flow. Ideally used alongside --cache/--system-cache options. Details TOKEN
Option u username Username to use cached credetials for. USERNAME
Option p password Password used to sign in with. DEPRECATED since v0.5 PASSWORD
Option proxy Use a proxy for HTTP requests. Proxy should be an HTTP proxy in the form http://ip:port, and can also be passed using the all-lowercase http_proxy environment variable. URL
Option ap-port Connect to an AP with a specified port. If no AP with that port is present a fallback AP will be used. Available ports are usually 80, 443 and 4070. PORT
Flag disable-discovery Disable zeroconf discovery mode.
Option backend Audio backend to use. Use ? to list options. Define also the device option when using pipe NAME
Option device Audio device to use. Use ? to list options if using alsa, portaudio or rodio. Enter the path to the output when using pipe. Defaults to the backend's default. NAME
Option format Output format: F64, F32, S32, S24, S24_3, S16. Defaults to S16. FORMAT
Option dither Dither algorithm: none, gpdf, tpdf, tpdf_hp. Defaults to tpdf for formats S16, S24, S24_3 and none for other formats. TYPE
Option m mixer Mixer to use: softvol, alsa. Defaults to softvol. MIXER
Option alsa-mixer-control alsa mixer control, e.g. PCM, Master or similar. Defaults to PCM. NAME
Option alsa-mixer-device alsa mixer device, e.g hw:0 or similar from aplay -l. Defaults to --device if specified, default otherwise. DEVICE
Option alsa-mixer-index alsa mixer index, Index of the cards mixer. Defaults to 0. NUMBER
Option initial-volume Initial volume in % from 0-100. Default for softvol: 50. For the alsa mixer: the current volume. VOLUME
Option zeroconf-backend Zeroconf (MDNS/DNS-SD) backend to use. Valid values are 'avahi', 'dns-sd' and 'libmdns', if librespot is compiled with the corresponding feature flags. BACKEND
Option zeroconf-port The port the internal server advertises over zeroconf: 1 - 65535. Ports <= 1024 may require root privileges. PORT
Option i zeroconf-interface Comma-separated interface IP addresses on which zeroconf will bind (Example "192.168.0.10,10.0.0.10"). Defaults to all interfaces. Ignored by DNS-SD. IP
Flag enable-volume-normalisation Enables volume normalisation for librespot
Option normalisation-method Specify the normalisation method to use: basic, dynamic. Defaults to dynamic. METHOD
Option normalisation-gain-type Specify the normalisation gain type to use: track, album, auto. Defaults to auto. TYPE
Option normalisation-pregain Pregain (dB) applied by the normalisation. Defaults to 0. PREGAIN
Option normalisation-threshold Threshold (dBFS) to prevent clipping. Defaults to -2.0. THRESHOLD
Option normalisation-attack Attack time (ms) in which the dynamic limiter is reducing gain. Defaults to 5. TIME
Option normalisation-release Release or decay time (ms) in which the dynamic limiter is restoring gain. Defaults to 100. TIME
Option normalisation-knee Knee steepness of the dynamic limiter. Default is 1.0. KNEE
Option volume-ctrl Volume control type cubic, fixed, linear, log. Defaults to log. VOLUME_CTRL
Option volume-range Range of the volume control (dB). Default for softvol: 60. For the alsa mixer: what the control supports. RANGE
Flag autoplay Autoplay similar songs when your music ends.
Flag disable-gapless Disables gapless playback by forcing the sink to close between tracks.
Flag passthrough Pass a raw stream to the output. Only works with the pipe and subprocess backends.

Option or Flags marked with *unreleased are as of yet not a part of a librespot release and exist only in builds of the development (dev) branch. To see the Options and Flags available for your version run librespot -h.

Any cli argument you can pass to librespot can also be passed as an environment variable by prefixing it with LIBRESPOT_, making it all caps and replacing any -'s with _'s. So an option foo-bar would become the environment variable LIBRESPOT_FOO_BAR.

Removed Options

Removed Replacement
mixer-card alsa-mixer-device
mixer-index alsa-mixer-index
mixer-name alsa-mixer-control

Authentication

Password login has been deprecated and is no longer supported. Instead, use either OAuth, access token or discovery to login to your Spotfy Premium account.

OAuth

This is the same methodology used by Spotify's desktop player where by the user completes a one-time, interactive authorization process in their web browser. Providing caching is enabled (either --cache or --system-cache), the resulting credentials data will be stored and reused for future logins. If you don't have a web browser running on your machine, there's a headless version.

  1. Run the following command to initiate the OAuth process.

    librespot --cache /some/dir --enable-oauth
  2. If there is no existing cached credentials in the specified directory, you will see a message similar to this:

[INFO  librespot] librespot 0.5.0-dev b68516c (Built on 1980-01-01, Build ID: 315532800, Profile: debug)
Browse to: https://accounts.spotify.com/authorize?response_type=code&client_id=...
  1. Open the provided URL in your web browser to complete the login process.

Headless OAuth

If your device doesn't have a web browser (e.g. headless/remote), run the following and open the provided URL in a browser running on a _different _machine:

librespot --cache /some/dir --enable-oauth --oauth-port 0

When the final OAuth redirect fails to load, copy the entire http://127.0.0.1/login?code=.... redirect URL from your browser back to the waiting librespot prompt on your headless device.

Alternatively, if you want more complicated options:

  • Run librespot on a different machine, complete the OAuth process there, and copy the resulting cached credentials data back over to your headless device.
  • Use SSH port-forwarding of the oauth-port (default 5588) from your different machine back to your headless device, enabling the final OAuth redirect to complete properly.

Access token

Provide a Spotify access token with 'streaming' scope using the --access-token option. Such a token can be obtained in a variety of methods depending on your needs:

cargo install librespot-oauth --example oauth && oauth

These tokens have a limited lifetime. However, providing caching is enabled (using either --cache or --system-cache), the resulting credentials data will be stored and reused for future logins so you only need to use this option once.

Discovery

Select the librespot instance from within Spotify's client to authenticate via Spotify Connect.

Volume normalisation

librespot supports ReplayGain volume normalisation, with the ReplayGain values provided by Spotify in the Ogg streams. There are two types of volume normalisation methods available:

Dynamic

The volume is increased or decreased as per the average ReplayGain of that track or its album. However, if this now results in peaks over the threshold, the gain is dynamically reduced for the duration of that peak, then recovered to the original target gain. This length of the attack and release for this reduction and recovery from zero to full effect by default mimic the Spotify client, and are configurable.

During the attack and release period, the rate of change from zero to full effect (the "knee") has a configurable steepness. By default this is 1.0, which means a linear slope. Values above 1.0 yield softer knees with a more gentle start and end but steeper rate of change mid-way. Values below 1.0 start and stop more sharply, and are flatter in between. Values of 0.0 and below first give an impulse response, then invert the limiter, and should not be used.

Basic

The volume is increased or decreased as per the average ReplayGain of that track or its album. If that would result in peaks above the maximum possible signal level (clipping), the gain is reduced accordingly. This gain is fixed for the entire duration of the track. This mode may be deprecated in a future release.

The equivalent librespot options to match the volume normalisation settings in official Spotify clients are:

Loud

--enable-volume-normalisation --normalisation-pregain 3

Normal (Default)

--enable-volume-normalisation --normalisation-pregain 0

Quiet

--enable-volume-normalisation --normalisation-pregain -9

Output format

librespot outputs 16-bit by default, but can be configured to output 64-bit floating point (F64), 32-bit floating point (F32), 32-bit integer (S32), 24-bit PCM in a 32-bit word (S24) or 24-bit integer packed as three bytes (S24_3). Software volume control and normalisation is done before sample conversion, so that there is no loss of dynamic range.

Mixer

By default, volume control will be done using the software volume mixer.

softvol and the rest of the audio sample pipeline completely works in 64-bit floating point. While some audiophiles may prefer to do volume control in hardware, a 64-bit pipeline is completely transparent and quite likely better than the 32-bit signed integer many hardware DACs work in.

There may be other valid reasons to use the alsa mixer, however:

  • Keeping the current playback volume instead of overwriting it with initial-volume (this is especially useful when you are switching back and forth librespot and other audio renderers).

  • Latching off the mute / unmute switch; librespot will toggle mute on hardware devices that support it when volume is dialed back to 0.

For the purists, you can use --mixer softvol --volume-ctrl fixed --initial-volume 100 to completely bypass volume control.

Volume control

The cubic volume control scale is available on both the softvol and alsa mixers. Cubic is like log, but has a bit more fine-grained control in the upper volume range. The specifics are documented here.

Note that just setting --backend alsa still uses librespot softvol. You also need to set --mixer alsa if you want to have volume control done by Alsa or in hardware. Note that softvol is recommended unless you have specific requirements, as softvol works in 64-bit floating point which is better than most hardware implementations, even if you have a 32-bit DAC.

Dithering

librespot supports dithering to lower the requantisation errors, that is caused by converting digital (ones and zeroes) to analog audio (continuous waveforms). Doing so lowers distortion and improves audio quality.

  • On S24, S24_3 and S24, the default is to use triangular dithering. Depending on personal preference you may use Gaussian dithering instead; it's not as good objectively, but it may be preferred subjectively if you are looking for a more "analog" sound akin to tape hiss.

  • Advanced users who know that they have a DAC without noise shaping have a third option: high-passed dithering, which is like triangular dithering except that it moves dithering noise up in frequency where it is less audible. Note: 99% of DACs are of delta-sigma design with noise shaping, so unless you have a multibit / R2R DAC, or otherwise know what you are doing, this is not for you.

  • Don't dither or shape noise on S32, F32, or F64. On F32 and F64 it's not supported anyway (there are no integer conversions and so no rounding errors) and on S32 the noise level is so far down that it is simply inaudible even after volume normalisation and control.