Merge pull request #59 from OzGav/main

Various improvements

docs/faq/how-to.md

@@ -1,10 +1,15 @@
+---
+title: Frequently Asked Questions - How Do I...?
+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).
 
 # 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.
+After a track has been played by MA once then data is retained for volumes to be normalised across all tracks being played. The setting in MA is the target level for the volume normalisation. 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. It is recommended to use a value between -23 and -17 LUFS (and -17 is the default 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)
 
@@ -48,6 +53,32 @@ Use the `media_player.play_media` service call shown above or `mass.play_media`
 
 Use the `mass.play_media` service call and set the `media_id` as the station name.
 
+# Play a Random Item
+
+Use mass search and an script/automation such as this:
+
+``` yaml
+alias: Random Album
+sequence:
+  - service: mass.search
+    data:
+      limit: 9
+      name: ARTISTNAME
+      media_type:
+        - album
+    response_variable: results
+  - service: mass.play_media
+    data:
+      media_id: "{{ results.albums[range(0, 8) | random].uri }}"
+    target:
+      device_id: XYZ
+mode: single
+```
+
+This could be modified for other item tyoes (e.g. tracks or playlists). 
+
+Thanks to [ministryofsillywalks](https://github.com/ministryofsillywalks) who showed us [here](https://github.com/orgs/music-assistant/discussions/1637#discussioncomment-9462085)
+
 # 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.
@@ -149,7 +180,7 @@ Trying to run MA with SSL is not recommended. Having said that, whilst you can n
 
 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/dashboards/iframe/)
 
 # Add a rotary encoder with push button to a piCorePlayer
 

docs/faq/troubleshooting.md

@@ -1,3 +1,8 @@
+---
+title: Troubleshooting
+description: Common Problems and Fixes
+---
+
 # 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.
@@ -49,7 +54,7 @@ Review the list of player providers. If your device doesn't support one of the l
 
 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 yourself. 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.
