Merge pull request #9 from OzGav/main

Second pass of existing info

docs/Installation.md

@@ -1,6 +1,6 @@
 ## Installing the Server
 
-Music Assistant can be operated as a complete standalone product but it is actually tailored to use side by side with Home Assistant, it is meant with automation in mind, hence our recommended installation method is to run the server as Home assistant Add-on which will be automatically installed when you add the Home Assistant Integration.
+Music Assistant (MA) can be operated as a complete standalone product but it is actually tailored to use side by side with Home Assistant. MA is built with automation in mind, hence our recommended installation method is to run the server as a Home assistant Add-on which will be automatically installed when you add the Home Assistant Integration.
 
 MA requires a 64bit Operating System and a minimum of 2GB of RAM on the physical device or the container (physical devices are recommended to have 4GB+ if they are running anything else)
 
@@ -38,23 +38,24 @@ ____________
 
 - 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. The Music Assistant fronted communicates with the server using the websockets API.
+- 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 at the same time as MA. The Music Assistant fronted communicates with the server using the websockets API.
 
-- 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 (hence you also get the sidepanel for free)
+- 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!)
 
 - 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. 
 
 !!! tip 
-    You can also 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, e.g. <http://d5369777-music-assistant-beta:8095>
+    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.
 - 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 favourited artists, albums and playlists. In a later release we'll provide options to browse the recommendations of the various streaming providers.
-- Items on disk are not favourited by default. You can see all items if you deselect the "in library" filter (the heart) and decide for yourself what you want in your favourites.
+- 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.
 - 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.

docs/companion-app.md

@@ -33,22 +33,22 @@
 
 
 !!! tip "This is still in very early alpha. Bugs *will* be present."
