Merge pull request #61 from OzGav/main

Various improvements

docs/faq/how-to.md

@@ -5,7 +5,7 @@ description: Common Uses for Music Assistant
 
 # Use Assist and AI to Play my Music?
 
-See [here](../integration/installation.md#openai-features). This adds a PLAY command. The core HA voice intents support NEXT TRACK, PAUSE, UNPAUSE and VOLUME to a specific player. Until all of the media player service calls are supported by HA (including to areas) you can use custom sentences. See this [discussion for how](https://github.com/orgs/music-assistant/discussions/2176).
+See [here](../integration/installation.md#openai-features). This adds a PLAY command to a specific player. The core HA voice intents support NEXT TRACK, PAUSE, UNPAUSE and VOLUME to a specific player or to an area. Until all of the media player service calls are supported by HA (including to areas) you can use custom sentences. See this [discussion for how](https://github.com/orgs/music-assistant/discussions/2176).
 
 # Use volume normalization? How does it work?
 

docs/faq/normalization.md → docs/faq/tech-info.md

@@ -1,3 +1,8 @@
+---
+title: Technical Information
+description: Indepth Information Regarding Certain MA Functions
+---
+
 # Technical Information
 
 This section contains more indepth technical information regarding Music Assistant's workings for those interested.
@@ -34,3 +39,17 @@ The player has native enqueue support so we tell it what the next track will be
 
 **FLOW MODE**
 As an alternative to native enqueuing we can also send one stream of audio to the player and let Music Assistant stitch the songs together (with gapless or crossfade). This mode is used by default for Airplay and snapcast and will be used by DLNA and Cast if crossfade gets enabled. Downside of this approach is that Google cast (and most DLNA players) looses metadata display (on the speaker itself). Some DLNA players support "icy metadata" which is what we send to inform what is playing. 
+
+## Player Perfect Sync
+
+Audio sync between speakers is only possible if there is accurate knowledge of the exact (millisecond-precise) timestamp a player played each audio frame. In practice there are 2 common strategies used to sync audio:
+
+1) Sending timestamped frames to each player - there is one master clock and audio frames are sent to each receiving device in a sync group including the timestamp. So each player will have knowledge when it should play each frame and it can drop or inject frames to keep in sync. This strategy is often used in the proprietary protocols such as Google Cast, Sonos, Roon RAAT, BluOS and even Apple Airplay (RAOP).
+This is by far the best (most precise) sync method because each player is responsible for sending the correct audio frames to the DAC (or digital transport).
+
+2) Server-side corrected sync. Each player is sent the audio stream from the centralized source and then the server keeps track of each player's latency and corrects it by pausing/forwarding, playing faster/slower or injecting frames. This is easier to implement because the only thing needed client-side is accurate progress reporting of the client (how many milliseconds it played) and the server contains all the centralized logic to keep the sync. This is used by, for example, slimproto (squeezebox) and snapcast.
+
+How well the time synchronisation works depends on multiple factors but often you will find that strategy 1 is superior to strategy 2 and/or strategy 2 needs tweaking to get it right. For instance on snapcast you often hear skipping (small disturbances to the sound while its adjusting) and slimproto works very poorly with wifi based devices due to changing player latency.
+
+RECOMMENDATION: To have the best synced audio experiences of players, try to stick with one ecosystem and, if possible, choose one of the options that implement strategy 1 (proprietary protocol).
+Airplay is favoured because it a very good sync protocol that originally was proprietary but has been reverse engineered. You can now have airplay targets in both commercially available audio gear (even high end equipment) and DIY devices. It outperforms all the strategy 2 stream protocols by a wide margin. The same applies to a $35 chromecast audio puck with the google cast protocol. It works really well out of the box.

docs/help/lokalise.md

@@ -2,7 +2,7 @@ If you're following the frontend repo, you may have seen that we are now using L
 
 [<img src="https://github.com/lokalise/i18n-ally/raw/screenshots/lokalise-logo.png?raw=true" alt="Lokalise logo" width="275px">](https://lokalise.com)
 
-At the time of writing MA is available in Danish 🇩🇰, Dutch 🇳🇱, English 🇬🇧, French 🇫🇷, German 🇩🇪, Hebrew 🇮🇱, Italian 🇮🇹 , Norwegian 🇳🇴, Polish 🇵🇱, Spanish 🇪🇸 and Ukranian 🇺🇦.
+At the time of writing MA is available in Czech 🇨🇿, Danish 🇩🇰, Dutch 🇳🇱, English 🇬🇧, French 🇫🇷, German 🇩🇪, Hebrew 🇮🇱, Italian 🇮🇹, Norwegian 🇳🇴, Polish 🇵🇱, Portuguese 🇵🇹, Russian 🇷🇺, Serbian 🇷🇸, Spanish 🇪🇸, Swedish 🇸🇪 and Ukranian 🇺🇦.
 
 We would love to support more languages, and we need your help to do so.
 

docs/installation.md

@@ -5,31 +5,24 @@ description: Installation guide for Music Assistant
 
 # Installing the Server
 
-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. Install using one of the three methods below.
+Music Assistant (MA) can be operated as a complete standalone product but it is actually designed to use side by side with Home Assistant. MA is built with automation in mind, hence the recommended installation method is to run the server as a Home assistant Add-on and then optionally [add the HA integration](https://music-assistant.io/integration/installation/). Install using one of the two methods below.
 
 
 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)
 
-## Primary installation method: Home Assistant Add-on Manual Installation
+## Primary installation method: Home Assistant Add-on
 
-Using [HAOS](https://developers.home-assistant.io/docs/operating-system/). If you dont need the HA Integration but want to run the Music Assistant Server then install the Music Assistant Add-on manually:
+This is only available when running [HAOS](https://developers.home-assistant.io/docs/operating-system/). To install the Music Assistant Add-on:
 
 1. Add the Music Assistant repository to your Home Assistant instance.
 
     [![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fmusic-assistant%2Fhome-assistant-addon)
 
 2. Install the Music Assistant add-on.
 
-[![Add Music Assistant as Add-on to Home Assistant.](https://my.home-assistant.io/badges/supervisor_addon.svg)](https://my.home-assistant.io/redirect/supervisor_addon/?addon=d5369777_music_assistant&repository_url=https%3A%2F%2Fgithub.com%2Fmusic-assistant%2Fhome-assistant-addon)
-
-## Secondary installation method: Home Assistant Integration Installation
-
-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.
+    [![Add Music Assistant as Add-on to Home Assistant.](https://my.home-assistant.io/badges/supervisor_addon.svg)](https://my.home-assistant.io/redirect/supervisor_addon/?addon=d5369777_music_assistant&repository_url=https%3A%2F%2Fgithub.com%2Fmusic-assistant%2Fhome-assistant-addon)
 
-## Tertiary installation method: Docker image
+## Secondary installation method: Docker image
 
 An alternative way to run the Music Assistant server is by running the docker image:
 
@@ -64,7 +57,8 @@ ____________
 
 ## 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).
+- 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).
+- If you are running Music Assistant in docker, you need to access the webinterface at http://youripaddress:8095.
 - 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.

docs/player-support/snapcast.md

@@ -15,7 +15,7 @@ MA includes a built-in Snapserver although an external server can also be used.
 ## Known Issues / Notes
 
 - 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".
+- Music Assistant only supports external Snapcast servers running version 0.27.0 (or newer). If using an external server you can confirm the version by launching 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.