Merge pull request #12 from OzGav/main

Various changes

docs/Installation.md

@@ -1,14 +1,14 @@
-## Installing the Server
+# 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.
 
 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 Integration Installation
+## Primary installation method: Home Assistant Integration Installation
 
 Go to the [Home Assistant Integration](integration.md) page and follow the instructions there which will install the integration and the server.
 
-### Secondary installation method: Home Assistant Add-on Manual Installation
+## Secondary installation method: Home Assistant Add-on Manual Installation
 
 If you dont need the HA Integration but want to run the Music Assistant Server then install the Music Assistant Add-on manually:
 
@@ -18,7 +18,7 @@ If you dont need the HA Integration but want to run the Music Assistant Server t
 [![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)
 
 
-### Tertiary installation method: Docker image
+## Tertiary installation method: Docker image
 
 An alternative way to run the Music Assistant server is by running the docker image:
 
@@ -32,7 +32,7 @@ Note that accessing remote (SMB) shares can be done from within MA itself using
 
 ____________
 
-### Server Notes
+## Server Notes
 
 - Because the server heavily relies on multicast techniques like mDNS and uPnP to discover players in your network it MUST be run in the same Layer 2 network as your player devices.
 
@@ -62,13 +62,5 @@ ____________
 - 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.
 - See the [GitHub discussion](https://github.com/orgs/music-assistant/discussions/710#discussioncomment-7987528) for more detailed information
 
-## Support and Documentation
-
-Because this project originated out of a Home Assistant integration, we maintain all our documentatation and enduser support in a separate reposity. Raise issues and discuss ideas here:
-https://github.com/music-assistant/hass-music-assistant
-
-You can also seek help on [Discord](https://discord.gg/kaVm8hGpne)
-
-
 [repository-badge]: https://img.shields.io/badge/Add%20repository%20to%20my-Home%20Assistant-41BDF5?logo=home-assistant&style=for-the-badge
 [repository-url]: https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fmusic-assistant%2Fhome-assistant-addon

docs/faq/how-to.md

@@ -1,36 +1,36 @@
-### **How do I Use Assist and AI to Play my Music?**
+# **Use Assist and AI to Play my Music?**
 
 See [here](../integration.md)
 
-### **How do I 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)
 
-### **How do I 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
 
-### **How do I 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.
 
-### **How do I stream to my browser**
+# **Stream to my browser**
 
 Use a [Snapserver](../player-support/snapcast.md) and the Snapweb option.
 
-### **How do I have my music continue if I change rooms**
+# **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 [here](https://github.com/orgs/music-assistant/discussions/702)
+You can read, ask or contribute [on this topic](https://github.com/orgs/music-assistant/discussions/702)
 
-### **How do I 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 +41,7 @@ data:
   shuffle: true
 ```
 
-### **How do I 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 +54,19 @@ data:
 
 See also how to use the mass.play_media service call
 
-### **How do I 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.
 
-### **How do I 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.
 
-### **How do I 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.
 
-### **How do I 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 +75,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. 
 
-### **How do I 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 +98,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.
 
-### **How do I 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
 
-### **How do I 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
 
-### **How do I use MA with Mopidy**
+# **Use MA with Mopidy**
 
 See here https://github.com/music-assistant/hass-music-assistant/discussions/439
 
-### **How do I use the MA service call `mass.play_media`**
+# **Use the MA service call `mass.play_media`**
 
 See [here](massplaymedia.md)
 
-### **How do I use the MA service call `mass.search`**
+# **Use the MA service call `mass.search`**
 
 See [here](masssearch.md)
 
-### **How do I get the URI?**
+# **Get the URI?**
 
 For playlists, artists, albums and radio you can simply use the name.
 
@@ -134,16 +134,16 @@ data:
 
 Similarly, if the album name is ambiguous you can specify the artist name first (`Queen - Greatest Hits`)
 
-### **How do I 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.
 
-### **How do I 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/
+If you are using docker then you can use an [iframe panel](https://www.home-assistant.io/integrations/panel_iframe/)
 
-### **How do I 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
+See [here](https://github.com/orgs/music-assistant/discussions/1123#discussioncomment-7945369)

docs/faq/normalization.md

@@ -1,4 +1,8 @@
-# Volume Normalization
+# Technical Information
+
+This section contains more indepth technical information regarding Music Assistant's workings for those interested.
+
+## Volume Normalization
 
 The normalization value to totally avoid clipping should be -23 LUFS based on this official documentation https://tech.ebu.ch/docs/r/r128.pdf but values differ per plattform so it is complicated to get the right value.
 
@@ -16,4 +20,17 @@ All tracks are processed as raw pcm by Music Assistant internally. So everything
 
 All further processing in MA is done at PCM raw audio level, such as the optional equalizer (in the future maybe some room correction or other filters) - if "flow mode" is enabled crossfading is also done on the raw pcm chunks but that will upsample all audio into one static sample rate and bit depth to create one "flow" of audio to send to the player.
 
-The final part in the chain is that MA sends either the raw pcm data to the player or encodes it into a codec of the user's choice, by default this is FLAC due to it being lossless while keeping a reasonable file size.
+The final part in the chain is that MA sends either the raw pcm data to the player or encodes it into FLAC due to it being lossless while keeping a reasonable file size.
+
+## Track Queueing
+
+MA has 3 ways of enqueuing tracks to players:
+
+**BASIC/FALLBACK**
+send tracks from the queue one by one. We just watch the player and if we see that it stopped playing at the end of a track, we tell it to play the next. This is the most basic form of enqueuing and completely handled by the MA queue controller and thus works with ALL players. This will NOT support gapless or crossfade. This setting is the default if the player has no native enqueue support or flow mode enabled. By default DLNA players use this option as well as the upcoming Home Assistant based players. Full metadata is sent to the player of what is playing.
+
+**NATIVE ENQUEUE SUPPORT**
+The player has native enqueue support so we tell it what the next track will be right before the current one ends. This is a special feature that not all players support. Its supported (and by default enabled) for Slimproto, Google Cast and Sonos players. Some DLNA players support it but others don't so we offer a player setting to enable it so a user can try himself if the player accepts it. benefit is full support gapless playback and in case of Slimproto and Sonos also crossfade. Also full metadata will be sent to the player what is currently playing.
+
+**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.