feat: improve defaults and project documentation

Author: KleoPadre

README.md

@@ -0,0 +1,49 @@
+# HomeWave
+
+HomeWave is a Home Assistant OS add-on that turns a Home Assistant host into a
+low-latency AirPlay 2 receiver. Audio is sent directly to Home Assistant's
+native PulseAudio service, so the platform's built-in audio-device selector
+remains the single place to choose the physical output.
+
+## Highlights
+
+- AirPlay 2 receiver powered by Shairport Sync and nqptp.
+- Native PulseAudio output with no ALSA fallback or duplicate sink selector.
+- Stable, low-latency defaults for `amd64`, `aarch64`, and `armv7`.
+- Per-stream 60 dB volume range: a practical silent minimum and full output at
+  the top of the AirPlay control.
+- Compact normal logs and optional diagnostics for troubleshooting.
+
+## Install
+
+In Home Assistant, open **Settings → Add-ons → Add-on Store → Repositories**
+and add:
+
+```text
+https://github.com/KleoPadre/homewave-ha
+```
+
+Install **HomeWave AirPlay 2**, select the output device in Home Assistant's
+audio-device selector, and start the add-on. Stop any other AirPlay receiver on
+the host before using HomeWave.
+
+## Settings
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `airplay_name` | `HomeWave` | Name displayed in the AirPlay receiver list. |
+| `audio_profile` | `stable` | Latency profile: minimal (0.10 s), standard (0.15 s), stable (0.30 s), or custom. |
+| `custom_buffer_seconds` | `0.15` | Buffer length for the custom profile, from 0.08 to 0.50 seconds. |
+| `offset_seconds` | `0.0` | Advanced timing correction from -2 to 2 seconds. Leave unchanged unless measured playback requires it. |
+| `interpolation` | `auto` | Resampling mode: auto, basic, or soxr. |
+| `default_airplay_volume` | `-24.0 dB` | Suggested initial source volume. AirPlay's range is mapped to a 60 dB per-stream curve. |
+| `diagnostics` | `false` | Enables detailed Shairport Sync statistics and debug logs. Keep disabled during normal use. |
+
+## Support and testing
+
+Use the `stable` profile first. If playback is reliable on a wired network, try
+`standard` or `minimal` for lower latency. If you encounter clicks or dropouts,
+return to `stable`, enable diagnostics, and review the add-on log.
+
+The add-on does not provide MQTT metadata or remote control in the 0.1 release
+series.

airplay2_lowlatency/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.3
+
+- Use the stable latency profile by default.
+- Keep normal logging concise and reserve detailed statistics for diagnostics.
+
 ## 0.1.2
 
 - Map the AirPlay volume control to a 60 dB per-stream attenuation range for a

airplay2_lowlatency/README.md

@@ -20,17 +20,17 @@ JohannVR, v3rm0n, or other Shairport Sync add-on before starting HomeWave.
 | Option | Allowed values | Default | Effect and safe correction |
 | --- | --- | --- | --- |
 | `airplay_name` | Non-empty text | `HomeWave` | Receiver name shown by AirPlay. |
-| `audio_profile` | `minimal`, `standard`, `stable`, `custom` | `standard` | Selects the buffer profile. Start with standard. |
+| `audio_profile` | `minimal`, `standard`, `stable`, `custom` | `stable` | Selects the buffer profile. Stable is recommended. |
 | `custom_buffer_seconds` | `0.08` to `0.50` | `0.15` | Used only by custom. Increase it when diagnostics show dropouts. |
 | `offset_seconds` | `-2` to `2` | `0.0` | Advanced playback synchronisation correction; change only after measurement. |
 | `interpolation` | `auto`, `basic`, `soxr` | `auto` | Advanced resampling. Keep auto unless diagnosing a device-specific issue. |
 | `default_airplay_volume` | `-30` to `0` dB | `-24.0` | Initial stream volume; never changes the global Home Assistant sink volume. |
 | `diagnostics` | `true`, `false` | `false` | Writes Shairport Sync statistics to the add-on log. Enable while investigating audio faults. |
 
 Latency profiles are `minimal` (0.10 seconds), `standard` (0.15 seconds),
-`stable` (0.30 seconds), and `custom` (0.08–0.50 seconds). Minimal is suitable
-for a stable wired network but may click on an unstable network. If standard
-clicks, enable diagnostics and try stable before lowering the buffer.
+`stable` (0.30 seconds), and `custom` (0.08–0.50 seconds). Stable is the
+recommended default. Minimal is suitable for a stable wired network but may
+click on an unstable network.
 
 AirPlay's `-30` to `0` dB control range is mapped to a 60 dB Shairport Sync
 attenuation range. This makes the lowest source setting practically silent and
@@ -46,6 +46,6 @@ For migration, stop and uninstall the prior receiver, install HomeWave, select
 the output device in Home Assistant, then start HomeWave. To roll back, stop
 HomeWave before re-enabling the former receiver. Do not run both at once.
 
-When troubleshooting, enable diagnostics, reproduce the issue, inspect the
-add-on log for underruns or overruns, then disable diagnostics after collecting
-the required information. Do not share logs containing private device names.
+Normal operation writes concise connection and error information to the add-on
+log. Enable diagnostics only for troubleshooting; it adds detailed statistics
+and debug-level messages. Do not share logs containing private device names.