-    Please help finding them, you can report any bugs on the [Discord server](https://discord.gg/kaVm8hGpne) or in the [repo issues](https://github.com/music-assistant/music-assistant-desktop/issues)
+    Please help finding them. You can report any bugs on the [Discord server](https://discord.gg/kaVm8hGpne) or in the [repo issues](https://github.com/music-assistant/music-assistant-desktop/issues)
 
 ## Setup
 
-When starting the app for the first time you are asked about some information about the Music Assistant Server.
+When starting the app for the first time you are asked for some information about the Music Assistant Server.
 
 ![image](https://github.com/Un10ck3d/massapp/assets/74015378/cb97aa3e-12d8-4992-bfc6-0b58cedb81da)
 
-!!! example "The app requires that the webserver is exposed. You can set that in the settings"
+!!! note "The app requires that the webserver is exposed. You can set that in the settings"
     ![How to fix](https://raw.githubusercontent.com/music-assistant/music-assistant-desktop/main/cant_connect_error.gif)
 
 ## Features
 
 ### [Squeezelite](https://en.wikipedia.org/wiki/Squeezelite)
 
-Squeezelite comes embedded into the application. This allows you playing music to your computer. The player name will be the same as your computer name. You can change the name in Music Assistant settings. You can also toggle if you wish to enable squeezelite at all.
+Squeezelite comes embedded in the application. This allows playback of music to your computer. The player name will be the same as your computer name. You can change the name in Music Assistant settings. You can also toggle if you wish to enable squeezelite at all.
 
 ### [Discord Rich Presence](https://discord.com/developers/docs/rich-presence/how-to#so-what-is-it)
 
@@ -66,7 +66,7 @@ This app is on the arch aur with the name `music-assistant-desktop` or `music-as
 
 You can install it with yay: `yay music-assistant-desktop-bin`
 
-### Debian (And debian based distrobutions)
+### Debian (And debian based distributions)
 
 You can download the .deb from the [releases](https://github.com/Un10ck3d/massapp/releases/latest/).
 
@@ -79,7 +79,7 @@ You can download the AppImage from the [releases](https://github.com/Un10ck3d/ma
 You can download the .dmg from the [releases](https://github.com/Un10ck3d/massapp/releases/latest/).
 
 
-!!! danger "The app is unsigned since we currently dont want to spend 90 USD/yr for an Apple Developer account."
+!!! danger "The app is unsigned since we currently don't want to spend 90 USD/yr for an Apple Developer account."
     Therefore it will warn you about an untrusted developer/app downloaded from internet. To open it follow [these instructions](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac)
 
 ### Windows

docs/faq/how-to.md

@@ -18,6 +18,8 @@ Install a squeeze lite compatible application to your mobile or other devices  (
 
 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.
+
 ### How do I stream to my browser
 
 Use a [Snapserver](../player-support/snapcast.md) and the Snapweb option.

docs/integration.md

@@ -20,6 +20,7 @@ Make sure to install at least the 2023.6.bx BETA version of the Music Assistant
 - Look for Music Assistant and click to add it.
 - 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.
 
 !!! note
     You need to set-up the players and music sources within Music Assistant itself.
@@ -32,6 +33,7 @@ Make sure to install at least the 2023.6.bx BETA version of the Music Assistant
 During [Chapter 5 of "Year of the Voice"](https://www.youtube.com/live/djEkgoS5dDQ?si=pt8-qYH3PTpsnOq9&t=3699), [JLo](https://blog.jlpouffier.fr/chatgpt-powered-music-search-engine-on-a-local-voice-assistant/) showed something he had been working on to use the OpenAI integration along with Music Assistant. Note that this originally worked by using custom intents and it was difficult to reliably specify a player or an area for the music to be sent to. For this reason the functionality is built into the MA Integration.
 
 **Installation Requirements**
+
 - You need to be running the latest BETA of the HA Integration
 - You need a voice assistant configured (even if you want to just type in the query)
 - You need to create/add another OpenAI integration that is purely for Music Assistant.
@@ -65,6 +67,9 @@ Other examples that work are (this is not an exhaustive list):
 `Play Journey Don’t stop believing in the Study on the media player`
 `In the Study on the speaker listen to Journey Don’t Stop Believing`
 
+!!! note
+    When adding a track it will be added to the top of the existing queue and played immediately. In all other cases the queue will be cleared and the requested music will then be added and playback will commence.
+
 **Troubleshooting**
 
 - If when trying to play to a specific player using the friendly name you receive “An unexpected error occurred while handling the intent” try adding an alias to the MA media player entity (which can be identical to the friendly name).

docs/music-providers/deezer.md

@@ -8,9 +8,9 @@ Music Assistant has support for [Deezer](https://www.deezer.com/). Contributed a
 
 ## Supported features
 - Searching from the Music Assistant interface support Artists, Albums, Tracks and Playlists.
-- Items in your Deezer library will be marked as a "Favorite" in Music Assistant.
-- Marking an item as a "Favorite" from the Music Assistant interface will also mark it as a favorite in Deezer.
-- Playback of Deezer content to all players supported by Music Assistant is in FLAC HiFi.
+- Items in your Deezer Favourites will be imported into the MA Library amd automatically marked as a "Favorite" in MA.
+- If you add an item from Deezer to the MA library then nothing will happen in Deezer unless you also mark it as a favourite (at which time the item will be added to the Deezer favourites)
+- Playback of Deezer content to all players supported by Music Assistant is in FLAC.
 - Artist, Album, Track and Playlist metadata is fully supported.
 - Playlist creation is possible as well as adding and removing tracks from existing playlists.
 - Easy oAuth login

docs/music-providers/youtube-music.md

@@ -2,24 +2,24 @@
 
 Music Assistant has support for Youtube Music. Contributed by @MarvinSchenkel.
 
-## Features and generic notes
+!!! danger "DISCLAIMER"
+    Please note that Youtube does not offer an official API to retrieve data and streams. This means that everything is built on a best-effort basis. Unexpected behavior will occur whilst using this provider. For this reason if you have another streaming provider you may find it more convenient to use that instead of this one.
 
-!!! tip "Note"
+!!! note
     Free accounts are NOT supported.
 
+## Features and Notes
+
 There is no support for the disc and track number in album tracks listings. Currently, the disc number is always 0 and the track number is the order number in which the tracks were returned by Youtube Music. This should generally give the desired result, but could mess up multi-disc albums.
 
 Whether music videos are selected for playback fully depends on what you are playing. If you have saved a specific album in your library, then that exact version will show up in MA and thus you will have the album version. However, if you start a radio on let's say a playlist, then Youtube Music decides which songs will be played in a 'dynamic radio' playlist which could include videos.
 
-The highest available stream from Youtube Music will be selected for playback (similar to configuring 'high' in the web-app). This then gets re-encoded by MA to a (default) lossless FLAC (assuming you have this as the output codec (which it is by default))
+The highest available stream from Youtube Music will be selected for playback (similar to configuring 'high' in the web-app). This then gets re-encoded by MA to a (default) lossless FLAC (assuming you have this as the output codec (which it is by default)).
 
-Uploaded Music should be able to be found when it is in a playlist. If it's just a single track being searched for then it may not be found, since often those uploaded songs don't have proper metadata. It will be hard to find them via the UI in MA
-
-!!! danger "DISCLAIMER"
-    Please note that Youtube does not offer an official API to retrieve data and streams. This means that everything is built on a best-effort basis. Unexpected behavior will occur whilst using this provider. For this reason if you have another streaming provider you may find it more convenient to use that instead of this one.
+Uploaded Music should be able to be found when it is in a playlist. If it's just a single track being searched for then it may not be found, since often those uploaded songs don't have proper metadata. It will be hard to find them via the UI in MA.
 
-## Installation instructions
-Music Assistant 2.0 uses OAuth for Youtube Music, which means login is axcomplished just like is done on Gmail for example. To add the Youtube Music provider to MA:
+## Installation Instructions
+Music Assistant uses OAuth for Youtube Music, which means login is axcomplished just like is done on Gmail for example. To add the Youtube Music provider to MA:
 
 - Navigate to 'Settings'
 - Under Music Providers, click 'Add new', select 'Youtube Music' and click 'Authenticate with Youtube Music'

docs/player-support/airplay.md

@@ -1,10 +1,8 @@
 # Airplay
-
-Available since version: 2.0.0b1
 
-Music Assistant has support for Airplay based devices. This includes Apple devices such as the Homepod but also a very wide range of 3rd party devices such as receivers and smart speakers. Due to the fact that Airplay uses lossless, timestamped streaming it is a very interesting protocol for lossless multi room streaming.
+Music Assistant has support for Airplay based devices. This includes Apple devices such as the Homepod but also a very wide range of 3rd party devices such as receivers and smart speakers. Due to the fact that Airplay uses lossless, timestamped streaming it is a very interesting protocol for lossless multi room playback.
 
-The Airplay provider within Music Assistant is based around the [fantastic work of Philippe44](https://github.com/philippe44/LMS-Raop), who created a bridge between slimproto and Airplay. Due to that fact, using Airplay in Music Assistant also requires the slimproto provider. Added benefit is that you can combine slimproto based devices (such as squeezelite, picoreplayer and original squeezebox hardware) with Airplay devices and play audio in sync.
+The Airplay provider within Music Assistant is based around the [fantastic work of Philippe44](https://github.com/philippe44/LMS-Raop), who created a bridge between slimproto and Airplay. Due to this fact, using Airplay in Music Assistant also requires the slimproto provider. The added benefit of this is that you can combine slimproto based devices (such as squeezelite, picoreplayer and original squeezebox hardware) with Airplay devices and play audio in sync.
 
 ## Features
 
@@ -14,15 +12,16 @@ The Airplay provider within Music Assistant is based around the [fantastic work
 - Audio quality is lossless 44.1/16bits PCM and optionally compressed as (lossless) ALAC
 - Any physical control buttons on the device should be  supported as long as flow mode is not enabled. 
 
-## Known issues / notes
+## Known Issues / Notes
 
 - Music Assistant implements RAOP (airplay 1) only, Airplay 2 devices should be backwards compatible by default.
-- If you are using Shairport then ensure you have disabled Airplay V2.
+- Whilst it is believed to have been fixed, issues have been reported when using Shairport and Airplay V2. If problems are encountered they try disabling Airplay V2.
 - To enable playback to a Macbook, you need to enable access to "everyone on the same network" in the Airplay settings of the Macbook.
 - Because Apple TV's require authentication, they are not supported yet (but will be in the future if there's any demand).
+- Samsung seems to have implemented AirPlay 2 in a way that it isn't fully backwards compatible. Everything seems to work, changing volume, song info is shown, and you can control the samsung device as expected, however there is no sound. Users of similar applications such as Roon and anything based on slimproto have the same problem. 
 
 ## Troubleshooting/tips
 
 - Some devices (such as Kodi or some 3rd party airplay receivers) require encryption. You can enable encryption in the player settings.
 - In settings you can disable any devices you do not use.
-- If you find your player is going unavailable when still powered on then it may not be sending its keep alive message. A timeout can be configured for each player. Some users have reported they have needed to set it as long as one hour.
+- If you find your player is going unavailable when still powered on then it may not be sending its keep alive message. A timeout can be configured for each player. Some users have reported they have needed to set it as long as one hour.