Merge pull request #14 from OzGav/main

Various changes

docs/Installation.md

@@ -42,24 +42,26 @@ ____________
 
 - You cannot run the slimproto integration in Home Assistant at the same time as the MA server.
 
-- The webinterface of the server can be reached on tcp port 8095 if enabled in the settings. By default, on HAOS based installations, the webserver is internal only and not exposed to the outside world. It is protected by HA authentication using the Ingress feature of Home Assistant (you also get the sidepanel shortcut for free!)
+- The webinterface of the server can be reached on TCP port 8095 if enabled in the settings. By default, on HAOS based installations, the webserver is internal only and not exposed to the outside world. It is protected by HA authentication using the Ingress feature of Home Assistant (you also get the sidepanel shortcut for free!)
 
 - You can access the frontend over https by following these steps:
-  (1) Expose the webserver via MA settings --> Core --> webserver
-  (2) To access the frontend behind a reverse proxy you will have to configure the reverse proxy to point at the 8095 port and expose it to whatever is desired (and add an ssl certificate). How that works differs for each implemention. 
+
+1. Expose the webserver via MA settings>>Core>>webserver
+
+2. To access the frontend behind a reverse proxy you will have to configure the reverse proxy to point at the 8095 port and expose it to whatever is desired (and add an ssl certificate). How that works differs for each implemention. 
 
 !!! tip 
     You can keep the server more secure by NOT exposing the webserver and let the addon talk directly to the webserver on the internal docker network. In that case address the internal dns name of the addon would be, for example, <http://d5369777-music-assistant-beta:8095>
 
 ## Usage and Notes
 
-- If you are running Music Assistant in docker, you need to access the webinterface at http://youripaddress:8095. When running the Home Assistant add-on, you can access the webinterface from the add-on (a shortcut can be added to the sidebar) which is more secure than via the port.
+- If you are running Music Assistant in docker, you need to access the webinterface at http://youripaddress:8095. When running the Home Assistant add-on, you can access the webinterface from the add-on (a shortcut can be added to the sidebar) which is more secure than via the port (although the port can be exposed in the settings).
 - Music from your music sources will be automatically loaded into the Music Assistant library. If you have multiple sources, they will be merged as one library.
-- In this first implementation there's only support for "Library items", so your artists, albums, tracks, playlists and radio stations. In a later release options will be provided to browse the recommendations of the various streaming providers.
+- In this first implementation the UI centres around the concept of the [Library](usage.md), so your artists, albums, tracks, playlists and radio stations. You can BROWSE the various providers to add aditional items to your Library. In a later release options will be provided to browse the recommendations of the various streaming providers.
 - Note that at the first startup it can take a while before data is available (first sync), the Music Assistant UI will notify you about tasks that are in progress.
 - Music sources are synced at addon (re)start and every 3 hours.
 - If a song is available on multiple providers (e.g. Spotify and a flac file on disk), the file/stream with the highest quality is always preferred when starting a stream.
