You need to try forked-daapd if you are an iTunes user, Airplay user, or interested in playing local music

Hi all,

I just migrated from the iTunes integration to the forked-daapd integration and I feel that forked-daapd isn’t getting the recognition it deserves for how great it is, so I thought I’d share my experience. My only regret is not moving from iTunes to forked-daapd years ago.


So, for those who don’t know about forked-daapd, I will give a brief summary. Basically forked-daapd is a media player that emulates iTunes, meaning you can use all your existing iTunes and iTunes remotes to control music. They will all see it as a normal iTunes server. What makes it special is first, how well it does this (more on this in a second), and secondly, the things it adds on to it, like spotify and last-fm integration and ability to cast to other devices like chromecast audio devices.


So, what was it about iTunes and the iTunes integration in hass that finally made me decide to ditch it for forked-daapd? Many things:

  • First, the latest version of iTunes had been giving me all sorts of problems with iTunes deciding not to connect to speakers, stop playing shortly after starting to play, not wanting to work if I made commands too close together, etc. In desperation, I made a whole appdaemon app just to manage all these constraints and continually retry playing the playlist until it worked properly. Sometimes this would take up to 30 seconds. This, of course, pissed me off.
  • Second, the server the hass iTunes component uses is no longer maintained. This means that sooner or later it will stop working… We have just been fortunate that daap doesn’t progress as a protocol.
  • Third, as mentioned before, forked-daapd can do lots of things that iTunes can’t, like stream to chromecast, scroble to, and play music from spotify to airplay or chromecast endpoints. It’s also very extensible, so you can add on other stuff which I probably don’t even know about yet.
  • Fourth, forked-daapd is a drop in replacement for iTunes. It really surprised me how well it worked. I literally was able just to drop my iTunes library into a folder it could access, change a few items in the config and clean up the folder a bit, and start it up. All of my playlists (I have 40+ smart playlists and another 20+ normal ones) just showed up ready to work. It also sucked in all my airplay and chromecast devices with no manual configuration from my part, and they were all available from the first startup to stream to.
  • But the big one for me is what I learned after I installed it. It just works way better than iTunes does. To be honest, I was shocked by how much better some FOSS software works with Apple’s ecosystem than Apple’s own software does. The difference was like night and day, and I started to suspect that Apple was putting bugs into iTunes to force people to move to Apple Music due to how stark the difference was. Let me list a few of these things:
  1. Choosing airplay speakers is nearly instant and never fails. With iTunes, I had some speakers which would fail most of the time, and the other ones would take many seconds to activate. If I tried playing a playlist before they had changed, it would fail with errors. This doesn’t happen with forked-daapd. It’s been 100% reliable so far.
  2. The media player doesn’t just stop playing for whatever reason after you ask it to play like iTunes was doing to me. Forked-daapd “just works” ;-).
  3. Unlike the iTunes integration, forked-daapd will expose all your playlists as sources, meaning that a card like mini-media-player will show them all in a drop down list for you. With the iTunes integration, I had to manually program all of my 60+ playlists into a list which was a hassle.
  4. Shuffle capability works out of the box, so you don’t have to do hacks like I did with the iTunes integration to make it work.
  5. You don’t have to manually start iTunes and itunes-api server every time you start up your mac and keep your mac running all the time to access your music. You can turn off your computer and access your music from homeassistant.

So, long story short, I have no regrets moving away from the iTunes integration.


So, how do you do this? Well we are very fortunate that it became a lot easier since forked-daapd was integrated into homeassistant core as a standard integration, and we got the addon. I will try to give a mini guide from memory below:

  1. In your homeassistant UI, go to supervisor->addon store->… menu->repositories and in the bottom line, paste in and click add
  2. Close that dialog and go back to add-on store and search for forked-daapd and install it.
  3. I recommend you check if there’s anything you want to change in the config file found at share/forked-daapd/forked-daapd.conf. Note that all the confguration happens there, there is nothing you can change from the addon config panel in supervisor. Here’s what I changed in order to make it work with my iTunes library’s smart playlists:
	itunes_overrides = true
	itunes_smartpl = true

I also changed the name of the library to something friendly and got commented out the podcasts, audiobooks, and compilations sections because I didn’t plan to use them. I think I also changed

	rating_updates = false

Because I have rated most of my songs already by hand.
And I added my subnet to

	trusted_networks = { "any", "192.168", "fd" }

Because the iTunes remotes wouldn’t properly connect otherwise…