+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 yourself. Search the Github [Issues](https://github.com/music-assistant/hass-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 
 

docs/index.md

@@ -59,7 +59,7 @@ Connects Home Assistant to your Music Assistant Server to allow control from you
 [![Jozef](assets/team/jozef.png){ width=100 }](https://github.com/jozefKruszynski "Jozef. Author of the Tidal provider and Voice Search")
 [![Jonathan](assets/team/jonathan.png){ width=100 }](https://github.com/arctixdev "Jonathan. Author of the Deezer provider and the Companion App")
 [![Gavin](assets/team/gavin.png){ width=100 }](https://github.com/OzGav "Gavin. Community Support and Documentation")
-[![Marvin](assets/team/marvin.png){ width=100 }](https://github.com/marvinschenkel "Marvin. Author of the YouTube provider")
+[![Marvin](assets/team/marvin.png){ width=100 }](https://github.com/marvinschenkel "Marvin. Author of the YouTube and Apple Music providers")
 [![Giel](assets/team/gieljnssns.png){ width=100 }](https://github.com/gieljnssns "Giel. Author of the Soundcloud provider")
 [![Santiago](assets/team/santiago.png){ width=100 }](https://github.com/santiagosotoc "Santiago. Author of the Snapcast provider")
 [![khers](assets/team/khers.png){ width=100 }](https://github.com/khers "Eric. Author of the Subsonic provider")

docs/installation.md

@@ -55,9 +55,9 @@ ____________
 
 - You can access the frontend over https by following these steps:
 
-1. Expose the webserver via MA settings>>Core>>webserver
+  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. 
+  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>

docs/music-providers/filesystem.md

@@ -1,3 +1,8 @@
+---
+title: File System Provider
+description: Features, Configuration, Issues and More for the File System Player Provider
+---
+
 # Filesystem Provider ![Preview image](../assets/icons/localfiles-icon.png){ width=70 align=right }
 
 Music Assistant has full support for reading your own (local) music files on disk or a remote server and catalogs it into the library, allowing playback to all player providers supported by Music Assistant. 
@@ -44,7 +49,7 @@ Music Assistant has support for SMB (also known as samba or CIFS) shares and DFS
 
 ## Tagging Files 
 
-- It is very important that all of your audio files contain proper [ID3 tag](https://en.wikipedia.org/wiki/ID3) information. The more comprehensive the tagging the better the results will be when using MA. For this reason it is strongly recommended that all files are tagged with [MusicBrainz Picard](https://picard.musicbrainz.org). This will ensure consistency and completeness of the tags that MA needs to work best. Other programs such as Mp3Tag are often also based on the Musicbrainz catalog and can work as well provided they include ISRC and all MBID tags.
+- It is very important that all of your audio files contain proper [ID3 tag](https://en.wikipedia.org/wiki/ID3) information. The more comprehensive the tagging the better the results will be when using MA. For this reason it is strongly recommended that all files are tagged with [MusicBrainz Picard](https://picard.musicbrainz.org). This will ensure consistency and completeness of the tags that MA needs to work best. Other programs such as [Mp3Tag](https://www.mp3tag.de/en/) are often also based on the Musicbrainz catalog and can work as well provided they include ISRC and all MBID tags.
 - Music Assistant puts you in control by fully trusting the ID3 tags you provide, only additional information is scraped from metadata providers.
 - Music Assistant has support for both embedded artwork and artwork stored in a common folder structure of Artist \ Album and .nfo files with enhanced metadata are also supported.
 - Files simply dumped into a random structure will also be imported but no other data will be retrieved from the folder structure.
@@ -54,4 +59,15 @@ Music Assistant has support for SMB (also known as samba or CIFS) shares and DFS
 
 ![image](../assets/screenshots/no-disc-tag.png)
 
+### Manually Adjusting Tags
+
+!!! danger
+    The following should be considered as advanced. Making manual changes to the tags can have undesired effects to the MA library if you make mistakes. Additionally, matching may not occur or may occur incorrectly between providers.
+
+Normally it is best to leave the Picard tags unchanged. However, some people do not agree with Musicbrainz that [remasters are the same as the original recording.](https://musicbrainz.org/doc/Style/Recording#Recordings_with_different_mastering) To separate these out you can edit the tags as follows:
 
+- Remove MusicBrainz Release ID and Recording ID
+- Keep MusicBrainz Artist ID
+- Remove ISRC (as that is also used as strong identifier for tracks)
+- Remove barcode (as that is also used as strong identifier for albums)
+- Because there is no version specific ID3 tag, place the version between brackets in the title. For example, Great Song (Vinyl Rip)

docs/player-support/index.md

@@ -1,3 +1,8 @@
+---
+title: Player Support
+description: Information Relevant to all Player Providers 
+---
+
 # Player Providers
 
 For specific player provider information refer to the relevant section in this document. Most players are enabled by default and will be automatically discovered by Music Assistant.
@@ -6,6 +11,9 @@ If a device supports multiple protocols then multiple players for the device wil
 
 ![Preview image](../assets/screenshots/player-disable.png){ width = 600 } 
 
+!!! note
+    If any player is not transitioning between somgs then check if the player has the option QUEUE FLOW MODE. Try enabling it if it does.
+
 ## Audio Quality
 
 Audio quality is the principal reason why native MA players are developed. These players provide the highest quality playback experience. HA players will work and may work well but they may also have been written with a basic objective such as enabling text to speech. Therefore, if there is a MA player available and a HA integration then you should always choose the MA player. 

docs/ui.md

@@ -1,3 +1,8 @@
+---
+title: User Interface
+description: A Walkthrough of the Music Assistant User Interface
+---
+
 # User Interface
 
 ## Main Menu
@@ -17,7 +22,7 @@ When visiting Browse you will only see what is already in the Library of the Str
 
 Searches can be done via any combinbination of words or partial words and also via a URL to a provider such as `https://open.spotify.com/album/0BwWUstDMUbgq2NYONRqlu` 
 
-Results are returned in the six categories of Top Results, Tracks, Artists, Albums, Playlists and Radio. Context sensitive menus are available for the various items.
+Results, limited to a maximum of 50 items, are returned in the six categories of Top Results, Tracks, Artists, Albums, Playlists and Radio. Context sensitive menus are available for the various items.
 ***************************************************************
 
 ## Player Bar