airplay2_lowlatency/README.ru.md

@@ -19,17 +19,16 @@ HomeWave — аддон Home Assistant OS, принимающий аудио Air
 | Параметр | Допустимые значения | По умолчанию | Действие и безопасная коррекция |
 | --- | --- | --- | --- |
 | `airplay_name` | Непустой текст | `HomeWave` | Имя приёмника в AirPlay. |
-| `audio_profile` | `minimal`, `standard`, `stable`, `custom` | `standard` | Выбирает профиль буфера; начните со standard. |
+| `audio_profile` | `minimal`, `standard`, `stable`, `custom` | `stable` | Выбирает профиль буфера; рекомендуется stable. |
 | `custom_buffer_seconds` | от `0.08` до `0.50` | `0.15` | Используется только в custom; увеличьте при пропусках в диагностике. |
 | `offset_seconds` | от `-2` до `2` | `0.0` | Расширенная коррекция синхронизации; меняйте только после измерения. |
 | `interpolation` | `auto`, `basic`, `soxr` | `auto` | Расширенный ресемплинг; оставьте auto, если нет особой причины. |
 | `default_airplay_volume` | от `-30` до `0` дБ | `-24.0` | Начальная громкость потока; не меняет общую громкость Home Assistant. |
 | `diagnostics` | `true`, `false` | `false` | Выводит статистику Shairport Sync в журнал аддона. |
 
 Профили задержки: `minimal` (0.10 секунды), `standard` (0.15), `stable` (0.30)
-и `custom` (0.08–0.50). Minimal подходит для стабильной проводной сети, но в
-нестабильной сети возможны щелчки. Если щелчки есть в standard, включите
-диагностику и сначала попробуйте stable.
+и `custom` (0.08–0.50). Stable используется по умолчанию. Minimal подходит для
+стабильной проводной сети, но в нестабильной сети возможны щелчки.
 
 Шкала AirPlay от `-30` до `0` дБ сопоставлена с 60 дБ ослабления Shairport
 Sync. Поэтому нижнее положение источника практически бесшумно, а верхнее

airplay2_lowlatency/config.yaml

@@ -1,6 +1,6 @@
 ---
 name: HomeWave AirPlay 2
-version: 0.1.2
+version: 0.1.3
 slug: airplay2_lowlatency
 description: Low-latency AirPlay 2 receiver using Home Assistant PulseAudio.
 url: https://github.com/KleoPadre/homewave-ha
@@ -15,7 +15,7 @@ host_network: true
 audio: true
 options:
   airplay_name: HomeWave
-  audio_profile: standard
+  audio_profile: stable
   custom_buffer_seconds: 0.15
   offset_seconds: 0.0
   interpolation: auto

airplay2_lowlatency/shairport-sync.conf.tpl

@@ -9,6 +9,10 @@ general =
   volume_max_db = 0.0;
   audio_backend_buffer_desired_length_in_seconds = @@BUFFER_SECONDS@@;
   audio_backend_latency_offset_in_seconds = @@OFFSET_SECONDS@@;
+};
+
+diagnostics =
+{
 @@DIAGNOSTICS@@
 };
 

airplay2_lowlatency/start-addon.sh

@@ -89,6 +89,8 @@ main() {
 
   if [[ "$diagnostics" == true ]]; then
     printf '  log_output_to = "stdout";\n  statistics = "yes";\n  log_verbosity = 2;\n' >"$diagnostics_file"
+  else
+    printf '  log_output_to = "stdout";\n  statistics = "no";\n  log_verbosity = 1;\n' >"$diagnostics_file"
   fi
 
   sed '/@@DIAGNOSTICS@@/r '"$diagnostics_file"$'\n/@@DIAGNOSTICS@@/d' "$TEMPLATE_PATH" |

airplay2_lowlatency/translations/en.yaml

@@ -6,7 +6,7 @@ configuration:
   audio_profile:
     name: Audio profile
     description: >-
-      Standard is recommended. Minimal has the lowest latency but may click on
+      Stable is recommended. Minimal has the lowest latency but may click on
       unstable networks; stable uses more buffering.
   custom_buffer_seconds:
     name: Custom buffer (seconds)

airplay2_lowlatency/translations/ru.yaml

@@ -6,7 +6,7 @@ configuration:
   audio_profile:
     name: Аудиопрофиль
     description: >-
-      Стандартный профиль рекомендован по умолчанию. Минимальный даёт наименьшую
+      Стабильный профиль рекомендован по умолчанию. Минимальный даёт наименьшую
       задержку, но при нестабильной сети возможны щелчки; стабильный использует
       больший буфер.
   custom_buffer_seconds:

tests/config-schema.bats

@@ -33,3 +33,15 @@
 
   [ "$status" -eq 0 ]
 }
+
+@test "manifest defaults to the stable profile with compact diagnostics" {
+  run ruby -e '
+    require "yaml"
+    config = YAML.load_file(ARGV.fetch(0))
+    options = config.fetch("options")
+    abort "stable profile must be the default" unless options.fetch("audio_profile") == "stable"
+    abort "diagnostics must be disabled by default" unless options.fetch("diagnostics") == false
+  ' "$BATS_TEST_DIRNAME/../airplay2_lowlatency/config.yaml"
+
+  [ "$status" -eq 0 ]
+}