diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000000..e69de29bb2 diff --git a/404.html b/404.html new file mode 100644 index 0000000000..fae31b60ed --- /dev/null +++ b/404.html @@ -0,0 +1 @@ + OwnTone

404 - Not found

\ No newline at end of file diff --git a/advanced/multiple-instances/index.html b/advanced/multiple-instances/index.html new file mode 100644 index 0000000000..7cd395fec3 --- /dev/null +++ b/advanced/multiple-instances/index.html @@ -0,0 +1 @@ + Multiple instances - OwnTone
Skip to content

Running Multiple Instances

To run multiple instances of owntone on a server, you should copy /etc/owntone.conf to /etc/owntone-zone.conf (for each zone) and modify the following to be unique across all instances:

  • the three port settings (general -> websocket_port, library -> port, and mpd -> port)

  • the database paths (general -> db_path, db_backup_path, and db_cache_path)

  • the service name (library -> name).

  • you probably also want to disable local output (set audio -> type = "disabled").

Then run owntone -c /etc/owntone-zone.conf to run owntone with the new zone configuration.

Owntone has a systemd template which lets you run this automatically on systems that use systemd. You can start or enable the service for a zone by sudo systemctl start owntone@zone and check that it is running with sudo systemctl status owntone@zone. Use sudo systemctl enable ownton@zone to get the service to start on reboot.

\ No newline at end of file diff --git a/advanced/outputs-alsa/index.html b/advanced/outputs-alsa/index.html new file mode 100644 index 0000000000..782881f278 --- /dev/null +++ b/advanced/outputs-alsa/index.html @@ -0,0 +1,292 @@ + Alsa - OwnTone
Skip to content

OwnTone and ALSA

ALSA is one of the main output configuration options for local audio; when using ALSA you will typically let the system select the soundcard on your machine as the default device/sound card - a mixer associated with the ALSA device is used for volume control. However if your machine has multiple sound cards and your system chooses the wrong playback device, you will need to manually select the card and mixer to complete the OwnTone configuration.

Quick introduction to ALSA devices

ALSA devices can be addressed in a number ways but traditionally we have referred to them using the hardware prefix, card number and optionally device number with something like hw:0 or hw:0,1. In ALSA configuration terms card X, device Y is known as hw:X,Y.

ALSA has other prefixes for each card and most importantly plughw. The plughw performs transparent sample format and sample rate conversions and maybe a better choice for many users rather than hw: which would fail when provided unsupported audio formats/sample rates.

Alternative ALSA names can be used to refer to physical ALSA devices and can be useful in a number of ways:

  • more descriptive rather than being a card number
  • consistent for USB numeration - USB ALSA devices may not have the same card number across reboots/reconnects

The ALSA device information required for configuration the server can be deterined using aplay, as described in the rest of this document, but OwnTone can also assist; when configured to log at INFO level the following information is provided during startup:

laudio: Available ALSA playback mixer(s) on hw:0 CARD=Intel (HDA Intel): 'Master' 'Headphone' 'Speaker' 'PCM' 'Mic' 'Beep'
+laudio: Available ALSA playback mixer(s) on hw:1 CARD=E30 (E30): 'E30 '
+laudio: Available ALSA playback mixer(s) on hw:2 CARD=Seri (Plantronics Blackwire 3210 Seri): 'Sidetone' 'Headset'
+
The CARD= string is the alternate ALSA name for the device and can be used in place of the traditional hw:x name.

On this machine the server reports that it can see the onboard HDA Intel sound card and two additional sound cards: a Topping E30 DAC and a Plantronics Headset which are both USB devices. We can address the first ALSA device as hw:0 or hw:CARD=Intel or hw:Intel or plughw:Intel, the second ALSA device as hw:1 or hw:E30 and so forth. The latter 2 devices being on USB will mean that hw:1 may not always refer to hw:E30 and thus in such a case using the alternate name is useful.

Configuring the server

OwnTone can support a single ALSA device or multiple ALSA devices.

# example audio section for server for a single soundcard
+audio {
+    nickname = "Computer"
+    type = "alsa"
+
+    card = "hw:1"           # defaults to 'default'
+    mixer = "Analogue"      # defaults to 'PCM' or 'Master'
+    mixer_device = "hw:1"   # defaults to same as 'card' value
+}
+

Multiple devices can be made available to OwnTone using seperate alsa { .. } sections.

audio {
+    type = "alsa"
+}
+
+alsa "hw:1" {
+    nickname = "Computer"
+    mixer = "Analogue"
+    mixer_device = "hw:1"
+}
+
+alsa "hw:2" {
+    nickname = "Second ALSA device"
+}
+

NB: When introducing alsa { .. } section(s) the ALSA specific configuration in the audio { .. } section will be ignored.

If there is only one sound card, verify if the default sound device is correct for playback, we will use the aplay utility.

# generate some audio if you don't have a wav file to hand
+$ sox -n -c 2 -r 44100 -b 16 -C 128 /tmp/sine441.wav synth 30 sin 500-100 fade h 0.2 30 0.2
+
+$ aplay -Ddefault /tmp/sine441.wav
+

If you can hear music played then you are good to use default for the server configuration. If you can not hear anything from the aplay firstly verify (using alsamixer) that the sound card is not muted. If the card is not muted AND there is no sound you can try the options below to determine the card and mixer for configuring the server.

Automatically Determine ALL relevant the sound card information

As shown above, OwnTone can help, consider the information that logged:

laudio: Available ALSA playback mixer(s) on hw:0 CARD=Intel (HDA Intel): 'Master' 'Headphone' 'Speaker' 'PCM' 'Mic' 'Beep'
+laudio: Available ALSA playback mixer(s) on hw:1 CARD=E30 (E30): 'E30 '
+laudio: Available ALSA playback mixer(s) on hw:2 CARD=Seri (Plantronics Blackwire 3210 Seri): 'Sidetone' 'Headset'
+

Using the information above, we can see 3 soundcards that we could use with OwnTone with the first soundcard having a number of seperate mixer devices (volume control) for headphone and the interal speakers - we'll configure the server to use both these and also the E30 device. The server configuration for theese multiple outputs would be:

# using ALSA device alias where possible
+
+alsa "hw:Intel" {
+    nickname = "Computer - Speaker"
+    mixer = "Speaker"
+}
+
+alsa "hw:Intel" {
+    nickname = "Computer - Headphones"
+    mixer = "Headphone"
+}
+
+alsa "plughw:E30" {
+    # this E30 device only support S32_LE so we can use the 'plughw' prefix to
+    # add transparent conversion support of more common S16/S24_LE formats
+
+    nickname = "E30 DAC"
+    mixer = "E30 "
+    mixer_device = "hw:E30"
+}
+

NB: it is troublesome to use hw or plughw ALSA addressing when running OwnTone on a machine with pulseaudio and if you wish to use refer to ALSA devices directly that you stop pulseaudio.

Manually Determining the sound cards you have / ALSA can see

The example below is how I determined the correct sound card and mixer values for a Raspberry Pi that has an additional DAC card (hat) mounted. Of course using the log output from the server would have given the same results.

Use aplay -l to list all the sound cards and their order as known to the system - you can have multiple card X, device Y entries; some cards can also have multiple playback devices such as the RPI's onboard soundcard which feeds both headphone (card 0, device 0) and HDMI (card 0, device 1).

$ aplay -l
+**** List of PLAYBACK Hardware Devices ****
+card 0: ALSA [bcm2835 ALSA], device 0: bcm2835 ALSA [bcm2835 ALSA]
+  Subdevices: 6/7
+  Subdevice #0: subdevice #0
+  Subdevice #1: subdevice #1
+  Subdevice #2: subdevice #2
+  Subdevice #3: subdevice #3
+  Subdevice #4: subdevice #4
+  Subdevice #5: subdevice #5
+  Subdevice #6: subdevice #6
+card 0: ALSA [bcm2835 ALSA], device 1: bcm2835 ALSA [bcm2835 IEC958/HDMI]
+  Subdevices: 1/1
+  Subdevice #0: subdevice #0
+card 1: IQaudIODAC [IQaudIODAC], device 0: IQaudIO DAC HiFi pcm512x-hifi-0 []
+  Subdevices: 1/1
+  Subdevice #0: subdevice #0
+

On this machine we see the second sound card installed, an IQaudIODAC dac hat, and identified as card 1 device 0. This is the playback device we want to be used by the server.

hw:1,0 is the IQaudIODAC that we want to use - we verify audiable playback through that sound card using aplay -Dhw:1 /tmp/sine441.wav. If the card has only one device, we can simply refer to the sound card using hw:X so in this case where the IQaudIODAC only has one device, we can refer to this card as hw:1 or hw:1,0.

Use aplay -L to get more information about the PCM devices defined on the system.

$ aplay -L
+null
+    Discard all samples (playback) or generate zero samples (capture)
+default:CARD=ALSA
+    bcm2835 ALSA, bcm2835 ALSA
+    Default Audio Device
+sysdefault:CARD=ALSA
+    bcm2835 ALSA, bcm2835 ALSA
+    Default Audio Device
+dmix:CARD=ALSA,DEV=0
+    bcm2835 ALSA, bcm2835 ALSA
+    Direct sample mixing device
+dmix:CARD=ALSA,DEV=1
+    bcm2835 ALSA, bcm2835 IEC958/HDMI
+    Direct sample mixing device
+dsnoop:CARD=ALSA,DEV=0
+    bcm2835 ALSA, bcm2835 ALSA
+    Direct sample snooping device
+dsnoop:CARD=ALSA,DEV=1
+    bcm2835 ALSA, bcm2835 IEC958/HDMI
+    Direct sample snooping device
+hw:CARD=ALSA,DEV=0
+    bcm2835 ALSA, bcm2835 ALSA
+    Direct hardware device without any conversions
+hw:CARD=ALSA,DEV=1
+    bcm2835 ALSA, bcm2835 IEC958/HDMI
+    Direct hardware device without any conversions
+plughw:CARD=ALSA,DEV=0
+    bcm2835 ALSA, bcm2835 ALSA
+    Hardware device with all software conversions
+plughw:CARD=ALSA,DEV=1
+    bcm2835 ALSA, bcm2835 IEC958/HDMI
+    Hardware device with all software conversions
+default:CARD=IQaudIODAC
+    IQaudIODAC, 
+    Default Audio Device
+sysdefault:CARD=IQaudIODAC
+    IQaudIODAC, 
+    Default Audio Device
+dmix:CARD=IQaudIODAC,DEV=0
+    IQaudIODAC, 
+    Direct sample mixing device
+dsnoop:CARD=IQaudIODAC,DEV=0
+    IQaudIODAC, 
+    Direct sample snooping device
+hw:CARD=IQaudIODAC,DEV=0
+    IQaudIODAC, 
+    Direct hardware device without any conversions
+plughw:CARD=IQaudIODAC,DEV=0
+    IQaudIODAC, 
+    Hardware device with all software conversions
+

For the server configuration, we will use:

audio {
+    nickname = "Computer"
+    type = "alsa"
+    card="hw:1"
+    # mixer=TBD
+    # mixer_device=TBD
+}
+

Mixer name

Once you have the card number (determined from aplay -l) we can inspect/confirm the name of the mixer that can be used for playback (it may NOT be PCM as expected by the server). In this example, the card 1 is of interest and thus we use -c 1 with the following command:

$ amixer -c 1 
+Simple mixer control 'DSP Program',0
+  Capabilities: enum
+  Items: 'FIR interpolation with de-emphasis' 'Low latency IIR with de-emphasis' 'High attenuation with de-emphasis' 'Fixed process flow' 'Ringing-less low latency FIR'
+  Item0: 'Ringing-less low latency FIR'
+Simple mixer control 'Analogue',0
+  Capabilities: pvolume
+  Playback channels: Front Left - Front Right
+  Limits: Playback 0 - 1
+  Mono:
+  Front Left: Playback 1 [100%] [0.00dB]
+  Front Right: Playback 1 [100%] [0.00dB]
+Simple mixer control 'Analogue Playback Boost',0
+  Capabilities: volume
+  Playback channels: Front Left - Front Right
+  Capture channels: Front Left - Front Right
+  Limits: 0 - 1
+  Front Left: 0 [0%] [0.00dB]
+  Front Right: 0 [0%] [0.00dB]
+...
+

This card has multiple controls but we want to find a mixer control listed with a pvolume (playback) capability - in this case that mixer value required for the server configuration is called Analogue.

For the server configuration, we will use:

audio {
+    nickname = "Computer"
+    type = "alsa"
+    card="hw:1"
+    mixer="Analogue"
+    # mixer_device=TBD
+}
+

Mixer device

This is the name of the underlying physical device used for the mixer - it is typically the same value as the value of card in which case a value is not required by the server configuration. An example of when you want to change explicitly configure this is if you need to use a dmix device (see below).

Handling Devices that cannot concurrently play multiple audio streams

Some devices such as various RPI DAC boards (IQaudio DAC, Allo Boss DAC...) cannot have multiple streams openned at the same time/cannot play multiple sound files at the same time. This results in Device or resource busy errors. You can confirm if your sound card has this problem by using the example below once have determined the names/cards information as above.

Using our hw:1 device we try:

# generate some audio
+$ sox -n -c 2 -r 44100 -b 16 -C 128 /tmp/sine441.wav synth 30 sin 500-100 fade h 0.2 30 0.2
+
+# attempt to play 2 files at the same time
+$ aplay -v -Dhw:1 /tmp/sine441.wav &
+Playing WAVE '/tmp/sine441.wav' : Signed 16 bit Little Endian, Rate 44100 Hz, Stereo
+Hardware PCM card 1 'IQaudIODAC' device 0 subdevice 0
+Its setup is:
+  stream       : PLAYBACK
+  access       : RW_INTERLEAVED
+  format       : S16_LE
+  subformat    : STD
+  channels     : 2
+  rate         : 44100
+  exact rate   : 44100 (44100/1)
+  msbits       : 16
+  buffer_size  : 22052
+  period_size  : 5513
+  period_time  : 125011
+  tstamp_mode  : NONE
+  tstamp_type  : MONOTONIC
+  period_step  : 1
+  avail_min    : 5513
+  period_event : 0
+  start_threshold  : 22052
+  stop_threshold   : 22052
+  silence_threshold: 0
+  silence_size : 0
+  boundary     : 1445199872
+  appl_ptr     : 0
+  hw_ptr       : 0
+$ aplay -v -Dhw:1 /tmp/sine441.wav
+aplay: main:788: audio open error: Device or resource busy
+

In this instance this device cannot open multiple streams - OwnTone can handle this situation transparently with some audio being truncated from the end of the current file as the server prepares to play the following track. If this handling is causing you problems you may wish to use ALSA's dmix functionally which provides a software mixing module. We will need to define a dmix component and configure the server to use that as it's sound card.

The downside to the dmix approach will be the need to fix a samplerate (48000 being the default) for this software mixing module meaning any files that have a mismatched samplerate will be resampled.

ALSA dmix configuration/setup

A dmix device can be defined in /etc/asound.conf or ~/.asoundrc for the same user running OwnTone. We will need to know the underlying physical soundcard to be used: in our examples above, hw:1,0 / card 1, device 0 representing our IQaudIODAC as per output of aplay -l. We also take the buffer_size and period_size from the output of playing a sound file via aplay -v.

# use 'dac' as the name of the device: "aplay -Ddac ...."
+pcm.!dac {
+    type plug
+    slave.pcm "dmixer"
+    hint.description "IQAudio DAC s/w dmix enabled device"
+}
+
+pcm.dmixer  {
+    type dmix
+    ipc_key 1024             # need to be uniq value
+    ipc_key_add_uid false    # multiple concurrent different users
+    ipc_perm 0666            # multi-user sharing permissions
+
+    slave {
+    pcm "hw:1,0"         # points at the underlying device - could also simply be hw:1
+    period_time 0
+    period_size 4096     # from the output of aplay -v
+    buffer_size 22052    # from the output of aplay -v
+    rate 44100           # locked in sample rate for resampling on dmix device
+    }
+    hint.description "IQAudio DAC s/w dmix device"
+}
+
+ctl.dmixer {
+    type hw
+    card 1                  # underlying device
+    device 0
+}
+

Running aplay -L we will see our newly defined devices dac and dmixer

$ aplay -L
+null
+    Discard all samples (playback) or generate zero samples (capture)
+dac
+    IQAudio DAC s/w dmix enabled device
+dmixer
+    IQAudio DAC s/w dmix device
+default:CARD=ALSA
+    bcm2835 ALSA, bcm2835 ALSA
+    Default Audio Device
+...
+

At this point we are able to rerun the concurrent aplay commands (adding -Ddac to specify the playback device to use) to verify ALSA configuration.