-- Music Assistant uses a custom stream port (TCP 8096 by default) to stream audio to players. Players must be able to reach the Home Assistant instance and this port. If you're running one of the recommended Home Assistant installation methods, this is all handled for you, otherwise you will have to make sure you're running HA in HOST network mode. Note: If the default port 8096 is occupied, the next port will be tried, and so on.
+- Music Assistant uses a custom stream port (TCP 8096 by default) to stream audio to players. Players must be able to reach the Home Assistant instance and this port. If you're running one of the recommended HAOS installation methods, this is all handled for you, otherwise you will have to make sure you're running MA in a container in HOST network mode. Note: If the default port 8096 is occupied, the next port will be tried, and so on.
 - See the [GitHub discussion](https://github.com/orgs/music-assistant/discussions/710#discussioncomment-7987528) for more detailed information
 
 [repository-badge]: https://img.shields.io/badge/Add%20repository%20to%20my-Home%20Assistant-41BDF5?logo=home-assistant&style=for-the-badge

docs/faq/how-to.md

@@ -1,36 +1,40 @@
-# **Use Assist and AI to Play my Music?**
+# Use Assist and AI to Play my Music?
 
 See [here](../integration.md)
 
-# **Use volume normalization? How does it work?**
+# Use volume normalization? How does it work?
 
 The setting in MA is the target level for the volume normalization. MA does not compress the dynamic range (because that is bad for quality) but just adjusts the gain of the entire track based on its overall loudness as measured by the EBU R128 standard. A greater negative value will typically make the track sound less loud but leaves a lot of headroom. However, for each individual track the gain could rise or fall to ensure that the overall loudness of all tracks played is at the selected level. We recommend to use a value between -23 and -17 LUFS (and -17 is the recommended starting point). **Do not** set it too high (close to zero) because that can make your music sound distorted due to clipping.
 
 More details [here](normalization.md)
 
-# **Stream to my local HA device**
+# Stream to my local HA device
 
 Install the [squeezelite addon](https://github.com/pssc/ha-addon-squeezelite) which will then allow streaming over an audio connection the HA host to your speaker or amplifier
 
-# **Stream to my non-networked or bluetooth speaker or amplifier**
+# Stream to my non-networked or bluetooth speaker or amplifier
 
 Install a [squeeze lite compatible application](https://sourceforge.net/projects/lmsclients/files/squeezelite/) to your mobile or other devices which MA will be able to stream to. If you have a spare Raspberry Pi then [PiCoreplayer](https://www.picoreplayer.org) is an excellent solution than can also connect to Bluetooth speakers.
 
 See here for info on [how to run squeezelite on Windows](https://github.com/orgs/music-assistant/discussions/1123#discussioncomment-6652948)
 
 The [MA Companion App](../companion-app.md) can also be configured to run a squeezelite client which will allow playback to the device running it.
 
-# **Stream to my browser**
+# Stream to my browser
 
 Use a [Snapserver](../player-support/snapcast.md) and the Snapweb option.
 
-# **Have my music continue if I change rooms**
+# Stream to Music Assistant
+
+You could use [Darkcast](http://www.darkice.org/) to stream to [Icecast](https://www.icecast.org/) which in turn sets up a web radio stream that you could add to MA! You could use this to stream your turntable around the house for example. Here is a [handy tutorial](https://maker.pro/raspberry-pi/projects/how-to-build-an-internet-radio-station-with-raspberry-pi-darkice-and-icecast). For input a [HiFiBerry](https://www.hifiberry.com/docs/hardware/comparison-of-hifiberry-cards-for-audio-recording/) could be used or a USB Audio Interface like [this one](https://www.behringer.com/product.html?modelCode=P0484) 
+
+# Have my music continue if I change rooms
 
 Start streaming to a group that includes all the rooms you will move between. Power off or mute all the rooms except the one you are in. When you move rooms just power (or mute) on and off the respective rooms. Depending on the complexity of your setup you may need to use nested groups of speakers.
 
 You can read, ask or contribute [on this topic](https://github.com/orgs/music-assistant/discussions/702)
 
-# **Shuffle Spotify/playlist/Youtube etc**
+# Shuffle Spotify/playlist/Youtube etc
 
 You don't shuffle the music providers you enable shuffle on the queue for the player and then whatever gets added to the queue gets shuffled. You enable shuffle on the queue from within MA by selecting the Shuffle Icon in the Player frontend or you can select the QUEUE at the bottom, then the context menu Top Right then SETTINGS then SHUFFLE ON or you can do it with yaml as follows:
 ``` yaml
@@ -41,7 +45,7 @@ data:
   shuffle: true
 ```
 
-# **Add items to the queue via a script or automation**
+# Add items to the queue via a script or automation
 
 ``` yaml
 service: media_player.play_media
@@ -54,19 +58,19 @@ data:
 
 See also how to use the mass.play_media service call
 
-# **Start a playlist with a script**
+# Start a playlist with a script
 
 Use the `media_player.play_media` service call shown above or `mass.play_media` service as described here.
 
-# **Start a radio stream with an automation**
+# Start a radio stream with an automation
 
 Use the `mass.play_media` service call and set the `media_id` as the station name.
 
-# **Clear the queue with a script or automation**
+# Clear the queue with a script or automation
 
 Use the HA service call of `media_player.clear_playlist` or the new `mass.play_media` service call and select the appropriate enqueue option if wanting to clear the queue and play something else.
 
-# **Add radio stations to MA**
+# Add radio stations to MA
 
 If you use the [TuneIn provider](../music-providers/tunein.md) then stations that are favourited in your account will appear.
 
@@ -75,7 +79,7 @@ If you use the [RadioBrowser provider](../music-providers/radio-browser.md) then
 Direct entry of stations can be done by navigating to the radio stations page and selecting the menu top right and ADD ITEM FROM URL
 This will also work for locally hosted streams such as from Icecast. 
 
-# **Create playlists or use M3U files**
+# Create playlists or use M3U files
 
 You can create playlists from the MA UI. Adding items can also be done feom the UI.
 
@@ -98,27 +102,27 @@ filesystem_smb://track/blah
 
 Relative paths to the playlist (e.g.` ../Mariah Carey/Merry Christmas/02 All I Want for Christmas Is You.flac` ) should also work.
 
-# **Go to next/previous radio station via a script**
+# Go to next/previous radio station via a script
 
 Create a playlist with multiple radio stations and start playing it. Now you can use next and previous to switch between the stations
 
-# **Stop the music after a period of time aka Sleep Timer**
+# Stop the music after a period of time aka Sleep Timer
 
 See here: https://github.com/music-assistant/hass-music-assistant/discussions/830
 
-# **Use MA with Mopidy**
+# Use MA with Mopidy
 
 See here https://github.com/music-assistant/hass-music-assistant/discussions/439
 
-# **Use the MA service call `mass.play_media`**
+# Use the MA service call `mass.play_media`
 
 See [here](massplaymedia.md)
 
-# **Use the MA service call `mass.search`**
+# Use the MA service call `mass.search`
 
 See [here](masssearch.md)
 
-# **Get the URI?**
+# Get the URI?
 
 For playlists, artists, albums and radio you can simply use the name.
 
@@ -134,16 +138,16 @@ data:
 
 Similarly, if the album name is ambiguous you can specify the artist name first (`Queen - Greatest Hits`)
 
-# **Run MA when I have SSL setup on my internal network?**
+# Run MA when I have SSL setup on my internal network?
 
 Trying to run MA with SSL is not recommended. Having said that, whilst you can not run the stream service behind SSL you can configure the frontend entirely to your requirements. The default is that the frontend is protected by Ingress in HAOS. For those using docker, it is possible to host it on a desired port and then run a (Ingress) reverse proxy. No support will be provided for these setups, we recommend you use HAOS.
 
-# **Get the MA icon in the HA sidebar?**
+# Get the MA icon in the HA sidebar?
 
 If you are running the addon within the HA host go to SETTINGS>>ADDONS>>MUSIC ASSISTANT and select "Show in sidebar".
 
 If you are using docker then you can use an [iframe panel](https://www.home-assistant.io/integrations/panel_iframe/)
 
-# **Add a rotary encoder with push button to a piCorePlayer**
+# Add a rotary encoder with push button to a piCorePlayer
 
 See [here](https://github.com/orgs/music-assistant/discussions/1123#discussioncomment-7945369)

docs/faq/troubleshooting.md

@@ -1,12 +1,12 @@
-# **First things to try and how to report issues**
+# First things to try and how to report issues
 
 Probably the most common issue is people trying to run MA with complicated network setups. Running behind VPNs, across subnets or VLANs, behind firewalls, local SSL, using reverse proxies or inside containers is not supported (it might work but we can’t troubleshoot for you as MA is run by a small team who don't have the resources to help with non-MA issues). Search Discord for these problems as users have regularly reported these issues and found that it is their setup that was causing the fault; their solution might help you.
 
-There are settings available in MA SETTINGS>>CORE>>STREAMSERVER>>ADVANCED that might help you if you have complicated setups. If you are running MA in your own docker container then make sure you have the correct  PUBLISHED IP ADDRESS set in the SETTINGS for the STREAMSERVER.
+There are settings available in MA SETTINGS>>CORE>>STREAMSERVER>>ADVANCED that might help you if you have complicated setups. If you are running MA in your own docker container then make sure you have the correct  PUBLISHED IP ADDRESS and BIND TO IP/INTERFACE set. Ensure containers are in HOST networking mode.
 
 Most players are discovered using mDNS (broadcast) so if your players do not get discovered it means that your network is blocking that traffic (e.g. IGMP or multicast snooping or filtering). You will have to check your settings (e.g. WiFi setup) if multicast is being blocked. Business solutions tend to block multicast traffic as much as possible as it hurts performance when there are many clients. In a home setup is it mandatory to have because all home gear relies on multicast.
 
-Make sure the HA internal url is set correctly. HA Settings --> System --> Network --> Home Assistant URL --> Local network (set to automatic or use your internal HA IP). If it is automatic you can try changing it to http://your.internal.ip:8123/
+Make sure the HA internal url is set correctly. HA SETTINGS>>SYSTEM>>NETWORK>>Home Assistant URL>>Local network (set to automatic or use your internal HA IP). If it is automatic you can try changing it to http://your.internal.ip:8123/
 
 MA streams at high quality which may max out poor network connections. If possible used wired connections for MA players. Input codec is not always the same as the output codec (which is FLAC) so playing a low qualiy MP3 will not change the apparent performance. If you exoerience stuttering or other interrupted playback issues which are not apparent on wired players or those close to your access points then poor WiFi is likely to blame. You will need to improve your WiFi coverage.
 
@@ -22,50 +22,50 @@ Report issues using the template with as much detail as possible. Often posts ar
 !!! note
     You can retrieve the full MA logs by going to the MA settings and clicking on CORE
 
-# **Why aren't tracks/albums matching between providers**
+# Why aren't tracks/albums matching between providers
 
 Matching items between streaming providers is challenging as they do not all provide the same or unique metadata to definitivly identify a match. If you think there is an obvious match (eg. same artist and track and album) then please submit an issue report. For more information about how MA uses metadata in various ways see here https://github.com/music-assistant/hass-music-assistant/discussions/543
 
-# **My media player is not available or not playing**
+# My media player is not available or not playing
 
 Review the list of player providers. If your device doesn't support one of the listed protocols then it won't currently work. Review the [GitHub Discussions](https://github.com/orgs/music-assistant/discussions) to see if others have requested support and join in the conversation.
 
 If your device does support one of the supported protocols then review the documentation for that player provider for known issues and troubleshooting tips.
 
 If your device still doesn't work and you think it should then review the full logs for discovery information and errors. Review the first things to try at the top of this page as usually if you get this far without identiying why the player isnt working it will be a networking or non-standard installation issue which, generally, you will need to resolve. Search the Github [Issues](https://github.com/orgs/music-assistant/issues), [Discussions](https://github.com/orgs/music-assistant/discussions) and [Discord](https://discord.gg/kaVm8hGpne)) as likely someone has asked your question before.
 
-# **All my media is missing** 
+# All my media is missing 
 
 Ensure the favourites filter is OFF. At the top of each view is a ❤️. Ensure it is hollow.
 
 If you are trying to view playlists through the HA media view then you should note that only favourited playlists will show up and additionally you need to have a MA player selected to see the MA Library. HA's media browser doesn't have any filter or sorting options like MA's frontend has.
 
-# **I don't see any tracks or albums for an Artist on a streaming provider** 
+# I don't see any tracks or albums for an Artist on a streaming provider
 
 See the [Usage and Music Provider notes](../usage.md)
 
-# **My local album art isn’t being picked up**
+# My local album art isn’t being picked up
 
 Art embedded in music tracks will always be picked up but folder.jpg images will only be imported if the folder name **exactly** matches the album (except for any characters that are prohibited in folder names. E.g. / )
 
-# **There isn't any metadata for my music**
+# There isn't any metadata for my music
 
 For local files, you can either fully tag your music (this is preferred and it is recommended to use [Picard](https://picard.musicbrainz.org/)) or have an artist folder with the artist.nfo in there (just like the images) and that will be preferred. Online metadata providers are only queried when there is no local data. https://kodi.wiki/view/NFO_files
 
-# **I have updated but MA looks like the old version or isn’t working**
+# I have updated but MA looks like the old version or isn’t working
 
 Possibly your browser is using a cached version of the front end. Try forcing a refresh Chrome, Firefox, or Edge for Windows: Press Ctrl+F5 (If that doesn’t work, try Shift+F5 or Ctrl+Shift+R).
 
 if the above doesn’t work look [here for some more options](https://www.webinstinct.com/faq/how-to-disable-browser-cache)
 
 For the IOS app see [here](https://community.home-assistant.io/t/anyone-know-how-to-clear-cache-in-the-ios-app/64569/10)
 
-### **The second zone of my amplifier is not seen by MA or MA won't turn on my amplifier**
+# The second zone of my amplifier is not seen by MA or MA won't turn on my amplifier
 
 MA is an INPUT to your amplifier. So you need to power on your amplifier and then select the INPUT that MA is streaming to (e.g. Airplay, DLNA, Chromsecast). For this reason MA does not see the amplifier zones it only sees the compatible inputs of the amplifier. 
 
 Some amplifiers may auto turn on when a signal is detected so check the amplifier options. If this functionality is not available then you will need to power on the amplifier via another means. The power icons that are seen beside the players must be seen as starting and stopping the stream to the player not as physically powering on or off the device.
 
-### **My local music isn’t being imported or I’m seeing missing ID3 tag warnings in the logs** 
+# My local music isn’t being imported or I’m seeing missing ID3 tag warnings in the logs
 
 This is likely a tagging problem. See [here](../music-providers/filesystem.md/)