Merge pull request #51 from OzGav/main

Various changes

docs/faq/how-to.md

@@ -84,6 +84,8 @@ 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.
 
+M3U, M3U8 and PLS playlists are supported.
+
 # 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

docs/faq/massannounce.md

@@ -9,7 +9,7 @@ This service call allows you to send audio announcements via a URL to a player.
 ![image](../assets/screenshots/service-call/play_announcement.png)
 
 !!! note
-    For sending text messages use the HA TTS service calls and target the MA media player entity
+    For sending text messages use the HA TTS service calls and target the MA media player entity. There are a number of options available to control the volume of announcements in the MA settings for each player.
 ```
 service: tts.google_say
   data:

docs/index.md

@@ -1,6 +1,6 @@
 # Music Assistant
 
-![MA Banner](assets/MA_banner.png)
+![Banner](assets/banner.png)
 
 Music Assistant is a music library manager for your offline and online music sources which can easily stream your favourite music to a wide range of supported players and be combined with the power of Home Assistant!
 
@@ -31,6 +31,8 @@ Music Assistant consists of multiple building blocks:
 
 The Music Assistant server is a free, opensource Media library manager that connects to your streaming services and a wide range of connected speakers. The server is the beating heart, the core of Music Assistant and it keeps track of your music sources. It must run on an always-on device like a Raspberry Pi, a NAS or an Intel NUC or alike. The server can access multiple music providers and stream to multiple player types.
 
+![MA Banner](assets/MA_banner.png)
+
 ## Music Assistant Integration
 
 Connects Home Assistant to your Music Assistant Server to allow control from your HA instance, allow you to automate your music and allows voice control! The Integration also allows the exposure of HA media players to MA furthering the options you have for playback.

docs/installation.md

@@ -22,6 +22,9 @@ Using [HAOS](https://developers.home-assistant.io/docs/operating-system/). If yo
 
 Using [HAOS](https://developers.home-assistant.io/docs/operating-system/). Go to the [Home Assistant Integration](integration/installation.md) page and follow the instructions there which will install the integration and the server (as an addon).
 
+!!! note 
+    When using this method (and ticking the `Use the official Music Assistant server add-on` checkbox) the Integration will install the server and auto update it. The server will be uninstalled if the Integration is removed. The server will be shutdown if the Integration is disabled. You will not be able to manually uninstall the server and if you manually shut it down it will be restarted.
+
 ## Tertiary installation method: Docker image
 
 An alternative way to run the Music Assistant server is by running the docker image:
@@ -42,8 +45,6 @@ ____________
 
 - The server itself hosts a very simple webserver to stream audio to devices. This webinterface must be accessible via HTTP (no HTTPS) by IP-address from local players. See the server's logging at startup to see if the server has correctly auto-detected the local IP.
 
-- The server itself hosts a websocket API and a JSON RPC API which is more or less compatible with LMS, however, you cannot run a separate LMS server on your network if the MA slimproto provider is enabled. The Music Assistant fronted communicates with the server using the websockets API.
-
 - You cannot run the slimproto integration in Home Assistant if the slimproto provider is emabled.
 
 - 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!)
@@ -60,11 +61,12 @@ ____________
 ## 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 (although the port can be exposed in the settings).
+- No providers are installed initially. You must navigate to the MA settings and add the providers (Music and Players) that you use.
 - 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 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.
+- 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. This can be seen by this symbol ![icon](assets/icons/sync-icon.png) next to the Music Provider entry in MA settings.
 - Music sources are synced at addon (re)start and every 3 hours (or other interval as selected in the settings).
-- 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.
+- 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. Highest quality is based on sample rate, bit depth and codec and local is preferred over cloud.
 - 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 privileged mode and HOST network mode. Note: If the default port 8096 is occupied, the next port will be tried, and so on.
 
 [repository-badge]: https://img.shields.io/badge/Add%20repository%20to%20my-Home%20Assistant-41BDF5?logo=home-assistant&style=for-the-badge

docs/integration/installation.md

@@ -8,10 +8,10 @@
 - Restart Home Assistant.
 - Go to HA Settings>>Devices & services>>Integrations and click the big `+ ADD INTEGRATION` button.
 - Look for Music Assistant and click to add it.
-- In the configuration if you do not intend to use the voice features then leave the Conversation Agent as None and you do not need to check the "expose players to Assist" checkbox. If you do intend to use voice it is slightly easier if you do the steps as part of the Installation Requirements first (see below). If you don't do them first then you will have to come back later and reconfigure the Conversation Agent.
 - If Music Assistant does not show, refresh your browser (cache).
-- The Music Assistant integration is ready for use.
-- The MA server addon will be installed automatically if you are using HAOS.
+- If using HAOS tick `Use the official Music Assistant Server add-on` checkbox if you want the Integration to install and manage the server. If you don't tick this box then you must have already installed and have running the MA server. You will need the server IP which you can find in the server logs. For example, `http://172.30.32.1:8095/` 
+- If you do not intend to use the voice features then leave the Conversation Agent as None and you do not need to check the `Expose players to Assist` checkbox. If you do intend to use voice it is slightly easier if you do the steps as part of the Installation Requirements first (see below). If you don't do them first then you will have to come back later and reconfigure the Conversation Agent.
+- Click SUBMIT and the Music Assistant integration is ready for use.
 
 !!! note
     You need to set-up the players and music sources within Music Assistant itself.
@@ -21,7 +21,7 @@
 
 ## Installation of the Home Assistant Player Provider
 
-First you must install the Home Assistant Plug-in provider
+Once the HA Integration is installed it is possible to stream to HA media player entities. In order to do that you need to install the HA Player Provider.  First you must install the Home Assistant Plug-in provider
 
 - Navigate to MA SETTINGS>>PROVIDERS and add the plug-in provider
 - If using the Music Assistant add-on (i.e. HAOS), you wont need any server details, it should auto connect to the local HA instance