Check all the options, because there might be some that apply to your circumstance.

  1. Import your music library to the folder defined at:
	directories = { "/share/forked-daapd/music" }

Protip: When importing your iTunes library, you will want the folder to look like this:

drwxr-xr-x 12 root root      4096 Dec 27 01:05 'Album Artwork'
prw-r--r--  1 root root         0 Dec 27 01:05  HomeAssistantAnnounce
drwxr-xr-x  4 root root      4096 Dec 27 01:05 'iPod Games'
-rwxr-xr-x  1 root root    771711 Dec 27 01:05 'iTunes Library-bak.itl'
-rwxr-xr-x  1 root root    983040 Dec 27 01:05 'iTunes Library Extras.itdb'
-rwxr-xr-x  1 root root 210706432 Dec 27 01:05 'iTunes Library Genius.itdb'
-rwxr-xr-x  1 root root  10894005 Dec 27 01:05 'iTunes Library.itl'
-rwxr-xr-x  1 root root  33386446 Dec 27 01:05 'iTunes Library.xml'
drwxr-xr-x 18 root root      4096 Dec 27 01:29 'iTunes Music'
drwxr-xr-x  3 root root      4096 Dec 27 01:29 'Mobile Applications'
drwxr-xr-x  2 root root      4096 Dec 27 01:29 'Previous iTunes Libraries'
-rwxr-xr-x  1 root root         8 Dec 27 01:29  sentinel

Now, many of these folders I’m sure are superfluous and can be deleted. The reason I’m showing you this folder is because it was nested within other iTunes folders which forked-daapd would not import. So you need to get to the folder that has the “iTunes Music” folder in it and place that in the path shown in the config file. Within the “iTunes Music” folder, there should be another folder called just “Music” that contains the actual folders with your music (If you told iTunes to keep your music library organized. If you didn’t do that, I’m not sure what yours would look like, but if you want to make it easy, tell iTunes to keep your music library organized and it should look like mine.

Protip 2: If you find any other .xml files in this folder other than “'iTunes Library.xml”, you will need to get rid of them, or you will likely have duplicate playlists like I did. I had another similar file that was like 6 years old. I deleted it and the duplicate playlists disappeared on the next restart.

Optional extras:
Now, in my case I just copied everything over from iTunes into here, but left iTunes as it was. I’m 30 years into collecting music so the pace of change is pretty small compared to what I’ve already ammassed, so for me it’s enough to just copy it over once a year, the changes are like pissing in a river and hardly noticed. There are some other ways to approach this, and I will link to some guides that explain this:

Option A: You could map your music folder from your mac onto a drive and use forked-daapd to access it from there, that way if you update your music library on the mac, forked-daapd will just pick it up This guide is a bit old and the homeassistant side is outdated since the official integration came, but it still gives you an idea how to do this The addon and’s inability to allow you to map network drives would make this rather difficult to do with Also, getting addons to navigate to devices outside of your local disk is difficult so you probably won’t be able to do it with the addon as I described. You’d have to do it in a similar way shown in the video (just ignore the homeassistant integration method he does).

Option B: You could actually make forked-daapd your only music library and point iTunes to it so that it uses it as it’s own libary. This guide explains that process. This sort of does the same thing as the first option above, but instead of having forked-daapd get it’s music from the mac, the mac get’s it’s music from your forked-daapd server. This is a bit too bold for me, I prefer just to keep 2 copies in case something goes wrong… But I’m sure it probably works just fine.

  1. Now that you’ve hopefully got everything setup right, you should with any luck be able to start up the addon by going to supervisor->dashboard->forked DAAPD->start
  2. At this point you should be able to access the forked-daapd UI at the address of your home assistant server, port 3689 like this:
    as an example. In my case I wasn’t able to access the UI via the supervisor UI button, but this works okay for me.
  3. Check to see if you’ve got music in the playlists (box with note icon) and artists and songs in the music tab (2 notes icon). If so, you’re good to go. It does take a while to start, so be patient or go watch the log for the addon in supervisor until it’s done scanning your library. Try playing a few songs to various speakers and see if it all works.
  4. Now you can go to settings and change anything you want, such as to hide some of the buttons you don’t use (like podcasts in my case), connect to for scrobling or spotify to stream from spotify (you will need a paid subscription for this though). If you need to pair an iTunes remote, you can do that from the remotes section. I also noticed that not all my artwork made it over from iTunes, so I enabled the artwork sources from the Artwork tab and then all the missing artwork got sucked in automatically.
  5. Once everything is working on the forked-daapd side, you can go add the integration in homeassistant at configuration->integration->+ add integration->forked-daapd. This should create a media player for your library and one for each of the airplay or chromecast destinations that you have in your house, and even one for the server running forked-daapd so that you can play to speakers connected to that if you want.
  6. Now you should see the forked-daapd box in the integrations and hopefully you can see that there’s a link to the entities it created. In this list you should see one that has the word “server” at the end. That’s the one you will need to control to send the music to the other media players.
  7. You can use my mini-media-player card as an example of how to set up your card. You will of course have to install the custom card mini-media-player first. mini-media-player is nice because it will put all your playlists as a drop down list which you can choose from. Optionally you can add buttons which go directly to your favorite playlists as I did in my example here

Now you should be rocking and rolling with forked-daapd. I hope you enjoy it as much as I do!

What else?

Well, through the process I came up with a few minor things that I will mention in a wishlist in case any of the devs swing by.

  1. I wish the icons for my speakers would show up as speaker icons that show as muted when the speakers are deactivated:

    Instead of as video endpoints which do not change when muted (all of my speakers except one chromecast are airtunes audio endpoints, so they should really show as speakers instead of video cast endpoints):
  2. Would be nice if the player would continue playing when a new playlist was chosen. With iTunes, it would just keep playing but the new playlist would start. With forked-daapd the player stops when you choose a playlist and you have to start it again. I also preferred how iTunes would start playing if it wasn’t already playing when you press the playlist button. Forked daapd chooses the playlist but doesn’t start playing.
  3. I realize this is more an issue with addons in general, but it would be nice if there were some way to access music libraries on external disks, over SMB shares, etc. rather than having to copy it into the share directory. I wanted to use an external disk but couldn’t get it to work. It looks like I will have to make a special partition on the disk and mount that partition as my share folder to make this work. I can do it but it’s a hassle. SMB would be even worse.
  4. Having all the music and playlists show up in my media browser would be really a lovely addition :-).