If there is only one card on the machine you may use pcm.!default instead of pcm.!dac - there is less configuration to be done later since many ALSA applications will use the device called default by default. Furthermore on RPI you can explicitly disable the onboard sound card to leave us with only the IQaudIODAC board enabled (won't affect HDMI sound output) by commenting out #dtparam=audio=on in /boot/config.txt and rebooting.

Config with dmix

We will use the newly defined card named dac which uses the underlying hw:1 device as per /etc/asound.conf or ~/.asoundrc configuration. Note that the mixer_device is now required and must refer to the real device (see the slave.pcm value) and not the named device (ie dac) that we created and are using for the card configuration value.

For the final server configuration, we will use:

audio {
+    nickname = "Computer"
+    type = "alsa"
+    card="dac"
+    mixer="Analogue"
+    mixer_device="hw:1"
+}
+

Setting up an Audio Equalizer

There exists an ALSA equalizer plugin. On debian (incl Raspberry Pi) systems you can install this plugin by apt install libasound2-plugin-equal; this is not currently available on Fedora (FC31) but can be easily built from source after installing the dependant ladspa package.

Once installed the user must setup a virtual device and use this device in the server configuration.

If you wish to use your hw:0 device for output:

# /etc/asound.conf
+ctl.equal {
+  type equal;
+
+  # library /usr/lib64/ladspa/caps.so
+}
+
+pcm.equal {
+  type plug;
+  slave.pcm {
+      type equal;
+
+      ## must be plughw:x,y and not hw:x,y
+      slave.pcm "plughw:0,0";
+
+      # library /usr/lib64/ladspa/caps.so
+  }
+  hint.description "equalised device"
+}
+

and in owntone.conf

alsa "equal" {
+    nickname = "Equalised Output"
+    # adjust accordingly for mixer with pvolume capability
+    mixer = "PCM"
+    mixer_device = "hw:0"
+}
+

Using the web UI and on the outputs selection you should see an output called Equalised Output which you should select and set the volume.

When starting playback for any audio tracks you should hopefully hear the output. In a terminal, run alsamixer -Dequal and you'll see the eqaliser - to test that this is all working, go and drop the upper frequencies and boosting the bass frequencies and give it a second - if this changes the sound profile from your speakers, well done, its done and you can adjust the equalizer as you desire.

Note however, the equalizer appears to require a plughw device which means you cannnot use this equalizer with a dmix output chain.

Troubleshooting

  • Errors in log Failed to open configured mixer element when selecting output device

  • Errors in log Invalid CTL or Failed to attach mixer when playing/adjusting volume

    mixer value is wrong. Verify name of mixer value in server config against the names from all devices capable of playback using amixer -c <card number>. Assume the device is card 1:

    (IFS=$'\n'
+ CARD=1
+ for i in $(amixer -c ${CARD} scontrols | awk -F\' '{ print $2 }'); do 
+   amixer -c ${CARD} sget "$i" | grep Capabilities | grep -q pvolume && echo $i
+   done
+)
+

    Look at the names output and choose the one that fits. The outputs can be something like:

    # laptop
+Master
+Headphone
+Speaker
+PCM
+Mic
+Beep
+
+# RPI with no additional DAC, card = 0
+PCM
+
+# RPI with additional DAC hat (IQAudioDAC, using a pcm512x chip)
+Analogue
+Digital
+

  • No sound during playback - valid mixer/verified by aplay

    Check that the mixer is not muted or volume set to 0. Using the value of mixer as per server config and unmute or set volume to max. Assume the device is card 1 and mixer = Analogue:

    amixer -c 1 set Analogue unmute  ## some mixers can not be muted resulting in "invalid command"
+amixer -c 1 set Analogue 100%
+

    An example of a device with volume turned all the way down - notice the Playback values are 0[0%]`:

    Simple mixer control 'Analogue',0
+Capabilities: pvolume
+Playback channels: Front Left - Front Right
+Limits: Playback 0 - 1
+Mono:
+Front Left: Playback 0 [0%] [-6.00dB]
+Front Right: Playback 0 [0%] [-6.00dB]
+

  • Server stops playing after moving to new track in paly queue, Error in log Could not open playback device The log contains these log lines:

    [2019-06-19 20:52:51] [  LOG]   laudio: open '/dev/snd/pcmC0D0p' failed (-16)[2019-06-19 20:52:51] [  LOG]   laudio: Could not open playback device: Device or resource busy
+[2019-06-19 20:52:51] [  LOG]   laudio: Device 'hw' does not support quality (48000/16/2), falling back to default
+[2019-06-19 20:52:51] [  LOG]   laudio: open '/dev/snd/pcmC0D0p' failed (-16)[2019-06-19 20:52:51] [  LOG]   laudio: Could not open playback device: Device or resource busy
+[2019-06-19 20:52:51] [  LOG]   laudio: ALSA device failed setting fallback quality[2019-06-19 20:52:51] [  LOG]   player: The ALSA device 'Computer' FAILED
+

    If you have a RPI with a DAC hat with a pcm512x chip will affect you. This is because the server wants to open the audio device for the next audio track whilst current track is still playing but the hardware does not allow this - see the comments above regarding determining concurrrent playback.

    This error will occur for output hardware that do not support concurrent device open and the server plays 2 files of different bitrate (44.1khz and 48khz) back to back.

    If you observe the error, you will need to use the dmix configuration as mentioned above.

\ No newline at end of file diff --git a/advanced/outputs-pulse/index.html b/advanced/outputs-pulse/index.html new file mode 100644 index 0000000000..a8d6d30e8e --- /dev/null +++ b/advanced/outputs-pulse/index.html @@ -0,0 +1,31 @@ + Pulse audio - OwnTone
Skip to content

OwnTone and Pulseaudio

You have the choice of running Pulseaudio either in system mode or user mode. For headless servers, i.e. systems without desktop users, system mode is recommended.

If there is a desktop user logged in most of the time, a setup with network access via localhost only for daemons is a more appropriate solution, since the normal user administration (with, e.g., pulseaudio -k) works as advertised. Also, the user specific configuration for pulseaudio is preserved across sessions as expected.

System Mode with Bluetooth support

Credit: Rob Pope

This guide was written based on headless Debian Jessie platforms. Most of the instructions will require that you are root.

Step 1: Setting up Pulseaudio

If you see a "Connection refused" error when starting the server, then you will probably need to setup Pulseaudio to run in system mode [1]. This means that the Pulseaudio daemon will be started during boot and be available to all users.

How to start Pulseaudio depends on your distribution, but in many cases you will need to add a pulseaudio.service file to /etc/systemd/system with the following content:

# systemd service file for Pulseaudio running in system mode
+[Unit]
+Description=Pulseaudio sound server
+Before=sound.target
+
+[Service]
+ExecStart=/usr/bin/pulseaudio --system --disallow-exit
+
+[Install]
+WantedBy=multi-user.target
+

If you want Bluetooth support, you must also configure Pulseaudio to load the Bluetooth module. First install it (Debian: apt install pulseaudio-module-bluetooth) and then add the following to /etc/pulse/system.pa:

#### Enable Bluetooth
+.ifexists module-bluetooth-discover.so
+load-module module-bluetooth-discover
+.endif
+

Now you need to make sure that Pulseaudio can communicate with the Bluetooth daemon through D-Bus. On Raspbian this is already enabled, and you can skip this step. Otherwise do one of the following:

  1. Add the pulse user to the bluetooth group: adduser pulse bluetooth
  2. Edit /etc/dbus-1/system.d/bluetooth.conf and change the policy for <policy context="default"\> to "allow"

Phew, almost done with Pulseaudio! Now you should:

  1. enable system mode on boot with systemctl enable pulseaudio
  2. reboot (or at least restart dbus and pulseaudio)
  3. check that the Bluetooth module is loaded with pactl list modules short

Step 2: Setting up the server

Add the user the server is running as (typically "owntone") to the "pulse-access" group:

adduser owntone pulse-access
+

Now (re)start the server.

Step 3: Adding a Bluetooth device

To connect with the device, run bluetoothctl and then:

power on
+agent on
+scan on
+**Note MAC address of BT Speaker**
+pair [MAC address]
+**Type Pin if prompted**
+trust [MAC address]
+connect [MAC address]
+

Now the speaker should appear. You can also verify that Pulseaudio has detected the speaker with pactl list sinks short.

User Mode with Network Access

Credit: wolfmanx and this blog

Step 1: Copy system pulseaudio configuration to the users home directory

mkdir -p ~/.pulse
+cp /etc/pulse/default.pa ~/.pulse/
+

Step 2: Enable TCP access from localhost only

Edit the file ~/.pulse/default.pa , adding the following line at the end:

load-module module-native-protocol-tcp auth-ip-acl=127.0.0.1
+

Step 3: Restart the pulseaudio deamon

pulseaudio -k
+# OR
+pulseaudio -D
+

Step 4: Adjust configuration file

In the audio section of /etc/owntone.conf, set server to localhost:

server = "localhost"
+

[1] Note that Pulseaudio will warn against system mode. However, in this use case it is actually the solution recommended by the Pulseaudio folks themselves.

\ No newline at end of file diff --git a/advanced/radio-streams/index.html b/advanced/radio-streams/index.html new file mode 100644 index 0000000000..7db935eb05 --- /dev/null +++ b/advanced/radio-streams/index.html @@ -0,0 +1,37 @@ + Radio streams - OwnTone
Skip to content

OwnTone and Radio Stream tweaking

Radio streams have many different ways in how metadata is sent. Many should just work as expected, but a few may require some tweaking. If you are not seeing expected title, track, artist, artwork in clients or web UI, the following may help.

First, understand what and how the particular stream is sending information. ffprobe is a command that can be used to interegrate most of the stream information. ffprobe <http://stream.url> should give you some useful output, look at the Metadata section, below is an example.

 Metadata:
+    icy-br          : 320
+    icy-description : DJ-mixed blend of modern and classic rock, electronica, world music, and more. Always 100% commercial-free
+    icy-genre       : Eclectic
+    icy-name        : Radio Paradise (320k aac)
+    icy-pub         : 1
+    icy-url         : https://radioparadise.com
+    StreamTitle     : Depeche Mode - Strangelove
+    StreamUrl       : http://img.radioparadise.com/covers/l/B000002LCI.jpg
+

In the example above, all tags are populated with correct information, no modifications to the server configuration should be needed. Note that StreamUrl points to the artwork image file.

Below is another example that will require some tweaks to the server, Notice icy-name is blank and StreamUrl doesn't point to an image.

Metadata:
+    icy-br          : 127
+    icy-pub         : 0
+    icy-description : Unspecified description
+    icy-url         : 
+    icy-genre       : various
+    icy-name        : 
+    StreamTitle     : Pour Some Sugar On Me - Def Leppard
+    StreamUrl       : https://radio.stream.domain/api9/eventdata/49790578
+

In the above, first fix is the blank name, second is the image artwork.

1) Set stream name/title via the M3U file

Set the name with an EXTINF tag in the m3u playlist file:

#EXTM3U
+#EXTINF:-1, - My Radio Stream Name
+http://radio.stream.domain/stream.url
+

The format is basically #EXTINF:<length>, <Artist Name> - <Artist Title>. Length is -1 since it's a stream, <Artist Name> was left blank since StreamTitle is accurate in the Metadata but <Artist Title> was set to My Radio Stream Name since icy-name was blank.

2) StreamUrl is a JSON file with metadata

If StreamUrl does not point directly to an artwork file then the link may be to a json file that contains an artwork link. If so, you can make the server download the file automatically and search for an artwork link, and also track duration.

Try to download the file, e.g. with curl "https://radio.stream.domain/api9/eventdata/49790578". Let's assume you get something like this:

{
+    "eventId": 49793707,
+    "eventStart": "2020-05-08 16:23:03",
+    "eventFinish": "2020-05-08 16:27:21",
+    "eventDuration": 254,
+    "eventType": "Song",
+    "eventSongTitle": "Pour Some Sugar On Me",
+    "eventSongArtist": "Def Leppard",
+    "eventImageUrl": "https://radio.stream.domain/artist/1-1/320x320/562.jpg?ver=1465083491",
+    "eventImageUrlSmall": "https://radio.stream.domain/artist/1-1/160x160/562.jpg?ver=1465083491",
+    "eventAppleMusicUrl": "https://geo.itunes.apple.com/dk/album/530707298?i=530707313"
+}
+

In this case, you would need to tell the server to look for "eventDuration" and "eventImageUrl" (or just "duration" and "url"). You can do that like this:

curl -X PUT "http://localhost:3689/api/settings/misc/streamurl_keywords_length" --data "{\"name\":\"streamurl_keywords_length\",\"value\":\"duration\"}"
+curl -X PUT "http://localhost:3689/api/settings/misc/streamurl_keywords_artwork_url" --data "{\"name\":\"streamurl_keywords_artwork_url\",\"value\":\"url\"}
+

If you want multiple search phrases then comma separate, e.g. "duration,length".

3) Set metadata with a custom script

If your radio station publishes metadata via another method than the above, e.g. just on their web site, then you will have to write a script that pulls the metadata and then pushes it to the server. To update metadata for the currently playing radio station use something like this JSON API request:

curl -X PUT "http://localhost:3689/api/queue/items/now_playing?title=Awesome%20title&artwork_url=http%3A%2F%2Fgyfgafguf.dk%2Fimages%2Fpige3.jpg"
+

If your radio station is not returning any artwork links, you can also just make a static artwork by placing a png/jpg in the same directory as the m3u, and with the same name, e.g. My Radio Stream.jpg for My Radio Stream.m3u.

\ No newline at end of file diff --git a/advanced/remote-access/index.html b/advanced/remote-access/index.html new file mode 100644 index 0000000000..18bf3d58d3 --- /dev/null +++ b/advanced/remote-access/index.html @@ -0,0 +1,2 @@ + Remote access - OwnTone
Skip to content

Remote access

It is possible to access a shared library over the internet from a DAAP client like iTunes. You must have remote access to the host machine.

First log in to the host and forward port 3689 to your local machine. You now need to broadcast the daap service to iTunes on your local machine. On macOS the command is:

dns-sd -P iTunesServer _daap._tcp local 3689 localhost.local 127.0.0.1 "ffid=12345"
+

The ffid key is required but its value does not matter.

Your library will now appear as 'iTunesServer' in iTunes.

You can also access your library remotely using something like Zerotier. See this guide for details.

\ No newline at end of file diff --git a/artwork/index.html b/artwork/index.html new file mode 100644 index 0000000000..166aa12b14 --- /dev/null +++ b/artwork/index.html @@ -0,0 +1 @@ + Artwork - OwnTone
Skip to content

Artwork

OwnTone has support for PNG and JPEG artwork which is either:

  • embedded in the media files
  • placed as separate image files in the library
  • made available online by the radio station

For media in your library, OwnTone will try to locate album and artist artwork (group artwork) by the following procedure:

  • if a file {artwork,cover,Folder}.{png,jpg} is found in one of the directories containing files that are part of the group, it is used as the artwork. The first file found is used, ordering is not guaranteed;
  • failing that, if [directory name].{png,jpg} is found in one of the directories containing files that are part of the group, it is used as the artwork. The first file found is used, ordering is not guaranteed;
  • failing that, individual files are examined and the first file found with an embedded artwork is used. Here again, ordering is not guaranteed.

{artwork,cover,Folder} are the default, you can add other base names in the configuration file. Here you can also enable/disable support for individual file artwork (instead of using the same artwork for all tracks in an entire album).

For playlists in your library, say /foo/bar.m3u, then for any http streams in the list, OwnTone will look for /foo/bar.{jpg,png}.

You can use symlinks for the artwork files.

OwnTone caches artwork in a separate cache file. The default path is /var/cache/owntone/cache.db and can be configured in the configuration file. The cache.db file can be deleted without losing the library and pairing informations.

\ No newline at end of file diff --git a/assets/extra.css b/assets/extra.css new file mode 100644 index 0000000000..1904d27018 --- /dev/null +++ b/assets/extra.css @@ -0,0 +1,86 @@ +/* + * MkDocs Material theme buttons have wrong colors for the theme + * setting: + * + * palette: + * scheme: default + * primary: white + * + * Thus the following CSS overwrites the button background- and + * text-colors. + */ +.md-button { + color: var(--md-accent-fg-color) !important; + border-color: currentColor !important; +} +.md-button:focus, +.md-button:hover { + color: var(--md-primary-fg-color) !important; + background-color: var(--md-accent-fg-color) !important; + border-color: var(--md-accent-fg-color) !important; +} + +/* + * The nav title has a click handler to scroll to the top + */ +.md-header-nav__title { + cursor: pointer; +} + +/* + * Text alignment + */ +.text-center { + text-align: center; +} + +/* + * Custom CSS for images + */ +.hidden { + visibility: hidden; + opacity: 0; + transition: visibility 0s linear 300ms, opacity 300ms; +} +.visible { + visibility: visible; + opacity: 1; + transition: visibility 0s linear 0s, opacity 300ms; +} +.fullscreen-image-background { + z-index: 25; + background-color: rgba(10, 10, 10, 0.5); + position: fixed; + bottom: 0; + left: 0; + right: 0; + top: 0; +} +.fullscreen-image-background img { + transition: opacity 1s; + cursor: zoom-out; + box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19); + z-index: 100; + position: fixed; + left: 0; + right: 0; + top: 0; + bottom: 0; + margin: 1rem auto; + max-height: calc(100vh - 2rem); + width: auto; +} +.zoom { + box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19); + border-radius: 0.2rem; + margin: 0.5rem; + width: 25%; + cursor: zoom-in; +} +.zoom-wrapper { + display: flex; + flex-direction: row; + align-items: center; + justify-content: center; + flex-wrap: wrap; +} diff --git a/assets/extra.js b/assets/extra.js new file mode 100644 index 0000000000..1717d99c06 --- /dev/null +++ b/assets/extra.js @@ -0,0 +1,32 @@ +/* + * Add click event handler for images with class="zoom" + */ +document.querySelectorAll('img.zoom').forEach(item => { + const p = item.parentElement; + if (!p.classList.contains('processed')) { + p.classList.add('processed'); + if (p.querySelectorAll('img.zoom').length === p.children.length) { + p.classList.add('zoom-wrapper'); + } + } + item.addEventListener('click', function () { + const img = document.getElementById('fullscreen-image-img'); + img.setAttribute('src', this.getAttribute('src')); + img.setAttribute('alt', this.getAttribute('alt')); + + const div = document.getElementById('fullscreen-image'); + div.classList.replace('hidden', 'visible'); + }) +}); + +var div = document.createElement('div'); +div.classList.add('fullscreen-image-background', 'hidden'); +div.id = 'fullscreen-image'; +var img = document.createElement('img'); +img.id = 'fullscreen-image-img'; +div.appendChild(img); + +div.addEventListener('click', function () { + this.classList.replace('visible', 'hidden'); +}); +document.body.appendChild(div); \ No newline at end of file diff --git a/assets/favicon.ico b/assets/favicon.ico new file mode 100644 index 0000000000..8521bedfcd Binary files /dev/null and b/assets/favicon.ico differ diff --git a/assets/images/favicon.png b/assets/images/favicon.png new file mode 100644 index 0000000000..1cf13b9f9d Binary files /dev/null and b/assets/images/favicon.png differ diff --git a/assets/images/screenshot-audiobooks-authors.png b/assets/images/screenshot-audiobooks-authors.png new file mode 100644 index 0000000000..c94b2bb7b3 Binary files /dev/null and b/assets/images/screenshot-audiobooks-authors.png differ diff --git a/assets/images/screenshot-audiobooks-books.png b/assets/images/screenshot-audiobooks-books.png new file mode 100644 index 0000000000..db6cae5f0a Binary files /dev/null and b/assets/images/screenshot-audiobooks-books.png differ diff --git a/assets/images/screenshot-files.png b/assets/images/screenshot-files.png new file mode 100644 index 0000000000..c940e804f2 Binary files /dev/null and b/assets/images/screenshot-files.png differ diff --git a/assets/images/screenshot-menu.png b/assets/images/screenshot-menu.png new file mode 100644 index 0000000000..28b795844d Binary files /dev/null and b/assets/images/screenshot-menu.png differ diff --git a/assets/images/screenshot-music-album.png b/assets/images/screenshot-music-album.png new file mode 100644 index 0000000000..0d0b9d06e2 Binary files /dev/null and b/assets/images/screenshot-music-album.png differ diff --git a/assets/images/screenshot-music-albums-options.png b/assets/images/screenshot-music-albums-options.png new file mode 100644 index 0000000000..5ff1272664 Binary files /dev/null and b/assets/images/screenshot-music-albums-options.png differ diff --git a/assets/images/screenshot-music-albums.png b/assets/images/screenshot-music-albums.png new file mode 100644 index 0000000000..725422dc77 Binary files /dev/null and b/assets/images/screenshot-music-albums.png differ diff --git a/assets/images/screenshot-music-artist.png b/assets/images/screenshot-music-artist.png new file mode 100644 index 0000000000..53d9fad2cc Binary files /dev/null and b/assets/images/screenshot-music-artist.png differ diff --git a/assets/images/screenshot-music-artists.png b/assets/images/screenshot-music-artists.png new file mode 100644 index 0000000000..770d8c7efa Binary files /dev/null and b/assets/images/screenshot-music-artists.png differ diff --git a/assets/images/screenshot-music-browse.png b/assets/images/screenshot-music-browse.png new file mode 100644 index 0000000000..1fdef89a31 Binary files /dev/null and b/assets/images/screenshot-music-browse.png differ diff --git a/assets/images/screenshot-music-spotify.png b/assets/images/screenshot-music-spotify.png new file mode 100644 index 0000000000..263b3db0fa Binary files /dev/null and b/assets/images/screenshot-music-spotify.png differ diff --git a/assets/images/screenshot-now-playing.png b/assets/images/screenshot-now-playing.png new file mode 100644 index 0000000000..bf37b6e034 Binary files /dev/null and b/assets/images/screenshot-now-playing.png differ diff --git a/assets/images/screenshot-outputs.png b/assets/images/screenshot-outputs.png new file mode 100644 index 0000000000..2c9468918e Binary files /dev/null and b/assets/images/screenshot-outputs.png differ diff --git a/assets/images/screenshot-podcast.png b/assets/images/screenshot-podcast.png new file mode 100644 index 0000000000..ffb538dd66 Binary files /dev/null and b/assets/images/screenshot-podcast.png differ diff --git a/assets/images/screenshot-podcasts.png b/assets/images/screenshot-podcasts.png new file mode 100644 index 0000000000..0731bfa1d5 Binary files /dev/null and b/assets/images/screenshot-podcasts.png differ diff --git a/assets/images/screenshot-queue.png b/assets/images/screenshot-queue.png new file mode 100644 index 0000000000..d5192fcaa0 Binary files /dev/null and b/assets/images/screenshot-queue.png differ diff --git a/assets/images/screenshot-search.png b/assets/images/screenshot-search.png new file mode 100644 index 0000000000..5a143962b0 Binary files /dev/null and b/assets/images/screenshot-search.png differ diff --git a/assets/javascripts/bundle.220ee61c.min.js b/assets/javascripts/bundle.220ee61c.min.js new file mode 100644 index 0000000000..116072a11e --- /dev/null +++ b/assets/javascripts/bundle.220ee61c.min.js @@ -0,0 +1,29 @@ +"use strict";(()=>{var Ci=Object.create;var gr=Object.defineProperty;var Ri=Object.getOwnPropertyDescriptor;var ki=Object.getOwnPropertyNames,Ht=Object.getOwnPropertySymbols,Hi=Object.getPrototypeOf,yr=Object.prototype.hasOwnProperty,nn=Object.prototype.propertyIsEnumerable;var rn=(e,t,r)=>t in e?gr(e,t,{enumerable:!0,configurable:!0,writable:!0,value:r}):e[t]=r,P=(e,t)=>{for(var r in t||(t={}))yr.call(t,r)&&rn(e,r,t[r]);if(Ht)for(var r of Ht(t))nn.call(t,r)&&rn(e,r,t[r]);return e};var on=(e,t)=>{var r={};for(var n in e)yr.call(e,n)&&t.indexOf(n)<0&&(r[n]=e[n]);if(e!=null&&Ht)for(var n of Ht(e))t.indexOf(n)<0&&nn.call(e,n)&&(r[n]=e[n]);return r};var Pt=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var Pi=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of ki(t))!yr.call(e,o)&&o!==r&&gr(e,o,{get:()=>t[o],enumerable:!(n=Ri(t,o))||n.enumerable});return e};var yt=(e,t,r)=>(r=e!=null?Ci(Hi(e)):{},Pi(t||!e||!e.__esModule?gr(r,"default",{value:e,enumerable:!0}):r,e));var sn=Pt((xr,an)=>{(function(e,t){typeof xr=="object"&&typeof an!="undefined"?t():typeof define=="function"&&define.amd?define(t):t()})(xr,function(){"use strict";function e(r){var n=!0,o=!1,i=null,s={text:!0,search:!0,url:!0,tel:!0,email:!0,password:!0,number:!0,date:!0,month:!0,week:!0,time:!0,datetime:!0,"datetime-local":!0};function a(O){return!!(O&&O!==document&&O.nodeName!=="HTML"&&O.nodeName!=="BODY"&&"classList"in O&&"contains"in O.classList)}function f(O){var Qe=O.type,De=O.tagName;return!!(De==="INPUT"&&s[Qe]&&!O.readOnly||De==="TEXTAREA"&&!O.readOnly||O.isContentEditable)}function c(O){O.classList.contains("focus-visible")||(O.classList.add("focus-visible"),O.setAttribute("data-focus-visible-added",""))}function u(O){O.hasAttribute("data-focus-visible-added")&&(O.classList.remove("focus-visible"),O.removeAttribute("data-focus-visible-added"))}function p(O){O.metaKey||O.altKey||O.ctrlKey||(a(r.activeElement)&&c(r.activeElement),n=!0)}function m(O){n=!1}function d(O){a(O.target)&&(n||f(O.target))&&c(O.target)}function h(O){a(O.target)&&(O.target.classList.contains("focus-visible")||O.target.hasAttribute("data-focus-visible-added"))&&(o=!0,window.clearTimeout(i),i=window.setTimeout(function(){o=!1},100),u(O.target))}function v(O){document.visibilityState==="hidden"&&(o&&(n=!0),Y())}function Y(){document.addEventListener("mousemove",N),document.addEventListener("mousedown",N),document.addEventListener("mouseup",N),document.addEventListener("pointermove",N),document.addEventListener("pointerdown",N),document.addEventListener("pointerup",N),document.addEventListener("touchmove",N),document.addEventListener("touchstart",N),document.addEventListener("touchend",N)}function B(){document.removeEventListener("mousemove",N),document.removeEventListener("mousedown",N),document.removeEventListener("mouseup",N),document.removeEventListener("pointermove",N),document.removeEventListener("pointerdown",N),document.removeEventListener("pointerup",N),document.removeEventListener("touchmove",N),document.removeEventListener("touchstart",N),document.removeEventListener("touchend",N)}function N(O){O.target.nodeName&&O.target.nodeName.toLowerCase()==="html"||(n=!1,B())}document.addEventListener("keydown",p,!0),document.addEventListener("mousedown",m,!0),document.addEventListener("pointerdown",m,!0),document.addEventListener("touchstart",m,!0),document.addEventListener("visibilitychange",v,!0),Y(),r.addEventListener("focus",d,!0),r.addEventListener("blur",h,!0),r.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&r.host?r.host.setAttribute("data-js-focus-visible",""):r.nodeType===Node.DOCUMENT_NODE&&(document.documentElement.classList.add("js-focus-visible"),document.documentElement.setAttribute("data-js-focus-visible",""))}if(typeof window!="undefined"&&typeof document!="undefined"){window.applyFocusVisiblePolyfill=e;var t;try{t=new CustomEvent("focus-visible-polyfill-ready")}catch(r){t=document.createEvent("CustomEvent"),t.initCustomEvent("focus-visible-polyfill-ready",!1,!1,{})}window.dispatchEvent(t)}typeof document!="undefined"&&e(document)})});var cn=Pt(Er=>{(function(e){var t=function(){try{return!!Symbol.iterator}catch(c){return!1}},r=t(),n=function(c){var u={next:function(){var p=c.shift();return{done:p===void 0,value:p}}};return r&&(u[Symbol.iterator]=function(){return u}),u},o=function(c){return encodeURIComponent(c).replace(/%20/g,"+")},i=function(c){return decodeURIComponent(String(c).replace(/\+/g," "))},s=function(){var c=function(p){Object.defineProperty(this,"_entries",{writable:!0,value:{}});var m=typeof p;if(m!=="undefined")if(m==="string")p!==""&&this._fromString(p);else if(p instanceof c){var d=this;p.forEach(function(B,N){d.append(N,B)})}else if(p!==null&&m==="object")if(Object.prototype.toString.call(p)==="[object Array]")for(var h=0;hd[0]?1:0}),c._entries&&(c._entries={});for(var p=0;p1?i(d[1]):"")}})})(typeof global!="undefined"?global:typeof window!="undefined"?window:typeof self!="undefined"?self:Er);(function(e){var t=function(){try{var o=new e.URL("b","http://a");return o.pathname="c d",o.href==="http://a/c%20d"&&o.searchParams}catch(i){return!1}},r=function(){var o=e.URL,i=function(f,c){typeof f!="string"&&(f=String(f)),c&&typeof c!="string"&&(c=String(c));var u=document,p;if(c&&(e.location===void 0||c!==e.location.href)){c=c.toLowerCase(),u=document.implementation.createHTMLDocument(""),p=u.createElement("base"),p.href=c,u.head.appendChild(p);try{if(p.href.indexOf(c)!==0)throw new Error(p.href)}catch(O){throw new Error("URL unable to set base "+c+" due to "+O)}}var m=u.createElement("a");m.href=f,p&&(u.body.appendChild(m),m.href=m.href);var d=u.createElement("input");if(d.type="url",d.value=f,m.protocol===":"||!/:/.test(m.href)||!d.checkValidity()&&!c)throw new TypeError("Invalid URL");Object.defineProperty(this,"_anchorElement",{value:m});var h=new e.URLSearchParams(this.search),v=!0,Y=!0,B=this;["append","delete","set"].forEach(function(O){var Qe=h[O];h[O]=function(){Qe.apply(h,arguments),v&&(Y=!1,B.search=h.toString(),Y=!0)}}),Object.defineProperty(this,"searchParams",{value:h,enumerable:!0});var N=void 0;Object.defineProperty(this,"_updateSearchParams",{enumerable:!1,configurable:!1,writable:!1,value:function(){this.search!==N&&(N=this.search,Y&&(v=!1,this.searchParams._fromString(this.search),v=!0))}})},s=i.prototype,a=function(f){Object.defineProperty(s,f,{get:function(){return this._anchorElement[f]},set:function(c){this._anchorElement[f]=c},enumerable:!0})};["hash","host","hostname","port","protocol"].forEach(function(f){a(f)}),Object.defineProperty(s,"search",{get:function(){return this._anchorElement.search},set:function(f){this._anchorElement.search=f,this._updateSearchParams()},enumerable:!0}),Object.defineProperties(s,{toString:{get:function(){var f=this;return function(){return f.href}}},href:{get:function(){return this._anchorElement.href.replace(/\?$/,"")},set:function(f){this._anchorElement.href=f,this._updateSearchParams()},enumerable:!0},pathname:{get:function(){return this._anchorElement.pathname.replace(/(^\/?)/,"/")},set:function(f){this._anchorElement.pathname=f},enumerable:!0},origin:{get:function(){var f={"http:":80,"https:":443,"ftp:":21}[this._anchorElement.protocol],c=this._anchorElement.port!=f&&this._anchorElement.port!=="";return this._anchorElement.protocol+"//"+this._anchorElement.hostname+(c?":"+this._anchorElement.port:"")},enumerable:!0},password:{get:function(){return""},set:function(f){},enumerable:!0},username:{get:function(){return""},set:function(f){},enumerable:!0}}),i.createObjectURL=function(f){return o.createObjectURL.apply(o,arguments)},i.revokeObjectURL=function(f){return o.revokeObjectURL.apply(o,arguments)},e.URL=i};if(t()||r(),e.location!==void 0&&!("origin"in e.location)){var n=function(){return e.location.protocol+"//"+e.location.hostname+(e.location.port?":"+e.location.port:"")};try{Object.defineProperty(e.location,"origin",{get:n,enumerable:!0})}catch(o){setInterval(function(){e.location.origin=n()},100)}}})(typeof global!="undefined"?global:typeof window!="undefined"?window:typeof self!="undefined"?self:Er)});var qr=Pt((Mt,Nr)=>{/*! + * clipboard.js v2.0.11 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */(function(t,r){typeof Mt=="object"&&typeof Nr=="object"?Nr.exports=r():typeof define=="function"&&define.amd?define([],r):typeof Mt=="object"?Mt.ClipboardJS=r():t.ClipboardJS=r()})(Mt,function(){return function(){var e={686:function(n,o,i){"use strict";i.d(o,{default:function(){return Ai}});var s=i(279),a=i.n(s),f=i(370),c=i.n(f),u=i(817),p=i.n(u);function m(j){try{return document.execCommand(j)}catch(T){return!1}}var d=function(T){var E=p()(T);return m("cut"),E},h=d;function v(j){var T=document.documentElement.getAttribute("dir")==="rtl",E=document.createElement("textarea");E.style.fontSize="12pt",E.style.border="0",E.style.padding="0",E.style.margin="0",E.style.position="absolute",E.style[T?"right":"left"]="-9999px";var H=window.pageYOffset||document.documentElement.scrollTop;return E.style.top="".concat(H,"px"),E.setAttribute("readonly",""),E.value=j,E}var Y=function(T,E){var H=v(T);E.container.appendChild(H);var I=p()(H);return m("copy"),H.remove(),I},B=function(T){var E=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body},H="";return typeof T=="string"?H=Y(T,E):T instanceof HTMLInputElement&&!["text","search","url","tel","password"].includes(T==null?void 0:T.type)?H=Y(T.value,E):(H=p()(T),m("copy")),H},N=B;function O(j){"@babel/helpers - typeof";return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?O=function(E){return typeof E}:O=function(E){return E&&typeof Symbol=="function"&&E.constructor===Symbol&&E!==Symbol.prototype?"symbol":typeof E},O(j)}var Qe=function(){var T=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{},E=T.action,H=E===void 0?"copy":E,I=T.container,q=T.target,Me=T.text;if(H!=="copy"&&H!=="cut")throw new Error('Invalid "action" value, use either "copy" or "cut"');if(q!==void 0)if(q&&O(q)==="object"&&q.nodeType===1){if(H==="copy"&&q.hasAttribute("disabled"))throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');if(H==="cut"&&(q.hasAttribute("readonly")||q.hasAttribute("disabled")))throw new Error(`Invalid "target" attribute. You can't cut text from elements with "readonly" or "disabled" attributes`)}else throw new Error('Invalid "target" value, use a valid Element');if(Me)return N(Me,{container:I});if(q)return H==="cut"?h(q):N(q,{container:I})},De=Qe;function $e(j){"@babel/helpers - typeof";return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?$e=function(E){return typeof E}:$e=function(E){return E&&typeof Symbol=="function"&&E.constructor===Symbol&&E!==Symbol.prototype?"symbol":typeof E},$e(j)}function Ei(j,T){if(!(j instanceof T))throw new TypeError("Cannot call a class as a function")}function tn(j,T){for(var E=0;E0&&arguments[0]!==void 0?arguments[0]:{};this.action=typeof I.action=="function"?I.action:this.defaultAction,this.target=typeof I.target=="function"?I.target:this.defaultTarget,this.text=typeof I.text=="function"?I.text:this.defaultText,this.container=$e(I.container)==="object"?I.container:document.body}},{key:"listenClick",value:function(I){var q=this;this.listener=c()(I,"click",function(Me){return q.onClick(Me)})}},{key:"onClick",value:function(I){var q=I.delegateTarget||I.currentTarget,Me=this.action(q)||"copy",kt=De({action:Me,container:this.container,target:this.target(q),text:this.text(q)});this.emit(kt?"success":"error",{action:Me,text:kt,trigger:q,clearSelection:function(){q&&q.focus(),window.getSelection().removeAllRanges()}})}},{key:"defaultAction",value:function(I){return vr("action",I)}},{key:"defaultTarget",value:function(I){var q=vr("target",I);if(q)return document.querySelector(q)}},{key:"defaultText",value:function(I){return vr("text",I)}},{key:"destroy",value:function(){this.listener.destroy()}}],[{key:"copy",value:function(I){var q=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body};return N(I,q)}},{key:"cut",value:function(I){return h(I)}},{key:"isSupported",value:function(){var I=arguments.length>0&&arguments[0]!==void 0?arguments[0]:["copy","cut"],q=typeof I=="string"?[I]:I,Me=!!document.queryCommandSupported;return q.forEach(function(kt){Me=Me&&!!document.queryCommandSupported(kt)}),Me}}]),E}(a()),Ai=Li},828:function(n){var o=9;if(typeof Element!="undefined"&&!Element.prototype.matches){var i=Element.prototype;i.matches=i.matchesSelector||i.mozMatchesSelector||i.msMatchesSelector||i.oMatchesSelector||i.webkitMatchesSelector}function s(a,f){for(;a&&a.nodeType!==o;){if(typeof a.matches=="function"&&a.matches(f))return a;a=a.parentNode}}n.exports=s},438:function(n,o,i){var s=i(828);function a(u,p,m,d,h){var v=c.apply(this,arguments);return u.addEventListener(m,v,h),{destroy:function(){u.removeEventListener(m,v,h)}}}function f(u,p,m,d,h){return typeof u.addEventListener=="function"?a.apply(null,arguments):typeof m=="function"?a.bind(null,document).apply(null,arguments):(typeof u=="string"&&(u=document.querySelectorAll(u)),Array.prototype.map.call(u,function(v){return a(v,p,m,d,h)}))}function c(u,p,m,d){return function(h){h.delegateTarget=s(h.target,p),h.delegateTarget&&d.call(u,h)}}n.exports=f},879:function(n,o){o.node=function(i){return i!==void 0&&i instanceof HTMLElement&&i.nodeType===1},o.nodeList=function(i){var s=Object.prototype.toString.call(i);return i!==void 0&&(s==="[object NodeList]"||s==="[object HTMLCollection]")&&"length"in i&&(i.length===0||o.node(i[0]))},o.string=function(i){return typeof i=="string"||i instanceof String},o.fn=function(i){var s=Object.prototype.toString.call(i);return s==="[object Function]"}},370:function(n,o,i){var s=i(879),a=i(438);function f(m,d,h){if(!m&&!d&&!h)throw new Error("Missing required arguments");if(!s.string(d))throw new TypeError("Second argument must be a String");if(!s.fn(h))throw new TypeError("Third argument must be a Function");if(s.node(m))return c(m,d,h);if(s.nodeList(m))return u(m,d,h);if(s.string(m))return p(m,d,h);throw new TypeError("First argument must be a String, HTMLElement, HTMLCollection, or NodeList")}function c(m,d,h){return m.addEventListener(d,h),{destroy:function(){m.removeEventListener(d,h)}}}function u(m,d,h){return Array.prototype.forEach.call(m,function(v){v.addEventListener(d,h)}),{destroy:function(){Array.prototype.forEach.call(m,function(v){v.removeEventListener(d,h)})}}}function p(m,d,h){return a(document.body,m,d,h)}n.exports=f},817:function(n){function o(i){var s;if(i.nodeName==="SELECT")i.focus(),s=i.value;else if(i.nodeName==="INPUT"||i.nodeName==="TEXTAREA"){var a=i.hasAttribute("readonly");a||i.setAttribute("readonly",""),i.select(),i.setSelectionRange(0,i.value.length),a||i.removeAttribute("readonly"),s=i.value}else{i.hasAttribute("contenteditable")&&i.focus();var f=window.getSelection(),c=document.createRange();c.selectNodeContents(i),f.removeAllRanges(),f.addRange(c),s=f.toString()}return s}n.exports=o},279:function(n){function o(){}o.prototype={on:function(i,s,a){var f=this.e||(this.e={});return(f[i]||(f[i]=[])).push({fn:s,ctx:a}),this},once:function(i,s,a){var f=this;function c(){f.off(i,c),s.apply(a,arguments)}return c._=s,this.on(i,c,a)},emit:function(i){var s=[].slice.call(arguments,1),a=((this.e||(this.e={}))[i]||[]).slice(),f=0,c=a.length;for(f;f{"use strict";/*! + * escape-html + * Copyright(c) 2012-2013 TJ Holowaychuk + * Copyright(c) 2015 Andreas Lubbe + * Copyright(c) 2015 Tiancheng "Timothy" Gu + * MIT Licensed + */var rs=/["'&<>]/;Yo.exports=ns;function ns(e){var t=""+e,r=rs.exec(t);if(!r)return t;var n,o="",i=0,s=0;for(i=r.index;i0&&i[i.length-1])&&(c[0]===6||c[0]===2)){r=0;continue}if(c[0]===3&&(!i||c[1]>i[0]&&c[1]=e.length&&(e=void 0),{value:e&&e[n++],done:!e}}};throw new TypeError(t?"Object is not iterable.":"Symbol.iterator is not defined.")}function W(e,t){var r=typeof Symbol=="function"&&e[Symbol.iterator];if(!r)return e;var n=r.call(e),o,i=[],s;try{for(;(t===void 0||t-- >0)&&!(o=n.next()).done;)i.push(o.value)}catch(a){s={error:a}}finally{try{o&&!o.done&&(r=n.return)&&r.call(n)}finally{if(s)throw s.error}}return i}function D(e,t,r){if(r||arguments.length===2)for(var n=0,o=t.length,i;n1||a(m,d)})})}function a(m,d){try{f(n[m](d))}catch(h){p(i[0][3],h)}}function f(m){m.value instanceof et?Promise.resolve(m.value.v).then(c,u):p(i[0][2],m)}function c(m){a("next",m)}function u(m){a("throw",m)}function p(m,d){m(d),i.shift(),i.length&&a(i[0][0],i[0][1])}}function pn(e){if(!Symbol.asyncIterator)throw new TypeError("Symbol.asyncIterator is not defined.");var t=e[Symbol.asyncIterator],r;return t?t.call(e):(e=typeof Ee=="function"?Ee(e):e[Symbol.iterator](),r={},n("next"),n("throw"),n("return"),r[Symbol.asyncIterator]=function(){return this},r);function n(i){r[i]=e[i]&&function(s){return new Promise(function(a,f){s=e[i](s),o(a,f,s.done,s.value)})}}function o(i,s,a,f){Promise.resolve(f).then(function(c){i({value:c,done:a})},s)}}function C(e){return typeof e=="function"}function at(e){var t=function(n){Error.call(n),n.stack=new Error().stack},r=e(t);return r.prototype=Object.create(Error.prototype),r.prototype.constructor=r,r}var It=at(function(e){return function(r){e(this),this.message=r?r.length+` errors occurred during unsubscription: +`+r.map(function(n,o){return o+1+") "+n.toString()}).join(` + `):"",this.name="UnsubscriptionError",this.errors=r}});function Ve(e,t){if(e){var r=e.indexOf(t);0<=r&&e.splice(r,1)}}var Ie=function(){function e(t){this.initialTeardown=t,this.closed=!1,this._parentage=null,this._finalizers=null}return e.prototype.unsubscribe=function(){var t,r,n,o,i;if(!this.closed){this.closed=!0;var s=this._parentage;if(s)if(this._parentage=null,Array.isArray(s))try{for(var a=Ee(s),f=a.next();!f.done;f=a.next()){var c=f.value;c.remove(this)}}catch(v){t={error:v}}finally{try{f&&!f.done&&(r=a.return)&&r.call(a)}finally{if(t)throw t.error}}else s.remove(this);var u=this.initialTeardown;if(C(u))try{u()}catch(v){i=v instanceof It?v.errors:[v]}var p=this._finalizers;if(p){this._finalizers=null;try{for(var m=Ee(p),d=m.next();!d.done;d=m.next()){var h=d.value;try{ln(h)}catch(v){i=i!=null?i:[],v instanceof It?i=D(D([],W(i)),W(v.errors)):i.push(v)}}}catch(v){n={error:v}}finally{try{d&&!d.done&&(o=m.return)&&o.call(m)}finally{if(n)throw n.error}}}if(i)throw new It(i)}},e.prototype.add=function(t){var r;if(t&&t!==this)if(this.closed)ln(t);else{if(t instanceof e){if(t.closed||t._hasParent(this))return;t._addParent(this)}(this._finalizers=(r=this._finalizers)!==null&&r!==void 0?r:[]).push(t)}},e.prototype._hasParent=function(t){var r=this._parentage;return r===t||Array.isArray(r)&&r.includes(t)},e.prototype._addParent=function(t){var r=this._parentage;this._parentage=Array.isArray(r)?(r.push(t),r):r?[r,t]:t},e.prototype._removeParent=function(t){var r=this._parentage;r===t?this._parentage=null:Array.isArray(r)&&Ve(r,t)},e.prototype.remove=function(t){var r=this._finalizers;r&&Ve(r,t),t instanceof e&&t._removeParent(this)},e.EMPTY=function(){var t=new e;return t.closed=!0,t}(),e}();var Sr=Ie.EMPTY;function jt(e){return e instanceof Ie||e&&"closed"in e&&C(e.remove)&&C(e.add)&&C(e.unsubscribe)}function ln(e){C(e)?e():e.unsubscribe()}var Le={onUnhandledError:null,onStoppedNotification:null,Promise:void 0,useDeprecatedSynchronousErrorHandling:!1,useDeprecatedNextContext:!1};var st={setTimeout:function(e,t){for(var r=[],n=2;n0},enumerable:!1,configurable:!0}),t.prototype._trySubscribe=function(r){return this._throwIfClosed(),e.prototype._trySubscribe.call(this,r)},t.prototype._subscribe=function(r){return this._throwIfClosed(),this._checkFinalizedStatuses(r),this._innerSubscribe(r)},t.prototype._innerSubscribe=function(r){var n=this,o=this,i=o.hasError,s=o.isStopped,a=o.observers;return i||s?Sr:(this.currentObservers=null,a.push(r),new Ie(function(){n.currentObservers=null,Ve(a,r)}))},t.prototype._checkFinalizedStatuses=function(r){var n=this,o=n.hasError,i=n.thrownError,s=n.isStopped;o?r.error(i):s&&r.complete()},t.prototype.asObservable=function(){var r=new F;return r.source=this,r},t.create=function(r,n){return new xn(r,n)},t}(F);var xn=function(e){ie(t,e);function t(r,n){var o=e.call(this)||this;return o.destination=r,o.source=n,o}return t.prototype.next=function(r){var n,o;(o=(n=this.destination)===null||n===void 0?void 0:n.next)===null||o===void 0||o.call(n,r)},t.prototype.error=function(r){var n,o;(o=(n=this.destination)===null||n===void 0?void 0:n.error)===null||o===void 0||o.call(n,r)},t.prototype.complete=function(){var r,n;(n=(r=this.destination)===null||r===void 0?void 0:r.complete)===null||n===void 0||n.call(r)},t.prototype._subscribe=function(r){var n,o;return(o=(n=this.source)===null||n===void 0?void 0:n.subscribe(r))!==null&&o!==void 0?o:Sr},t}(x);var Et={now:function(){return(Et.delegate||Date).now()},delegate:void 0};var wt=function(e){ie(t,e);function t(r,n,o){r===void 0&&(r=1/0),n===void 0&&(n=1/0),o===void 0&&(o=Et);var i=e.call(this)||this;return i._bufferSize=r,i._windowTime=n,i._timestampProvider=o,i._buffer=[],i._infiniteTimeWindow=!0,i._infiniteTimeWindow=n===1/0,i._bufferSize=Math.max(1,r),i._windowTime=Math.max(1,n),i}return t.prototype.next=function(r){var n=this,o=n.isStopped,i=n._buffer,s=n._infiniteTimeWindow,a=n._timestampProvider,f=n._windowTime;o||(i.push(r),!s&&i.push(a.now()+f)),this._trimBuffer(),e.prototype.next.call(this,r)},t.prototype._subscribe=function(r){this._throwIfClosed(),this._trimBuffer();for(var n=this._innerSubscribe(r),o=this,i=o._infiniteTimeWindow,s=o._buffer,a=s.slice(),f=0;f0?e.prototype.requestAsyncId.call(this,r,n,o):(r.actions.push(this),r._scheduled||(r._scheduled=ut.requestAnimationFrame(function(){return r.flush(void 0)})))},t.prototype.recycleAsyncId=function(r,n,o){var i;if(o===void 0&&(o=0),o!=null?o>0:this.delay>0)return e.prototype.recycleAsyncId.call(this,r,n,o);var s=r.actions;n!=null&&((i=s[s.length-1])===null||i===void 0?void 0:i.id)!==n&&(ut.cancelAnimationFrame(n),r._scheduled=void 0)},t}(Wt);var Sn=function(e){ie(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t.prototype.flush=function(r){this._active=!0;var n=this._scheduled;this._scheduled=void 0;var o=this.actions,i;r=r||o.shift();do if(i=r.execute(r.state,r.delay))break;while((r=o[0])&&r.id===n&&o.shift());if(this._active=!1,i){for(;(r=o[0])&&r.id===n&&o.shift();)r.unsubscribe();throw i}},t}(Dt);var Oe=new Sn(wn);var M=new F(function(e){return e.complete()});function Vt(e){return e&&C(e.schedule)}function Cr(e){return e[e.length-1]}function Ye(e){return C(Cr(e))?e.pop():void 0}function Te(e){return Vt(Cr(e))?e.pop():void 0}function zt(e,t){return typeof Cr(e)=="number"?e.pop():t}var pt=function(e){return e&&typeof e.length=="number"&&typeof e!="function"};function Nt(e){return C(e==null?void 0:e.then)}function qt(e){return C(e[ft])}function Kt(e){return Symbol.asyncIterator&&C(e==null?void 0:e[Symbol.asyncIterator])}function Qt(e){return new TypeError("You provided "+(e!==null&&typeof e=="object"?"an invalid object":"'"+e+"'")+" where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.")}function zi(){return typeof Symbol!="function"||!Symbol.iterator?"@@iterator":Symbol.iterator}var Yt=zi();function Gt(e){return C(e==null?void 0:e[Yt])}function Bt(e){return un(this,arguments,function(){var r,n,o,i;return $t(this,function(s){switch(s.label){case 0:r=e.getReader(),s.label=1;case 1:s.trys.push([1,,9,10]),s.label=2;case 2:return[4,et(r.read())];case 3:return n=s.sent(),o=n.value,i=n.done,i?[4,et(void 0)]:[3,5];case 4:return[2,s.sent()];case 5:return[4,et(o)];case 6:return[4,s.sent()];case 7:return s.sent(),[3,2];case 8:return[3,10];case 9:return r.releaseLock(),[7];case 10:return[2]}})})}function Jt(e){return C(e==null?void 0:e.getReader)}function U(e){if(e instanceof F)return e;if(e!=null){if(qt(e))return Ni(e);if(pt(e))return qi(e);if(Nt(e))return Ki(e);if(Kt(e))return On(e);if(Gt(e))return Qi(e);if(Jt(e))return Yi(e)}throw Qt(e)}function Ni(e){return new F(function(t){var r=e[ft]();if(C(r.subscribe))return r.subscribe(t);throw new TypeError("Provided object does not correctly implement Symbol.observable")})}function qi(e){return new F(function(t){for(var r=0;r=2;return function(n){return n.pipe(e?A(function(o,i){return e(o,i,n)}):de,ge(1),r?He(t):Dn(function(){return new Zt}))}}function Vn(){for(var e=[],t=0;t=2,!0))}function pe(e){e===void 0&&(e={});var t=e.connector,r=t===void 0?function(){return new x}:t,n=e.resetOnError,o=n===void 0?!0:n,i=e.resetOnComplete,s=i===void 0?!0:i,a=e.resetOnRefCountZero,f=a===void 0?!0:a;return function(c){var u,p,m,d=0,h=!1,v=!1,Y=function(){p==null||p.unsubscribe(),p=void 0},B=function(){Y(),u=m=void 0,h=v=!1},N=function(){var O=u;B(),O==null||O.unsubscribe()};return y(function(O,Qe){d++,!v&&!h&&Y();var De=m=m!=null?m:r();Qe.add(function(){d--,d===0&&!v&&!h&&(p=$r(N,f))}),De.subscribe(Qe),!u&&d>0&&(u=new rt({next:function($e){return De.next($e)},error:function($e){v=!0,Y(),p=$r(B,o,$e),De.error($e)},complete:function(){h=!0,Y(),p=$r(B,s),De.complete()}}),U(O).subscribe(u))})(c)}}function $r(e,t){for(var r=[],n=2;ne.next(document)),e}function K(e,t=document){return Array.from(t.querySelectorAll(e))}function z(e,t=document){let r=ce(e,t);if(typeof r=="undefined")throw new ReferenceError(`Missing element: expected "${e}" to be present`);return r}function ce(e,t=document){return t.querySelector(e)||void 0}function _e(){return document.activeElement instanceof HTMLElement&&document.activeElement||void 0}function tr(e){return L(b(document.body,"focusin"),b(document.body,"focusout")).pipe(ke(1),l(()=>{let t=_e();return typeof t!="undefined"?e.contains(t):!1}),V(e===_e()),J())}function Xe(e){return{x:e.offsetLeft,y:e.offsetTop}}function Kn(e){return L(b(window,"load"),b(window,"resize")).pipe(Ce(0,Oe),l(()=>Xe(e)),V(Xe(e)))}function rr(e){return{x:e.scrollLeft,y:e.scrollTop}}function dt(e){return L(b(e,"scroll"),b(window,"resize")).pipe(Ce(0,Oe),l(()=>rr(e)),V(rr(e)))}var Yn=function(){if(typeof Map!="undefined")return Map;function e(t,r){var n=-1;return t.some(function(o,i){return o[0]===r?(n=i,!0):!1}),n}return function(){function t(){this.__entries__=[]}return Object.defineProperty(t.prototype,"size",{get:function(){return this.__entries__.length},enumerable:!0,configurable:!0}),t.prototype.get=function(r){var n=e(this.__entries__,r),o=this.__entries__[n];return o&&o[1]},t.prototype.set=function(r,n){var o=e(this.__entries__,r);~o?this.__entries__[o][1]=n:this.__entries__.push([r,n])},t.prototype.delete=function(r){var n=this.__entries__,o=e(n,r);~o&&n.splice(o,1)},t.prototype.has=function(r){return!!~e(this.__entries__,r)},t.prototype.clear=function(){this.__entries__.splice(0)},t.prototype.forEach=function(r,n){n===void 0&&(n=null);for(var o=0,i=this.__entries__;o0},e.prototype.connect_=function(){!Wr||this.connected_||(document.addEventListener("transitionend",this.onTransitionEnd_),window.addEventListener("resize",this.refresh),va?(this.mutationsObserver_=new MutationObserver(this.refresh),this.mutationsObserver_.observe(document,{attributes:!0,childList:!0,characterData:!0,subtree:!0})):(document.addEventListener("DOMSubtreeModified",this.refresh),this.mutationEventsAdded_=!0),this.connected_=!0)},e.prototype.disconnect_=function(){!Wr||!this.connected_||(document.removeEventListener("transitionend",this.onTransitionEnd_),window.removeEventListener("resize",this.refresh),this.mutationsObserver_&&this.mutationsObserver_.disconnect(),this.mutationEventsAdded_&&document.removeEventListener("DOMSubtreeModified",this.refresh),this.mutationsObserver_=null,this.mutationEventsAdded_=!1,this.connected_=!1)},e.prototype.onTransitionEnd_=function(t){var r=t.propertyName,n=r===void 0?"":r,o=ba.some(function(i){return!!~n.indexOf(i)});o&&this.refresh()},e.getInstance=function(){return this.instance_||(this.instance_=new e),this.instance_},e.instance_=null,e}(),Gn=function(e,t){for(var r=0,n=Object.keys(t);r0},e}(),Jn=typeof WeakMap!="undefined"?new WeakMap:new Yn,Xn=function(){function e(t){if(!(this instanceof e))throw new TypeError("Cannot call a class as a function.");if(!arguments.length)throw new TypeError("1 argument required, but only 0 present.");var r=ga.getInstance(),n=new La(t,r,this);Jn.set(this,n)}return e}();["observe","unobserve","disconnect"].forEach(function(e){Xn.prototype[e]=function(){var t;return(t=Jn.get(this))[e].apply(t,arguments)}});var Aa=function(){return typeof nr.ResizeObserver!="undefined"?nr.ResizeObserver:Xn}(),Zn=Aa;var eo=new x,Ca=$(()=>k(new Zn(e=>{for(let t of e)eo.next(t)}))).pipe(g(e=>L(ze,k(e)).pipe(R(()=>e.disconnect()))),X(1));function he(e){return{width:e.offsetWidth,height:e.offsetHeight}}function ye(e){return Ca.pipe(S(t=>t.observe(e)),g(t=>eo.pipe(A(({target:r})=>r===e),R(()=>t.unobserve(e)),l(()=>he(e)))),V(he(e)))}function bt(e){return{width:e.scrollWidth,height:e.scrollHeight}}function ar(e){let t=e.parentElement;for(;t&&(e.scrollWidth<=t.scrollWidth&&e.scrollHeight<=t.scrollHeight);)t=(e=t).parentElement;return t?e:void 0}var to=new x,Ra=$(()=>k(new IntersectionObserver(e=>{for(let t of e)to.next(t)},{threshold:0}))).pipe(g(e=>L(ze,k(e)).pipe(R(()=>e.disconnect()))),X(1));function sr(e){return Ra.pipe(S(t=>t.observe(e)),g(t=>to.pipe(A(({target:r})=>r===e),R(()=>t.unobserve(e)),l(({isIntersecting:r})=>r))))}function ro(e,t=16){return dt(e).pipe(l(({y:r})=>{let n=he(e),o=bt(e);return r>=o.height-n.height-t}),J())}var cr={drawer:z("[data-md-toggle=drawer]"),search:z("[data-md-toggle=search]")};function no(e){return cr[e].checked}function Ke(e,t){cr[e].checked!==t&&cr[e].click()}function Ue(e){let t=cr[e];return b(t,"change").pipe(l(()=>t.checked),V(t.checked))}function ka(e,t){switch(e.constructor){case HTMLInputElement:return e.type==="radio"?/^Arrow/.test(t):!0;case HTMLSelectElement:case HTMLTextAreaElement:return!0;default:return e.isContentEditable}}function Ha(){return L(b(window,"compositionstart").pipe(l(()=>!0)),b(window,"compositionend").pipe(l(()=>!1))).pipe(V(!1))}function oo(){let e=b(window,"keydown").pipe(A(t=>!(t.metaKey||t.ctrlKey)),l(t=>({mode:no("search")?"search":"global",type:t.key,claim(){t.preventDefault(),t.stopPropagation()}})),A(({mode:t,type:r})=>{if(t==="global"){let n=_e();if(typeof n!="undefined")return!ka(n,r)}return!0}),pe());return Ha().pipe(g(t=>t?M:e))}function le(){return new URL(location.href)}function ot(e){location.href=e.href}function io(){return new x}function ao(e,t){if(typeof t=="string"||typeof t=="number")e.innerHTML+=t.toString();else if(t instanceof Node)e.appendChild(t);else if(Array.isArray(t))for(let r of t)ao(e,r)}function _(e,t,...r){let n=document.createElement(e);if(t)for(let o of Object.keys(t))typeof t[o]!="undefined"&&(typeof t[o]!="boolean"?n.setAttribute(o,t[o]):n.setAttribute(o,""));for(let o of r)ao(n,o);return n}function fr(e){if(e>999){let t=+((e-950)%1e3>99);return`${((e+1e-6)/1e3).toFixed(t)}k`}else return e.toString()}function so(){return location.hash.substring(1)}function Dr(e){let t=_("a",{href:e});t.addEventListener("click",r=>r.stopPropagation()),t.click()}function Pa(e){return L(b(window,"hashchange"),e).pipe(l(so),V(so()),A(t=>t.length>0),X(1))}function co(e){return Pa(e).pipe(l(t=>ce(`[id="${t}"]`)),A(t=>typeof t!="undefined"))}function Vr(e){let t=matchMedia(e);return er(r=>t.addListener(()=>r(t.matches))).pipe(V(t.matches))}function fo(){let e=matchMedia("print");return L(b(window,"beforeprint").pipe(l(()=>!0)),b(window,"afterprint").pipe(l(()=>!1))).pipe(V(e.matches))}function zr(e,t){return e.pipe(g(r=>r?t():M))}function ur(e,t={credentials:"same-origin"}){return ue(fetch(`${e}`,t)).pipe(fe(()=>M),g(r=>r.status!==200?Ot(()=>new Error(r.statusText)):k(r)))}function We(e,t){return ur(e,t).pipe(g(r=>r.json()),X(1))}function uo(e,t){let r=new DOMParser;return ur(e,t).pipe(g(n=>n.text()),l(n=>r.parseFromString(n,"text/xml")),X(1))}function pr(e){let t=_("script",{src:e});return $(()=>(document.head.appendChild(t),L(b(t,"load"),b(t,"error").pipe(g(()=>Ot(()=>new ReferenceError(`Invalid script: ${e}`))))).pipe(l(()=>{}),R(()=>document.head.removeChild(t)),ge(1))))}function po(){return{x:Math.max(0,scrollX),y:Math.max(0,scrollY)}}function lo(){return L(b(window,"scroll",{passive:!0}),b(window,"resize",{passive:!0})).pipe(l(po),V(po()))}function mo(){return{width:innerWidth,height:innerHeight}}function ho(){return b(window,"resize",{passive:!0}).pipe(l(mo),V(mo()))}function bo(){return G([lo(),ho()]).pipe(l(([e,t])=>({offset:e,size:t})),X(1))}function lr(e,{viewport$:t,header$:r}){let n=t.pipe(ee("size")),o=G([n,r]).pipe(l(()=>Xe(e)));return G([r,t,o]).pipe(l(([{height:i},{offset:s,size:a},{x:f,y:c}])=>({offset:{x:s.x-f,y:s.y-c+i},size:a})))}(()=>{function e(n,o){parent.postMessage(n,o||"*")}function t(...n){return n.reduce((o,i)=>o.then(()=>new Promise(s=>{let a=document.createElement("script");a.src=i,a.onload=s,document.body.appendChild(a)})),Promise.resolve())}var r=class extends EventTarget{constructor(n){super(),this.url=n,this.m=i=>{i.source===this.w&&(this.dispatchEvent(new MessageEvent("message",{data:i.data})),this.onmessage&&this.onmessage(i))},this.e=(i,s,a,f,c)=>{if(s===`${this.url}`){let u=new ErrorEvent("error",{message:i,filename:s,lineno:a,colno:f,error:c});this.dispatchEvent(u),this.onerror&&this.onerror(u)}};let o=document.createElement("iframe");o.hidden=!0,document.body.appendChild(this.iframe=o),this.w.document.open(),this.w.document.write(`

Build instructions for OwnTone

This document contains instructions for building OwnTone from the git tree. If you just want to build from a release tarball, you don't need the build tools (git, autotools, autoconf, automake, gawk, gperf, gettext, bison and flex), and you can skip the autoreconf step.

Quick version for Debian/Ubuntu users

If you are the lucky kind, this should get you all the required tools and libraries:

sudo apt-get install \
+  build-essential git autotools-dev autoconf automake libtool gettext gawk \
+  gperf bison flex libconfuse-dev libunistring-dev libsqlite3-dev \
+  libavcodec-dev libavformat-dev libavfilter-dev libswscale-dev libavutil-dev \
+  libasound2-dev libmxml-dev libgcrypt20-dev libavahi-client-dev zlib1g-dev \
+  libevent-dev libplist-dev libsodium-dev libjson-c-dev libwebsockets-dev \
+  libcurl4-openssl-dev libprotobuf-c-dev
+

Note that OwnTone will also work with other versions and flavours of libgcrypt and libcurl, so the above are just suggestions.

The following features require extra packages, and that you add a configure argument when you run ./configure:

Feature Configure argument Packages
Chromecast --enable-chromecast libgnutls*-dev
Pulseaudio --with-pulseaudio libpulse-dev

These features can be disabled saving you package dependencies:

Feature Configure argument Packages
Spotify (built-in) --disable-spotify libprotobuf-c-dev
Player web UI --disable-webinterface libwebsockets-dev
Live web UI --without-libwebsockets libwebsockets-dev

Then run the following (adding configure arguments for optional features):

git clone https://github.com/owntone/owntone-server.git
+cd owntone-server
+autoreconf -i
+./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --enable-install-user
+make
+sudo make install
+

Using --enable-install-user means that make install will also add system user and group for owntone.

With the above configure arguments, a systemd service file will be installed to /etc/systemd/system/owntone.service so that the server will start on boot. Use --disable-install-systemd if you don't want that.

Now edit /etc/owntone.conf. Note the guide at the top highlighting which settings that normally require modification.

Start the server with sudo systemctl start owntone and check that it is running with sudo systemctl status owntone.

See the Documentation for usage information.

Quick version for Fedora

If you haven't already enabled the free RPM fusion packages do that, since you will need ffmpeg. You can google how to do that. Then run:

sudo dnf install \
+  git automake autoconf gettext-devel gperf gawk libtool bison flex \
+  sqlite-devel libconfuse-devel libunistring-devel mxml-devel libevent-devel \
+  avahi-devel libgcrypt-devel zlib-devel alsa-lib-devel ffmpeg-devel \
+  libplist-devel libsodium-devel json-c-devel libwebsockets-devel \
+  libcurl-devel protobuf-c-devel
+

Clone the OwnTone repo:

git clone https://github.com/owntone/owntone-server.git
+cd owntone-server
+

Then run the following:

autoreconf -i
+./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --enable-install-user
+make
+sudo make install
+

Using --enable-install-user means that make install will also add system user and group for owntone.

With the above configure arguments, a systemd service file will be installed to /etc/systemd/system/owntone.service so that the server will start on boot. Use --disable-install-systemd if you don't want that.

Now edit /etc/owntone.conf. Note the guide at the top highlighting which settings that normally require modification.

Start the server with sudo systemctl start owntone and check that it is running with sudo systemctl status owntone.

See the Documentation for usage information.

Quick version for FreeBSD

There is a script in the 'scripts' folder that will at least attempt to do all the work for you. And should the script not work for you, you can still look through it and use it as an installation guide.

Quick version for macOS (using Homebrew)

This workflow file used for building OwnTone via Github actions includes all the steps that you need to execute: .github/workflows/macos.yml

"Quick" version for macOS (using macports)

Caution: 1) this approach may be out of date, consider using the Homebrew method above since it is continuously tested. 2) macports requires many downloads and lots of time to install (and sometimes build) ports... you'll want a decent network connection and some patience!

Install macports (which requires Xcode): https://www.macports.org/install.php

sudo port install \
+  autoconf automake libtool pkgconfig git gperf bison flex libgcrypt \
+  libunistring libconfuse ffmpeg libevent json-c libwebsockets curl \
+  libplist libsodium protobuf-c
+

Download, configure, build and install the Mini-XML library: http://www.msweet.org/projects.php/Mini-XML

Download, configure, build and install the libinotify library: https://github.com/libinotify-kqueue/libinotify-kqueue

Add the following to .bashrc:

# add /usr/local to pkg-config path
+export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/opt/local/lib/pkgconfig
+# libunistring doesn't support pkg-config, set overrides
+export LIBUNISTRING_CFLAGS=-I/opt/local/include
+export LIBUNISTRING_LIBS="-L/opt/local/lib -lunistring"
+

Optional features require the following additional ports:

Feature Configure argument Ports
Chromecast --enable-chromecast gnutls
Pulseaudio --with-pulseaudio pulseaudio

Clone the OwnTone repo:

git clone https://github.com/owntone/owntone-server.git
+cd owntone-server
+

Finally, configure, build and install, adding configure arguments for optional features:

autoreconf -i
+./configure
+make
+sudo make install
+

Note: if for some reason you've installed the avahi port, you need to add --without-avahi to configure above.

Edit /usr/local/etc/owntone.conf and change the uid to a nice system daemon (eg: unknown), and run the following:

sudo mkdir -p /usr/local/var/run
+sudo mkdir -p /usr/local/var/log # or change logfile in conf
+sudo chown unknown /usr/local/var/cache/owntone # or change conf
+

Run OwnTone:

sudo /usr/local/sbin/owntone
+

Verify it's running (you need to Ctrl+C to stop dns-sd):

dns-sd -B _daap._tcp
+

Long version - requirements

Required tools:

  • autotools: autoconf 2.63+, automake 1.10+, libtool 2.2. Run autoreconf -i at the top of the source tree to generate the build system.
  • gettext: libunistring requires iconv and gettext provides the autotools macro definitions for iconv.
  • gperf
  • bison 3.0+ (yacc is not sufficient)
  • flex (lex is not sufficient)

Libraries:

If using binary packages, remember that you need the development packages to build OwnTone (usually named -dev or -devel).

sqlite3 needs to be built with support for the unlock notify API; this isn't always the case in binary packages, so you may need to rebuild sqlite3 to enable the unlock notify API (you can check for the presence of the sqlite3_unlock_notify symbol in the sqlite3 library). Refer to the sqlite3 documentation, look for SQLITE_ENABLE_UNLOCK_NOTIFY.

Long version - building and installing

Start by generating the build system by running autoreconf -i. This will generate the configure script and Makefile.in.

To display the configure options run ./configure --help.

Support for Spotify is optional. Use --disable-spotify to disable this feature.

Support for LastFM scrobbling is optional. Use --enable-lastfm to enable this feature.

Support for the MPD protocol is optional. Use --disable-mpd to disable this feature.

Support for Chromecast devices is optional. Use --enable-chromecast to enable this feature.

The player web interface is optional. Use --disable-webinterface to disable this feature. If enabled, sudo make install will install the prebuild html, js, css files. The prebuild files are:

  • htdocs/index.html
  • htdocs/player/*

The source for the player web interface is located under the web-src folder and requires nodejs >= 6.0 to be built. In the web-src folder run npm install to install all dependencies for the player web interface. After that run npm run build. This will build the web interface and update the htdocs folder. (See Web interface for more informations)

Building with libwebsockets is required if you want the web interface. It will be enabled if the library is present (with headers). Use --without-libwebsockets to disable.

Building with Pulseaudio is optional. It will be enabled if the library is present (with headers). Use --without-pulseaudio to disable.

Recommended build settings:

./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --enable-install-user
+

After configure run the usual make, and if that went well, sudo make install.

With the above configure arguments, a systemd service file will be installed to /etc/systemd/system/owntone.service so that the server will start on boot. Use --disable-install-systemd if you don't want that.

Using --enable-install-user means that make install will also add a system user and group for owntone.

After installation:

  • edit the configuration file, /etc/owntone.conf
  • make sure the Avahi daemon is installed and running (Debian: apt install avahi-daemon)

OwnTone will drop privileges to any user you specify in the configuration file if it's started as root.

This user must have read permission to your library and read/write permissions to the database location ($localstatedir/cache/owntone by default).

Non-priviliged user version (for development)

OwnTone is meant to be run as system wide daemon, but for development purposes you may want to run it isolated to your regular user.

The following description assumes that you want all runtime data stored in $HOME/owntone_data and the source in $HOME/projects/owntone-server.

Prepare directories for runtime data: 

mkdir -p $HOME/owntone_data/etc
+mkdir -p $HOME/owntone_data/media
+

Copy one or more mp3 file to test with to owntone_data/media.

Checkout OwnTone and configure build: 

cd $HOME/projects
+git clone https://github.com/owntone/owntone-server.git
+cd owntone-server
+autoreconf -vi
+./configure --prefix=$HOME/owntone_data/usr --sysconfdir=$HOME/owntone_data/etc --localstatedir=$HOME/owntone_data/var
+

Build and install runtime:

make install
+

Edit owntone_data/etc/owntone.conf, find the following configuration settings and set them to these values:

    uid = ${USER}
+    loglevel = "debug"
+    directories = { "${HOME}/owntone_data/media" }
+

Run the server:

./src/owntone -f
+
(you can also use the copy of the binary in $HOME/owntone_data/usr/sbin)

\ No newline at end of file diff --git a/clients/cli/index.html b/clients/cli/index.html new file mode 100644 index 0000000000..81206675c7 --- /dev/null +++ b/clients/cli/index.html @@ -0,0 +1,4 @@ + CLI - OwnTone

Command line

You can choose between:

Here is an example of how to use curl with DAAP/DACP. Say you have a playlist with a radio station, and you want to make a script that starts playback of that station:

  1. Run sqlite3 [your OwnTone db]. Use select id,title from files to get the id of the radio station, and use select id,title from playlists to get the id of the playlist.
  2. Convert the two ids to hex.
  3. Put the following lines in the script with the relevant ids inserted (also observe that you must use a session-id < 100, and that you must login and logout):
curl "http://localhost:3689/login?pairing-guid=0x1&request-session-id=50"
+curl "http://localhost:3689/ctrl-int/1/playspec?database-spec='dmap.persistentid:0x1'&container-spec='dmap.persistentid:0x[PLAYLIST-ID]'&container-item-spec='dmap.containeritemid:0x[FILE ID]'&session-id=50"
+curl "http://localhost:3689/logout?session-id=50"
+
\ No newline at end of file diff --git a/clients/mpd/index.html b/clients/mpd/index.html new file mode 100644 index 0000000000..007871305c --- /dev/null +++ b/clients/mpd/index.html @@ -0,0 +1 @@ + MPD clients - OwnTone

MPD clients

You can - to some extent - use clients for MPD to control OwnTone.

By default OwnTone listens on port 6600 for MPD clients. You can change this in the configuration file.

Currently only a subset of the commands offered by MPD (see MPD protocol documentation) are supported.

Due to some differences between OwnTone and MPD not all commands will act the same way they would running MPD:

  • crossfade, mixrampdb, mixrampdelay and replaygain will have no effect
  • single, repeat: unlike MPD, OwnTone does not support setting single and repeat separately on/off, instead repeat off, repeat all and repeat single are supported. Thus setting single on will result in repeat single, repeat on results in repeat all.

The following table shows what is working for a selection of MPD clients:

Client Type Status
mpc CLI Working commands: mpc, add, crop, current, del (ranges are not yet supported), play, next, prev (behaves like cdprev), pause, toggle, cdprev, seek, clear, outputs, enable, disable, playlist, ls, load, volume, repeat, random, single, search, find, list, update (initiates an init-rescan, the path argument is not supported)
ympd Web Everything except "add stream" should work
\ No newline at end of file diff --git a/clients/remote/index.html b/clients/remote/index.html new file mode 100644 index 0000000000..9fc679585b --- /dev/null +++ b/clients/remote/index.html @@ -0,0 +1,7 @@ + Remote - OwnTone

Using Remote

Remote gets a list of output devices from the server; this list includes any and all devices on the network we know of that advertise AirPlay: AirPort Express, Apple TV, ... It also includes the local audio output, that is, the sound card on the server (even if there is no soundcard).

OwnTone remembers your selection and the individual volume for each output device; selected devices will be automatically re-selected, except if they return online during playback.

Pairing

  1. Open the web interface
  2. Start Remote, go to Settings, Add Library
  3. Enter the pair code in the web interface (update the page with F5 if it does not automatically pick up the pairing request)

If Remote doesn't connect to OwnTone after you entered the pairing code something went wrong. Check the log file to see the error message. Here are some common reasons:

  • You did not enter the correct pairing code

    You will see an error in the log about pairing failure with a HTTP response code that is not 0.

    Solution: Try again.

  • No response from Remote, possibly a network issue

    If you see an error in the log with either:

    • a HTTP response code that is 0
    • "Empty pairing request callback"

    it means that OwnTone could not establish a connection to Remote. This might be a network issue, your router may not be allowing multicast between the Remote device and the host OwnTone is running on.

    Solution 1: Sometimes it resolves the issue if you force Remote to quit, restart it and do the pairing proces again. Another trick is to establish some other connection (eg SSH) from the iPod/iPhone/iPad to the host.

    Solution 2: Check your router settings if you can whitelist multicast addresses under IGMP settings. For Apple Bonjour, setting a multicast address of 224.0.0.251 and a netmask of 255.255.255.255 should work.

  • Otherwise try using avahi-browse for troubleshooting:

    • in a terminal, run avahi-browse -r -k _touch-remote._tcp
    • start Remote, goto Settings, Add Library
    • after a couple seconds at most, you should get something similar to this:
    + ath0 IPv4 59eff13ea2f98dbbef6c162f9df71b784a3ef9a3      _touch-remote._tcp   local
+= ath0 IPv4 59eff13ea2f98dbbef6c162f9df71b784a3ef9a3      _touch-remote._tcp   local
+   hostname = [Foobar.local]
+   address = [192.168.1.1]
+   port = [49160]
+   txt = ["DvTy=iPod touch" "RemN=Remote" "txtvers=1" "RemV=10000" "Pair=FAEA410630AEC05E" "DvNm=Foobar"]
+

    Hit Ctrl-C to terminate avahi-browse.

  • To check for network issues you can try to connect to address and port with telnet.

\ No newline at end of file diff --git a/clients/supported-clients/index.html b/clients/supported-clients/index.html new file mode 100644 index 0000000000..a8351d8f7d --- /dev/null +++ b/clients/supported-clients/index.html @@ -0,0 +1 @@ + Supported clients - OwnTone

Supported clients

OwnTone supports these kinds of clients:

  • DAAP clients, like iTunes or Rhythmbox
  • Remote clients, like Apple Remote or compatibles for Android/Windows Phone
  • AirPlay devices, like AirPort Express, Shairport and various AirPlay speakers
  • Chromecast devices
  • MPD clients, like mpc
  • MP3 network stream clients, like VLC and almost any other music player
  • RSP clients, like Roku Soundbridge

Like iTunes, you can control OwnTone with Remote and stream your music to AirPlay devices.

A single OwnTone instance can handle several clients concurrently, regardless of the protocol.

By default all clients on 192.168.* (and the ipv6 equivalent) are allowed to connect without authentication. You can change that in the configuration file.

Here is a list of working and non-working DAAP and Remote clients. The list is probably obsolete when you read it :-)

Client Developer Type Platform Working (vers.)
iTunes Apple DAAP Win Yes (12.10.1)
Apple Music Apple DAAP MacOS Yes
Rhythmbox Gnome DAAP Linux Yes
Diapente diapente DAAP Android Yes
WinAmp DAAPClient WardFamily DAAP WinAmp Yes
Amarok w/DAAP plugin KDE DAAP Linux/Win Yes (2.8.0)
Banshee DAAP Linux/Win/OSX No (2.6.2)
jtunes4 DAAP Java No
Firefly Client (DAAP) Java No
Remote Apple Remote iOS Yes (4.3)
Retune SquallyDoc Remote Android Yes (3.5.23)
TunesRemote+ Melloware Remote Android Yes (2.5.3)
Remote for iTunes Hyperfine Remote Android Yes
Remote for Windows Phone Komodex Remote Windows Phone Yes (2.2.1.0)
TunesRemote SE Remote Java Yes (r108)
rtRemote for Windows bizmodeller Remote Windows Yes (1.2.0.67)
\ No newline at end of file diff --git a/clients/web-interface/index.html b/clients/web-interface/index.html new file mode 100644 index 0000000000..adc4c3b10c --- /dev/null +++ b/clients/web-interface/index.html @@ -0,0 +1,22 @@ + Web interface - OwnTone

OwnTone web interface

Mobile friendly player web interface for OwnTone build with Vue.js, Bulma.

You can find the web interface at http://owntone.local:3689 or alternatively at http://SERVER_ADDRESS:3689.

Use the web interface to control playback, trigger manual library rescans, pair with remotes, select speakers, authenticate with Spotify, etc.

Screenshots

Now playing Queue Music browse Music artists Music artist Music albums Music albums options Music album Spotiy Audiobooks authors Audiobooks Podcasts Podcast Files Search Menu Outputs

Usage

You can find OwnTone's web interface at http://owntone.local:3689 or alternatively at http://SERVER_ADDRESS:3689.

Build Setup

The source is located in the web-src folder.

cd web-src
+

The web interface is built with Vite, makes use of Prettier for code formatting and ESLint for code linting (the project was set up following the guide ESLint and Prettier with Vite and Vue.js 3

# install dependencies
+npm install
+
+# Serve with hot reload at localhost:3000
+# (assumes that OwnTone server is running on localhost:3689)
+npm run serve
+
+# Serve with hot reload at localhost:3000
+# (with remote OwnTone server reachable under owntone.local:3689)
+VITE_OWNTONE_URL=http://owntone.local:3689 npm run serve
+
+# Build for production with minification (will update web interface
+# in "../htdocs")
+npm run build
+
+# Format code
+npm run format
+
+# Lint code (and fix errors that can be automatically fixed)
+npm run lint
+

After running npm run serve the web interface is reachable at localhost:3000. By default it expects owntone to be running at localhost:3689 and proxies all JSON API calls to this location.

If the server is running at a different location you have to set the env variable VITE_OWNTONE_URL.

\ No newline at end of file diff --git a/getting-started/index.html b/getting-started/index.html new file mode 100644 index 0000000000..71e6b8a497 --- /dev/null +++ b/getting-started/index.html @@ -0,0 +1 @@ + Getting started - OwnTone

Getting started

After installation (see Installation) do the following:

  1. Edit the configuration file (usually /etc/owntone.conf) to suit your needs
  2. Start or restart the server (usually /etc/init.d/owntone restart)
  3. Go to the web interface http://owntone.local:3689, or, if that won't work, to http://SERVER_ADDRESS:3689
  4. Wait for the library scan to complete
  5. If you will be using a remote, e.g. Apple Remote: Start the remote, go to Settings, Add Library
  6. Enter the pair code in the web interface (update the page with F5 if it does not automatically pick up the pairing request)
\ No newline at end of file diff --git a/index.html b/index.html new file mode 100644 index 0000000000..d327c41ff3 --- /dev/null +++ b/index.html @@ -0,0 +1 @@ + OwnTone

OwnTone

OwnTone is an open source (audio) media server for GNU/Linux, FreeBSD and MacOS.

It allows sharing and streaming your media library to iTunes (DAAP1), Roku (RSP), AirPlay devices (multiroom), Chromecast and also supports local playback.

You can control OwnTone via its web interface, Apple Remote (and compatible DAAP/DACP clients), MPD clients or via its JSON API.

Besides serving your local music, podcast and audiobook media files, OwnTone supports internet radios and Spotify (requires Spotify premium account).

Prior to version 28, OwnTone was called forked-daapd, which again was a rewrite of mt-daapd (Firefly Media Server).

OwnTone is written in C with a web interface written in Vue.js.

Features

  • Stream to AirPlay (synchronized multiroom) and Chromecast devices
  • Share local library with iTunes and Roku
  • Local audio playback with ALSA or PulseAudio

  • Supports multiple different clients:

    • Remote apps like Apple Remote (iOS) or Retune (Android)
    • Integrated mobile friendly web interface
    • MPD clients

  • Supports music and audiobook files, podcast files and RSS and internet radio

  • Supports audio files in most formats
  • Supports playing your Spotify library (requires Spotify premium account)
  • Runs on low power devices like the Raspberry Pi

Now playing Music browse Music album

(You can find more screenshots from OwnTone's web interface here)

Looking for help?

Before you continue, make sure you know what version of OwnTone you have, and what features it was built with (e.g. Spotify support).

How to find out? Go to the web interface and check. No web interface? Then check the top of OwnTone's log file (usually /var/log/owntone.log).

Note that you are viewing a snapshot of the instructions that may or may not match the version of OwnTone that you are using.

If you are looking for help on building OwnTone (not using it), then please see the documentation on Building from Source.

References

You can find source and documentation, also for older versions, here:

  1. DAAP stands for Digital Audio Access Protocol which is the protocol used by iTunes and friends to share/stream media libraries over the network. ↩

\ No newline at end of file diff --git a/installation/index.html b/installation/index.html new file mode 100644 index 0000000000..5e5ed56ef0 --- /dev/null +++ b/installation/index.html @@ -0,0 +1 @@ + Installation - OwnTone

How to get and install OwnTone

You can compile and run OwnTone on pretty much any Linux- or BSD-platform. The instructions are here.

Apt repositories, images and precompiled binaries are available for some platforms. These can save you some work and make it easier to stay up to date:

Platform How to get
RPi w/Raspberry Pi OS Add OwnTone repository to apt sources, see:
OwnTone server (iTunes server) - Raspberry Pi Forums
Debian/Ubuntu amd64 Download .deb as artifact from Github workflow
(requires that you are logged in)
OpenWrt Run opkg install libwebsockets-full owntone
Docker See linuxserver/docker-daapd

OwnTone is not in the official Debian repositories due to lack of Debian maintainer and Debian policy difficulties concerning the web UI, see this issue.

\ No newline at end of file diff --git a/integrations/lastfm/index.html b/integrations/lastfm/index.html new file mode 100644 index 0000000000..4d3a21d0a4 --- /dev/null +++ b/integrations/lastfm/index.html @@ -0,0 +1 @@ + LastFM - OwnTone

LastFM

You can have OwnTone scrobble the music you listen to. To set up scrobbling go to the web interface and authorize OwnTone with your LastFM credentials.

OwnTone will not store your LastFM username/password, only the session key. The session key does not expire.

\ No newline at end of file diff --git a/integrations/spotify/index.html b/integrations/spotify/index.html new file mode 100644 index 0000000000..e88aa392a5 --- /dev/null +++ b/integrations/spotify/index.html @@ -0,0 +1,7 @@ + Spotify - OwnTone

Spotify

OwnTone has built-in support for playback of the tracks in your Spotify library.

You must have a Spotify premium account. If you normally log into Spotify with your Facebook account you must first go to Spotify's web site where you can get the Spotify username and password that matches your account.

You must also make sure that your browser can reach OwnTone's web interface via the address http://owntone.local:3689. Try it right now! That is where Spotify's OAuth page will redirect your browser with the token that OwnTone needs, so it must work. The address is announced by the server via mDNS, but if that for some reason doesn't work then configure it via router or .hosts file. You can remove it again after completing the login.

To authorize OwnTone, open the web interface, locate Settings > Online Services and then click the Authorize button. You will then be sent to Spotify's authorization service, which will send you back to the web interface after you have given the authorization.

Spotify no longer automatically notifies clients about library updates, so you have to trigger updates manually. You can for instance set up a cron job that runs /usr/bin/curl http://localhost:3689/api/update

To logout and remove Spotify tracks + credentials make a request to http://owntone.local:3689/api/spotify-logout.

Limitations: You will not be able to do any playlist management through OwnTone - use a Spotify client for that. You also can only listen to your music by letting OwnTone do the playback - so that means you can't stream to DAAP clients (e.g. iTunes) and RSP clients.

Via librespot/spocon

You can also use OwnTone with one of the various incarnations of librespot. This adds librespot as a selectable metaspeaker in Spotify's client, and when you start playback, librespot can be configured to start writing audio to a pipe that you have added to your library. This will be detected by OwnTone that then starts playback. You can also have a pipe for metadata and playback events, e.g. volume changes.

The easiest way of accomplishing this may be with Spocon, since it requires minimal configuration. After installing, create two pipes (with mkfifo) and set the configuration in the player section:

# Audio output device (MIXER, PIPE, STDOUT)
+output = "PIPE"
+# Output raw (signed) PCM to this file (`player.output` must be PIPE)
+pipe = "/srv/music/spotify"
+# Output metadata in Shairport Sync format (https://github.com/mikebrady/shairport-sync-metadata-reader)
+metadataPipe = "/srv/music/spotify.metadata"
+
\ No newline at end of file diff --git a/json-api/index.html b/json-api/index.html new file mode 100644 index 0000000000..9cebf6efff --- /dev/null +++ b/json-api/index.html @@ -0,0 +1,759 @@ + JSON API - OwnTone

OwnTone API Endpoint Reference

Available API endpoints:

  • Player: control playback, volume, shuffle/repeat modes
  • Outputs / Speakers: list available outputs and enable/disable outputs
  • Queue: list, add or modify the current queue
  • Library: list playlists, artists, albums and tracks from your library or trigger library rescan
  • Search: search for playlists, artists, albums and tracks
  • Server info: get server information
  • Settings: list and change settings for the player web interface
  • Push notifications: receive push notifications

JSON-Object model:

Player

Method Endpoint Description
GET /api/player Get player status
PUT /api/player/play, /api/player/pause, /api/player/stop, /api/player/toggle Start, pause or stop playback
PUT /api/player/next, /api/player/previous Skip forward or backward
PUT /api/player/shuffle Set shuffle mode
PUT /api/player/consume Set consume mode
PUT /api/player/repeat Set repeat mode
PUT /api/player/volume Set master volume or volume for a specific output
PUT /api/player/seek Seek to a position in the currently playing track

Get player status

Endpoint

GET /api/player
+

Response

Key Type Value
state string play, pause or stop
repeat string off, all or single
consume boolean true if consume mode is enabled
shuffle boolean true if shuffle mode is enabled
volume integer Master volume in percent (0 - 100)
item_id integer The current playing queue item id
item_length_ms integer Total length in milliseconds of the current queue item
item_progress_ms integer Progress into the current queue item in milliseconds

Example

curl -X GET "http://localhost:3689/api/player"
+
{
+  "state": "pause",
+  "repeat": "off",
+  "consume": false,
+  "shuffle": false,
+  "volume": 50,
+  "item_id": 269,
+  "item_length_ms": 278093,
+  "item_progress_ms": 3674
+}
+

Control playback

Start or resume, pause, stop playback.

Endpoint

PUT /api/player/play
+
PUT /api/player/pause
+
PUT /api/player/stop
+
PUT /api/player/toggle
+

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/play"
+
curl -X PUT "http://localhost:3689/api/player/pause"
+
curl -X PUT "http://localhost:3689/api/player/stop"
+
curl -X PUT "http://localhost:3689/api/player/toggle"
+

Skip tracks

Skip forward or backward

Endpoint

PUT /api/player/next
+
PUT /api/player/previous
+

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/next"
+
curl -X PUT "http://localhost:3689/api/player/previous"
+

Set shuffle mode

Enable or disable shuffle mode

Endpoint

PUT /api/player/shuffle
+

Query parameters

Parameter Value
state The new shuffle state, should be either true or false

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/shuffle?state=true"
+

Set consume mode

Enable or disable consume mode

Endpoint

PUT /api/player/consume
+

Query parameters

Parameter Value
state The new consume state, should be either true or false

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/consume?state=true"
+

Set repeat mode

Change repeat mode

Endpoint

PUT /api/player/repeat
+

Query parameters

Parameter Value
state The new repeat mode, should be either off, all or single

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/repeat?state=all"
+

Set volume

Change master volume or volume of a specific output.

Endpoint

PUT /api/player/volume
+

Query parameters

Parameter Value
volume The new volume (0 - 100)
step The increase or decrease volume by the given amount (-100 - 100)
output_id (Optional) If an output id is given, only the volume of this output will be changed. If parameter is omited, the master volume will be changed.

Either volume or step must be present as query parameter

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/volume?volume=50"
+
curl -X PUT "http://localhost:3689/api/player/volume?step=-5"
+
curl -X PUT "http://localhost:3689/api/player/volume?volume=50&output_id=0"
+

Seek

Seek to a position in the currently playing track.

Endpoint

PUT /api/player/seek
+

Query parameters

Parameter Value
position_ms The new position in milliseconds to seek to
seek_ms A relative amount of milliseconds to seek to

Response

On success returns the HTTP 204 No Content success status response code.

Example

Seek to position:

curl -X PUT "http://localhost:3689/api/player/seek?position_ms=2000"
+

Relative seeking (skip 30 seconds backwards):

curl -X PUT "http://localhost:3689/api/player/seek?seek_ms=-30000"
+

Outputs / Speakers

Method Endpoint Description
GET /api/outputs Get a list of available outputs
PUT /api/outputs/set Set enabled outputs
GET /api/outputs/{id} Get an output
PUT /api/outputs/{id} Change an output setting
PUT /api/outputs/{id}/toggle Enable or disable an output, depending on the current state

Get a list of available outputs

Endpoint

GET /api/outputs
+

Response

Key Type Value
outputs array Array of output objects

output object

Key Type Value
id string Output id
name string Output name
type string Type of the output: AirPlay, Chromecast, ALSA, Pulseaudio, fifo
selected boolean true if output is enabled
has_password boolean true if output is password protected
requires_auth boolean true if output requires authentication
needs_auth_key boolean true if output requires an authorization key (device verification)
volume integer Volume in percent (0 - 100)

Example

curl -X GET "http://localhost:3689/api/outputs"
+
{
+  "outputs": [
+    {
+      "id": "123456789012345",
+      "name": "kitchen",
+      "type": "AirPlay",
+      "selected": true,
+      "has_password": false,
+      "requires_auth": false,
+      "needs_auth_key": false,
+      "volume": 0
+    },
+    {
+      "id": "0",
+      "name": "Computer",
+      "type": "ALSA",
+      "selected": true,
+      "has_password": false,
+      "requires_auth": false,
+      "needs_auth_key": false,
+      "volume": 19
+    },
+    {
+      "id": "100",
+      "name": "daapd-fifo",
+      "type": "fifo",
+      "selected": false,
+      "has_password": false,
+      "requires_auth": false,
+      "needs_auth_key": false,
+      "volume": 0
+    }
+  ]
+}
+

Set enabled outputs

Set the enabled outputs by passing an array of output ids. The server enables all outputs with the given ids and disables the remaining outputs.

Endpoint

PUT /api/outputs/set
+

Body parameters

Parameter Type Value
outputs array Array of output ids

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/outputs/set" --data "{\"outputs\":[\"198018693182577\",\"0\"]}"
+

Get an output

Get an output

Endpoint

GET /api/outputs/{id}
+

Path parameters

Parameter Value
id Output id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the output object.

Example

curl -X GET "http://localhost:3689/api/outputs/0"
+
{
+  "id": "0",
+  "name": "Computer",
+  "type": "ALSA",
+  "selected": true,
+  "has_password": false,
+  "requires_auth": false,
+  "needs_auth_key": false,
+  "volume": 3
+}
+

Change an output

Enable or disable an output and change its volume.

Endpoint

PUT /api/outputs/{id}
+

Path parameters

Parameter Value
id Output id

Body parameters

Parameter Type Value
selected boolean (Optional) true to enable and false to disable the output
volume integer (Optional) Volume in percent (0 - 100)
pin string (Optional) PIN for device verification

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/outputs/0" --data "{\"selected\":true, \"volume\": 50}"
+

Toggle an output

Enable or disable an output, depending on its current state

Endpoint

PUT /api/outputs/{id}/toggle
+

Path parameters

Parameter Value
id Output id

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/outputs/0/toggle"
+

Queue

Method Endpoint Description
GET /api/queue Get a list of queue items
PUT /api/queue/clear Remove all items from the queue
POST /api/queue/items/add Add items to the queue
PUT /api/queue/items/{id}|now_playing Updating a queue item in the queue
DELETE /api/queue/items/{id} Remove a queue item from the queue

List queue items

Lists the items in the current queue

Endpoint

GET /api/queue
+

Query parameters

Parameter Value
id (Optional) If a queue item id is given, only the item with the id will be returend. Use id=now_playing to get the currently playing item.
start (Optional) If a startand an end position is given, only the items from start (included) to end (excluded) will be returned. If only a start position is given, only the item at this position will be returned.
end (Optional) See start parameter

Response

Key Type Value
version integer Version number of the current queue
count integer Number of items in the current queue
items array Array of queue item objects

Example

curl -X GET "http://localhost:3689/api/queue"
+
{
+  "version": 833,
+  "count": 20,
+  "items": [
+    {
+      "id": 12122,
+      "position": 0,
+      "track_id": 10749,
+      "title": "Angels",
+      "artist": "The xx",
+      "artist_sort": "xx, The",
+      "album": "Coexist",
+      "album_sort": "Coexist",
+      "albumartist": "The xx",
+      "albumartist_sort": "xx, The",
+      "genre": "Indie Rock",
+      "year": 2012,
+      "track_number": 1,
+      "disc_number": 1,
+      "length_ms": 171735,
+      "media_kind": "music",
+      "data_kind": "file",
+      "path": "/music/srv/The xx/Coexist/01 Angels.mp3",
+      "uri": "library:track:10749"
+    },
+    ...
+  ]
+}
+

Clearing the queue

Remove all items form the current queue

Endpoint

PUT /api/queue/clear
+

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/queue/clear"
+

Adding items to the queue

Add tracks, playlists artists or albums to the current queue

Endpoint

POST /api/queue/items/add
+

Query parameters

Parameter Value
uris Comma seperated list of resource identifiers (track, playlist, artist or album object uri)
expression A smart playlist query expression identifying the tracks that will be added to the queue.
position (Optional) If a position is given, new items are inserted starting from this position into the queue.
playback (Optional) If the playback parameter is set to start, playback will be started after adding the new items.
playback_from_position (Optional) If the playback parameter is set to start, playback will be started with the queue item at the position given in playback_from_position.
clear (Optional) If the clear parameter is set to true, the queue will be cleared before adding the new items.
shuffle (Optional) If the shuffle parameter is set to true, the shuffle mode is activated. If it is set to something else, the shuffle mode is deactivated. To leave the shuffle mode untouched the parameter should be ommited.
limit (Optional) Maximum number of tracks to add

Either the uris or the expression parameter must be set. If both are set the uris parameter takes presedence and the expression parameter will be ignored.

Response

On success returns the HTTP 200 OK success status response code.

Key Type Value
count integer number of tracks added to the queue

Example

Add new items by uri:

curl -X POST "http://localhost:3689/api/queue/items/add?uris=library:playlist:68,library:artist:2932599850102967727"
+
{
+  "count": 42
+}
+

Add new items by query language:

curl -X POST "http://localhost:3689/api/queue/items/add?expression=media_kind+is+music"
+
{
+  "count": 42
+}
+

Clear current queue, add 10 new random tracks of genre Pop and start playback 

curl -X POST "http://localhost:3689/api/queue/items/add?limit=10&clear=true&playback=start&expression=genre+is+%22Pop%22+order+by+random+desc"
+

{
+  "count": 10
+}
+

Updating a queue item

Update or move a queue item in the current queue

Endpoint

PUT /api/queue/items/{id}
+
or 
PUT /api/queue/items/now_playing
+

Path parameters

Parameter Value
id Queue item id

(or use now_playing to update the currenly playing track)

Query parameters

Parameter Value
new_position The new position for the queue item in the current queue.
title New track title
album New album title
artist New artist
album_artist New album artist
composer New composer
genre New genre
artwork_url New URL to track artwork

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/queue/items/3?new_position=0"
+
curl -X PUT "http://localhost:3689/api/queue/items/3?title=Awesome%20title&artwork_url=http%3A%2F%2Fgyfgafguf.dk%2Fimages%2Fpige3.jpg"
+
curl -X PUT "http://localhost:3689/api/queue/items/now_playing?title=Awesome%20title&artwork_url=http%3A%2F%2Fgyfgafguf.dk%2Fimages%2Fpige3.jpg"
+

Removing a queue item

Remove a queue item from the current queue

Endpoint

DELETE /api/queue/items/{id}
+

Path parameters

Parameter Value
id Queue item id

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/queue/items/2"
+

Library

Method Endpoint Description
GET /api/library Get library information
GET /api/library/playlists Get a list of playlists
GET /api/library/playlists/{id} Get a playlist
PUT /api/library/playlists/{id} Update a playlist attribute
DELETE /api/library/playlists/{id} Delete a playlist
GET /api/library/playlists/{id}/tracks Get list of tracks for a playlist
PUT /api/library/playlists/{id}/tracks Update play count of tracks for a playlist
GET /api/library/playlists/{id}/playlists Get list of playlists for a playlist folder
GET /api/library/artists Get a list of artists
GET /api/library/artists/{id} Get an artist
GET /api/library/artists/{id}/albums Get list of albums for an artist
GET /api/library/albums Get a list of albums
GET /api/library/albums/{id} Get an album
GET /api/library/albums/{id}/tracks Get list of tracks for an album
GET /api/library/tracks/{id} Get a track
GET /api/library/tracks/{id}/playlists Get list of playlists for a track
PUT /api/library/tracks Update multiple track properties
PUT /api/library/tracks/{id} Update single track properties
GET /api/library/genres Get list of genres
GET /api/library/count Get count of tracks, artists and albums
GET /api/library/files Get list of directories in the local library
POST /api/library/add Add an item to the library
PUT /api/update Trigger a library rescan
PUT /api/rescan Trigger a library metadata rescan
PUT /api/library/backup Request library backup db

Library information

List some library stats

Endpoint

GET /api/library
+

Response

Key Type Value
songs integer Array of playlist objects
db_playtime integer Total playtime of all songs in the library
artists integer Number of album artists in the library
albums integer Number of albums in the library
started_at string Server startup time (timestamp in ISO 8601 format)
updated_at string Last library update (timestamp in ISO 8601 format)
updating boolean true if library rescan is in progress

Example

curl -X GET "http://localhost:3689/api/library"
+
{
+  "songs": 217,
+  "db_playtime": 66811,
+  "artists": 9,
+  "albums": 19,
+  "started_at": "2018-11-19T19:06:08Z",
+  "updated_at": "2018-11-19T19:06:16Z",
+  "updating": false
+}
+

List playlists

Lists all playlists in your library (does not return playlist folders)

Endpoint

GET /api/library/playlists
+

Query parameters

Parameter Value
offset (Optional) Offset of the first playlist to return
limit (Optional) Maximum number of playlists to return

Response

Key Type Value
items array Array of playlist objects
total integer Total number of playlists in the library
offset integer Requested offset of the first playlist
limit integer Requested maximum number of playlists

Example

curl -X GET "http://localhost:3689/api/library/playlists"
+
{
+  "items": [
+    {
+      "id": 1,
+      "name": "radio",
+      "path": "/music/srv/radio.m3u",
+      "smart_playlist": false,
+      "uri": "library:playlist:1"
+    },
+    ...
+  ],
+  "total": 20,
+  "offset": 0,
+  "limit": -1
+}
+

Get a playlist

Get a specific playlists in your library

Endpoint

GET /api/library/playlists/{id}
+

Path parameters

Parameter Value
id Playlist id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the playlist object.

Example

curl -X GET "http://localhost:3689/api/library/playlists/1"
+
{
+  "id": 1,
+  "name": "radio",
+  "path": "/music/srv/radio.m3u",
+  "smart_playlist": false,
+  "uri": "library:playlist:1"
+}
+

Update a playlist

Update attributes of a specific playlists in your library

Endpoint

PUT /api/library/playlists/{id}
+

Path parameters

Parameter Value
id Playlist id

Query parameters

Parameter Value
query_limit For RSS feeds, this sets how many podcasts to retrieve

Example

curl -X PUT "http://localhost:3689/api/library/playlists/25?query_limit=20"
+

Delete a playlist

Delete a playlist, e.g. a RSS feed

Endpoint

DELETE /api/library/playlists/{id}
+

Path parameters

Parameter Value
id Playlist id

Example

curl -X DELETE "http://localhost:3689/api/library/playlists/25"
+

List playlist tracks

Lists the tracks in a playlists

Endpoint

GET /api/library/playlists/{id}/tracks
+

Path parameters

Parameter Value
id Playlist id

Query parameters

Parameter Value
offset (Optional) Offset of the first track to return
limit (Optional) Maximum number of tracks to return

Response

Key Type Value
items array Array of track objects
total integer Total number of tracks in the playlist
offset integer Requested offset of the first track
limit integer Requested maximum number of tracks

Example

curl -X GET "http://localhost:3689/api/library/playlists/1/tracks"
+
{
+  "items": [
+    {
+      "id": 10766,
+      "title": "Solange wir tanzen",
+      "artist": "Heinrich",
+      "artist_sort": "Heinrich",
+      "album": "Solange wir tanzen",
+      "album_sort": "Solange wir tanzen",
+      "albumartist": "Heinrich",
+      "albumartist_sort": "Heinrich",
+      "genre": "Electronica",
+      "year": 2014,
+      "track_number": 1,
+      "disc_number": 1,
+      "length_ms": 223085,
+      "play_count": 2,
+      "skip_count": 1,
+      "time_played": "2018-02-23T10:31:20Z",
+      "media_kind": "music",
+      "data_kind": "file",
+      "path": "/music/srv/Heinrich/Solange wir tanzen/01 Solange wir tanzen.mp3",
+      "uri": "library:track:10766"
+    },
+    ...
+  ],
+  "total": 20,
+  "offset": 0,
+  "limit": -1
+}
+

Update playlist tracks

Updates the play count for tracks in a playlists

Endpoint

PUT /api/library/playlists/{id}/tracks
+

Path parameters

Parameter Value
id Playlist id

Query parameters

Parameter Value
play_count Either increment, played or reset. increment will increment play_count and update time_played, played will be like increment but only where play_count is 0, reset will set play_count and skip_count to zero and delete time_played and time_skipped

Example

curl -X PUT "http://localhost:3689/api/library/playlists/1/tracks?play_count=played"
+

List playlists in a playlist folder

Lists the playlists in a playlist folder

Note: The root playlist folder has id 0.

Endpoint

GET /api/library/playlists/{id}/playlists
+

Path parameters

Parameter Value
id Playlist id

Query parameters

Parameter Value
offset (Optional) Offset of the first playlist to return
limit (Optional) Maximum number of playlist to return

Response

Key Type Value
items array Array of playlist objects
total integer Total number of playlists in the playlist folder
offset integer Requested offset of the first playlist
limit integer Requested maximum number of playlist

Example

curl -X GET "http://localhost:3689/api/library/playlists/0/tracks"
+
{
+  "items": [
+    {
+      "id": 11,
+      "name": "Spotify",
+      "path": "spotify:playlistfolder",
+      "parent_id": "0",
+      "smart_playlist": false,
+      "folder": true,
+      "uri": "library:playlist:11"
+    },
+    {
+      "id": 8,
+      "name": "bytefm",
+      "path": "/srv/music/Playlists/bytefm.m3u",
+      "parent_id": "0",
+      "smart_playlist": false,
+      "folder": false,
+      "uri": "library:playlist:8"
+    }
+  ],
+  "total": 2,
+  "offset": 0,
+  "limit": -1
+}
+

List artists

Lists the artists in your library

Endpoint

GET /api/library/artists
+

Query parameters

Parameter Value
offset (Optional) Offset of the first artist to return
limit (Optional) Maximum number of artists to return

Response

Key Type Value
items array Array of artist objects
total integer Total number of artists in the library
offset integer Requested offset of the first artist
limit integer Requested maximum number of artists

Example

curl -X GET "http://localhost:3689/api/library/artists"
+
{
+  "items": [
+    {
+      "id": "3815427709949443149",
+      "name": "ABAY",
+      "name_sort": "ABAY",
+      "album_count": 1,
+      "track_count": 10,
+      "length_ms": 2951554,
+      "uri": "library:artist:3815427709949443149"
+    },
+    ...
+  ],
+  "total": 20,
+  "offset": 0,
+  "limit": -1
+}
+

Get an artist

Get a specific artist in your library

Endpoint

GET /api/library/artists/{id}
+

Path parameters

Parameter Value
id Artist id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the artist object.

Example

curl -X GET "http://localhost:3689/api/library/artists/3815427709949443149"
+
{
+  "id": "3815427709949443149",
+  "name": "ABAY",
+  "name_sort": "ABAY",
+  "album_count": 1,
+  "track_count": 10,
+  "length_ms": 2951554,
+  "uri": "library:artist:3815427709949443149"
+}
+

List artist albums

Lists the albums of an artist

Endpoint

GET /api/library/artists/{id}/albums
+

Path parameters

Parameter Value
id Artist id

Query parameters

Parameter Value
offset (Optional) Offset of the first album to return
limit (Optional) Maximum number of albums to return

Response

Key Type Value
items array Array of album objects
total integer Total number of albums of this artist
offset integer Requested offset of the first album
limit integer Requested maximum number of albums

Example

curl -X GET "http://localhost:3689/api/library/artists/32561671101664759/albums"
+
{
+  "items": [
+    {
+      "id": "8009851123233197743",
+      "name": "Add Violence",
+      "name_sort": "Add Violence",
+      "artist": "Nine Inch Nails",
+      "artist_id": "32561671101664759",
+      "track_count": 5,
+      "length_ms": 1634961,
+      "uri": "library:album:8009851123233197743"
+    },
+    ...
+  ],
+  "total": 20,
+  "offset": 0,
+  "limit": -1
+}
+

List albums

Lists the albums in your library

Endpoint

GET /api/library/albums
+

Query parameters

Parameter Value
offset (Optional) Offset of the first album to return
limit (Optional) Maximum number of albums to return

Response

Key Type Value
items array Array of album objects
total integer Total number of albums in the library
offset integer Requested offset of the first albums
limit integer Requested maximum number of albums

Example

curl -X GET "http://localhost:3689/api/library/albums"
+
{
+  "items": [
+    {
+      "id": "8009851123233197743",
+      "name": "Add Violence",
+      "name_sort": "Add Violence",
+      "artist": "Nine Inch Nails",
+      "artist_id": "32561671101664759",
+      "track_count": 5,
+      "length_ms": 1634961,
+      "uri": "library:album:8009851123233197743"
+    },
+    ...
+  ],
+  "total": 20,
+  "offset": 0,
+  "limit": -1
+}
+

Get an album

Get a specific album in your library

Endpoint

GET /api/library/albums/{id}
+

Path parameters

Parameter Value
id Album id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the album object.

Example

curl -X GET "http://localhost:3689/api/library/albums/8009851123233197743"
+
{
+  "id": "8009851123233197743",
+  "name": "Add Violence",
+  "name_sort": "Add Violence",
+  "artist": "Nine Inch Nails",
+  "artist_id": "32561671101664759",
+  "track_count": 5,
+  "length_ms": 1634961,
+  "uri": "library:album:8009851123233197743"
+}
+

List album tracks

Lists the tracks in an album

Endpoint

GET /api/library/albums/{id}/tracks
+

Path parameters

Parameter Value
id Album id

Query parameters

Parameter Value
offset (Optional) Offset of the first track to return
limit (Optional) Maximum number of tracks to return

Response

Key Type Value
items array Array of track objects
total integer Total number of tracks
offset integer Requested offset of the first track
limit integer Requested maximum number of tracks

Example

curl -X GET "http://localhost:3689/api/library/albums/1/tracks"
+
{
+  "items": [
+    {
+      "id": 10766,
+      "title": "Solange wir tanzen",
+      "artist": "Heinrich",
+      "artist_sort": "Heinrich",
+      "album": "Solange wir tanzen",
+      "album_sort": "Solange wir tanzen",
+      "albumartist": "Heinrich",
+      "albumartist_sort": "Heinrich",
+      "genre": "Electronica",
+      "year": 2014,
+      "track_number": 1,
+      "disc_number": 1,
+      "length_ms": 223085,
+      "play_count": 2,
+      "last_time_played": "2018-02-23T10:31:20Z",
+      "media_kind": "music",
+      "data_kind": "file",
+      "path": "/music/srv/Heinrich/Solange wir tanzen/01 Solange wir tanzen.mp3",
+      "uri": "library:track:10766"
+    },
+    ...
+  ],
+  "total": 20,
+  "offset": 0,
+  "limit": -1
+}
+

Get a track

Get a specific track in your library

Endpoint

GET /api/library/tracks/{id}
+

Path parameters

Parameter Value
id Track id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the track object.

Example

curl -X GET "http://localhost:3689/api/library/tracks/1"
+
{
+  "id": 1,
+  "title": "Pardon Me",
+  "title_sort": "Pardon Me",
+  "artist": "Incubus",
+  "artist_sort": "Incubus",
+  "album": "Make Yourself",
+  "album_sort": "Make Yourself",
+  "album_id": "6683985628074308431",
+  "album_artist": "Incubus",
+  "album_artist_sort": "Incubus",
+  "album_artist_id": "4833612337650426236",
+  "composer": "Alex Katunich/Brandon Boyd/Chris Kilmore/Jose Antonio Pasillas II/Mike Einziger",
+  "genre": "Alternative Rock",
+  "year": 2001,
+  "track_number": 12,
+  "disc_number": 1,
+  "length_ms": 223170,
+  "rating": 0,
+  "usermark": 0,
+  "play_count": 0,
+  "skip_count": 0,
+  "time_added": "2019-01-20T11:58:29Z",
+  "date_released": "2001-05-27",
+  "seek_ms": 0,
+  "media_kind": "music",
+  "data_kind": "file",
+  "path": "/music/srv/Incubus/Make Yourself/12 Pardon Me.mp3",
+  "uri": "library:track:1",
+  "artwork_url": "/artwork/item/1"
+}
+

List playlists for a track

Get the list of playlists that contain a track (does not return smart playlists)

Endpoint

GET /api/library/tracks/{id}/playlists
+

Path parameters

Parameter Value
id Track id

Query parameters

Parameter Value
offset (Optional) Offset of the first playlist to return
limit (Optional) Maximum number of playlist to return

Response

Key Type Value
items array Array of playlist objects
total integer Total number of playlists
offset integer Requested offset of the first playlist
limit integer Requested maximum number of playlists

Example

curl -X GET "http://localhost:3689/api/library/tracks/27/playlists"
+
{
+  "items": [
+    {
+      "id": 1,
+      "name": "playlist",
+      "path": "/music/srv/playlist.m3u",
+      "smart_playlist": false,
+      "uri": "library:playlist:1"
+    },
+    ...
+  ],
+  "total": 2,
+  "offset": 0,
+  "limit": -1
+}
+

Update track properties

Change properties of one or more tracks (supported properties are "rating", "play_count" and "usermark")

Endpoint

PUT /api/library/tracks
+

Body parameters

Parameter Type Value
tracks array Array of track objects

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT -d '{ "tracks": [ { "id": 1, "rating": 100, "usermark": 4 }, { "id": 2, "usermark": 3 } ] }' "http://localhost:3689/api/library/tracks"
+

Endpoint

PUT /api/library/tracks/{id}
+

Path parameters

Parameter Value
id Track id

Query parameters

Parameter Value
rating The new rating (0 - 100)
play_count Either increment or reset. increment will increment play_count and update time_played, reset will set play_count and skip_count to zero and delete time_played and time_skipped
usermark The new usermark (>= 0)

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/library/tracks/1?rating=100"
+
curl -X PUT "http://localhost:3689/api/library/tracks/1?play_count=increment"
+

List genres

Get list of genres

Endpoint

GET /api/library/genres
+
Response

Key Type Value
items array Array of browse-info objects
total integer Total number of genres in the library
offset integer Requested offset of the first genre
limit integer Requested maximum number of genres

Example

curl -X GET "http://localhost:3689/api/library/genres"
+
{
+  "items": [
+    {
+      "name": "Classical"
+    },
+    {
+      "name": "Drum & Bass"
+    },
+    {
+      "name": "Pop"
+    },
+    {
+      "name": "Rock/Pop"
+    },
+    {
+      "name": "'90s Alternative"
+    }
+  ],
+  "total": 5,
+  "offset": 0,
+  "limit": -1
+}
+

List albums for genre

Lists the albums in a genre

Endpoint

GET api/search?type=albums&expression=genre+is+\"{genre name}\""
+

Query parameters

Parameter Value
genre genre name (uri encoded and html esc seq for chars: '/&)
offset (Optional) Offset of the first album to return
limit (Optional) Maximum number of albums to return

Response

Key Type Value
items array Array of album objects
total integer Total number of albums in the library
offset integer Requested offset of the first albums
limit integer Requested maximum number of albums

Example

curl -X GET "http://localhost:3689/api/search?type=albums&expression=genre+is+\"Pop\""
+curl -X GET "http://localhost:3689/api/search?type=albums&expression=genre+is+\"Rock%2FPop\""            # Rock/Pop
+curl -X GET "http://localhost:3689/api/search?type=albums&expression=genre+is+\"Drum%20%26%20Bass\""     # Drum & Bass
+curl -X GET "http://localhost:3689/api/search?type=albums&expression=genre+is+\"%2790s%20Alternative\""  # '90 Alternative
+
{
+  "albums": {
+    "items": [
+      {
+        "id": "320189328729146437",
+        "name": "Best Ever",
+        "name_sort": "Best Ever",
+        "artist": "ABC",
+        "artist_id": "8760559201889050080",
+        "track_count": 1,
+        "length_ms": 3631,
+        "uri": "library:album:320189328729146437"
+      },
+      {
+        "id": "7964595866631625723",
+        "name": "Greatest Hits",
+        "name_sort": "Greatest Hits",
+        "artist": "Marvin Gaye",
+        "artist_id": "5261930703203735930",
+        "track_count": 2,
+        "length_ms": 7262,
+        "uri": "library:album:7964595866631625723"
+      },
+      {
+        "id": "3844610748145176456",
+        "name": "The Very Best of Etta",
+        "name_sort": "Very Best of Etta",
+        "artist": "Etta James",
+        "artist_id": "2627182178555864595",
+        "track_count": 1,
+        "length_ms": 177926,
+        "uri": "library:album:3844610748145176456"
+      }
+    ],
+    "total": 3,
+    "offset": 0,
+    "limit": -1
+  }
+}
+

Get count of tracks, artists and albums

Get information about the number of tracks, artists and albums and the total playtime

Endpoint

GET /api/library/count
+

Query parameters

Parameter Value
expression (Optional) The smart playlist query expression, if this parameter is omitted returns the information for the whole library

Response

Key Type Value
tracks integer Number of tracks matching the expression
artists integer Number of artists matching the expression
albums integer Number of albums matching the expression
db_playtime integer Total playtime in milliseconds of all tracks matching the expression

Example

curl -X GET "http://localhost:3689/api/library/count?expression=data_kind+is+file"
+
{
+  "tracks": 6811,
+  "artists": 355,
+  "albums": 646,
+  "db_playtime": 1590767
+}
+

List local directories

List the local directories and the directory contents (tracks and playlists)

Endpoint

GET /api/library/files
+

Query parameters

Parameter Value
directory (Optional) A path to a directory in your local library.

Response

Key Type Value
directories array Array of directory objects containing the sub directories
tracks object paging object containing track objects that matches the directory
playlists object paging object containing playlist objects that matches the directory

Example

curl -X GET "http://localhost:3689/api/library/files?directory=/music/srv"
+
{
+  "directories": [
+    {
+      "path": "/music/srv/Audiobooks"
+    },
+    {
+      "path": "/music/srv/Music"
+    },
+    {
+      "path": "/music/srv/Playlists"
+    },
+    {
+      "path": "/music/srv/Podcasts"
+    }
+  ],
+  "tracks": {
+    "items": [
+      {
+        "id": 1,
+        "title": "input.pipe",
+        "artist": "Unknown artist",
+        "artist_sort": "Unknown artist",
+        "album": "Unknown album",
+        "album_sort": "Unknown album",
+        "album_id": "4201163758598356043",
+        "album_artist": "Unknown artist",
+        "album_artist_sort": "Unknown artist",
+        "album_artist_id": "4187901437947843388",
+        "genre": "Unknown genre",
+        "year": 0,
+        "track_number": 0,
+        "disc_number": 0,
+        "length_ms": 0,
+        "play_count": 0,
+        "skip_count": 0,
+        "time_added": "2018-11-24T08:41:35Z",
+        "seek_ms": 0,
+        "media_kind": "music",
+        "data_kind": "pipe",
+        "path": "/music/srv/input.pipe",
+        "uri": "library:track:1",
+        "artwork_url": "/artwork/item/1"
+      }
+    ],
+    "total": 1,
+    "offset": 0,
+    "limit": -1
+  },
+  "playlists": {
+    "items": [
+      {
+        "id": 8,
+        "name": "radio",
+        "path": "/music/srv/radio.m3u",
+        "smart_playlist": true,
+        "uri": "library:playlist:8"
+      }
+    ],
+    "total": 1,
+    "offset": 0,
+    "limit": -1
+  }
+}
+

Add an item to the library

This endpoint currently only supports addind RSS feeds.

Endpoint

POST /api/library/add
+

Query parameters

Parameter Value
url URL of the RSS to add

Response

On success returns the HTTP 200 OK success status response code.

Example

curl -X POST "http://localhost:3689/api/library/add?url=http%3A%2F%2Fmyurl.com%2Flink.rss"
+

Trigger rescan

Trigger a library rescan

Endpoint

PUT /api/update
+

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/update"
+
{
+  "songs": 217,
+  "db_playtime": 66811,
+  "artists": 9,
+  "albums": 19,
+  "started_at": "2018-11-19T19:06:08Z",
+  "updated_at": "2018-11-19T19:06:16Z",
+  "updating": false
+}
+

Trigger metadata rescan

Trigger a library metadata rescan even if files have not been updated. Maintenence method.

Endpoint

PUT /api/rescan
+

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/rescan"
+

Backup DB

Request a library backup - configuration must be enabled and point to a valid writable path. Maintenance method.

Endpoint

PUT /api/library/backup
+

Response

On success returns the HTTP 200 OK success status response code. If backups are not enabled returns HTTP 503 Service Unavailable response code. Otherwise a HTTP 500 Internal Server Error response is returned.

Example

curl -X PUT "http://localhost:3689/api/library/backup"
+
Method Endpoint Description
GET /api/search Search for playlists, artists, albums, tracks,genres by a simple search term
GET /api/search Search by complex query expression

Search by search term

Search for playlists, artists, albums, tracks, genres that include the given query in their title (case insensitive matching).

Endpoint

GET /api/search
+

Query parameters

Parameter Value
query The search keyword
type Comma separated list of the result types (playlist, artist, album, track, genre)
media_kind (Optional) Filter results by media kind (music, movie, podcast, audiobook, musicvideo, tvshow). Filter only applies to artist, album and track result types.
offset (Optional) Offset of the first item to return for each type
limit (Optional) Maximum number of items to return for each type

Response

Key Type Value
tracks object paging object containing track objects that matches the query
artists object paging object containing artist objects that matches the query
albums object paging object containing album objects that matches the query
playlists object paging object containing playlist objects that matches the query

Example

Search for all tracks, artists, albums and playlists that contain "the" in their title and return the first two results for each type:

curl -X GET "http://localhost:3689/api/search?type=tracks,artists,albums,playlists&query=the&offset=0&limit=2"
+
{
+  "tracks": {
+    "items": [
+      {
+        "id": 35,
+        "title": "Another Love",
+        "artist": "Tom Odell",
+        "artist_sort": "Tom Odell",
+        "album": "Es is was es is",
+        "album_sort": "Es is was es is",
+        "album_id": "6494853621007413058",
+        "album_artist": "Various artists",
+        "album_artist_sort": "Various artists",
+        "album_artist_id": "8395563705718003786",
+        "genre": "Singer/Songwriter",
+        "year": 2013,
+        "track_number": 7,
+        "disc_number": 1,
+        "length_ms": 251030,
+        "play_count": 0,
+        "media_kind": "music",
+        "data_kind": "file",
+        "path": "/music/srv/Compilations/Es is was es is/07 Another Love.m4a",
+        "uri": "library:track:35"
+      },
+      {
+        "id": 215,
+        "title": "Away From the Sun",
+        "artist": "3 Doors Down",
+        "artist_sort": "3 Doors Down",
+        "album": "Away From the Sun",
+        "album_sort": "Away From the Sun",
+        "album_id": "8264078270267374619",
+        "album_artist": "3 Doors Down",
+        "album_artist_sort": "3 Doors Down",
+        "album_artist_id": "5030128490104968038",
+        "genre": "Rock",
+        "year": 2002,
+        "track_number": 2,
+        "disc_number": 1,
+        "length_ms": 233278,
+        "play_count": 0,
+        "media_kind": "music",
+        "data_kind": "file",
+        "path": "/music/srv/Away From the Sun/02 Away From the Sun.mp3",
+        "uri": "library:track:215"
+      }
+    ],
+    "total": 14,
+    "offset": 0,
+    "limit": 2
+  },
+  "artists": {
+    "items": [
+      {
+        "id": "8737690491750445895",
+        "name": "The xx",
+        "name_sort": "xx, The",
+        "album_count": 2,
+        "track_count": 25,
+        "length_ms": 5229196,
+        "uri": "library:artist:8737690491750445895"
+      }
+    ],
+    "total": 1,
+    "offset": 0,
+    "limit": 2
+  },
+  "albums": {
+    "items": [
+      {
+        "id": "8264078270267374619",
+        "name": "Away From the Sun",
+        "name_sort": "Away From the Sun",
+        "artist": "3 Doors Down",
+        "artist_id": "5030128490104968038",
+        "track_count": 12,
+        "length_ms": 2818174,
+        "uri": "library:album:8264078270267374619"
+      },
+      {
+        "id": "6835720495312674468",
+        "name": "The Better Life",
+        "name_sort": "Better Life",
+        "artist": "3 Doors Down",
+        "artist_id": "5030128490104968038",
+        "track_count": 11,
+        "length_ms": 2393332,
+        "uri": "library:album:6835720495312674468"
+      }
+    ],
+    "total": 3,
+    "offset": 0,
+    "limit": 2
+  },
+  "playlists": {
+    "items": [],
+    "total": 0,
+    "offset": 0,
+    "limit": 2
+  }
+}
+

Search by query language

Search for artists, albums, tracks by a smart playlist query expression (see README_SMARTPL.md for the expression syntax).

Endpoint

GET /api/search
+

Query parameters

Parameter Value
expression The smart playlist query expression
type Comma separated list of the result types (artist, album, track
offset (Optional) Offset of the first item to return for each type
limit (Optional) Maximum number of items to return for each type

Response

Key Type Value
tracks object paging object containing track objects that matches the query
artists object paging object containing artist objects that matches the query
albums object paging object containing album objects that matches the query

Example

Search for music tracks ordered descending by the time added to the library and limit result to 2 items:

curl -X GET "http://localhost:3689/api/search?type=tracks&expression=media_kind+is+music+order+by+time_added+desc&offset=0&limit=2"
+

Server info

Method Endpoint Description
GET /api/config Get configuration information

Config

Endpoint

GET /api/config
+

Response

Key Type Value
version string Server version
websocket_port integer Port number for the websocket (or 0 if websocket is disabled)
buildoptions array Array of strings indicating which features are supported by the server

Example

curl -X GET "http://localhost:3689/api/config"
+
{
+  "websocket_port": 3688,
+  "version": "25.0",
+  "buildoptions": [
+    "ffmpeg",
+    "iTunes XML",
+    "Spotify",
+    "LastFM",
+    "MPD",
+    "Device verification",
+    "Websockets",
+    "ALSA"
+  ]
+}
+

Settings

Method Endpoint Description
GET /api/settings Get all available categories
GET /api/settings/{category-name} Get all available options for a category
GET /api/settings/{category-name}/{option-name} Get a single setting option
PUT /api/settings/{category-name}/{option-name} Change the value of a setting option
DELETE /api/settings/{category-name}/{option-name} Reset a setting option to its default

List categories

List all settings categories with their options

Endpoint

GET /api/settings
+

Response

Key Type Value
categories array Array of settings category objects

Example

curl -X GET "http://localhost:3689/api/settings"
+
{
+  "categories": [
+    {
+      "name": "webinterface",
+      "options": [
+        {
+          "name": "show_composer_now_playing",
+          "type": 1,
+          "value": true
+        },
+        {
+          "name": "show_composer_for_genre",
+          "type": 2,
+          "value": "classical"
+        }
+      ]
+    }
+  ]
+}
+

Get a category

Get a settings category with their options

Endpoint

GET /api/settings/{category-name}
+

Response

Returns a settings category object

Example

curl -X GET "http://localhost:3689/api/settings/webinterface"
+
{
+  "name": "webinterface",
+  "options": [
+    {
+      "name": "show_composer_now_playing",
+      "type": 1,
+      "value": true
+    },
+    {
+      "name": "show_composer_for_genre",
+      "type": 2,
+      "value": "classical"
+    }
+  ]
+}
+

Get an option

Get a single settings option

Endpoint

GET /api/settings/{category-name}/{option-name}
+

Response

Returns a settings option object

Example

curl -X GET "http://localhost:3689/api/settings/webinterface/show_composer_now_playing"
+
{
+  "name": "show_composer_now_playing",
+  "type": 1,
+  "value": true
+}
+

Change an option value

Get a single settings option

Endpoint

PUT /api/settings/{category-name}/{option-name}
+

Request

Key Type Value
name string Option name
value (integer / boolean / string) New option value

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/settings/webinterface/show_composer_now_playing" --data "{\"name\":\"show_composer_now_playing\",\"value\":true}"
+

Delete an option

Delete a single settings option (thus resetting it to default)

Endpoint

DELETE /api/settings/{category-name}/{option-name}
+

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X DELETE "http://localhost:3689/api/settings/webinterface/show_composer_now_playing"
+

Push notifications

If the server was built with websocket support it exposes a websocket at localhost:3688 to inform clients of changes (e. g. player state or library updates). The port depends on the server configuration and can be read using the /api/config endpoint.

After connecting to the websocket, the client should send a message containing the event types it is interested in. After that the server will send a message each time one of the events occurred.

Message

Key Type Value
notify array Array of event types

Event types

Type Description
update Library update started or finished
database Library database changed (new/modified/deleted tracks)
outputs An output was enabled or disabled
player Player state changes
options Playback option changes (shuffle, repeat, consume mode)
volume Volume changes
queue Queue changes

Example

curl --include \
+     --no-buffer \
+     --header "Connection: Upgrade" \
+     --header "Upgrade: websocket" \
+     --header "Host: localhost:3688" \
+     --header "Origin: http://localhost:3688" \
+     --header "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
+     --header "Sec-WebSocket-Version: 13" \
+     --header "Sec-WebSocket-Protocol: notify" \
+     http://localhost:3688/ \
+     --data "{ \"notify\": [ \"player\" ] }"
+
{ 
+  "notify": [
+    "player"
+  ]
+}
+

Object model

queue item object

Key Type Value
id string Item id
position integer Position in the queue (starting with zero)
track_id string Track id
title string Title
artist string Track artist name
artist_sort string Track artist sort name
album string Album name
album_sort string Album sort name
album_id string Album id
album_artist string Album artist name
album_artist_sort string Album artist sort name
album_artist_id string Album artist id
composer string Composer (optional)
genre string Genre
year integer Release year
track_number integer Track number
disc_number integer Disc number
length_ms integer Track length in milliseconds
media_kind string Media type of this track: music, movie, podcast, audiobook, musicvideo, tvshow
data_kind string Data type of this track: file, url, spotify, pipe
path string Path
uri string Resource identifier
artwork_url string (optional) Artwork url
type string file (codec) type (ie mp3/flac/...)
bitrate string file bitrate (ie 192/128/...)
samplerate string file sample rate (ie 44100/48000/...)
channel string file channel (ie mono/stereo/xx ch))

playlist object

Key Type Value
id string Playlist id
name string Playlist name
path string Path
parent_id integer Playlist id of the parent (folder) playlist
type string Type of this playlist: special, folder, smart, plain
smart_playlist boolean true if playlist is a smart playlist
folder boolean true if it is a playlist folder
uri string Resource identifier

artist object

Key Type Value
id string Artist id
name string Artist name
name_sort string Artist sort name
album_count integer Number of albums
track_count integer Number of tracks
length_ms integer Total length of tracks in milliseconds
uri string Resource identifier
artwork_url string (optional) Artwork url

album object

Key Type Value
id string Album id
name string Album name
name_sort string Album sort name
artist_id string Album artist id
artist string Album artist name
track_count integer Number of tracks
length_ms integer Total length of tracks in milliseconds
uri string Resource identifier
artwork_url string (optional) Artwork url

track object

Key Type Value
id integer Track id
title string Title
title_sort string Sort title
artist string Track artist name
artist_sort string Track artist sort name
album string Album name
album_sort string Album sort name
album_id string Album id
album_artist string Album artist name
album_artist_sort string Album artist sort name
album_artist_id string Album artist id
composer string Track composer
genre string Genre
comment string Comment
year integer Release year
track_number integer Track number
disc_number integer Disc number
length_ms integer Track length in milliseconds
rating integer Track rating (ranges from 0 to 100)
play_count integer How many times the track was played
skip_count integer How many times the track was skipped
time_played string Timestamp in ISO 8601 format
time_skipped string Timestamp in ISO 8601 format
time_added string Timestamp in ISO 8601 format
date_released string Date in the format yyyy-mm-dd
seek_ms integer Resume point in milliseconds (available only for podcasts and audiobooks)
media_kind string Media type of this track: music, movie, podcast, audiobook, musicvideo, tvshow
data_kind string Data type of this track: file, url, spotify, pipe
path string Path
uri string Resource identifier
artwork_url string (optional) Artwork url
usermark integer User review marking of track (ranges from 0)

paging object

Key Type Value
items array Array of result objects
total integer Total number of items
offset integer Requested offset of the first item
limit integer Requested maximum number of items

browse-info object

Key Type Value
name string Name (depends on the type of the query)
name_sort string Sort name
artist_count integer Number of artists
album_count integer Number of albums
track_count integer Number of tracks
time_played string Timestamp in ISO 8601 format
time_added string Timestamp in ISO 8601 format

directory object

Key Type Value
path string Directory path

category object

Key Type Value
name string Category name
options array Array of option in this category

option object

Key Type Value
name string Option name
type integer The type of the value for this option (0: integer, 1: boolean, 2: string)
value (integer / boolean / string) Current value for this option

Artwork urls

Artwork urls in queue item, artist, album and track objects can be either relative urls or absolute urls to the artwork image. Absolute artwork urls are pointing to external artwork images (e. g. for radio streams that provide artwork metadata), while relative artwork urls are served from the server.

It is possible to add the query parameters maxwidth and/or maxheight to relative artwork urls, in order to get a smaller image (the server only scales down never up).

Note that even if a relative artwork url attribute is present, it is not guaranteed to exist.

\ No newline at end of file diff --git a/library/index.html b/library/index.html new file mode 100644 index 0000000000..e9c2318691 --- /dev/null +++ b/library/index.html @@ -0,0 +1,3 @@ + Library - OwnTone

Library

The library is scanned in bulk mode at startup, but the server will be available even while this scan is in progress. You can follow the progress of the scan in the log file or via the web interface. When the scan is complete you will see the log message: "Bulk library scan completed in X sec".

The very first scan will take longer than subsequent startup scans, since every file gets analyzed. At the following startups the server looks for changed files and only analyzis those.

Updates to the library are reflected in real time after the initial scan, so you do not need to manually start rescans. The directories are monitored for changes and rescanned on the fly. Note that if you have your library on a network mount then real time updating may not work. Read below about what to do in that case.

If you change any of the directory settings in the library section of the configuration file a rescan is required before the new setting will take effect. You can do this by using "Update library" from the web interface.

Symlinks are supported and dereferenced, but it is best to use them for directories only.

Files starting with . (dot) and _ (underscore) are ignored.

Pipes (for e.g. multiroom with Shairport-sync)

Some programs, like for instance Shairport-sync, can be configured to output audio to a named pipe. If this pipe is placed in the library, OwnTone will automatically detect that it is there, and when there is audio being written to it, playback of the audio will be autostarted (and stopped).

Using this feature, OwnTone can act as an AirPlay multiroom "router": You can have an AirPlay source (e.g. your iPhone) send audio Shairport-sync, which forwards it to OwnTone through the pipe, which then plays it on whatever speakers you have selected (through Remote).

The format of the audio being written to the pipe must be PCM16.

You can also start playback of pipes manually. You will find them in remotes listed under "Unknown artist" and "Unknown album". The track title will be the name of the pipe.

Shairport-sync can write metadata to a pipe, and OwnTone can read this. This requires that the metadata pipe has the same filename as the audio pipe plus a ".metadata" suffix. Say Shairport-sync is configured to write audio to "/foo/bar/pipe", then the metadata pipe should be "/foo/bar/pipe.metadata".

Libraries on network mounts

Most network filesharing protocols do not offer notifications when the library is changed. So that means OwnTone cannot update its database in real time. Instead you can schedule a cron job to update the database.

The first step in doing this is to add two entries to the 'directories' configuration item in owntone.conf:

  directories = { "/some/local/dir", "/your/network/mount/library" }
+

Now you can make a cron job that runs this command:

  touch /some/local/dir/trigger.init-rescan
+

When OwnTone detects a file with filename ending .init-rescan it will perform a bulk scan similar to the startup scan.

Alternatively, you can force a metadata scan of the library even if the files have not changed by creating a filename ending .meta-rescan.

Supported formats

OwnTone should support pretty much all audio formats. It relies on libav (or ffmpeg) to extract metadata and decode the files on the fly when the client doesn't support the format.

Formats are attributed a code, so any new format will need to be explicitely added. Currently supported:

  • MPEG4: mp4a, mp4v
  • AAC: alac
  • MP3 (and friends): mpeg
  • FLAC: flac
  • OGG VORBIS: ogg
  • Musepack: mpc
  • WMA: wma (WMA Pro), wmal (WMA Lossless), wmav (WMA video)
  • AIFF: aif
  • WAV: wav
  • Monkey's audio: ape

Troubleshooting library issues

If you place a file with the filename ending .full-rescan in your library, you can trigger a full rescan of your library. This will clear all music and playlists from OwnTone's database and initiate a fresh bulk scan. Pairing and speaker information will be kept. Only use this for troubleshooting, it is not necessary during normal operation.

\ No newline at end of file diff --git a/outputs/airplay/index.html b/outputs/airplay/index.html new file mode 100644 index 0000000000..8a9bd96644 --- /dev/null +++ b/outputs/airplay/index.html @@ -0,0 +1 @@ + Airplay - OwnTone

AirPlay devices/speakers

OwnTone will discover the AirPlay devices available on your network. For devices that are password-protected, the device's AirPlay name and password must be given in the configuration file. See the sample configuration file for the syntax.

If your Apple TV requires device verification (always required by Apple TV4 with tvOS 10.2) then you can do that through Settings > Remotes & Outputs in the web interface: Select the device and then enter the PIN that the Apple TV displays.

If your speaker is silent when you start playback, and there is no obvious error message in the log, you can try disabling ipv6 in the config. Some speakers announce that they support ipv6, but in fact don't (at least not with forked- daapd).

If the speaker becomes unselected when you start playback, and you in the log see "ANNOUNCE request failed in session startup: 400 Bad Request", then try the Apple Home app > Allow Speakers & TV Access > Anyone On the Same Network (or Everyone).

\ No newline at end of file diff --git a/outputs/chromecast/index.html b/outputs/chromecast/index.html new file mode 100644 index 0000000000..5b4fe87e64 --- /dev/null +++ b/outputs/chromecast/index.html @@ -0,0 +1 @@ + Chromecast - OwnTone

Chromecast

OwnTone will discover Chromecast devices available on your network, and you can then select the device as a speaker. There is no configuration required.

\ No newline at end of file diff --git a/outputs/local-audio/index.html b/outputs/local-audio/index.html new file mode 100644 index 0000000000..3d3a1f8029 --- /dev/null +++ b/outputs/local-audio/index.html @@ -0,0 +1 @@ + Local audio - OwnTone

Local audio

Local audio through ALSA

In the config file, you can select ALSA for local audio. This is the default.

When using ALSA, the server will try to syncronize playback with AirPlay. You can adjust the syncronization in the config file.

For most setups the default values in the config file should work. If they don't, there is help here

Local audio, Bluetooth and more through Pulseaudio

In the config file, you can select Pulseaudio for local audio. In addition to local audio, Pulseaudio also supports an array of other targets, e.g. Bluetooth or DLNA. However, Pulseaudio does require some setup, so here is a separate page with some help on that: Pulse audio

Note that if you select Pulseaudio the "card" setting in the config file has no effect. Instead all soundcards detected by Pulseaudio will be listed as speakers by OwnTone.

You can adjust the latency of Pulseaudio playback in the config file.

\ No newline at end of file diff --git a/outputs/streaming/index.html b/outputs/streaming/index.html new file mode 100644 index 0000000000..088ad294c6 --- /dev/null +++ b/outputs/streaming/index.html @@ -0,0 +1 @@ + Streaming - OwnTone

MP3 network streaming (streaming to iOS)

You can listen to audio being played by OwnTone by opening this network stream address in pretty much any music player:

http://owntone.local:3689/stream.mp3 or http://SERVER_ADDRESS:3689/stream.mp3

This is currently the only way of listening to your audio on iOS devices, since Apple does not allow AirPlay receiver apps, and because Apple Home Sharing cannot be supported by OwnTone. So what you can do instead is install a music player app like VLC, connect to the stream and control playback with Remote.

In the speaker selection list, clicking on the icon should start the stream playing in the background on browsers that support that.

Note that MP3 encoding must be supported by ffmpeg/libav for this to work. If it is not available you will see a message in the log file. In Debian/Ubuntu you get MP3 encoding support by installing the package "libavcodec-extra".

\ No newline at end of file diff --git a/playlists/index.html b/playlists/index.html new file mode 100644 index 0000000000..e6e2b0499c --- /dev/null +++ b/playlists/index.html @@ -0,0 +1 @@ + Playlists & radio - OwnTone

Playlists and internet radio

OwnTone supports M3U and PLS playlists. Just drop your playlist somewhere in your library with an .m3u or .pls extension and it will pick it up.

From the web interface, and some mpd clients, you can also create and modify playlists by saving the current queue. Click the "Save" button. Note that this requires that allow_modifying_stored_playlists is enabled in the configuration file, and that the server has write access to default_playlist_directory.

If the playlist contains an http URL it will be added as an internet radio station, and the URL will be probed for Shoutcast (ICY) metadata. If the radio station provides artwork, OwnTone will download it during playback and send it to any remotes or AirPlay devices requesting it.

Instead of downloading M3U's from your radio stations, you can also make an empty M3U file and insert links in it to the M3U's of your radio stations.

Radio streams can only be played by OwnTone, so that means they will not be available to play in DAAP clients like iTunes.

The server can import playlists from iTunes Music Library XML files. By default, metadata from our parsers is preferred over what's in the iTunes DB; use itunes_overrides = true if you prefer iTunes' metadata.

OwnTone has support for smart playlists. How to create a smart playlist is documented in Smart playlists.

If you're not satisfied with internet radio metadata that OwnTone shows, then you can read about tweaking it in Radio streams.

\ No newline at end of file diff --git a/search/search_index.json b/search/search_index.json new file mode 100644 index 0000000000..95afadc336 --- /dev/null +++ b/search/search_index.json @@ -0,0 +1 @@ +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"OwnTone","text":"

OwnTone is an open source (audio) media server for GNU/Linux, FreeBSD and MacOS.

It allows sharing and streaming your media library to iTunes (DAAP1), Roku (RSP), AirPlay devices (multiroom), Chromecast and also supports local playback.

You can control OwnTone via its web interface, Apple Remote (and compatible DAAP/DACP clients), MPD clients or via its JSON API.

Besides serving your local music, podcast and audiobook media files, OwnTone supports internet radios and Spotify (requires Spotify premium account).

Prior to version 28, OwnTone was called forked-daapd, which again was a rewrite of mt-daapd (Firefly Media Server).

OwnTone is written in C with a web interface written in Vue.js.

"},{"location":"#features","title":"Features","text":"
  • Stream to AirPlay (synchronized multiroom) and Chromecast devices
  • Share local library with iTunes and Roku
  • Local audio playback with ALSA or PulseAudio

  • Supports multiple different clients:

    • Remote apps like Apple Remote (iOS) or Retune (Android)
    • Integrated mobile friendly web interface
    • MPD clients

  • Supports music and audiobook files, podcast files and RSS and internet radio

  • Supports audio files in most formats
  • Supports playing your Spotify library (requires Spotify premium account)
  • Runs on low power devices like the Raspberry Pi

(You can find more screenshots from OwnTone's web interface here)

"},{"location":"#looking-for-help","title":"Looking for help?","text":"

Before you continue, make sure you know what version of OwnTone you have, and what features it was built with (e.g. Spotify support).

How to find out? Go to the web interface and check. No web interface? Then check the top of OwnTone's log file (usually /var/log/owntone.log).

Note that you are viewing a snapshot of the instructions that may or may not match the version of OwnTone that you are using.

If you are looking for help on building OwnTone (not using it), then please see the documentation on Building from Source.

"},{"location":"#references","title":"References","text":"

You can find source and documentation, also for older versions, here:

  • https://github.com/owntone/owntone-server.git

  1. DAAP stands for Digital Audio Access Protocol which is the protocol used by iTunes and friends to share/stream media libraries over the network.\u00a0\u21a9

"},{"location":"artwork/","title":"Artwork","text":"

OwnTone has support for PNG and JPEG artwork which is either:

  • embedded in the media files
  • placed as separate image files in the library
  • made available online by the radio station

For media in your library, OwnTone will try to locate album and artist artwork (group artwork) by the following procedure:

  • if a file {artwork,cover,Folder}.{png,jpg} is found in one of the directories containing files that are part of the group, it is used as the artwork. The first file found is used, ordering is not guaranteed;
  • failing that, if [directory name].{png,jpg} is found in one of the directories containing files that are part of the group, it is used as the artwork. The first file found is used, ordering is not guaranteed;
  • failing that, individual files are examined and the first file found with an embedded artwork is used. Here again, ordering is not guaranteed.

{artwork,cover,Folder} are the default, you can add other base names in the configuration file. Here you can also enable/disable support for individual file artwork (instead of using the same artwork for all tracks in an entire album).

For playlists in your library, say /foo/bar.m3u, then for any http streams in the list, OwnTone will look for /foo/bar.{jpg,png}.

You can use symlinks for the artwork files.

OwnTone caches artwork in a separate cache file. The default path is /var/cache/owntone/cache.db and can be configured in the configuration file. The cache.db file can be deleted without losing the library and pairing informations.

"},{"location":"building/","title":"Build instructions for OwnTone","text":"

This document contains instructions for building OwnTone from the git tree. If you just want to build from a release tarball, you don't need the build tools (git, autotools, autoconf, automake, gawk, gperf, gettext, bison and flex), and you can skip the autoreconf step.

"},{"location":"building/#quick-version-for-debianubuntu-users","title":"Quick version for Debian/Ubuntu users","text":"

If you are the lucky kind, this should get you all the required tools and libraries:

sudo apt-get install \\\nbuild-essential git autotools-dev autoconf automake libtool gettext gawk \\\ngperf bison flex libconfuse-dev libunistring-dev libsqlite3-dev \\\nlibavcodec-dev libavformat-dev libavfilter-dev libswscale-dev libavutil-dev \\\nlibasound2-dev libmxml-dev libgcrypt20-dev libavahi-client-dev zlib1g-dev \\\nlibevent-dev libplist-dev libsodium-dev libjson-c-dev libwebsockets-dev \\\nlibcurl4-openssl-dev libprotobuf-c-dev\n

Note that OwnTone will also work with other versions and flavours of libgcrypt and libcurl, so the above are just suggestions.

The following features require extra packages, and that you add a configure argument when you run ./configure:

Feature Configure argument Packages Chromecast --enable-chromecast libgnutls*-dev Pulseaudio --with-pulseaudio libpulse-dev

These features can be disabled saving you package dependencies:

Feature Configure argument Packages Spotify (built-in) --disable-spotify libprotobuf-c-dev Player web UI --disable-webinterface libwebsockets-dev Live web UI --without-libwebsockets libwebsockets-dev

Then run the following (adding configure arguments for optional features):

git clone https://github.com/owntone/owntone-server.git\ncd owntone-server\nautoreconf -i\n./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --enable-install-user\nmake\nsudo make install\n

Using --enable-install-user means that make install will also add system user and group for owntone.

With the above configure arguments, a systemd service file will be installed to /etc/systemd/system/owntone.service so that the server will start on boot. Use --disable-install-systemd if you don't want that.

Now edit /etc/owntone.conf. Note the guide at the top highlighting which settings that normally require modification.

Start the server with sudo systemctl start owntone and check that it is running with sudo systemctl status owntone.

See the Documentation for usage information.

"},{"location":"building/#quick-version-for-fedora","title":"Quick version for Fedora","text":"

If you haven't already enabled the free RPM fusion packages do that, since you will need ffmpeg. You can google how to do that. Then run:

sudo dnf install \\\ngit automake autoconf gettext-devel gperf gawk libtool bison flex \\\nsqlite-devel libconfuse-devel libunistring-devel mxml-devel libevent-devel \\\navahi-devel libgcrypt-devel zlib-devel alsa-lib-devel ffmpeg-devel \\\nlibplist-devel libsodium-devel json-c-devel libwebsockets-devel \\\nlibcurl-devel protobuf-c-devel\n

Clone the OwnTone repo:

git clone https://github.com/owntone/owntone-server.git\ncd owntone-server\n

Then run the following:

autoreconf -i\n./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --enable-install-user\nmake\nsudo make install\n

Using --enable-install-user means that make install will also add system user and group for owntone.

With the above configure arguments, a systemd service file will be installed to /etc/systemd/system/owntone.service so that the server will start on boot. Use --disable-install-systemd if you don't want that.

Now edit /etc/owntone.conf. Note the guide at the top highlighting which settings that normally require modification.

Start the server with sudo systemctl start owntone and check that it is running with sudo systemctl status owntone.

See the Documentation for usage information.

"},{"location":"building/#quick-version-for-freebsd","title":"Quick version for FreeBSD","text":"

There is a script in the 'scripts' folder that will at least attempt to do all the work for you. And should the script not work for you, you can still look through it and use it as an installation guide.

"},{"location":"building/#quick-version-for-macos-using-homebrew","title":"Quick version for macOS (using Homebrew)","text":"

This workflow file used for building OwnTone via Github actions includes all the steps that you need to execute: .github/workflows/macos.yml

"},{"location":"building/#quick-version-for-macos-using-macports","title":"\"Quick\" version for macOS (using macports)","text":"

Caution: 1) this approach may be out of date, consider using the Homebrew method above since it is continuously tested. 2) macports requires many downloads and lots of time to install (and sometimes build) ports... you'll want a decent network connection and some patience!

Install macports (which requires Xcode): https://www.macports.org/install.php

sudo port install \\\nautoconf automake libtool pkgconfig git gperf bison flex libgcrypt \\\nlibunistring libconfuse ffmpeg libevent json-c libwebsockets curl \\\nlibplist libsodium protobuf-c\n

Download, configure, build and install the Mini-XML library: http://www.msweet.org/projects.php/Mini-XML

Download, configure, build and install the libinotify library: https://github.com/libinotify-kqueue/libinotify-kqueue

Add the following to .bashrc:

# add /usr/local to pkg-config path\nexport PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/opt/local/lib/pkgconfig\n# libunistring doesn't support pkg-config, set overrides\nexport LIBUNISTRING_CFLAGS=-I/opt/local/include\nexport LIBUNISTRING_LIBS=\"-L/opt/local/lib -lunistring\"\n

Optional features require the following additional ports:

Feature Configure argument Ports Chromecast --enable-chromecast gnutls Pulseaudio --with-pulseaudio pulseaudio

Clone the OwnTone repo:

git clone https://github.com/owntone/owntone-server.git\ncd owntone-server\n

Finally, configure, build and install, adding configure arguments for optional features:

autoreconf -i\n./configure\nmake\nsudo make install\n

Note: if for some reason you've installed the avahi port, you need to add --without-avahi to configure above.

Edit /usr/local/etc/owntone.conf and change the uid to a nice system daemon (eg: unknown), and run the following:

sudo mkdir -p /usr/local/var/run\nsudo mkdir -p /usr/local/var/log # or change logfile in conf\nsudo chown unknown /usr/local/var/cache/owntone # or change conf\n

Run OwnTone:

sudo /usr/local/sbin/owntone\n

Verify it's running (you need to Ctrl+C to stop dns-sd):

dns-sd -B _daap._tcp\n
"},{"location":"building/#long-version-requirements","title":"Long version - requirements","text":"

Required tools:

  • autotools: autoconf 2.63+, automake 1.10+, libtool 2.2. Run autoreconf -i at the top of the source tree to generate the build system.
  • gettext: libunistring requires iconv and gettext provides the autotools macro definitions for iconv.
  • gperf
  • bison 3.0+ (yacc is not sufficient)
  • flex (lex is not sufficient)

Libraries:

  • Avahi client libraries (avahi-client), 0.6.24 minimum from http://avahi.org/
  • sqlite3 3.5.0+ with unlock notify API enabled (read below) from http://sqlite.org/download.html
  • ffmpeg (libav) from http://ffmpeg.org/
  • libconfuse from http://www.nongnu.org/confuse/
  • libevent 2.1.4+ from http://libevent.org/
  • MiniXML (aka mxml or libmxml) from http://minixml.org/software.php
  • gcrypt 1.2.0+ from http://gnupg.org/download/index.en.html#libgcrypt
  • zlib from http://zlib.net/
  • libunistring 0.9.3+ from http://www.gnu.org/software/libunistring/#downloading
  • libjson-c from https://github.com/json-c/json-c/wiki
  • libcurl from http://curl.haxx.se/libcurl/
  • libplist 0.16+ from http://github.com/JonathanBeck/libplist/downloads
  • libsodium from https://download.libsodium.org/doc/
  • libprotobuf-c from https://github.com/protobuf-c/protobuf-c/wiki
  • libasound (optional - ALSA local audio) often already installed as part of your distro
  • libpulse (optional - Pulseaudio local audio) from https://www.freedesktop.org/wiki/Software/PulseAudio/Download/
  • libgnutls (optional - Chromecast support) from http://www.gnutls.org/
  • libwebsockets 2.0.2+ (optional - websocket support) from https://libwebsockets.org/

If using binary packages, remember that you need the development packages to build OwnTone (usually named -dev or -devel).

sqlite3 needs to be built with support for the unlock notify API; this isn't always the case in binary packages, so you may need to rebuild sqlite3 to enable the unlock notify API (you can check for the presence of the sqlite3_unlock_notify symbol in the sqlite3 library). Refer to the sqlite3 documentation, look for SQLITE_ENABLE_UNLOCK_NOTIFY.

"},{"location":"building/#long-version-building-and-installing","title":"Long version - building and installing","text":"

Start by generating the build system by running autoreconf -i. This will generate the configure script and Makefile.in.

To display the configure options run ./configure --help.

Support for Spotify is optional. Use --disable-spotify to disable this feature.

Support for LastFM scrobbling is optional. Use --enable-lastfm to enable this feature.

Support for the MPD protocol is optional. Use --disable-mpd to disable this feature.

Support for Chromecast devices is optional. Use --enable-chromecast to enable this feature.

The player web interface is optional. Use --disable-webinterface to disable this feature. If enabled, sudo make install will install the prebuild html, js, css files. The prebuild files are:

  • htdocs/index.html
  • htdocs/player/*

The source for the player web interface is located under the web-src folder and requires nodejs >= 6.0 to be built. In the web-src folder run npm install to install all dependencies for the player web interface. After that run npm run build. This will build the web interface and update the htdocs folder. (See Web interface for more informations)

Building with libwebsockets is required if you want the web interface. It will be enabled if the library is present (with headers). Use --without-libwebsockets to disable.

Building with Pulseaudio is optional. It will be enabled if the library is present (with headers). Use --without-pulseaudio to disable.

Recommended build settings:

./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --enable-install-user\n

After configure run the usual make, and if that went well, sudo make install.

With the above configure arguments, a systemd service file will be installed to /etc/systemd/system/owntone.service so that the server will start on boot. Use --disable-install-systemd if you don't want that.

Using --enable-install-user means that make install will also add a system user and group for owntone.

After installation:

  • edit the configuration file, /etc/owntone.conf
  • make sure the Avahi daemon is installed and running (Debian: apt install avahi-daemon)

OwnTone will drop privileges to any user you specify in the configuration file if it's started as root.

This user must have read permission to your library and read/write permissions to the database location ($localstatedir/cache/owntone by default).

"},{"location":"building/#non-priviliged-user-version-for-development","title":"Non-priviliged user version (for development)","text":"

OwnTone is meant to be run as system wide daemon, but for development purposes you may want to run it isolated to your regular user.

The following description assumes that you want all runtime data stored in $HOME/owntone_data and the source in $HOME/projects/owntone-server.

Prepare directories for runtime data: 

mkdir -p $HOME/owntone_data/etc\nmkdir -p $HOME/owntone_data/media\n

Copy one or more mp3 file to test with to owntone_data/media.

Checkout OwnTone and configure build: 

cd $HOME/projects\ngit clone https://github.com/owntone/owntone-server.git\ncd owntone-server\nautoreconf -vi\n./configure --prefix=$HOME/owntone_data/usr --sysconfdir=$HOME/owntone_data/etc --localstatedir=$HOME/owntone_data/var\n

Build and install runtime:

make install\n

Edit owntone_data/etc/owntone.conf, find the following configuration settings and set them to these values:

    uid = ${USER}\n    loglevel = \"debug\"\n    directories = { \"${HOME}/owntone_data/media\" }\n

Run the server:

./src/owntone -f\n
(you can also use the copy of the binary in $HOME/owntone_data/usr/sbin)

"},{"location":"getting-started/","title":"Getting started","text":"

After installation (see Installation) do the following:

  1. Edit the configuration file (usually /etc/owntone.conf) to suit your needs
  2. Start or restart the server (usually /etc/init.d/owntone restart)
  3. Go to the web interface http://owntone.local:3689, or, if that won't work, to http://SERVER_ADDRESS:3689
  4. Wait for the library scan to complete
  5. If you will be using a remote, e.g. Apple Remote: Start the remote, go to Settings, Add Library
  6. Enter the pair code in the web interface (update the page with F5 if it does not automatically pick up the pairing request)
"},{"location":"installation/","title":"How to get and install OwnTone","text":"

You can compile and run OwnTone on pretty much any Linux- or BSD-platform. The instructions are here.

Apt repositories, images and precompiled binaries are available for some platforms. These can save you some work and make it easier to stay up to date:

Platform How to get RPi w/Raspberry Pi OS Add OwnTone repository to apt sources, see:OwnTone server (iTunes server) - Raspberry Pi Forums Debian/Ubuntu amd64 Download .deb as artifact from Github workflow(requires that you are logged in) OpenWrt Run opkg install libwebsockets-full owntone Docker See linuxserver/docker-daapd

OwnTone is not in the official Debian repositories due to lack of Debian maintainer and Debian policy difficulties concerning the web UI, see this issue.

"},{"location":"json-api/","title":"OwnTone API Endpoint Reference","text":"

Available API endpoints:

  • Player: control playback, volume, shuffle/repeat modes
  • Outputs / Speakers: list available outputs and enable/disable outputs
  • Queue: list, add or modify the current queue
  • Library: list playlists, artists, albums and tracks from your library or trigger library rescan
  • Search: search for playlists, artists, albums and tracks
  • Server info: get server information
  • Settings: list and change settings for the player web interface
  • Push notifications: receive push notifications

JSON-Object model:

  • Queue item
  • Playlist
  • Artist
  • Album
  • Track
"},{"location":"json-api/#player","title":"Player","text":"Method Endpoint Description GET /api/player Get player status PUT /api/player/play, /api/player/pause, /api/player/stop, /api/player/toggle Start, pause or stop playback PUT /api/player/next, /api/player/previous Skip forward or backward PUT /api/player/shuffle Set shuffle mode PUT /api/player/consume Set consume mode PUT /api/player/repeat Set repeat mode PUT /api/player/volume Set master volume or volume for a specific output PUT /api/player/seek Seek to a position in the currently playing track"},{"location":"json-api/#get-player-status","title":"Get player status","text":"

Endpoint

GET /api/player\n

Response

Key Type Value state string play, pause or stop repeat string off, all or single consume boolean true if consume mode is enabled shuffle boolean true if shuffle mode is enabled volume integer Master volume in percent (0 - 100) item_id integer The current playing queue item id item_length_ms integer Total length in milliseconds of the current queue item item_progress_ms integer Progress into the current queue item in milliseconds

Example

curl -X GET \"http://localhost:3689/api/player\"\n
{\n\"state\": \"pause\",\n\"repeat\": \"off\",\n\"consume\": false,\n\"shuffle\": false,\n\"volume\": 50,\n\"item_id\": 269,\n\"item_length_ms\": 278093,\n\"item_progress_ms\": 3674\n}\n
"},{"location":"json-api/#control-playback","title":"Control playback","text":"

Start or resume, pause, stop playback.

Endpoint

PUT /api/player/play\n
PUT /api/player/pause\n
PUT /api/player/stop\n
PUT /api/player/toggle\n

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/player/play\"\n
curl -X PUT \"http://localhost:3689/api/player/pause\"\n
curl -X PUT \"http://localhost:3689/api/player/stop\"\n
curl -X PUT \"http://localhost:3689/api/player/toggle\"\n
"},{"location":"json-api/#skip-tracks","title":"Skip tracks","text":"

Skip forward or backward

Endpoint

PUT /api/player/next\n
PUT /api/player/previous\n

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/player/next\"\n
curl -X PUT \"http://localhost:3689/api/player/previous\"\n
"},{"location":"json-api/#set-shuffle-mode","title":"Set shuffle mode","text":"

Enable or disable shuffle mode

Endpoint

PUT /api/player/shuffle\n

Query parameters

Parameter Value state The new shuffle state, should be either true or false

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/player/shuffle?state=true\"\n
"},{"location":"json-api/#set-consume-mode","title":"Set consume mode","text":"

Enable or disable consume mode

Endpoint

PUT /api/player/consume\n

Query parameters

Parameter Value state The new consume state, should be either true or false

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/player/consume?state=true\"\n
"},{"location":"json-api/#set-repeat-mode","title":"Set repeat mode","text":"

Change repeat mode

Endpoint

PUT /api/player/repeat\n

Query parameters

Parameter Value state The new repeat mode, should be either off, all or single

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/player/repeat?state=all\"\n
"},{"location":"json-api/#set-volume","title":"Set volume","text":"

Change master volume or volume of a specific output.

Endpoint

PUT /api/player/volume\n

Query parameters

Parameter Value volume The new volume (0 - 100) step The increase or decrease volume by the given amount (-100 - 100) output_id (Optional) If an output id is given, only the volume of this output will be changed. If parameter is omited, the master volume will be changed.

Either volume or step must be present as query parameter

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/player/volume?volume=50\"\n
curl -X PUT \"http://localhost:3689/api/player/volume?step=-5\"\n
curl -X PUT \"http://localhost:3689/api/player/volume?volume=50&output_id=0\"\n
"},{"location":"json-api/#seek","title":"Seek","text":"

Seek to a position in the currently playing track.

Endpoint

PUT /api/player/seek\n

Query parameters

Parameter Value position_ms The new position in milliseconds to seek to seek_ms A relative amount of milliseconds to seek to

Response

On success returns the HTTP 204 No Content success status response code.

Example

Seek to position:

curl -X PUT \"http://localhost:3689/api/player/seek?position_ms=2000\"\n

Relative seeking (skip 30 seconds backwards):

curl -X PUT \"http://localhost:3689/api/player/seek?seek_ms=-30000\"\n
"},{"location":"json-api/#outputs-speakers","title":"Outputs / Speakers","text":"Method Endpoint Description GET /api/outputs Get a list of available outputs PUT /api/outputs/set Set enabled outputs GET /api/outputs/{id} Get an output PUT /api/outputs/{id} Change an output setting PUT /api/outputs/{id}/toggle Enable or disable an output, depending on the current state"},{"location":"json-api/#get-a-list-of-available-outputs","title":"Get a list of available outputs","text":"

Endpoint

GET /api/outputs\n

Response

Key Type Value outputs array Array of output objects

output object

Key Type Value id string Output id name string Output name type string Type of the output: AirPlay, Chromecast, ALSA, Pulseaudio, fifo selected boolean true if output is enabled has_password boolean true if output is password protected requires_auth boolean true if output requires authentication needs_auth_key boolean true if output requires an authorization key (device verification) volume integer Volume in percent (0 - 100)

Example

curl -X GET \"http://localhost:3689/api/outputs\"\n
{\n\"outputs\": [\n{\n\"id\": \"123456789012345\",\n\"name\": \"kitchen\",\n\"type\": \"AirPlay\",\n\"selected\": true,\n\"has_password\": false,\n\"requires_auth\": false,\n\"needs_auth_key\": false,\n\"volume\": 0\n},\n{\n\"id\": \"0\",\n\"name\": \"Computer\",\n\"type\": \"ALSA\",\n\"selected\": true,\n\"has_password\": false,\n\"requires_auth\": false,\n\"needs_auth_key\": false,\n\"volume\": 19\n},\n{\n\"id\": \"100\",\n\"name\": \"daapd-fifo\",\n\"type\": \"fifo\",\n\"selected\": false,\n\"has_password\": false,\n\"requires_auth\": false,\n\"needs_auth_key\": false,\n\"volume\": 0\n}\n]\n}\n
"},{"location":"json-api/#set-enabled-outputs","title":"Set enabled outputs","text":"

Set the enabled outputs by passing an array of output ids. The server enables all outputs with the given ids and disables the remaining outputs.

Endpoint

PUT /api/outputs/set\n

Body parameters

Parameter Type Value outputs array Array of output ids

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/outputs/set\" --data \"{\\\"outputs\\\":[\\\"198018693182577\\\",\\\"0\\\"]}\"\n
"},{"location":"json-api/#get-an-output","title":"Get an output","text":"

Get an output

Endpoint

GET /api/outputs/{id}\n

Path parameters

Parameter Value id Output id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the output object.

Example

curl -X GET \"http://localhost:3689/api/outputs/0\"\n
{\n\"id\": \"0\",\n\"name\": \"Computer\",\n\"type\": \"ALSA\",\n\"selected\": true,\n\"has_password\": false,\n\"requires_auth\": false,\n\"needs_auth_key\": false,\n\"volume\": 3\n}\n
"},{"location":"json-api/#change-an-output","title":"Change an output","text":"

Enable or disable an output and change its volume.

Endpoint

PUT /api/outputs/{id}\n

Path parameters

Parameter Value id Output id

Body parameters

Parameter Type Value selected boolean (Optional) true to enable and false to disable the output volume integer (Optional) Volume in percent (0 - 100) pin string (Optional) PIN for device verification

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/outputs/0\" --data \"{\\\"selected\\\":true, \\\"volume\\\": 50}\"\n
"},{"location":"json-api/#toggle-an-output","title":"Toggle an output","text":"

Enable or disable an output, depending on its current state

Endpoint

PUT /api/outputs/{id}/toggle\n

Path parameters

Parameter Value id Output id

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/outputs/0/toggle\"\n
"},{"location":"json-api/#queue","title":"Queue","text":"Method Endpoint Description GET /api/queue Get a list of queue items PUT /api/queue/clear Remove all items from the queue POST /api/queue/items/add Add items to the queue PUT /api/queue/items/{id}|now_playing Updating a queue item in the queue DELETE /api/queue/items/{id} Remove a queue item from the queue"},{"location":"json-api/#list-queue-items","title":"List queue items","text":"

Lists the items in the current queue

Endpoint

GET /api/queue\n

Query parameters

Parameter Value id (Optional) If a queue item id is given, only the item with the id will be returend. Use id=now_playing to get the currently playing item. start (Optional) If a startand an end position is given, only the items from start (included) to end (excluded) will be returned. If only a start position is given, only the item at this position will be returned. end (Optional) See start parameter

Response

Key Type Value version integer Version number of the current queue count integer Number of items in the current queue items array Array of queue item objects

Example

curl -X GET \"http://localhost:3689/api/queue\"\n
{\n\"version\": 833,\n\"count\": 20,\n\"items\": [\n{\n\"id\": 12122,\n\"position\": 0,\n\"track_id\": 10749,\n\"title\": \"Angels\",\n\"artist\": \"The xx\",\n\"artist_sort\": \"xx, The\",\n\"album\": \"Coexist\",\n\"album_sort\": \"Coexist\",\n\"albumartist\": \"The xx\",\n\"albumartist_sort\": \"xx, The\",\n\"genre\": \"Indie Rock\",\n\"year\": 2012,\n\"track_number\": 1,\n\"disc_number\": 1,\n\"length_ms\": 171735,\n\"media_kind\": \"music\",\n\"data_kind\": \"file\",\n\"path\": \"/music/srv/The xx/Coexist/01 Angels.mp3\",\n\"uri\": \"library:track:10749\"\n},\n...\n]\n}\n
"},{"location":"json-api/#clearing-the-queue","title":"Clearing the queue","text":"

Remove all items form the current queue

Endpoint

PUT /api/queue/clear\n

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/queue/clear\"\n
"},{"location":"json-api/#adding-items-to-the-queue","title":"Adding items to the queue","text":"

Add tracks, playlists artists or albums to the current queue

Endpoint

POST /api/queue/items/add\n

Query parameters

Parameter Value uris Comma seperated list of resource identifiers (track, playlist, artist or album object uri) expression A smart playlist query expression identifying the tracks that will be added to the queue. position (Optional) If a position is given, new items are inserted starting from this position into the queue. playback (Optional) If the playback parameter is set to start, playback will be started after adding the new items. playback_from_position (Optional) If the playback parameter is set to start, playback will be started with the queue item at the position given in playback_from_position. clear (Optional) If the clear parameter is set to true, the queue will be cleared before adding the new items. shuffle (Optional) If the shuffle parameter is set to true, the shuffle mode is activated. If it is set to something else, the shuffle mode is deactivated. To leave the shuffle mode untouched the parameter should be ommited. limit (Optional) Maximum number of tracks to add

Either the uris or the expression parameter must be set. If both are set the uris parameter takes presedence and the expression parameter will be ignored.

Response

On success returns the HTTP 200 OK success status response code.

Key Type Value count integer number of tracks added to the queue

Example

Add new items by uri:

curl -X POST \"http://localhost:3689/api/queue/items/add?uris=library:playlist:68,library:artist:2932599850102967727\"\n
{\n\"count\": 42\n}\n

Add new items by query language:

curl -X POST \"http://localhost:3689/api/queue/items/add?expression=media_kind+is+music\"\n
{\n\"count\": 42\n}\n

Clear current queue, add 10 new random tracks of genre Pop and start playback 

curl -X POST \"http://localhost:3689/api/queue/items/add?limit=10&clear=true&playback=start&expression=genre+is+%22Pop%22+order+by+random+desc\"\n

{\n\"count\": 10\n}\n
"},{"location":"json-api/#updating-a-queue-item","title":"Updating a queue item","text":"

Update or move a queue item in the current queue

Endpoint

PUT /api/queue/items/{id}\n
or 
PUT /api/queue/items/now_playing\n

Path parameters

Parameter Value id Queue item id

(or use now_playing to update the currenly playing track)

Query parameters

Parameter Value new_position The new position for the queue item in the current queue. title New track title album New album title artist New artist album_artist New album artist composer New composer genre New genre artwork_url New URL to track artwork

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/queue/items/3?new_position=0\"\n
curl -X PUT \"http://localhost:3689/api/queue/items/3?title=Awesome%20title&artwork_url=http%3A%2F%2Fgyfgafguf.dk%2Fimages%2Fpige3.jpg\"\n
curl -X PUT \"http://localhost:3689/api/queue/items/now_playing?title=Awesome%20title&artwork_url=http%3A%2F%2Fgyfgafguf.dk%2Fimages%2Fpige3.jpg\"\n
"},{"location":"json-api/#removing-a-queue-item","title":"Removing a queue item","text":"

Remove a queue item from the current queue

Endpoint

DELETE /api/queue/items/{id}\n

Path parameters

Parameter Value id Queue item id

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/queue/items/2\"\n
"},{"location":"json-api/#library","title":"Library","text":"Method Endpoint Description GET /api/library Get library information GET /api/library/playlists Get a list of playlists GET /api/library/playlists/{id} Get a playlist PUT /api/library/playlists/{id} Update a playlist attribute DELETE /api/library/playlists/{id} Delete a playlist GET /api/library/playlists/{id}/tracks Get list of tracks for a playlist PUT /api/library/playlists/{id}/tracks Update play count of tracks for a playlist GET /api/library/playlists/{id}/playlists Get list of playlists for a playlist folder GET /api/library/artists Get a list of artists GET /api/library/artists/{id} Get an artist GET /api/library/artists/{id}/albums Get list of albums for an artist GET /api/library/albums Get a list of albums GET /api/library/albums/{id} Get an album GET /api/library/albums/{id}/tracks Get list of tracks for an album GET /api/library/tracks/{id} Get a track GET /api/library/tracks/{id}/playlists Get list of playlists for a track PUT /api/library/tracks Update multiple track properties PUT /api/library/tracks/{id} Update single track properties GET /api/library/genres Get list of genres GET /api/library/count Get count of tracks, artists and albums GET /api/library/files Get list of directories in the local library POST /api/library/add Add an item to the library PUT /api/update Trigger a library rescan PUT /api/rescan Trigger a library metadata rescan PUT /api/library/backup Request library backup db"},{"location":"json-api/#library-information","title":"Library information","text":"

List some library stats

Endpoint

GET /api/library\n

Response

Key Type Value songs integer Array of playlist objects db_playtime integer Total playtime of all songs in the library artists integer Number of album artists in the library albums integer Number of albums in the library started_at string Server startup time (timestamp in ISO 8601 format) updated_at string Last library update (timestamp in ISO 8601 format) updating boolean true if library rescan is in progress

Example

curl -X GET \"http://localhost:3689/api/library\"\n
{\n\"songs\": 217,\n\"db_playtime\": 66811,\n\"artists\": 9,\n\"albums\": 19,\n\"started_at\": \"2018-11-19T19:06:08Z\",\n\"updated_at\": \"2018-11-19T19:06:16Z\",\n\"updating\": false\n}\n
"},{"location":"json-api/#list-playlists","title":"List playlists","text":"

Lists all playlists in your library (does not return playlist folders)

Endpoint

GET /api/library/playlists\n

Query parameters

Parameter Value offset (Optional) Offset of the first playlist to return limit (Optional) Maximum number of playlists to return

Response

Key Type Value items array Array of playlist objects total integer Total number of playlists in the library offset integer Requested offset of the first playlist limit integer Requested maximum number of playlists

Example

curl -X GET \"http://localhost:3689/api/library/playlists\"\n
{\n\"items\": [\n{\n\"id\": 1,\n\"name\": \"radio\",\n\"path\": \"/music/srv/radio.m3u\",\n\"smart_playlist\": false,\n\"uri\": \"library:playlist:1\"\n},\n...\n],\n\"total\": 20,\n\"offset\": 0,\n\"limit\": -1\n}\n
"},{"location":"json-api/#get-a-playlist","title":"Get a playlist","text":"

Get a specific playlists in your library

Endpoint

GET /api/library/playlists/{id}\n

Path parameters

Parameter Value id Playlist id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the playlist object.

Example

curl -X GET \"http://localhost:3689/api/library/playlists/1\"\n
{\n\"id\": 1,\n\"name\": \"radio\",\n\"path\": \"/music/srv/radio.m3u\",\n\"smart_playlist\": false,\n\"uri\": \"library:playlist:1\"\n}\n
"},{"location":"json-api/#update-a-playlist","title":"Update a playlist","text":"

Update attributes of a specific playlists in your library

Endpoint

PUT /api/library/playlists/{id}\n

Path parameters

Parameter Value id Playlist id

Query parameters

Parameter Value query_limit For RSS feeds, this sets how many podcasts to retrieve

Example

curl -X PUT \"http://localhost:3689/api/library/playlists/25?query_limit=20\"\n
"},{"location":"json-api/#delete-a-playlist","title":"Delete a playlist","text":"

Delete a playlist, e.g. a RSS feed

Endpoint

DELETE /api/library/playlists/{id}\n

Path parameters

Parameter Value id Playlist id

Example

curl -X DELETE \"http://localhost:3689/api/library/playlists/25\"\n
"},{"location":"json-api/#list-playlist-tracks","title":"List playlist tracks","text":"

Lists the tracks in a playlists

Endpoint

GET /api/library/playlists/{id}/tracks\n

Path parameters

Parameter Value id Playlist id

Query parameters

Parameter Value offset (Optional) Offset of the first track to return limit (Optional) Maximum number of tracks to return

Response

Key Type Value items array Array of track objects total integer Total number of tracks in the playlist offset integer Requested offset of the first track limit integer Requested maximum number of tracks

Example

curl -X GET \"http://localhost:3689/api/library/playlists/1/tracks\"\n
{\n\"items\": [\n{\n\"id\": 10766,\n\"title\": \"Solange wir tanzen\",\n\"artist\": \"Heinrich\",\n\"artist_sort\": \"Heinrich\",\n\"album\": \"Solange wir tanzen\",\n\"album_sort\": \"Solange wir tanzen\",\n\"albumartist\": \"Heinrich\",\n\"albumartist_sort\": \"Heinrich\",\n\"genre\": \"Electronica\",\n\"year\": 2014,\n\"track_number\": 1,\n\"disc_number\": 1,\n\"length_ms\": 223085,\n\"play_count\": 2,\n\"skip_count\": 1,\n\"time_played\": \"2018-02-23T10:31:20Z\",\n\"media_kind\": \"music\",\n\"data_kind\": \"file\",\n\"path\": \"/music/srv/Heinrich/Solange wir tanzen/01 Solange wir tanzen.mp3\",\n\"uri\": \"library:track:10766\"\n},\n...\n],\n\"total\": 20,\n\"offset\": 0,\n\"limit\": -1\n}\n
"},{"location":"json-api/#update-playlist-tracks","title":"Update playlist tracks","text":"

Updates the play count for tracks in a playlists

Endpoint

PUT /api/library/playlists/{id}/tracks\n

Path parameters

Parameter Value id Playlist id

Query parameters

Parameter Value play_count Either increment, played or reset. increment will increment play_count and update time_played, played will be like increment but only where play_count is 0, reset will set play_count and skip_count to zero and delete time_played and time_skipped

Example

curl -X PUT \"http://localhost:3689/api/library/playlists/1/tracks?play_count=played\"\n
"},{"location":"json-api/#list-playlists-in-a-playlist-folder","title":"List playlists in a playlist folder","text":"

Lists the playlists in a playlist folder

Note: The root playlist folder has id 0.

Endpoint

GET /api/library/playlists/{id}/playlists\n

Path parameters

Parameter Value id Playlist id

Query parameters

Parameter Value offset (Optional) Offset of the first playlist to return limit (Optional) Maximum number of playlist to return

Response

Key Type Value items array Array of playlist objects total integer Total number of playlists in the playlist folder offset integer Requested offset of the first playlist limit integer Requested maximum number of playlist

Example

curl -X GET \"http://localhost:3689/api/library/playlists/0/tracks\"\n
{\n\"items\": [\n{\n\"id\": 11,\n\"name\": \"Spotify\",\n\"path\": \"spotify:playlistfolder\",\n\"parent_id\": \"0\",\n\"smart_playlist\": false,\n\"folder\": true,\n\"uri\": \"library:playlist:11\"\n},\n{\n\"id\": 8,\n\"name\": \"bytefm\",\n\"path\": \"/srv/music/Playlists/bytefm.m3u\",\n\"parent_id\": \"0\",\n\"smart_playlist\": false,\n\"folder\": false,\n\"uri\": \"library:playlist:8\"\n}\n],\n\"total\": 2,\n\"offset\": 0,\n\"limit\": -1\n}\n
"},{"location":"json-api/#list-artists","title":"List artists","text":"

Lists the artists in your library

Endpoint

GET /api/library/artists\n

Query parameters

Parameter Value offset (Optional) Offset of the first artist to return limit (Optional) Maximum number of artists to return

Response

Key Type Value items array Array of artist objects total integer Total number of artists in the library offset integer Requested offset of the first artist limit integer Requested maximum number of artists

Example

curl -X GET \"http://localhost:3689/api/library/artists\"\n
{\n\"items\": [\n{\n\"id\": \"3815427709949443149\",\n\"name\": \"ABAY\",\n\"name_sort\": \"ABAY\",\n\"album_count\": 1,\n\"track_count\": 10,\n\"length_ms\": 2951554,\n\"uri\": \"library:artist:3815427709949443149\"\n},\n...\n],\n\"total\": 20,\n\"offset\": 0,\n\"limit\": -1\n}\n
"},{"location":"json-api/#get-an-artist","title":"Get an artist","text":"

Get a specific artist in your library

Endpoint

GET /api/library/artists/{id}\n

Path parameters

Parameter Value id Artist id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the artist object.

Example

curl -X GET \"http://localhost:3689/api/library/artists/3815427709949443149\"\n
{\n\"id\": \"3815427709949443149\",\n\"name\": \"ABAY\",\n\"name_sort\": \"ABAY\",\n\"album_count\": 1,\n\"track_count\": 10,\n\"length_ms\": 2951554,\n\"uri\": \"library:artist:3815427709949443149\"\n}\n
"},{"location":"json-api/#list-artist-albums","title":"List artist albums","text":"

Lists the albums of an artist

Endpoint

GET /api/library/artists/{id}/albums\n

Path parameters

Parameter Value id Artist id

Query parameters

Parameter Value offset (Optional) Offset of the first album to return limit (Optional) Maximum number of albums to return

Response

Key Type Value items array Array of album objects total integer Total number of albums of this artist offset integer Requested offset of the first album limit integer Requested maximum number of albums

Example

curl -X GET \"http://localhost:3689/api/library/artists/32561671101664759/albums\"\n
{\n\"items\": [\n{\n\"id\": \"8009851123233197743\",\n\"name\": \"Add Violence\",\n\"name_sort\": \"Add Violence\",\n\"artist\": \"Nine Inch Nails\",\n\"artist_id\": \"32561671101664759\",\n\"track_count\": 5,\n\"length_ms\": 1634961,\n\"uri\": \"library:album:8009851123233197743\"\n},\n...\n],\n\"total\": 20,\n\"offset\": 0,\n\"limit\": -1\n}\n
"},{"location":"json-api/#list-albums","title":"List albums","text":"

Lists the albums in your library

Endpoint

GET /api/library/albums\n

Query parameters

Parameter Value offset (Optional) Offset of the first album to return limit (Optional) Maximum number of albums to return

Response

Key Type Value items array Array of album objects total integer Total number of albums in the library offset integer Requested offset of the first albums limit integer Requested maximum number of albums

Example

curl -X GET \"http://localhost:3689/api/library/albums\"\n
{\n\"items\": [\n{\n\"id\": \"8009851123233197743\",\n\"name\": \"Add Violence\",\n\"name_sort\": \"Add Violence\",\n\"artist\": \"Nine Inch Nails\",\n\"artist_id\": \"32561671101664759\",\n\"track_count\": 5,\n\"length_ms\": 1634961,\n\"uri\": \"library:album:8009851123233197743\"\n},\n...\n],\n\"total\": 20,\n\"offset\": 0,\n\"limit\": -1\n}\n
"},{"location":"json-api/#get-an-album","title":"Get an album","text":"

Get a specific album in your library

Endpoint

GET /api/library/albums/{id}\n

Path parameters

Parameter Value id Album id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the album object.

Example

curl -X GET \"http://localhost:3689/api/library/albums/8009851123233197743\"\n
{\n\"id\": \"8009851123233197743\",\n\"name\": \"Add Violence\",\n\"name_sort\": \"Add Violence\",\n\"artist\": \"Nine Inch Nails\",\n\"artist_id\": \"32561671101664759\",\n\"track_count\": 5,\n\"length_ms\": 1634961,\n\"uri\": \"library:album:8009851123233197743\"\n}\n
"},{"location":"json-api/#list-album-tracks","title":"List album tracks","text":"

Lists the tracks in an album

Endpoint

GET /api/library/albums/{id}/tracks\n

Path parameters

Parameter Value id Album id

Query parameters

Parameter Value offset (Optional) Offset of the first track to return limit (Optional) Maximum number of tracks to return

Response

Key Type Value items array Array of track objects total integer Total number of tracks offset integer Requested offset of the first track limit integer Requested maximum number of tracks

Example

curl -X GET \"http://localhost:3689/api/library/albums/1/tracks\"\n
{\n\"items\": [\n{\n\"id\": 10766,\n\"title\": \"Solange wir tanzen\",\n\"artist\": \"Heinrich\",\n\"artist_sort\": \"Heinrich\",\n\"album\": \"Solange wir tanzen\",\n\"album_sort\": \"Solange wir tanzen\",\n\"albumartist\": \"Heinrich\",\n\"albumartist_sort\": \"Heinrich\",\n\"genre\": \"Electronica\",\n\"year\": 2014,\n\"track_number\": 1,\n\"disc_number\": 1,\n\"length_ms\": 223085,\n\"play_count\": 2,\n\"last_time_played\": \"2018-02-23T10:31:20Z\",\n\"media_kind\": \"music\",\n\"data_kind\": \"file\",\n\"path\": \"/music/srv/Heinrich/Solange wir tanzen/01 Solange wir tanzen.mp3\",\n\"uri\": \"library:track:10766\"\n},\n...\n],\n\"total\": 20,\n\"offset\": 0,\n\"limit\": -1\n}\n
"},{"location":"json-api/#get-a-track","title":"Get a track","text":"

Get a specific track in your library

Endpoint

GET /api/library/tracks/{id}\n

Path parameters

Parameter Value id Track id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the track object.

Example

curl -X GET \"http://localhost:3689/api/library/tracks/1\"\n
{\n\"id\": 1,\n\"title\": \"Pardon Me\",\n\"title_sort\": \"Pardon Me\",\n\"artist\": \"Incubus\",\n\"artist_sort\": \"Incubus\",\n\"album\": \"Make Yourself\",\n\"album_sort\": \"Make Yourself\",\n\"album_id\": \"6683985628074308431\",\n\"album_artist\": \"Incubus\",\n\"album_artist_sort\": \"Incubus\",\n\"album_artist_id\": \"4833612337650426236\",\n\"composer\": \"Alex Katunich/Brandon Boyd/Chris Kilmore/Jose Antonio Pasillas II/Mike Einziger\",\n\"genre\": \"Alternative Rock\",\n\"year\": 2001,\n\"track_number\": 12,\n\"disc_number\": 1,\n\"length_ms\": 223170,\n\"rating\": 0,\n\"usermark\": 0,\n\"play_count\": 0,\n\"skip_count\": 0,\n\"time_added\": \"2019-01-20T11:58:29Z\",\n\"date_released\": \"2001-05-27\",\n\"seek_ms\": 0,\n\"media_kind\": \"music\",\n\"data_kind\": \"file\",\n\"path\": \"/music/srv/Incubus/Make Yourself/12 Pardon Me.mp3\",\n\"uri\": \"library:track:1\",\n\"artwork_url\": \"/artwork/item/1\"\n}\n
"},{"location":"json-api/#list-playlists-for-a-track","title":"List playlists for a track","text":"

Get the list of playlists that contain a track (does not return smart playlists)

Endpoint

GET /api/library/tracks/{id}/playlists\n

Path parameters

Parameter Value id Track id

Query parameters

Parameter Value offset (Optional) Offset of the first playlist to return limit (Optional) Maximum number of playlist to return

Response

Key Type Value items array Array of playlist objects total integer Total number of playlists offset integer Requested offset of the first playlist limit integer Requested maximum number of playlists

Example

curl -X GET \"http://localhost:3689/api/library/tracks/27/playlists\"\n
{\n\"items\": [\n{\n\"id\": 1,\n\"name\": \"playlist\",\n\"path\": \"/music/srv/playlist.m3u\",\n\"smart_playlist\": false,\n\"uri\": \"library:playlist:1\"\n},\n...\n],\n\"total\": 2,\n\"offset\": 0,\n\"limit\": -1\n}\n
"},{"location":"json-api/#update-track-properties","title":"Update track properties","text":"

Change properties of one or more tracks (supported properties are \"rating\", \"play_count\" and \"usermark\")

Endpoint

PUT /api/library/tracks\n

Body parameters

Parameter Type Value tracks array Array of track objects

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT -d '{ \"tracks\": [ { \"id\": 1, \"rating\": 100, \"usermark\": 4 }, { \"id\": 2, \"usermark\": 3 } ] }' \"http://localhost:3689/api/library/tracks\"\n

Endpoint

PUT /api/library/tracks/{id}\n

Path parameters

Parameter Value id Track id

Query parameters

Parameter Value rating The new rating (0 - 100) play_count Either increment or reset. increment will increment play_count and update time_played, reset will set play_count and skip_count to zero and delete time_played and time_skipped usermark The new usermark (>= 0)

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/library/tracks/1?rating=100\"\n
curl -X PUT \"http://localhost:3689/api/library/tracks/1?play_count=increment\"\n
"},{"location":"json-api/#list-genres","title":"List genres","text":"

Get list of genres

Endpoint

GET /api/library/genres\n
Response

Key Type Value items array Array of browse-info objects total integer Total number of genres in the library offset integer Requested offset of the first genre limit integer Requested maximum number of genres

Example

curl -X GET \"http://localhost:3689/api/library/genres\"\n
{\n\"items\": [\n{\n\"name\": \"Classical\"\n},\n{\n\"name\": \"Drum & Bass\"\n},\n{\n\"name\": \"Pop\"\n},\n{\n\"name\": \"Rock/Pop\"\n},\n{\n\"name\": \"'90s Alternative\"\n}\n],\n\"total\": 5,\n\"offset\": 0,\n\"limit\": -1\n}\n
"},{"location":"json-api/#list-albums-for-genre","title":"List albums for genre","text":"

Lists the albums in a genre

Endpoint

GET api/search?type=albums&expression=genre+is+\\\"{genre name}\\\"\"\n

Query parameters

Parameter Value genre genre name (uri encoded and html esc seq for chars: '/&) offset (Optional) Offset of the first album to return limit (Optional) Maximum number of albums to return

Response

Key Type Value items array Array of album objects total integer Total number of albums in the library offset integer Requested offset of the first albums limit integer Requested maximum number of albums

Example

curl -X GET \"http://localhost:3689/api/search?type=albums&expression=genre+is+\\\"Pop\\\"\"\ncurl -X GET \"http://localhost:3689/api/search?type=albums&expression=genre+is+\\\"Rock%2FPop\\\"\"            # Rock/Pop\ncurl -X GET \"http://localhost:3689/api/search?type=albums&expression=genre+is+\\\"Drum%20%26%20Bass\\\"\"     # Drum & Bass\ncurl -X GET \"http://localhost:3689/api/search?type=albums&expression=genre+is+\\\"%2790s%20Alternative\\\"\"  # '90 Alternative\n
{\n\"albums\": {\n\"items\": [\n{\n\"id\": \"320189328729146437\",\n\"name\": \"Best Ever\",\n\"name_sort\": \"Best Ever\",\n\"artist\": \"ABC\",\n\"artist_id\": \"8760559201889050080\",\n\"track_count\": 1,\n\"length_ms\": 3631,\n\"uri\": \"library:album:320189328729146437\"\n},\n{\n\"id\": \"7964595866631625723\",\n\"name\": \"Greatest Hits\",\n\"name_sort\": \"Greatest Hits\",\n\"artist\": \"Marvin Gaye\",\n\"artist_id\": \"5261930703203735930\",\n\"track_count\": 2,\n\"length_ms\": 7262,\n\"uri\": \"library:album:7964595866631625723\"\n},\n{\n\"id\": \"3844610748145176456\",\n\"name\": \"The Very Best of Etta\",\n\"name_sort\": \"Very Best of Etta\",\n\"artist\": \"Etta James\",\n\"artist_id\": \"2627182178555864595\",\n\"track_count\": 1,\n\"length_ms\": 177926,\n\"uri\": \"library:album:3844610748145176456\"\n}\n],\n\"total\": 3,\n\"offset\": 0,\n\"limit\": -1\n}\n}\n
"},{"location":"json-api/#get-count-of-tracks-artists-and-albums","title":"Get count of tracks, artists and albums","text":"

Get information about the number of tracks, artists and albums and the total playtime

Endpoint

GET /api/library/count\n

Query parameters

Parameter Value expression (Optional) The smart playlist query expression, if this parameter is omitted returns the information for the whole library

Response

Key Type Value tracks integer Number of tracks matching the expression artists integer Number of artists matching the expression albums integer Number of albums matching the expression db_playtime integer Total playtime in milliseconds of all tracks matching the expression

Example

curl -X GET \"http://localhost:3689/api/library/count?expression=data_kind+is+file\"\n
{\n\"tracks\": 6811,\n\"artists\": 355,\n\"albums\": 646,\n\"db_playtime\": 1590767\n}\n
"},{"location":"json-api/#list-local-directories","title":"List local directories","text":"

List the local directories and the directory contents (tracks and playlists)

Endpoint

GET /api/library/files\n

Query parameters

Parameter Value directory (Optional) A path to a directory in your local library.

Response

Key Type Value directories array Array of directory objects containing the sub directories tracks object paging object containing track objects that matches the directory playlists object paging object containing playlist objects that matches the directory

Example

curl -X GET \"http://localhost:3689/api/library/files?directory=/music/srv\"\n
{\n\"directories\": [\n{\n\"path\": \"/music/srv/Audiobooks\"\n},\n{\n\"path\": \"/music/srv/Music\"\n},\n{\n\"path\": \"/music/srv/Playlists\"\n},\n{\n\"path\": \"/music/srv/Podcasts\"\n}\n],\n\"tracks\": {\n\"items\": [\n{\n\"id\": 1,\n\"title\": \"input.pipe\",\n\"artist\": \"Unknown artist\",\n\"artist_sort\": \"Unknown artist\",\n\"album\": \"Unknown album\",\n\"album_sort\": \"Unknown album\",\n\"album_id\": \"4201163758598356043\",\n\"album_artist\": \"Unknown artist\",\n\"album_artist_sort\": \"Unknown artist\",\n\"album_artist_id\": \"4187901437947843388\",\n\"genre\": \"Unknown genre\",\n\"year\": 0,\n\"track_number\": 0,\n\"disc_number\": 0,\n\"length_ms\": 0,\n\"play_count\": 0,\n\"skip_count\": 0,\n\"time_added\": \"2018-11-24T08:41:35Z\",\n\"seek_ms\": 0,\n\"media_kind\": \"music\",\n\"data_kind\": \"pipe\",\n\"path\": \"/music/srv/input.pipe\",\n\"uri\": \"library:track:1\",\n\"artwork_url\": \"/artwork/item/1\"\n}\n],\n\"total\": 1,\n\"offset\": 0,\n\"limit\": -1\n},\n\"playlists\": {\n\"items\": [\n{\n\"id\": 8,\n\"name\": \"radio\",\n\"path\": \"/music/srv/radio.m3u\",\n\"smart_playlist\": true,\n\"uri\": \"library:playlist:8\"\n}\n],\n\"total\": 1,\n\"offset\": 0,\n\"limit\": -1\n}\n}\n
"},{"location":"json-api/#add-an-item-to-the-library","title":"Add an item to the library","text":"

This endpoint currently only supports addind RSS feeds.

Endpoint

POST /api/library/add\n

Query parameters

Parameter Value url URL of the RSS to add

Response

On success returns the HTTP 200 OK success status response code.

Example

curl -X POST \"http://localhost:3689/api/library/add?url=http%3A%2F%2Fmyurl.com%2Flink.rss\"\n
"},{"location":"json-api/#trigger-rescan","title":"Trigger rescan","text":"

Trigger a library rescan

Endpoint

PUT /api/update\n

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/update\"\n
{\n\"songs\": 217,\n\"db_playtime\": 66811,\n\"artists\": 9,\n\"albums\": 19,\n\"started_at\": \"2018-11-19T19:06:08Z\",\n\"updated_at\": \"2018-11-19T19:06:16Z\",\n\"updating\": false\n}\n
"},{"location":"json-api/#trigger-metadata-rescan","title":"Trigger metadata rescan","text":"

Trigger a library metadata rescan even if files have not been updated. Maintenence method.

Endpoint

PUT /api/rescan\n

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/rescan\"\n
"},{"location":"json-api/#backup-db","title":"Backup DB","text":"

Request a library backup - configuration must be enabled and point to a valid writable path. Maintenance method.

Endpoint

PUT /api/library/backup\n

Response

On success returns the HTTP 200 OK success status response code. If backups are not enabled returns HTTP 503 Service Unavailable response code. Otherwise a HTTP 500 Internal Server Error response is returned.

Example

curl -X PUT \"http://localhost:3689/api/library/backup\"\n
"},{"location":"json-api/#search","title":"Search","text":"Method Endpoint Description GET /api/search Search for playlists, artists, albums, tracks,genres by a simple search term GET /api/search Search by complex query expression"},{"location":"json-api/#search-by-search-term","title":"Search by search term","text":"

Search for playlists, artists, albums, tracks, genres that include the given query in their title (case insensitive matching).

Endpoint

GET /api/search\n

Query parameters

Parameter Value query The search keyword type Comma separated list of the result types (playlist, artist, album, track, genre) media_kind (Optional) Filter results by media kind (music, movie, podcast, audiobook, musicvideo, tvshow). Filter only applies to artist, album and track result types. offset (Optional) Offset of the first item to return for each type limit (Optional) Maximum number of items to return for each type

Response

Key Type Value tracks object paging object containing track objects that matches the query artists object paging object containing artist objects that matches the query albums object paging object containing album objects that matches the query playlists object paging object containing playlist objects that matches the query

Example

Search for all tracks, artists, albums and playlists that contain \"the\" in their title and return the first two results for each type:

curl -X GET \"http://localhost:3689/api/search?type=tracks,artists,albums,playlists&query=the&offset=0&limit=2\"\n
{\n\"tracks\": {\n\"items\": [\n{\n\"id\": 35,\n\"title\": \"Another Love\",\n\"artist\": \"Tom Odell\",\n\"artist_sort\": \"Tom Odell\",\n\"album\": \"Es is was es is\",\n\"album_sort\": \"Es is was es is\",\n\"album_id\": \"6494853621007413058\",\n\"album_artist\": \"Various artists\",\n\"album_artist_sort\": \"Various artists\",\n\"album_artist_id\": \"8395563705718003786\",\n\"genre\": \"Singer/Songwriter\",\n\"year\": 2013,\n\"track_number\": 7,\n\"disc_number\": 1,\n\"length_ms\": 251030,\n\"play_count\": 0,\n\"media_kind\": \"music\",\n\"data_kind\": \"file\",\n\"path\": \"/music/srv/Compilations/Es is was es is/07 Another Love.m4a\",\n\"uri\": \"library:track:35\"\n},\n{\n\"id\": 215,\n\"title\": \"Away From the Sun\",\n\"artist\": \"3 Doors Down\",\n\"artist_sort\": \"3 Doors Down\",\n\"album\": \"Away From the Sun\",\n\"album_sort\": \"Away From the Sun\",\n\"album_id\": \"8264078270267374619\",\n\"album_artist\": \"3 Doors Down\",\n\"album_artist_sort\": \"3 Doors Down\",\n\"album_artist_id\": \"5030128490104968038\",\n\"genre\": \"Rock\",\n\"year\": 2002,\n\"track_number\": 2,\n\"disc_number\": 1,\n\"length_ms\": 233278,\n\"play_count\": 0,\n\"media_kind\": \"music\",\n\"data_kind\": \"file\",\n\"path\": \"/music/srv/Away From the Sun/02 Away From the Sun.mp3\",\n\"uri\": \"library:track:215\"\n}\n],\n\"total\": 14,\n\"offset\": 0,\n\"limit\": 2\n},\n\"artists\": {\n\"items\": [\n{\n\"id\": \"8737690491750445895\",\n\"name\": \"The xx\",\n\"name_sort\": \"xx, The\",\n\"album_count\": 2,\n\"track_count\": 25,\n\"length_ms\": 5229196,\n\"uri\": \"library:artist:8737690491750445895\"\n}\n],\n\"total\": 1,\n\"offset\": 0,\n\"limit\": 2\n},\n\"albums\": {\n\"items\": [\n{\n\"id\": \"8264078270267374619\",\n\"name\": \"Away From the Sun\",\n\"name_sort\": \"Away From the Sun\",\n\"artist\": \"3 Doors Down\",\n\"artist_id\": \"5030128490104968038\",\n\"track_count\": 12,\n\"length_ms\": 2818174,\n\"uri\": \"library:album:8264078270267374619\"\n},\n{\n\"id\": \"6835720495312674468\",\n\"name\": \"The Better Life\",\n\"name_sort\": \"Better Life\",\n\"artist\": \"3 Doors Down\",\n\"artist_id\": \"5030128490104968038\",\n\"track_count\": 11,\n\"length_ms\": 2393332,\n\"uri\": \"library:album:6835720495312674468\"\n}\n],\n\"total\": 3,\n\"offset\": 0,\n\"limit\": 2\n},\n\"playlists\": {\n\"items\": [],\n\"total\": 0,\n\"offset\": 0,\n\"limit\": 2\n}\n}\n
"},{"location":"json-api/#search-by-query-language","title":"Search by query language","text":"

Search for artists, albums, tracks by a smart playlist query expression (see README_SMARTPL.md for the expression syntax).

Endpoint

GET /api/search\n

Query parameters

Parameter Value expression The smart playlist query expression type Comma separated list of the result types (artist, album, track offset (Optional) Offset of the first item to return for each type limit (Optional) Maximum number of items to return for each type

Response

Key Type Value tracks object paging object containing track objects that matches the query artists object paging object containing artist objects that matches the query albums object paging object containing album objects that matches the query

Example

Search for music tracks ordered descending by the time added to the library and limit result to 2 items:

curl -X GET \"http://localhost:3689/api/search?type=tracks&expression=media_kind+is+music+order+by+time_added+desc&offset=0&limit=2\"\n
"},{"location":"json-api/#server-info","title":"Server info","text":"Method Endpoint Description GET /api/config Get configuration information"},{"location":"json-api/#config","title":"Config","text":"

Endpoint

GET /api/config\n

Response

Key Type Value version string Server version websocket_port integer Port number for the websocket (or 0 if websocket is disabled) buildoptions array Array of strings indicating which features are supported by the server

Example

curl -X GET \"http://localhost:3689/api/config\"\n
{\n\"websocket_port\": 3688,\n\"version\": \"25.0\",\n\"buildoptions\": [\n\"ffmpeg\",\n\"iTunes XML\",\n\"Spotify\",\n\"LastFM\",\n\"MPD\",\n\"Device verification\",\n\"Websockets\",\n\"ALSA\"\n]\n}\n
"},{"location":"json-api/#settings","title":"Settings","text":"Method Endpoint Description GET /api/settings Get all available categories GET /api/settings/{category-name} Get all available options for a category GET /api/settings/{category-name}/{option-name} Get a single setting option PUT /api/settings/{category-name}/{option-name} Change the value of a setting option DELETE /api/settings/{category-name}/{option-name} Reset a setting option to its default"},{"location":"json-api/#list-categories","title":"List categories","text":"

List all settings categories with their options

Endpoint

GET /api/settings\n

Response

Key Type Value categories array Array of settings category objects

Example

curl -X GET \"http://localhost:3689/api/settings\"\n
{\n\"categories\": [\n{\n\"name\": \"webinterface\",\n\"options\": [\n{\n\"name\": \"show_composer_now_playing\",\n\"type\": 1,\n\"value\": true\n},\n{\n\"name\": \"show_composer_for_genre\",\n\"type\": 2,\n\"value\": \"classical\"\n}\n]\n}\n]\n}\n
"},{"location":"json-api/#get-a-category","title":"Get a category","text":"

Get a settings category with their options

Endpoint

GET /api/settings/{category-name}\n

Response

Returns a settings category object

Example

curl -X GET \"http://localhost:3689/api/settings/webinterface\"\n
{\n\"name\": \"webinterface\",\n\"options\": [\n{\n\"name\": \"show_composer_now_playing\",\n\"type\": 1,\n\"value\": true\n},\n{\n\"name\": \"show_composer_for_genre\",\n\"type\": 2,\n\"value\": \"classical\"\n}\n]\n}\n
"},{"location":"json-api/#get-an-option","title":"Get an option","text":"

Get a single settings option

Endpoint

GET /api/settings/{category-name}/{option-name}\n

Response

Returns a settings option object

Example

curl -X GET \"http://localhost:3689/api/settings/webinterface/show_composer_now_playing\"\n
{\n\"name\": \"show_composer_now_playing\",\n\"type\": 1,\n\"value\": true\n}\n
"},{"location":"json-api/#change-an-option-value","title":"Change an option value","text":"

Get a single settings option

Endpoint

PUT /api/settings/{category-name}/{option-name}\n

Request

Key Type Value name string Option name value (integer / boolean / string) New option value

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT \"http://localhost:3689/api/settings/webinterface/show_composer_now_playing\" --data \"{\\\"name\\\":\\\"show_composer_now_playing\\\",\\\"value\\\":true}\"\n
"},{"location":"json-api/#delete-an-option","title":"Delete an option","text":"

Delete a single settings option (thus resetting it to default)

Endpoint

DELETE /api/settings/{category-name}/{option-name}\n

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X DELETE \"http://localhost:3689/api/settings/webinterface/show_composer_now_playing\"\n
"},{"location":"json-api/#push-notifications","title":"Push notifications","text":"

If the server was built with websocket support it exposes a websocket at localhost:3688 to inform clients of changes (e. g. player state or library updates). The port depends on the server configuration and can be read using the /api/config endpoint.

After connecting to the websocket, the client should send a message containing the event types it is interested in. After that the server will send a message each time one of the events occurred.

Message

Key Type Value notify array Array of event types

Event types

Type Description update Library update started or finished database Library database changed (new/modified/deleted tracks) outputs An output was enabled or disabled player Player state changes options Playback option changes (shuffle, repeat, consume mode) volume Volume changes queue Queue changes

Example

curl --include \\\n--no-buffer \\\n--header \"Connection: Upgrade\" \\\n--header \"Upgrade: websocket\" \\\n--header \"Host: localhost:3688\" \\\n--header \"Origin: http://localhost:3688\" \\\n--header \"Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==\" \\\n--header \"Sec-WebSocket-Version: 13\" \\\n--header \"Sec-WebSocket-Protocol: notify\" \\\nhttp://localhost:3688/ \\\n--data \"{ \\\"notify\\\": [ \\\"player\\\" ] }\"\n
{ \"notify\": [\n\"player\"\n]\n}\n
"},{"location":"json-api/#object-model","title":"Object model","text":""},{"location":"json-api/#queue-item-object","title":"queue item object","text":"Key Type Value id string Item id position integer Position in the queue (starting with zero) track_id string Track id title string Title artist string Track artist name artist_sort string Track artist sort name album string Album name album_sort string Album sort name album_id string Album id album_artist string Album artist name album_artist_sort string Album artist sort name album_artist_id string Album artist id composer string Composer (optional) genre string Genre year integer Release year track_number integer Track number disc_number integer Disc number length_ms integer Track length in milliseconds media_kind string Media type of this track: music, movie, podcast, audiobook, musicvideo, tvshow data_kind string Data type of this track: file, url, spotify, pipe path string Path uri string Resource identifier artwork_url string (optional) Artwork url type string file (codec) type (ie mp3/flac/...) bitrate string file bitrate (ie 192/128/...) samplerate string file sample rate (ie 44100/48000/...) channel string file channel (ie mono/stereo/xx ch))"},{"location":"json-api/#playlist-object","title":"playlist object","text":"Key Type Value id string Playlist id name string Playlist name path string Path parent_id integer Playlist id of the parent (folder) playlist type string Type of this playlist: special, folder, smart, plain smart_playlist boolean true if playlist is a smart playlist folder boolean true if it is a playlist folder uri string Resource identifier"},{"location":"json-api/#artist-object","title":"artist object","text":"Key Type Value id string Artist id name string Artist name name_sort string Artist sort name album_count integer Number of albums track_count integer Number of tracks length_ms integer Total length of tracks in milliseconds uri string Resource identifier artwork_url string (optional) Artwork url"},{"location":"json-api/#album-object","title":"album object","text":"Key Type Value id string Album id name string Album name name_sort string Album sort name artist_id string Album artist id artist string Album artist name track_count integer Number of tracks length_ms integer Total length of tracks in milliseconds uri string Resource identifier artwork_url string (optional) Artwork url"},{"location":"json-api/#track-object","title":"track object","text":"Key Type Value id integer Track id title string Title title_sort string Sort title artist string Track artist name artist_sort string Track artist sort name album string Album name album_sort string Album sort name album_id string Album id album_artist string Album artist name album_artist_sort string Album artist sort name album_artist_id string Album artist id composer string Track composer genre string Genre comment string Comment year integer Release year track_number integer Track number disc_number integer Disc number length_ms integer Track length in milliseconds rating integer Track rating (ranges from 0 to 100) play_count integer How many times the track was played skip_count integer How many times the track was skipped time_played string Timestamp in ISO 8601 format time_skipped string Timestamp in ISO 8601 format time_added string Timestamp in ISO 8601 format date_released string Date in the format yyyy-mm-dd seek_ms integer Resume point in milliseconds (available only for podcasts and audiobooks) media_kind string Media type of this track: music, movie, podcast, audiobook, musicvideo, tvshow data_kind string Data type of this track: file, url, spotify, pipe path string Path uri string Resource identifier artwork_url string (optional) Artwork url usermark integer User review marking of track (ranges from 0)"},{"location":"json-api/#paging-object","title":"paging object","text":"Key Type Value items array Array of result objects total integer Total number of items offset integer Requested offset of the first item limit integer Requested maximum number of items"},{"location":"json-api/#browse-info-object","title":"browse-info object","text":"Key Type Value name string Name (depends on the type of the query) name_sort string Sort name artist_count integer Number of artists album_count integer Number of albums track_count integer Number of tracks time_played string Timestamp in ISO 8601 format time_added string Timestamp in ISO 8601 format"},{"location":"json-api/#directory-object","title":"directory object","text":"Key Type Value path string Directory path"},{"location":"json-api/#category-object","title":"category object","text":"Key Type Value name string Category name options array Array of option in this category"},{"location":"json-api/#option-object","title":"option object","text":"Key Type Value name string Option name type integer The type of the value for this option (0: integer, 1: boolean, 2: string) value (integer / boolean / string) Current value for this option"},{"location":"json-api/#artwork-urls","title":"Artwork urls","text":"

Artwork urls in queue item, artist, album and track objects can be either relative urls or absolute urls to the artwork image. Absolute artwork urls are pointing to external artwork images (e. g. for radio streams that provide artwork metadata), while relative artwork urls are served from the server.

It is possible to add the query parameters maxwidth and/or maxheight to relative artwork urls, in order to get a smaller image (the server only scales down never up).

Note that even if a relative artwork url attribute is present, it is not guaranteed to exist.

"},{"location":"library/","title":"Library","text":"

The library is scanned in bulk mode at startup, but the server will be available even while this scan is in progress. You can follow the progress of the scan in the log file or via the web interface. When the scan is complete you will see the log message: \"Bulk library scan completed in X sec\".

The very first scan will take longer than subsequent startup scans, since every file gets analyzed. At the following startups the server looks for changed files and only analyzis those.

Updates to the library are reflected in real time after the initial scan, so you do not need to manually start rescans. The directories are monitored for changes and rescanned on the fly. Note that if you have your library on a network mount then real time updating may not work. Read below about what to do in that case.

If you change any of the directory settings in the library section of the configuration file a rescan is required before the new setting will take effect. You can do this by using \"Update library\" from the web interface.

Symlinks are supported and dereferenced, but it is best to use them for directories only.

Files starting with . (dot) and _ (underscore) are ignored.

"},{"location":"library/#pipes-for-eg-multiroom-with-shairport-sync","title":"Pipes (for e.g. multiroom with Shairport-sync)","text":"

Some programs, like for instance Shairport-sync, can be configured to output audio to a named pipe. If this pipe is placed in the library, OwnTone will automatically detect that it is there, and when there is audio being written to it, playback of the audio will be autostarted (and stopped).

Using this feature, OwnTone can act as an AirPlay multiroom \"router\": You can have an AirPlay source (e.g. your iPhone) send audio Shairport-sync, which forwards it to OwnTone through the pipe, which then plays it on whatever speakers you have selected (through Remote).

The format of the audio being written to the pipe must be PCM16.

You can also start playback of pipes manually. You will find them in remotes listed under \"Unknown artist\" and \"Unknown album\". The track title will be the name of the pipe.

Shairport-sync can write metadata to a pipe, and OwnTone can read this. This requires that the metadata pipe has the same filename as the audio pipe plus a \".metadata\" suffix. Say Shairport-sync is configured to write audio to \"/foo/bar/pipe\", then the metadata pipe should be \"/foo/bar/pipe.metadata\".

"},{"location":"library/#libraries-on-network-mounts","title":"Libraries on network mounts","text":"

Most network filesharing protocols do not offer notifications when the library is changed. So that means OwnTone cannot update its database in real time. Instead you can schedule a cron job to update the database.

The first step in doing this is to add two entries to the 'directories' configuration item in owntone.conf:

  directories = { \"/some/local/dir\", \"/your/network/mount/library\" }\n

Now you can make a cron job that runs this command:

  touch /some/local/dir/trigger.init-rescan\n

When OwnTone detects a file with filename ending .init-rescan it will perform a bulk scan similar to the startup scan.

Alternatively, you can force a metadata scan of the library even if the files have not changed by creating a filename ending .meta-rescan.

"},{"location":"library/#supported-formats","title":"Supported formats","text":"

OwnTone should support pretty much all audio formats. It relies on libav (or ffmpeg) to extract metadata and decode the files on the fly when the client doesn't support the format.

Formats are attributed a code, so any new format will need to be explicitely added. Currently supported:

  • MPEG4: mp4a, mp4v
  • AAC: alac
  • MP3 (and friends): mpeg
  • FLAC: flac
  • OGG VORBIS: ogg
  • Musepack: mpc
  • WMA: wma (WMA Pro), wmal (WMA Lossless), wmav (WMA video)
  • AIFF: aif
  • WAV: wav
  • Monkey's audio: ape
"},{"location":"library/#troubleshooting-library-issues","title":"Troubleshooting library issues","text":"

If you place a file with the filename ending .full-rescan in your library, you can trigger a full rescan of your library. This will clear all music and playlists from OwnTone's database and initiate a fresh bulk scan. Pairing and speaker information will be kept. Only use this for troubleshooting, it is not necessary during normal operation.

"},{"location":"playlists/","title":"Playlists and internet radio","text":"

OwnTone supports M3U and PLS playlists. Just drop your playlist somewhere in your library with an .m3u or .pls extension and it will pick it up.

From the web interface, and some mpd clients, you can also create and modify playlists by saving the current queue. Click the \"Save\" button. Note that this requires that allow_modifying_stored_playlists is enabled in the configuration file, and that the server has write access to default_playlist_directory.

If the playlist contains an http URL it will be added as an internet radio station, and the URL will be probed for Shoutcast (ICY) metadata. If the radio station provides artwork, OwnTone will download it during playback and send it to any remotes or AirPlay devices requesting it.

Instead of downloading M3U's from your radio stations, you can also make an empty M3U file and insert links in it to the M3U's of your radio stations.

Radio streams can only be played by OwnTone, so that means they will not be available to play in DAAP clients like iTunes.

The server can import playlists from iTunes Music Library XML files. By default, metadata from our parsers is preferred over what's in the iTunes DB; use itunes_overrides = true if you prefer iTunes' metadata.

OwnTone has support for smart playlists. How to create a smart playlist is documented in Smart playlists.

If you're not satisfied with internet radio metadata that OwnTone shows, then you can read about tweaking it in Radio streams.

"},{"location":"smart-playlists/","title":"OwnTone smart playlists","text":"

To add a smart playlist to the server, create a new text file with a filename ending with .smartpl; the filename doesn't matter, only the .smartpl ending does. The file must be placed somewhere in your library folder.

"},{"location":"smart-playlists/#syntax","title":"Syntax","text":"

The contents of a smart playlist must follow the syntax:

\"Playlist Name\" { expression }\n

There is exactly one smart playlist allowed for a .smartpl file.

An expression consists of:

field-name operator operand\n

Where valid field-names (with their types) are:

  • artist (string)
  • album_artist (string)
  • album (string)
  • title (string)
  • genre (string)
  • composer (string)
  • comment (string)
  • path (string)
  • type (string)
  • grouping (string)
  • data_kind (enumeration)
  • media_kind (enumeration)
  • play_count (integer)
  • skip_count (integer)
  • rating (integer)
  • year (integer)
  • compilation (integer)
  • track (integer)
  • disc (integer)
  • time_added (date)
  • time_modified (date)
  • time_played (date)
  • time_skipped (date)
  • random (special)
  • file_size (integer)

Valid operators include:

  • is, includes, starts with, ends with (string)
  • >, <, <=, >=, = (int)
  • after, before (date)
  • is (enumeration)

The is operator must exactly match the field value, while the includes operator matches a substring. The starts with operator matches, if the value starts with the given prefix, and ends with matches the opposite. All these matches are case-insensitive.

Valid operands include:

  • \"string value\" (string)
  • integer (int)

Valid operands for the enumeration data_kind are:

  • file
  • url
  • spotify
  • pipe

Valid operands for the enumeration media_kind are:

  • music
  • movie
  • podcast
  • audiobook
  • tvshow

Multiple expressions can be anded or ored together, using the keywords OR and AND. The unary not operator is also supported using the keyword NOT.

It is possible to define the sort order and limit the number of items by adding an order clause and/or a limit clause after the last expression:

\"Playlist Name\" { expression ORDER BY field-name sort-direction LIMIT limit }\n

\"sort-direction\" is either ASC (ascending) or DESC (descending). \"limit\" is the maximum number of items.

There is additionally a special random field-name that can be used in conjunction with limit to select a random number of items based on current expression.

"},{"location":"smart-playlists/#examples","title":"Examples","text":"
\"techno\" {\n   genre includes \"techno\"\n   and artist includes \"zombie\"\n}\n

This would match songs by \"Rob Zombie\" or \"White Zombie\", as well as those with a genre of \"Techno-Industrial\" or \"Trance/Techno\", for example.

\"techno 2015\" {\n   genre includes \"techno\"\n   and artist includes \"zombie\"\n   and not genre includes \"industrial\"\n}\n

This would exclude e. g. songs with the genre \"Techno-Industrial\".

\"Local music\" {\n  data_kind is file\n  and media_kind is music\n}\n

This would match all songs added as files to the library that are not placed under the folders for podcasts, audiobooks.

\"Unplayed podcasts and audiobooks\" {\n  play_count = 0\n  and (media_kind is podcast or media_kind is audiobook)\n}\n

This would match any podcast and audiobook file that was never played.

\"Recently added music\" {\n  media_kind is music\n  order by time_added desc\n  limit 10\n}\n
This would match the last 10 music files added to the library.

\"Random 10 Rated Pop songs\" {\n  rating > 0 and\n  genre is \"Pop\" and\n  media_kind is music\n  order by random desc\n  limit 10\n}\n
This generates a random set of, maximum of 10, rated Pop music tracks every time the playlist is queried.

"},{"location":"smart-playlists/#date-operand-syntax","title":"Date operand syntax","text":"

One example of a valid date is a date in yyyy-mm-dd format:

\"Files added after January 1, 2004\" {\n  time_added after 2004-01-01\n}\n

There are also some special date keywords:

  • today, yesterday, this week, last week, last month, last year

These dates refer to the start of that period; today means 00:00hrs of today, this week means current Monday 00:00hrs, last week means the previous Monday 00:00hrs, last month is the first day of the previous month at 00:00hrs etc.

A valid date can also be made by applying an interval to a date. Intervals can be defined as days, weeks, months, years. As an example, a valid date might be:

3 weeks before today or 3 weeks ago

Examples:

\"Recently Added\" {\n    time_added after 2 weeks ago\n}\n

This matches all songs added in the last 2 weeks.

\"Recently played audiobooks\" {\n    time_played after last week\n    and media_kind is audiobook\n}\n

This matches all audiobooks played since the start of the last Monday 00:00AM.

All dates, except for YYYY-DD-HH, are relative to the day of when the server evaluates the smartpl query; time_added after today run on a Monday would match against items added since Monday 00:00hrs and evaluating the same smartpl on Friday would only match against added on Friday 00:00hrs.

Note that time_added after 4 weeks ago and time_added after last month are subtly different; the former is exactly 4 weeks ago (from today) whereas the latter is the first day of the previous month.

"},{"location":"smart-playlists/#differences-to-mt-daapd-smart-playlists","title":"Differences to mt-daapd smart playlists","text":"

The syntax is really close to the mt-daapd smart playlist syntax (see http://sourceforge.net/p/mt-daapd/code/HEAD/tree/tags/release-0.2.4.2/contrib/mt-daapd.playlist).

Even this documentation is based on the file linked above.

Some differences are:

  • only one smart playlist per file
  • the not operator must be placed before an expression and not before the operator
  • ||, &&, ! are not supported (use or, and, not)
  • comments are not supported
"},{"location":"advanced/multiple-instances/","title":"Running Multiple Instances","text":"

To run multiple instances of owntone on a server, you should copy /etc/owntone.conf to /etc/owntone-zone.conf (for each zone) and modify the following to be unique across all instances:

  • the three port settings (general -> websocket_port, library -> port, and mpd -> port)

  • the database paths (general -> db_path, db_backup_path, and db_cache_path)

  • the service name (library -> name).

  • you probably also want to disable local output (set audio -> type = \"disabled\").

Then run owntone -c /etc/owntone-zone.conf to run owntone with the new zone configuration.

Owntone has a systemd template which lets you run this automatically on systems that use systemd. You can start or enable the service for a zone by sudo systemctl start owntone@zone and check that it is running with sudo systemctl status owntone@zone. Use sudo systemctl enable ownton@zone to get the service to start on reboot.

"},{"location":"advanced/outputs-alsa/","title":"OwnTone and ALSA","text":"

ALSA is one of the main output configuration options for local audio; when using ALSA you will typically let the system select the soundcard on your machine as the default device/sound card - a mixer associated with the ALSA device is used for volume control. However if your machine has multiple sound cards and your system chooses the wrong playback device, you will need to manually select the card and mixer to complete the OwnTone configuration.

"},{"location":"advanced/outputs-alsa/#quick-introduction-to-alsa-devices","title":"Quick introduction to ALSA devices","text":"

ALSA devices can be addressed in a number ways but traditionally we have referred to them using the hardware prefix, card number and optionally device number with something like hw:0 or hw:0,1. In ALSA configuration terms card X, device Y is known as hw:X,Y.

ALSA has other prefixes for each card and most importantly plughw. The plughw performs transparent sample format and sample rate conversions and maybe a better choice for many users rather than hw: which would fail when provided unsupported audio formats/sample rates.

Alternative ALSA names can be used to refer to physical ALSA devices and can be useful in a number of ways:

  • more descriptive rather than being a card number
  • consistent for USB numeration - USB ALSA devices may not have the same card number across reboots/reconnects

The ALSA device information required for configuration the server can be deterined using aplay, as described in the rest of this document, but OwnTone can also assist; when configured to log at INFO level the following information is provided during startup:

laudio: Available ALSA playback mixer(s) on hw:0 CARD=Intel (HDA Intel): 'Master' 'Headphone' 'Speaker' 'PCM' 'Mic' 'Beep'\nlaudio: Available ALSA playback mixer(s) on hw:1 CARD=E30 (E30): 'E30 '\nlaudio: Available ALSA playback mixer(s) on hw:2 CARD=Seri (Plantronics Blackwire 3210 Seri): 'Sidetone' 'Headset'\n
The CARD= string is the alternate ALSA name for the device and can be used in place of the traditional hw:x name.

On this machine the server reports that it can see the onboard HDA Intel sound card and two additional sound cards: a Topping E30 DAC and a Plantronics Headset which are both USB devices. We can address the first ALSA device as hw:0 or hw:CARD=Intel or hw:Intel or plughw:Intel, the second ALSA device as hw:1 or hw:E30 and so forth. The latter 2 devices being on USB will mean that hw:1 may not always refer to hw:E30 and thus in such a case using the alternate name is useful.

"},{"location":"advanced/outputs-alsa/#configuring-the-server","title":"Configuring the server","text":"

OwnTone can support a single ALSA device or multiple ALSA devices.

# example audio section for server for a single soundcard\naudio {\n    nickname = \"Computer\"\n    type = \"alsa\"\n\n    card = \"hw:1\"           # defaults to 'default'\n    mixer = \"Analogue\"      # defaults to 'PCM' or 'Master'\n    mixer_device = \"hw:1\"   # defaults to same as 'card' value\n}\n

Multiple devices can be made available to OwnTone using seperate alsa { .. } sections.

audio {\n    type = \"alsa\"\n}\n\nalsa \"hw:1\" {\n    nickname = \"Computer\"\n    mixer = \"Analogue\"\n    mixer_device = \"hw:1\"\n}\n\nalsa \"hw:2\" {\n    nickname = \"Second ALSA device\"\n}\n

NB: When introducing alsa { .. } section(s) the ALSA specific configuration in the audio { .. } section will be ignored.

If there is only one sound card, verify if the default sound device is correct for playback, we will use the aplay utility.

# generate some audio if you don't have a wav file to hand\n$ sox -n -c 2 -r 44100 -b 16 -C 128 /tmp/sine441.wav synth 30 sin 500-100 fade h 0.2 30 0.2\n\n$ aplay -Ddefault /tmp/sine441.wav\n

If you can hear music played then you are good to use default for the server configuration. If you can not hear anything from the aplay firstly verify (using alsamixer) that the sound card is not muted. If the card is not muted AND there is no sound you can try the options below to determine the card and mixer for configuring the server.

"},{"location":"advanced/outputs-alsa/#automatically-determine-all-relevant-the-sound-card-information","title":"Automatically Determine ALL relevant the sound card information","text":"

As shown above, OwnTone can help, consider the information that logged:

laudio: Available ALSA playback mixer(s) on hw:0 CARD=Intel (HDA Intel): 'Master' 'Headphone' 'Speaker' 'PCM' 'Mic' 'Beep'\nlaudio: Available ALSA playback mixer(s) on hw:1 CARD=E30 (E30): 'E30 '\nlaudio: Available ALSA playback mixer(s) on hw:2 CARD=Seri (Plantronics Blackwire 3210 Seri): 'Sidetone' 'Headset'\n

Using the information above, we can see 3 soundcards that we could use with OwnTone with the first soundcard having a number of seperate mixer devices (volume control) for headphone and the interal speakers - we'll configure the server to use both these and also the E30 device. The server configuration for theese multiple outputs would be:

# using ALSA device alias where possible\n\nalsa \"hw:Intel\" {\n    nickname = \"Computer - Speaker\"\n    mixer = \"Speaker\"\n}\n\nalsa \"hw:Intel\" {\n    nickname = \"Computer - Headphones\"\n    mixer = \"Headphone\"\n}\n\nalsa \"plughw:E30\" {\n    # this E30 device only support S32_LE so we can use the 'plughw' prefix to\n    # add transparent conversion support of more common S16/S24_LE formats\n\n    nickname = \"E30 DAC\"\n    mixer = \"E30 \"\n    mixer_device = \"hw:E30\"\n}\n

NB: it is troublesome to use hw or plughw ALSA addressing when running OwnTone on a machine with pulseaudio and if you wish to use refer to ALSA devices directly that you stop pulseaudio.

"},{"location":"advanced/outputs-alsa/#manually-determining-the-sound-cards-you-have-alsa-can-see","title":"Manually Determining the sound cards you have / ALSA can see","text":"

The example below is how I determined the correct sound card and mixer values for a Raspberry Pi that has an additional DAC card (hat) mounted. Of course using the log output from the server would have given the same results.

Use aplay -l to list all the sound cards and their order as known to the system - you can have multiple card X, device Y entries; some cards can also have multiple playback devices such as the RPI's onboard soundcard which feeds both headphone (card 0, device 0) and HDMI (card 0, device 1).

$ aplay -l\n**** List of PLAYBACK Hardware Devices ****\ncard 0: ALSA [bcm2835 ALSA], device 0: bcm2835 ALSA [bcm2835 ALSA]\n  Subdevices: 6/7\n  Subdevice #0: subdevice #0\n  Subdevice #1: subdevice #1\n  Subdevice #2: subdevice #2\n  Subdevice #3: subdevice #3\n  Subdevice #4: subdevice #4\n  Subdevice #5: subdevice #5\n  Subdevice #6: subdevice #6\ncard 0: ALSA [bcm2835 ALSA], device 1: bcm2835 ALSA [bcm2835 IEC958/HDMI]\n  Subdevices: 1/1\n  Subdevice #0: subdevice #0\ncard 1: IQaudIODAC [IQaudIODAC], device 0: IQaudIO DAC HiFi pcm512x-hifi-0 []\n  Subdevices: 1/1\n  Subdevice #0: subdevice #0\n

On this machine we see the second sound card installed, an IQaudIODAC dac hat, and identified as card 1 device 0. This is the playback device we want to be used by the server.

hw:1,0 is the IQaudIODAC that we want to use - we verify audiable playback through that sound card using aplay -Dhw:1 /tmp/sine441.wav. If the card has only one device, we can simply refer to the sound card using hw:X so in this case where the IQaudIODAC only has one device, we can refer to this card as hw:1 or hw:1,0.

Use aplay -L to get more information about the PCM devices defined on the system.

$ aplay -L\nnull\n    Discard all samples (playback) or generate zero samples (capture)\ndefault:CARD=ALSA\n    bcm2835 ALSA, bcm2835 ALSA\n    Default Audio Device\nsysdefault:CARD=ALSA\n    bcm2835 ALSA, bcm2835 ALSA\n    Default Audio Device\ndmix:CARD=ALSA,DEV=0\n    bcm2835 ALSA, bcm2835 ALSA\n    Direct sample mixing device\ndmix:CARD=ALSA,DEV=1\n    bcm2835 ALSA, bcm2835 IEC958/HDMI\n    Direct sample mixing device\ndsnoop:CARD=ALSA,DEV=0\n    bcm2835 ALSA, bcm2835 ALSA\n    Direct sample snooping device\ndsnoop:CARD=ALSA,DEV=1\n    bcm2835 ALSA, bcm2835 IEC958/HDMI\n    Direct sample snooping device\nhw:CARD=ALSA,DEV=0\n    bcm2835 ALSA, bcm2835 ALSA\n    Direct hardware device without any conversions\nhw:CARD=ALSA,DEV=1\n    bcm2835 ALSA, bcm2835 IEC958/HDMI\n    Direct hardware device without any conversions\nplughw:CARD=ALSA,DEV=0\n    bcm2835 ALSA, bcm2835 ALSA\n    Hardware device with all software conversions\nplughw:CARD=ALSA,DEV=1\n    bcm2835 ALSA, bcm2835 IEC958/HDMI\n    Hardware device with all software conversions\ndefault:CARD=IQaudIODAC\n    IQaudIODAC, \n    Default Audio Device\nsysdefault:CARD=IQaudIODAC\n    IQaudIODAC, \n    Default Audio Device\ndmix:CARD=IQaudIODAC,DEV=0\n    IQaudIODAC, \n    Direct sample mixing device\ndsnoop:CARD=IQaudIODAC,DEV=0\n    IQaudIODAC, \n    Direct sample snooping device\nhw:CARD=IQaudIODAC,DEV=0\n    IQaudIODAC, \n    Direct hardware device without any conversions\nplughw:CARD=IQaudIODAC,DEV=0\n    IQaudIODAC, \n    Hardware device with all software conversions\n

For the server configuration, we will use:

audio {\n    nickname = \"Computer\"\n    type = \"alsa\"\n    card=\"hw:1\"\n    # mixer=TBD\n    # mixer_device=TBD\n}\n
"},{"location":"advanced/outputs-alsa/#mixer-name","title":"Mixer name","text":"

Once you have the card number (determined from aplay -l) we can inspect/confirm the name of the mixer that can be used for playback (it may NOT be PCM as expected by the server). In this example, the card 1 is of interest and thus we use -c 1 with the following command:

$ amixer -c 1 \nSimple mixer control 'DSP Program',0\n  Capabilities: enum\n  Items: 'FIR interpolation with de-emphasis' 'Low latency IIR with de-emphasis' 'High attenuation with de-emphasis' 'Fixed process flow' 'Ringing-less low latency FIR'\n  Item0: 'Ringing-less low latency FIR'\nSimple mixer control 'Analogue',0\n  Capabilities: pvolume\n  Playback channels: Front Left - Front Right\n  Limits: Playback 0 - 1\n  Mono:\n  Front Left: Playback 1 [100%] [0.00dB]\n  Front Right: Playback 1 [100%] [0.00dB]\nSimple mixer control 'Analogue Playback Boost',0\n  Capabilities: volume\n  Playback channels: Front Left - Front Right\n  Capture channels: Front Left - Front Right\n  Limits: 0 - 1\n  Front Left: 0 [0%] [0.00dB]\n  Front Right: 0 [0%] [0.00dB]\n...\n

This card has multiple controls but we want to find a mixer control listed with a pvolume (playback) capability - in this case that mixer value required for the server configuration is called Analogue.

For the server configuration, we will use:

audio {\n    nickname = \"Computer\"\n    type = \"alsa\"\n    card=\"hw:1\"\n    mixer=\"Analogue\"\n    # mixer_device=TBD\n}\n
"},{"location":"advanced/outputs-alsa/#mixer-device","title":"Mixer device","text":"

This is the name of the underlying physical device used for the mixer - it is typically the same value as the value of card in which case a value is not required by the server configuration. An example of when you want to change explicitly configure this is if you need to use a dmix device (see below).

"},{"location":"advanced/outputs-alsa/#handling-devices-that-cannot-concurrently-play-multiple-audio-streams","title":"Handling Devices that cannot concurrently play multiple audio streams","text":"

Some devices such as various RPI DAC boards (IQaudio DAC, Allo Boss DAC...) cannot have multiple streams openned at the same time/cannot play multiple sound files at the same time. This results in Device or resource busy errors. You can confirm if your sound card has this problem by using the example below once have determined the names/cards information as above.

Using our hw:1 device we try:

# generate some audio\n$ sox -n -c 2 -r 44100 -b 16 -C 128 /tmp/sine441.wav synth 30 sin 500-100 fade h 0.2 30 0.2\n\n# attempt to play 2 files at the same time\n$ aplay -v -Dhw:1 /tmp/sine441.wav &\nPlaying WAVE '/tmp/sine441.wav' : Signed 16 bit Little Endian, Rate 44100 Hz, Stereo\nHardware PCM card 1 'IQaudIODAC' device 0 subdevice 0\nIts setup is:\n  stream       : PLAYBACK\n  access       : RW_INTERLEAVED\n  format       : S16_LE\n  subformat    : STD\n  channels     : 2\n  rate         : 44100\n  exact rate   : 44100 (44100/1)\n  msbits       : 16\n  buffer_size  : 22052\n  period_size  : 5513\n  period_time  : 125011\n  tstamp_mode  : NONE\n  tstamp_type  : MONOTONIC\n  period_step  : 1\n  avail_min    : 5513\n  period_event : 0\n  start_threshold  : 22052\n  stop_threshold   : 22052\n  silence_threshold: 0\n  silence_size : 0\n  boundary     : 1445199872\n  appl_ptr     : 0\n  hw_ptr       : 0\n$ aplay -v -Dhw:1 /tmp/sine441.wav\naplay: main:788: audio open error: Device or resource busy\n

In this instance this device cannot open multiple streams - OwnTone can handle this situation transparently with some audio being truncated from the end of the current file as the server prepares to play the following track. If this handling is causing you problems you may wish to use ALSA's dmix functionally which provides a software mixing module. We will need to define a dmix component and configure the server to use that as it's sound card.

The downside to the dmix approach will be the need to fix a samplerate (48000 being the default) for this software mixing module meaning any files that have a mismatched samplerate will be resampled.

"},{"location":"advanced/outputs-alsa/#alsa-dmix-configurationsetup","title":"ALSA dmix configuration/setup","text":"

A dmix device can be defined in /etc/asound.conf or ~/.asoundrc for the same user running OwnTone. We will need to know the underlying physical soundcard to be used: in our examples above, hw:1,0 / card 1, device 0 representing our IQaudIODAC as per output of aplay -l. We also take the buffer_size and period_size from the output of playing a sound file via aplay -v.

# use 'dac' as the name of the device: \"aplay -Ddac ....\"\npcm.!dac {\n    type plug\n    slave.pcm \"dmixer\"\n    hint.description \"IQAudio DAC s/w dmix enabled device\"\n}\n\npcm.dmixer  {\n    type dmix\n    ipc_key 1024             # need to be uniq value\n    ipc_key_add_uid false    # multiple concurrent different users\n    ipc_perm 0666            # multi-user sharing permissions\n\n    slave {\n    pcm \"hw:1,0\"         # points at the underlying device - could also simply be hw:1\n    period_time 0\n    period_size 4096     # from the output of aplay -v\n    buffer_size 22052    # from the output of aplay -v\n    rate 44100           # locked in sample rate for resampling on dmix device\n    }\n    hint.description \"IQAudio DAC s/w dmix device\"\n}\n\nctl.dmixer {\n    type hw\n    card 1                  # underlying device\n    device 0\n}\n

Running aplay -L we will see our newly defined devices dac and dmixer

$ aplay -L\nnull\n    Discard all samples (playback) or generate zero samples (capture)\ndac\n    IQAudio DAC s/w dmix enabled device\ndmixer\n    IQAudio DAC s/w dmix device\ndefault:CARD=ALSA\n    bcm2835 ALSA, bcm2835 ALSA\n    Default Audio Device\n...\n

At this point we are able to rerun the concurrent aplay commands (adding -Ddac to specify the playback device to use) to verify ALSA configuration.

If there is only one card on the machine you may use pcm.!default instead of pcm.!dac - there is less configuration to be done later since many ALSA applications will use the device called default by default. Furthermore on RPI you can explicitly disable the onboard sound card to leave us with only the IQaudIODAC board enabled (won't affect HDMI sound output) by commenting out #dtparam=audio=on in /boot/config.txt and rebooting.

"},{"location":"advanced/outputs-alsa/#config-with-dmix","title":"Config with dmix","text":"

We will use the newly defined card named dac which uses the underlying hw:1 device as per /etc/asound.conf or ~/.asoundrc configuration. Note that the mixer_device is now required and must refer to the real device (see the slave.pcm value) and not the named device (ie dac) that we created and are using for the card configuration value.

For the final server configuration, we will use:

audio {\n    nickname = \"Computer\"\n    type = \"alsa\"\n    card=\"dac\"\n    mixer=\"Analogue\"\n    mixer_device=\"hw:1\"\n}\n
"},{"location":"advanced/outputs-alsa/#setting-up-an-audio-equalizer","title":"Setting up an Audio Equalizer","text":"

There exists an ALSA equalizer plugin. On debian (incl Raspberry Pi) systems you can install this plugin by apt install libasound2-plugin-equal; this is not currently available on Fedora (FC31) but can be easily built from source after installing the dependant ladspa package.

Once installed the user must setup a virtual device and use this device in the server configuration.

If you wish to use your hw:0 device for output:

# /etc/asound.conf\nctl.equal {\n  type equal;\n\n  # library /usr/lib64/ladspa/caps.so\n}\n\npcm.equal {\n  type plug;\n  slave.pcm {\n      type equal;\n\n      ## must be plughw:x,y and not hw:x,y\n      slave.pcm \"plughw:0,0\";\n\n      # library /usr/lib64/ladspa/caps.so\n  }\n  hint.description \"equalised device\"\n}\n

and in owntone.conf

alsa \"equal\" {\n    nickname = \"Equalised Output\"\n    # adjust accordingly for mixer with pvolume capability\n    mixer = \"PCM\"\n    mixer_device = \"hw:0\"\n}\n

Using the web UI and on the outputs selection you should see an output called Equalised Output which you should select and set the volume.

When starting playback for any audio tracks you should hopefully hear the output. In a terminal, run alsamixer -Dequal and you'll see the eqaliser - to test that this is all working, go and drop the upper frequencies and boosting the bass frequencies and give it a second - if this changes the sound profile from your speakers, well done, its done and you can adjust the equalizer as you desire.

Note however, the equalizer appears to require a plughw device which means you cannnot use this equalizer with a dmix output chain.

"},{"location":"advanced/outputs-alsa/#troubleshooting","title":"Troubleshooting","text":"
  • Errors in log Failed to open configured mixer element when selecting output device

  • Errors in log Invalid CTL or Failed to attach mixer when playing/adjusting volume

    mixer value is wrong. Verify name of mixer value in server config against the names from all devices capable of playback using amixer -c <card number>. Assume the device is card 1:

    (IFS=$'\\n'\n CARD=1\n for i in $(amixer -c ${CARD} scontrols | awk -F\\' '{ print $2 }'); do \n   amixer -c ${CARD} sget \"$i\" | grep Capabilities | grep -q pvolume && echo $i\n   done\n)\n

    Look at the names output and choose the one that fits. The outputs can be something like:

    # laptop\nMaster\nHeadphone\nSpeaker\nPCM\nMic\nBeep\n\n# RPI with no additional DAC, card = 0\nPCM\n\n# RPI with additional DAC hat (IQAudioDAC, using a pcm512x chip)\nAnalogue\nDigital\n

  • No sound during playback - valid mixer/verified by aplay

    Check that the mixer is not muted or volume set to 0. Using the value of mixer as per server config and unmute or set volume to max. Assume the device is card 1 and mixer = Analogue:

    amixer -c 1 set Analogue unmute  ## some mixers can not be muted resulting in \"invalid command\"\namixer -c 1 set Analogue 100%\n

    An example of a device with volume turned all the way down - notice the Playback values are 0[0%]`:

    Simple mixer control 'Analogue',0\nCapabilities: pvolume\nPlayback channels: Front Left - Front Right\nLimits: Playback 0 - 1\nMono:\nFront Left: Playback 0 [0%] [-6.00dB]\nFront Right: Playback 0 [0%] [-6.00dB]\n

  • Server stops playing after moving to new track in paly queue, Error in log Could not open playback device The log contains these log lines:

    [2019-06-19 20:52:51] [  LOG]   laudio: open '/dev/snd/pcmC0D0p' failed (-16)[2019-06-19 20:52:51] [  LOG]   laudio: Could not open playback device: Device or resource busy\n[2019-06-19 20:52:51] [  LOG]   laudio: Device 'hw' does not support quality (48000/16/2), falling back to default\n[2019-06-19 20:52:51] [  LOG]   laudio: open '/dev/snd/pcmC0D0p' failed (-16)[2019-06-19 20:52:51] [  LOG]   laudio: Could not open playback device: Device or resource busy\n[2019-06-19 20:52:51] [  LOG]   laudio: ALSA device failed setting fallback quality[2019-06-19 20:52:51] [  LOG]   player: The ALSA device 'Computer' FAILED\n

    If you have a RPI with a DAC hat with a pcm512x chip will affect you. This is because the server wants to open the audio device for the next audio track whilst current track is still playing but the hardware does not allow this - see the comments above regarding determining concurrrent playback.

    This error will occur for output hardware that do not support concurrent device open and the server plays 2 files of different bitrate (44.1khz and 48khz) back to back.

    If you observe the error, you will need to use the dmix configuration as mentioned above.

"},{"location":"advanced/outputs-pulse/","title":"OwnTone and Pulseaudio","text":"

You have the choice of running Pulseaudio either in system mode or user mode. For headless servers, i.e. systems without desktop users, system mode is recommended.

If there is a desktop user logged in most of the time, a setup with network access via localhost only for daemons is a more appropriate solution, since the normal user administration (with, e.g., pulseaudio -k) works as advertised. Also, the user specific configuration for pulseaudio is preserved across sessions as expected.

  • System mode
  • User mode
"},{"location":"advanced/outputs-pulse/#system-mode-with-bluetooth-support","title":"System Mode with Bluetooth support","text":"

Credit: Rob Pope

This guide was written based on headless Debian Jessie platforms. Most of the instructions will require that you are root.

"},{"location":"advanced/outputs-pulse/#step-1-setting-up-pulseaudio","title":"Step 1: Setting up Pulseaudio","text":"

If you see a \"Connection refused\" error when starting the server, then you will probably need to setup Pulseaudio to run in system mode [1]. This means that the Pulseaudio daemon will be started during boot and be available to all users.

How to start Pulseaudio depends on your distribution, but in many cases you will need to add a pulseaudio.service file to /etc/systemd/system with the following content:

# systemd service file for Pulseaudio running in system mode\n[Unit]\nDescription=Pulseaudio sound server\nBefore=sound.target\n\n[Service]\nExecStart=/usr/bin/pulseaudio --system --disallow-exit\n\n[Install]\nWantedBy=multi-user.target\n

If you want Bluetooth support, you must also configure Pulseaudio to load the Bluetooth module. First install it (Debian: apt install pulseaudio-module-bluetooth) and then add the following to /etc/pulse/system.pa:

#### Enable Bluetooth\n.ifexists module-bluetooth-discover.so\nload-module module-bluetooth-discover\n.endif\n

Now you need to make sure that Pulseaudio can communicate with the Bluetooth daemon through D-Bus. On Raspbian this is already enabled, and you can skip this step. Otherwise do one of the following:

  1. Add the pulse user to the bluetooth group: adduser pulse bluetooth
  2. Edit /etc/dbus-1/system.d/bluetooth.conf and change the policy for <policy context=\"default\"\\> to \"allow\"

Phew, almost done with Pulseaudio! Now you should:

  1. enable system mode on boot with systemctl enable pulseaudio
  2. reboot (or at least restart dbus and pulseaudio)
  3. check that the Bluetooth module is loaded with pactl list modules short
"},{"location":"advanced/outputs-pulse/#step-2-setting-up-the-server","title":"Step 2: Setting up the server","text":"

Add the user the server is running as (typically \"owntone\") to the \"pulse-access\" group:

adduser owntone pulse-access\n

Now (re)start the server.

"},{"location":"advanced/outputs-pulse/#step-3-adding-a-bluetooth-device","title":"Step 3: Adding a Bluetooth device","text":"

To connect with the device, run bluetoothctl and then:

power on\nagent on\nscan on\n**Note MAC address of BT Speaker**\npair [MAC address]\n**Type Pin if prompted**\ntrust [MAC address]\nconnect [MAC address]\n

Now the speaker should appear. You can also verify that Pulseaudio has detected the speaker with pactl list sinks short.

"},{"location":"advanced/outputs-pulse/#user-mode-with-network-access","title":"User Mode with Network Access","text":"

Credit: wolfmanx and this blog

"},{"location":"advanced/outputs-pulse/#step-1-copy-system-pulseaudio-configuration-to-the-users-home-directory","title":"Step 1: Copy system pulseaudio configuration to the users home directory","text":"
mkdir -p ~/.pulse\ncp /etc/pulse/default.pa ~/.pulse/\n
"},{"location":"advanced/outputs-pulse/#step-2-enable-tcp-access-from-localhost-only","title":"Step 2: Enable TCP access from localhost only","text":"

Edit the file ~/.pulse/default.pa , adding the following line at the end:

load-module module-native-protocol-tcp auth-ip-acl=127.0.0.1\n
"},{"location":"advanced/outputs-pulse/#step-3-restart-the-pulseaudio-deamon","title":"Step 3: Restart the pulseaudio deamon","text":"
pulseaudio -k\n# OR\npulseaudio -D\n
"},{"location":"advanced/outputs-pulse/#step-4-adjust-configuration-file","title":"Step 4: Adjust configuration file","text":"

In the audio section of /etc/owntone.conf, set server to localhost:

server = \"localhost\"\n

[1] Note that Pulseaudio will warn against system mode. However, in this use case it is actually the solution recommended by the Pulseaudio folks themselves.

"},{"location":"advanced/radio-streams/","title":"OwnTone and Radio Stream tweaking","text":"

Radio streams have many different ways in how metadata is sent. Many should just work as expected, but a few may require some tweaking. If you are not seeing expected title, track, artist, artwork in clients or web UI, the following may help.

First, understand what and how the particular stream is sending information. ffprobe is a command that can be used to interegrate most of the stream information. ffprobe <http://stream.url> should give you some useful output, look at the Metadata section, below is an example.

 Metadata:\n    icy-br          : 320\n    icy-description : DJ-mixed blend of modern and classic rock, electronica, world music, and more. Always 100% commercial-free\n    icy-genre       : Eclectic\n    icy-name        : Radio Paradise (320k aac)\n    icy-pub         : 1\n    icy-url         : https://radioparadise.com\n    StreamTitle     : Depeche Mode - Strangelove\n    StreamUrl       : http://img.radioparadise.com/covers/l/B000002LCI.jpg\n

In the example above, all tags are populated with correct information, no modifications to the server configuration should be needed. Note that StreamUrl points to the artwork image file.

Below is another example that will require some tweaks to the server, Notice icy-name is blank and StreamUrl doesn't point to an image.

Metadata:\n    icy-br          : 127\n    icy-pub         : 0\n    icy-description : Unspecified description\n    icy-url         : \n    icy-genre       : various\n    icy-name        : \n    StreamTitle     : Pour Some Sugar On Me - Def Leppard\n    StreamUrl       : https://radio.stream.domain/api9/eventdata/49790578\n

In the above, first fix is the blank name, second is the image artwork.

"},{"location":"advanced/radio-streams/#1-set-stream-nametitle-via-the-m3u-file","title":"1) Set stream name/title via the M3U file","text":"

Set the name with an EXTINF tag in the m3u playlist file:

#EXTM3U\n#EXTINF:-1, - My Radio Stream Name\nhttp://radio.stream.domain/stream.url\n

The format is basically #EXTINF:<length>, <Artist Name> - <Artist Title>. Length is -1 since it's a stream, <Artist Name> was left blank since StreamTitle is accurate in the Metadata but <Artist Title> was set to My Radio Stream Name since icy-name was blank.

"},{"location":"advanced/radio-streams/#2-streamurl-is-a-json-file-with-metadata","title":"2) StreamUrl is a JSON file with metadata","text":"

If StreamUrl does not point directly to an artwork file then the link may be to a json file that contains an artwork link. If so, you can make the server download the file automatically and search for an artwork link, and also track duration.

Try to download the file, e.g. with curl \"https://radio.stream.domain/api9/eventdata/49790578\". Let's assume you get something like this:

{\n    \"eventId\": 49793707,\n    \"eventStart\": \"2020-05-08 16:23:03\",\n    \"eventFinish\": \"2020-05-08 16:27:21\",\n    \"eventDuration\": 254,\n    \"eventType\": \"Song\",\n    \"eventSongTitle\": \"Pour Some Sugar On Me\",\n    \"eventSongArtist\": \"Def Leppard\",\n    \"eventImageUrl\": \"https://radio.stream.domain/artist/1-1/320x320/562.jpg?ver=1465083491\",\n    \"eventImageUrlSmall\": \"https://radio.stream.domain/artist/1-1/160x160/562.jpg?ver=1465083491\",\n    \"eventAppleMusicUrl\": \"https://geo.itunes.apple.com/dk/album/530707298?i=530707313\"\n}\n

In this case, you would need to tell the server to look for \"eventDuration\" and \"eventImageUrl\" (or just \"duration\" and \"url\"). You can do that like this:

curl -X PUT \"http://localhost:3689/api/settings/misc/streamurl_keywords_length\" --data \"{\\\"name\\\":\\\"streamurl_keywords_length\\\",\\\"value\\\":\\\"duration\\\"}\"\ncurl -X PUT \"http://localhost:3689/api/settings/misc/streamurl_keywords_artwork_url\" --data \"{\\\"name\\\":\\\"streamurl_keywords_artwork_url\\\",\\\"value\\\":\\\"url\\\"}\n

If you want multiple search phrases then comma separate, e.g. \"duration,length\".

"},{"location":"advanced/radio-streams/#3-set-metadata-with-a-custom-script","title":"3) Set metadata with a custom script","text":"

If your radio station publishes metadata via another method than the above, e.g. just on their web site, then you will have to write a script that pulls the metadata and then pushes it to the server. To update metadata for the currently playing radio station use something like this JSON API request:

curl -X PUT \"http://localhost:3689/api/queue/items/now_playing?title=Awesome%20title&artwork_url=http%3A%2F%2Fgyfgafguf.dk%2Fimages%2Fpige3.jpg\"\n

If your radio station is not returning any artwork links, you can also just make a static artwork by placing a png/jpg in the same directory as the m3u, and with the same name, e.g. My Radio Stream.jpg for My Radio Stream.m3u.

"},{"location":"advanced/remote-access/","title":"Remote access","text":"

It is possible to access a shared library over the internet from a DAAP client like iTunes. You must have remote access to the host machine.

First log in to the host and forward port 3689 to your local machine. You now need to broadcast the daap service to iTunes on your local machine. On macOS the command is:

dns-sd -P iTunesServer _daap._tcp local 3689 localhost.local 127.0.0.1 \"ffid=12345\"\n

The ffid key is required but its value does not matter.

Your library will now appear as 'iTunesServer' in iTunes.

You can also access your library remotely using something like Zerotier. See this guide for details.

"},{"location":"clients/cli/","title":"Command line","text":"

You can choose between:

  • a MPD command line client (easiest) like mpc
  • curl with OwnTone's JSON API (see JSON API docs)
  • curl with DAAP/DACP commands (hardest)

Here is an example of how to use curl with DAAP/DACP. Say you have a playlist with a radio station, and you want to make a script that starts playback of that station:

  1. Run sqlite3 [your OwnTone db]. Use select id,title from files to get the id of the radio station, and use select id,title from playlists to get the id of the playlist.
  2. Convert the two ids to hex.
  3. Put the following lines in the script with the relevant ids inserted (also observe that you must use a session-id < 100, and that you must login and logout):
curl \"http://localhost:3689/login?pairing-guid=0x1&request-session-id=50\"\ncurl \"http://localhost:3689/ctrl-int/1/playspec?database-spec='dmap.persistentid:0x1'&container-spec='dmap.persistentid:0x[PLAYLIST-ID]'&container-item-spec='dmap.containeritemid:0x[FILE ID]'&session-id=50\"\ncurl \"http://localhost:3689/logout?session-id=50\"\n
"},{"location":"clients/mpd/","title":"MPD clients","text":"

You can - to some extent - use clients for MPD to control OwnTone.

By default OwnTone listens on port 6600 for MPD clients. You can change this in the configuration file.

Currently only a subset of the commands offered by MPD (see MPD protocol documentation) are supported.

Due to some differences between OwnTone and MPD not all commands will act the same way they would running MPD:

  • crossfade, mixrampdb, mixrampdelay and replaygain will have no effect
  • single, repeat: unlike MPD, OwnTone does not support setting single and repeat separately on/off, instead repeat off, repeat all and repeat single are supported. Thus setting single on will result in repeat single, repeat on results in repeat all.

The following table shows what is working for a selection of MPD clients:

Client Type Status mpc CLI Working commands: mpc, add, crop, current, del (ranges are not yet supported), play, next, prev (behaves like cdprev), pause, toggle, cdprev, seek, clear, outputs, enable, disable, playlist, ls, load, volume, repeat, random, single, search, find, list, update (initiates an init-rescan, the path argument is not supported) ympd Web Everything except \"add stream\" should work"},{"location":"clients/remote/","title":"Using Remote","text":"

Remote gets a list of output devices from the server; this list includes any and all devices on the network we know of that advertise AirPlay: AirPort Express, Apple TV, ... It also includes the local audio output, that is, the sound card on the server (even if there is no soundcard).

OwnTone remembers your selection and the individual volume for each output device; selected devices will be automatically re-selected, except if they return online during playback.

"},{"location":"clients/remote/#pairing","title":"Pairing","text":"
  1. Open the web interface
  2. Start Remote, go to Settings, Add Library
  3. Enter the pair code in the web interface (update the page with F5 if it does not automatically pick up the pairing request)

If Remote doesn't connect to OwnTone after you entered the pairing code something went wrong. Check the log file to see the error message. Here are some common reasons:

  • You did not enter the correct pairing code

    You will see an error in the log about pairing failure with a HTTP response code that is not 0.

    Solution: Try again.

  • No response from Remote, possibly a network issue

    If you see an error in the log with either:

    • a HTTP response code that is 0
    • \"Empty pairing request callback\"

    it means that OwnTone could not establish a connection to Remote. This might be a network issue, your router may not be allowing multicast between the Remote device and the host OwnTone is running on.

    Solution 1: Sometimes it resolves the issue if you force Remote to quit, restart it and do the pairing proces again. Another trick is to establish some other connection (eg SSH) from the iPod/iPhone/iPad to the host.

    Solution 2: Check your router settings if you can whitelist multicast addresses under IGMP settings. For Apple Bonjour, setting a multicast address of 224.0.0.251 and a netmask of 255.255.255.255 should work.

  • Otherwise try using avahi-browse for troubleshooting:

    • in a terminal, run avahi-browse -r -k _touch-remote._tcp
    • start Remote, goto Settings, Add Library
    • after a couple seconds at most, you should get something similar to this:
    + ath0 IPv4 59eff13ea2f98dbbef6c162f9df71b784a3ef9a3      _touch-remote._tcp   local\n= ath0 IPv4 59eff13ea2f98dbbef6c162f9df71b784a3ef9a3      _touch-remote._tcp   local\n   hostname = [Foobar.local]\n   address = [192.168.1.1]\n   port = [49160]\n   txt = [\"DvTy=iPod touch\" \"RemN=Remote\" \"txtvers=1\" \"RemV=10000\" \"Pair=FAEA410630AEC05E\" \"DvNm=Foobar\"]\n

    Hit Ctrl-C to terminate avahi-browse.

  • To check for network issues you can try to connect to address and port with telnet.

"},{"location":"clients/supported-clients/","title":"Supported clients","text":"

OwnTone supports these kinds of clients:

  • DAAP clients, like iTunes or Rhythmbox
  • Remote clients, like Apple Remote or compatibles for Android/Windows Phone
  • AirPlay devices, like AirPort Express, Shairport and various AirPlay speakers
  • Chromecast devices
  • MPD clients, like mpc
  • MP3 network stream clients, like VLC and almost any other music player
  • RSP clients, like Roku Soundbridge

Like iTunes, you can control OwnTone with Remote and stream your music to AirPlay devices.

A single OwnTone instance can handle several clients concurrently, regardless of the protocol.

By default all clients on 192.168.* (and the ipv6 equivalent) are allowed to connect without authentication. You can change that in the configuration file.

Here is a list of working and non-working DAAP and Remote clients. The list is probably obsolete when you read it :-)

Client Developer Type Platform Working (vers.) iTunes Apple DAAP Win Yes (12.10.1) Apple Music Apple DAAP MacOS Yes Rhythmbox Gnome DAAP Linux Yes Diapente diapente DAAP Android Yes WinAmp DAAPClient WardFamily DAAP WinAmp Yes Amarok w/DAAP plugin KDE DAAP Linux/Win Yes (2.8.0) Banshee DAAP Linux/Win/OSX No (2.6.2) jtunes4 DAAP Java No Firefly Client (DAAP) Java No Remote Apple Remote iOS Yes (4.3) Retune SquallyDoc Remote Android Yes (3.5.23) TunesRemote+ Melloware Remote Android Yes (2.5.3) Remote for iTunes Hyperfine Remote Android Yes Remote for Windows Phone Komodex Remote Windows Phone Yes (2.2.1.0) TunesRemote SE Remote Java Yes (r108) rtRemote for Windows bizmodeller Remote Windows Yes (1.2.0.67)"},{"location":"clients/web-interface/","title":"OwnTone web interface","text":"

Mobile friendly player web interface for OwnTone build with Vue.js, Bulma.

You can find the web interface at http://owntone.local:3689 or alternatively at http://SERVER_ADDRESS:3689.

Use the web interface to control playback, trigger manual library rescans, pair with remotes, select speakers, authenticate with Spotify, etc.

"},{"location":"clients/web-interface/#screenshots","title":"Screenshots","text":""},{"location":"clients/web-interface/#usage","title":"Usage","text":"

You can find OwnTone's web interface at http://owntone.local:3689 or alternatively at http://SERVER_ADDRESS:3689.

"},{"location":"clients/web-interface/#build-setup","title":"Build Setup","text":"

The source is located in the web-src folder.

cd web-src\n

The web interface is built with Vite, makes use of Prettier for code formatting and ESLint for code linting (the project was set up following the guide ESLint and Prettier with Vite and Vue.js 3

# install dependencies\nnpm install\n\n# Serve with hot reload at localhost:3000\n# (assumes that OwnTone server is running on localhost:3689)\nnpm run serve\n\n# Serve with hot reload at localhost:3000\n# (with remote OwnTone server reachable under owntone.local:3689)\nVITE_OWNTONE_URL=http://owntone.local:3689 npm run serve\n\n# Build for production with minification (will update web interface\n# in \"../htdocs\")\nnpm run build\n\n# Format code\nnpm run format\n\n# Lint code (and fix errors that can be automatically fixed)\nnpm run lint\n

After running npm run serve the web interface is reachable at localhost:3000. By default it expects owntone to be running at localhost:3689 and proxies all JSON API calls to this location.

If the server is running at a different location you have to set the env variable VITE_OWNTONE_URL.

"},{"location":"integrations/lastfm/","title":"LastFM","text":"

You can have OwnTone scrobble the music you listen to. To set up scrobbling go to the web interface and authorize OwnTone with your LastFM credentials.

OwnTone will not store your LastFM username/password, only the session key. The session key does not expire.

"},{"location":"integrations/spotify/","title":"Spotify","text":"

OwnTone has built-in support for playback of the tracks in your Spotify library.

You must have a Spotify premium account. If you normally log into Spotify with your Facebook account you must first go to Spotify's web site where you can get the Spotify username and password that matches your account.

You must also make sure that your browser can reach OwnTone's web interface via the address http://owntone.local:3689. Try it right now! That is where Spotify's OAuth page will redirect your browser with the token that OwnTone needs, so it must work. The address is announced by the server via mDNS, but if that for some reason doesn't work then configure it via router or .hosts file. You can remove it again after completing the login.

To authorize OwnTone, open the web interface, locate Settings > Online Services and then click the Authorize button. You will then be sent to Spotify's authorization service, which will send you back to the web interface after you have given the authorization.

Spotify no longer automatically notifies clients about library updates, so you have to trigger updates manually. You can for instance set up a cron job that runs /usr/bin/curl http://localhost:3689/api/update

To logout and remove Spotify tracks + credentials make a request to http://owntone.local:3689/api/spotify-logout.

Limitations: You will not be able to do any playlist management through OwnTone - use a Spotify client for that. You also can only listen to your music by letting OwnTone do the playback - so that means you can't stream to DAAP clients (e.g. iTunes) and RSP clients.

"},{"location":"integrations/spotify/#via-librespotspocon","title":"Via librespot/spocon","text":"

You can also use OwnTone with one of the various incarnations of librespot. This adds librespot as a selectable metaspeaker in Spotify's client, and when you start playback, librespot can be configured to start writing audio to a pipe that you have added to your library. This will be detected by OwnTone that then starts playback. You can also have a pipe for metadata and playback events, e.g. volume changes.

The easiest way of accomplishing this may be with Spocon, since it requires minimal configuration. After installing, create two pipes (with mkfifo) and set the configuration in the player section:

# Audio output device (MIXER, PIPE, STDOUT)\noutput = \"PIPE\"\n# Output raw (signed) PCM to this file (`player.output` must be PIPE)\npipe = \"/srv/music/spotify\"\n# Output metadata in Shairport Sync format (https://github.com/mikebrady/shairport-sync-metadata-reader)\nmetadataPipe = \"/srv/music/spotify.metadata\"\n
"},{"location":"outputs/airplay/","title":"AirPlay devices/speakers","text":"

OwnTone will discover the AirPlay devices available on your network. For devices that are password-protected, the device's AirPlay name and password must be given in the configuration file. See the sample configuration file for the syntax.

If your Apple TV requires device verification (always required by Apple TV4 with tvOS 10.2) then you can do that through Settings > Remotes & Outputs in the web interface: Select the device and then enter the PIN that the Apple TV displays.

If your speaker is silent when you start playback, and there is no obvious error message in the log, you can try disabling ipv6 in the config. Some speakers announce that they support ipv6, but in fact don't (at least not with forked- daapd).

If the speaker becomes unselected when you start playback, and you in the log see \"ANNOUNCE request failed in session startup: 400 Bad Request\", then try the Apple Home app > Allow Speakers & TV Access > Anyone On the Same Network (or Everyone).

"},{"location":"outputs/chromecast/","title":"Chromecast","text":"

OwnTone will discover Chromecast devices available on your network, and you can then select the device as a speaker. There is no configuration required.

"},{"location":"outputs/local-audio/","title":"Local audio","text":""},{"location":"outputs/local-audio/#local-audio-through-alsa","title":"Local audio through ALSA","text":"

In the config file, you can select ALSA for local audio. This is the default.

When using ALSA, the server will try to syncronize playback with AirPlay. You can adjust the syncronization in the config file.

For most setups the default values in the config file should work. If they don't, there is help here

"},{"location":"outputs/local-audio/#local-audio-bluetooth-and-more-through-pulseaudio","title":"Local audio, Bluetooth and more through Pulseaudio","text":"

In the config file, you can select Pulseaudio for local audio. In addition to local audio, Pulseaudio also supports an array of other targets, e.g. Bluetooth or DLNA. However, Pulseaudio does require some setup, so here is a separate page with some help on that: Pulse audio

Note that if you select Pulseaudio the \"card\" setting in the config file has no effect. Instead all soundcards detected by Pulseaudio will be listed as speakers by OwnTone.

You can adjust the latency of Pulseaudio playback in the config file.

"},{"location":"outputs/streaming/","title":"MP3 network streaming (streaming to iOS)","text":"

You can listen to audio being played by OwnTone by opening this network stream address in pretty much any music player:

http://owntone.local:3689/stream.mp3 or http://SERVER_ADDRESS:3689/stream.mp3

This is currently the only way of listening to your audio on iOS devices, since Apple does not allow AirPlay receiver apps, and because Apple Home Sharing cannot be supported by OwnTone. So what you can do instead is install a music player app like VLC, connect to the stream and control playback with Remote.

In the speaker selection list, clicking on the icon should start the stream playing in the background on browsers that support that.

Note that MP3 encoding must be supported by ffmpeg/libav for this to work. If it is not available you will see a message in the log file. In Debian/Ubuntu you get MP3 encoding support by installing the package \"libavcodec-extra\".

"}]} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml new file mode 100644 index 0000000000..00c26f7d02 --- /dev/null +++ b/sitemap.xml @@ -0,0 +1,128 @@ + + + + https://owntone.github.io/owntone-server/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/artwork/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/building/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/getting-started/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/installation/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/json-api/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/library/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/playlists/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/smart-playlists/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/advanced/multiple-instances/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/advanced/outputs-alsa/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/advanced/outputs-pulse/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/advanced/radio-streams/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/advanced/remote-access/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/clients/cli/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/clients/mpd/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/clients/remote/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/clients/supported-clients/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/clients/web-interface/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/integrations/lastfm/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/integrations/spotify/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/outputs/airplay/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/outputs/chromecast/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/outputs/local-audio/ + 2023-08-12 + daily + + + https://owntone.github.io/owntone-server/outputs/streaming/ + 2023-08-12 + daily + + \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz new file mode 100644 index 0000000000..eda8ea8113 Binary files /dev/null and b/sitemap.xml.gz differ diff --git a/smart-playlists/index.html b/smart-playlists/index.html new file mode 100644 index 0000000000..39a3d04a1a --- /dev/null +++ b/smart-playlists/index.html @@ -0,0 +1,43 @@ + Smart playlists - OwnTone

OwnTone smart playlists

To add a smart playlist to the server, create a new text file with a filename ending with .smartpl; the filename doesn't matter, only the .smartpl ending does. The file must be placed somewhere in your library folder.

Syntax

The contents of a smart playlist must follow the syntax:

"Playlist Name" { expression }
+

There is exactly one smart playlist allowed for a .smartpl file.

An expression consists of:

field-name operator operand
+

Where valid field-names (with their types) are:

  • artist (string)
  • album_artist (string)
  • album (string)
  • title (string)
  • genre (string)
  • composer (string)
  • comment (string)
  • path (string)
  • type (string)
  • grouping (string)
  • data_kind (enumeration)
  • media_kind (enumeration)
  • play_count (integer)
  • skip_count (integer)
  • rating (integer)
  • year (integer)
  • compilation (integer)
  • track (integer)
  • disc (integer)
  • time_added (date)
  • time_modified (date)
  • time_played (date)
  • time_skipped (date)
  • random (special)
  • file_size (integer)

Valid operators include:

  • is, includes, starts with, ends with (string)
  • >, <, <=, >=, = (int)
  • after, before (date)
  • is (enumeration)

The is operator must exactly match the field value, while the includes operator matches a substring. The starts with operator matches, if the value starts with the given prefix, and ends with matches the opposite. All these matches are case-insensitive.

Valid operands include:

  • "string value" (string)
  • integer (int)

Valid operands for the enumeration data_kind are:

  • file
  • url
  • spotify
  • pipe

Valid operands for the enumeration media_kind are:

  • music
  • movie
  • podcast
  • audiobook
  • tvshow

Multiple expressions can be anded or ored together, using the keywords OR and AND. The unary not operator is also supported using the keyword NOT.

It is possible to define the sort order and limit the number of items by adding an order clause and/or a limit clause after the last expression:

"Playlist Name" { expression ORDER BY field-name sort-direction LIMIT limit }
+

"sort-direction" is either ASC (ascending) or DESC (descending). "limit" is the maximum number of items.

There is additionally a special random field-name that can be used in conjunction with limit to select a random number of items based on current expression.

Examples

"techno" {
+   genre includes "techno"
+   and artist includes "zombie"
+}
+

This would match songs by "Rob Zombie" or "White Zombie", as well as those with a genre of "Techno-Industrial" or "Trance/Techno", for example.

"techno 2015" {
+   genre includes "techno"
+   and artist includes "zombie"
+   and not genre includes "industrial"
+}
+

This would exclude e. g. songs with the genre "Techno-Industrial".

"Local music" {
+  data_kind is file
+  and media_kind is music
+}
+

This would match all songs added as files to the library that are not placed under the folders for podcasts, audiobooks.

"Unplayed podcasts and audiobooks" {
+  play_count = 0
+  and (media_kind is podcast or media_kind is audiobook)
+}
+

This would match any podcast and audiobook file that was never played.

"Recently added music" {
+  media_kind is music
+  order by time_added desc
+  limit 10
+}
+
This would match the last 10 music files added to the library.

"Random 10 Rated Pop songs" {
+  rating > 0 and
+  genre is "Pop" and
+  media_kind is music
+  order by random desc
+  limit 10
+}
+
This generates a random set of, maximum of 10, rated Pop music tracks every time the playlist is queried.

Date operand syntax

One example of a valid date is a date in yyyy-mm-dd format:

"Files added after January 1, 2004" {
+  time_added after 2004-01-01
+}
+

There are also some special date keywords:

  • today, yesterday, this week, last week, last month, last year

These dates refer to the start of that period; today means 00:00hrs of today, this week means current Monday 00:00hrs, last week means the previous Monday 00:00hrs, last month is the first day of the previous month at 00:00hrs etc.

A valid date can also be made by applying an interval to a date. Intervals can be defined as days, weeks, months, years. As an example, a valid date might be:

3 weeks before today or 3 weeks ago

Examples:

"Recently Added" {
+    time_added after 2 weeks ago
+}
+

This matches all songs added in the last 2 weeks.

"Recently played audiobooks" {
+    time_played after last week
+    and media_kind is audiobook
+}
+

This matches all audiobooks played since the start of the last Monday 00:00AM.

All dates, except for YYYY-DD-HH, are relative to the day of when the server evaluates the smartpl query; time_added after today run on a Monday would match against items added since Monday 00:00hrs and evaluating the same smartpl on Friday would only match against added on Friday 00:00hrs.

Note that time_added after 4 weeks ago and time_added after last month are subtly different; the former is exactly 4 weeks ago (from today) whereas the latter is the first day of the previous month.

Differences to mt-daapd smart playlists

The syntax is really close to the mt-daapd smart playlist syntax (see http://sourceforge.net/p/mt-daapd/code/HEAD/tree/tags/release-0.2.4.2/contrib/mt-daapd.playlist).

Even this documentation is based on the file linked above.

Some differences are:

  • only one smart playlist per file
  • the not operator must be placed before an expression and not before the operator
  • ||, &&, ! are not supported (use or, and, not)
  • comments are not supported
\ No newline at end of file