docs/music-providers/plex.md

@@ -2,8 +2,8 @@
 
 Music Assistant has support for using Plex (MusicLibrary). Contributed by [micha91](https://github.com/micha91)
 
-!!! warning 
-    Please be advised this provider is currently not maintained. Issues may take a long time to be resolved. Consider sharing your music directly with MA instead
+!!! note 
+    Please be advised that this provider currently has no dedicated developer. Issues may take longer to resolve as this will be maintained on a best effort basis. Consider sharing your music directly with MA instead
 
 ## Configuration
 

docs/player-support/slimproto.md

@@ -14,6 +14,6 @@ This means you can use squeezebox players directly with Music Assistant. This ap
 
 ## Known Issues / Notes
 
-- Make sure that you do not have Logitech Media Server running
+- Running LMS on the same server as MA with the MA slimproto provider enabled can have undesired effects
 - Make sure that you do not have the "slimproto" integration running in Home Assistant
 - Ordinarily do not use flow mode unless using older squeezebox hardware player that has issues transitioning. Enabling flow mode may solve playback issues however it might come with the side effect of disabling actual physical buttons and/or display of metadata on the device itself

docs/player-support/snapcast.md

@@ -14,14 +14,14 @@ MA includes a built-in Snapserver although an external server can also be used.
 
 ## Known Issues / Notes
 
-- The Snapcast provider is not enabled by default. A built-in Snapserver with the Snapweb option is launched when this provider is added. Once enabled the workings of the server are transparent and the clients appear in the MA UI
-- Music Assistant only supports Snapcast version 0.27.0 (or newer)
-- The Snapcast provider will use the built-in Snapserver by default although a switch in the settings allows the use of an external server if desired. When using an external server the server IP and port must be entered.
+- The Snapcast provider will use the built-in Snapserver by default although a switch in the settings allows the use of an external server if desired. When using an external server the server IP and port must be entered. 
+- Music Assistant only supports external Snapcast servers running version 0.27.0 (or newer). If using an external server ensure it is launched with the command "snapserver -v".
+- If not using an external server then the built-in Snapserver with the Snapweb option will be launched when this provider is added. Once enabled the workings of the server are transparent and the clients appear in the MA UI.
+- Clients are created by pointing a browser or Snapdroid at `<YOUR_MA_IP_ADDRESS>:1780`. The browser tab must remain open to maintain the stream.
+- Client names for all clients can be adjusted in Snapweb and Snapdroid via their respective UIs. Additionally, it is possible to rename the players in the MA settings.
 - The built-in Snapserver can only accept connections from Music Assistant
 - If it is necessary to adjust the latency of a client, it must be done from another interface such as Snapdroid or Snapweb
 - Pausing the player is NOT supported. If you try and do that you will get weird behaviour.
 - The Snapcast app for iOS is broken as it uses an old version of Snapclient. Using it brings problems with this provider
-- If using an external server ensure it is launched with the command "snapserver -v".
 - Ensure that the ports 1704 and 1705 on the Snapserver host are open. Also ensure that for each client a port equal to or greater than 4953 is open
 - Try the default Snapcast settings and then make changes as necessary.
-- Client names for all clients can be adjusted in Snapweb and Snapdroid via their respective UIs

docs/player-support/sonos.md

@@ -11,3 +11,4 @@ Music Assistant has support for Sonos devices.
 ## Known Issues / Notes
 
 - Issues have been reported with the Sonos Arc and Unifi networking equipment. Ensure Multicast DNS and IGMP snooping are turned on if you have problems
+- Using the Sonos HA Integration at the same time as the MA player provider may cause problems. Recommend only using the MA player provider.

docs/release.md

@@ -14,7 +14,16 @@ Once 2.0 is released, the beta for version 2.1 will be available. It is possible
 
 There is also a dev/nightly add-on which can be run to get the absolute latest version but this comes with risk of intermittent problems during the development cycle.
 
-It is possible to run the stable, beta or dev server add-ons side by side if desired as they don't share any data. Thus you can temporarily run the beta add-on to try out new features and then revert to the stable version.
+!!! warning
+    This next section is for ADVANCED users. If you make a mistake you will have to remove all versions of the addon and start again. Be WARNED!
+
+### Running Parallel Server Versions
+
+It is possible to run the stable, beta or dev server add-ons side by side as they don't share any data. Thus you can temporarily run the beta add-on to try out new features and then revert to the stable version. You can do this in one of two ways:
+
+1. If you setup the Integration with the `Use the official addon` checkbox ticked then disable the HA Integration which will stop the stable server. Now start the Beta/Dev server. Reverse this process to restore the stable server.
+
+2. If you setup the HA Integration without selecting `Use the official addon` checkbox then you will have to manually start and stop the relevant servers
 
 ## HA Integration
 

docs/usage.md

@@ -1,3 +1,13 @@
+## Online Metadata Sources
+
+Music Assistant relies heavily on metadata to work well and it gets this information from locally tagged files and online sources. The free online resources have limits and MA is often hitting those limits so further restrictions have been put in place. This means that:
+
+- Online resources will only be queried on the (first) open or play of an item
+- No more background scanning for missing metadata
+- Users with local files that are badly tagged or without images in the music folders will see no more artist thumbs
+- If a user has no album artist tag, we no longer try to look it up in musicbrainz
+- Simply default to various artists if the album artist tag is missing in local files
+
 ## The Library
 
 The Music Assistant Library is a database containing details of the music which the user has indicated they are interested in listening to on a regular basis. It consists of information about Artists, Albums, Tracks, Playlists and Radio Stations which allows easy searching, display and cross referencing across the User Interface.