But these are minor things. I’m really over the moon overall with how this solved all the problems I was having with iTunes and it’s integration. Now my music is always online and responds instantly and reliably to my requests. Haven’t had any failures so far. Thanks to the maintainers of the integration and the addon, this became a much easier process thanks to you! Hopefully this little guide makes it even easier for people to access.

Enjoy the music!


So apparently my timing is bad as it seems that the forked-daapd addon isn’t working for hassOS users at the moment since they removed avahi-daemon from HassOS. I am running supervised on Debian so it still works for me. Hopefully this gets sorted, because this addon makes things considerably easier. For those on HassOS, for now you might have to install on a separate machine or wait until this is resolved.

Awesome write-up!
Here is an alternative to the hassio addon, using portainer, that is working with the latest homeassistant, hassos and supervisor on raspberry pi 4.


Thanks for the info guys. Have it up and running, it’s great so far.

Just wondering if you guys got local audio up and running. I have a pair of USB speakers plugged in but no luck getting it work. The documentation talks about running aplay -l to obtain device details, but that doesn’t seem available in Home Assistant.

Home Assistant does see my speakers though:

    name: USB-Audio - USB  AUDIO
    type: AUDIO
      - chan_id: '0'
        chan_type: digital audio playback

I am not sure how this translates into the ‘audio’ section of forked-daapd.conf.

1 Like

Haven’t had any use for local audio personally, sorry.

It appears that the owner of the addon made the adjustments necessary to fix the issues on HassOS 5.8 so if any HassOS users are brave enough to try the new fix, it would be great to report back to the issue linked here with your experiences so the dev knows whether or not it works (he can’t test it himself).

1 Like

No problem, it is just one of those ‘nice to have’ things.

OK, I can test it. I assume I can just stop the containers I’ve added under portainer and install the add-on. Reading the documentation, I don’t see a reference to shairport-sync. Do I need to install that separately or is it included in the add-on? Or maybe I don’t need it.

OK, I have the add-on installed, but I cannot access the web-ui. Either through the sidebar (“502: Bad Gateway”) or via http://[ip address]:3688 or via http://[ip address]:3689 (ERR_CONNECTION_REFUSED).

I think it’s port 3688:

	# Websocket port for the web interface.
	websocket_port = 3688

I see this in the add-on log:

forked-daapd: client.c:791: avahi_client_errno: Assertion `client' failed.

I tried to re-install and received this error message (it was there the first time I installed as well, but it seemed to install anyway):

When I return to the add-on, it is there and can be run, but unable to access the web-ui.

I’ll just stop the add-on for now.

Hi, I also couldn’t access the UI via ingress, but going to the local URL for it worked. For me that’s:

It looks like you may not have the new version because he said he took out the avahi error message in the latest. Would be great if you stopped by the GitHub issue and shared your results.

Thanks, I’ve posted that on this tread.

Also, have you been able to get the media_player.play_media to play a specified playlist or track? I’ve set up the custom:mini-media-player card in lovelace and I can play content from there, but not with the media_player integration. Can this be scripted to play a specific track?

The forked-daapd integration talks about named pipes. I’ve set autostart pipes, but the intergration says it should be named “librespot-java”. Do you know how this should be renamed? Don’t see an option for its name in the forked-daapd.conf file.

Yes, I can play playlists. I haven’t tried individual tracks. I don’t think it supports it. To play a playlist you need to select it as a source as below:

  service: media_player.select_source
    entity_id: media_player.forked_daapd_server
    source: "radio2 (playlist)"

Then you have to tell the media player to play (this is a bit weird, my other media players don’t need 2 steps like this, but this is how it’s done with forked-daapd). That’s done like this:

  service: media_player.media_play
    entity_id: media_player.forked_daapd_server

I haven’t tried doing anything with named pipes. It wasn’t needed for anything I wanted to do. If you use the addon and built in integration you can do airplay, itunes playlists, chromecast, spotify, etc… all without touching them. But if you get them working, let me know what they are useful for :slight_smile:

Awesome, it works! :clap::clap::clap:. Happy to use playlists.

Not sure about named pipes either TBO. I’m still learning about how all this stuff works. I’d like to explore the possibility of piping audio from mopidy at some stage as it has a soundcloud plug in.

Sorry for asking so many questions. You mentioned the shuffle capability works out of the box. Can you tell me how that works?

@scstraus thank you for your comprehensive guide!

The forked-daapd integrations does not set up for me, saying i gave the wrong password for the API. The API password actually is the password for the library that you also would need to give in the Apple Music App. I have NOT setup a password for this, so I leave the password field on integration setup empty. The forked-daapd log file gives [ LOG] httpd: Web interface request to '/api/config' denied: Incorrect password so the integration seems to send something weird to forked-daapd, as the other clients (macOS Music App, iOS Remote App) have no problems connecting to my forked-daapd.

Anyone else having this problem? Any ideas?

IIRC I had this problem too and just solved it by setting a password for the library.

I posted question about individual tracks question on another thread. There is a ‘forked’ forked-daapd integration that sacrifices TTS for the ability to play individual tracks.

Also, I’ve found the shairport-sync thing pretty handy in the end. I can play my soundcloud tracks and output the music to the shairport-sync and in turn out via the forked-daapd speakers without losing the functionality I am getting by being able to control them via home assistant.

1 Like

Password on library is not an option for me as it breaks other use cases

I will try to double check next time I get a chance.

For testing I set a password and deleted the DB and cache and did a fresh restart. Lo and behold, the apps do not ask for a password and do work and the HASS integration still fails with “incorrect password”. Seems like my forked-daapd does not properly set a password for the API. The config extract looks like this:

library {
	name = "mydaapd"
	port = 3689
	password = "test"
	directories = { "/music" }
#	follow_symlinks = true
	podcasts = { "/music/Podcasts" }
	audiobooks = { "/music/Audiobooks" }
	compilations = { "/music/Various Artists" }
#	compilation_artist = ""
#	hide_singles = false
#	radio_playlists = true
#	name_library    = "Library"
#	name_music      = "Music"
#	name_movies     = "Movies"
#	name_tvshows    = "TV Shows"
#	name_podcasts   = "Podcasts"
#	name_audiobooks = "Audiobooks"
#	name_radio      = "Radio"
	artwork_basenames = { "artwork", "cover", "Folder" }
	artwork_individual = false
	filetypes_ignore = { ".db", ".ini", ".db-journal", ".pdf", ".metadata" }
#	filepath_ignore = { "myregex" }
	filescan_disable = false
	itunes_overrides = false
	itunes_smartpl = yes
#	no_decode = { "format", "format" }
#	force_decode = { "format", "format" }
#	pipe_autostart = true
#	rating_updates = false

This is so frustrating.

OK, this is embarassing: the password to be used is the Web UI admin password, NOT the library password!

Ah actually I didn’t add a password, I commented out the password line in the config file. It should look like this:

        # Password for the library. Optional.
#       password = ""

But it seems that you got it figured out anyway.