amniotic 1.3.4__tar.gz

amniotic-1.3.4/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: amniotic
+Version: 1.3.4
+Summary: A multi-output ambient sound mixer for Home Assistant
+Home-page: https://github.com/None/amniotic
+Author: Frontmatter
+Author-email: innovative.fowler@mask.pro.fmtr.dev
+License: Copyright © 2025 Frontmatter. All rights reserved.
+Keywords: ambient sound audio white noise masking sleep
+Description-Content-Type: text/markdown
+Requires-Dist: fmtr.tools[api,av,caching,debug,ha.api,http,logging,mqtt,path.app,sets,tabular,version.dev,yaml]
+Requires-Dist: haco
+Provides-Extra: all
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
+
+# Amniotic
+
+A multi-output ambient sound mixer for Home Assistant.
+
+Amniotic lets you use a single device to create on-the-fly, custom ambient audio mixes - e.g. mixing Waterfall sounds with Birdsong on one media player entity, while playing Fireplace sounds from a second audio device - to suit your tastes and environment.
+
+The library integrates with Home Assistant via MQTT as a new device, allowing you to create and control ambient mixes from the Home Assistant interface.
+
+### Why Would I Want Such a Thing?
+
+I won't explain the general reasons for introducing non-musical sounds into one's environment, but if you find [sound masking](https://en.wikipedia.org/wiki/Sound_masking) helps you concentrate in noisy environments, if you're (as I am) slightly [misophonic](https://www.webmd.com/mental-health/what-is-misophonia), if you use [white noise machines](https://en.wikipedia.org/wiki/White_noise_machine) to induce sleep or relaxation, or if you just think sound is an important factor in setting a pleasant ambience, then you might find Amniotic useful.
+
+### Can't I do This with Spotify, Volumio, HifiBerry etc.?
+
+Since those systems are intended for music, they aren't designed for playing or mixing multiple streams simultaneously with a single device, even if set up in multi-room configurations. Also, the streaming services often won't allow a single account to play multiple streams, even
+_if_ multiple devices are used.
+
+Anyway, those limitations motivated this library.
+
+There are two ways to install and run Amniotic:
+
+- On the Home Assistant machine itself, as an add-on.
+- Install manually, on a separate machine.
+
+## Home Assistant Addon
+
+To add as an Addon, click here:
+
+[![Open your Home Assistant instance and show the add add-on repository dialog with the repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://fmtr.link/amniotic/addon-install)
+
+## Dashboard
+
+[Lovelace Dashboard](https://fmtr.link/amniotic/doc/dashboard)
+
+![Dashboard Screenshot](https://fmtr.link/amniotic/doc/dashboard/screenshot)
+
+## Getting Started
+
+Better documentation is coming soon. Currently, the easiest workflow is the following:
+
+- Install as an Addon, using the button above.
+- If you're using a non-default address for Home Assistant on your network (i.e. not
+  `homeassistant.local`), set that in the Addon configuration.
+- Add some audio files to the Home Assistant `/media/Amniotic` directory.
+
+#### Adding the Dashboard to Lovelace
+
+- Find the [Lovelace Dashboard View here](https://fmtr.link/amniotic/doc/dashboard).
+- Click on the Copy icon to "Copy raw file"
+- In your Home Assistant UI, navigate to a dashboard you'd like to add the View to.
+- Click on the Edit Dashboard icon.
+- Click the `+` to add a new View.
+- Click on the three dots in the top right corner of the new View editor, and select `Edit in YAML`.
+- Overwrite the _entire_ edit box with the contents of your clipboard.
+- Click `Save`.
+- Click `Done` in the dashboard editor.
+
+#### Using the Dashboard
+- Select a Recording from the dropdown.
+- Toggle to Enable the Recording.
+- Select a Media Player to stream the Theme to. Note: Your media player needs to support streaming from a basic HTTP stream, which most should.
+- Click Stream to Media Player.
+- Your Theme should start playing on your Media Player.
+- You can now Enable additional Recordings in the Theme, modify their volume, etc., to create a custom mix.
+- Note: there's also a Current Theme URL, for if you want to manually paste stream to a non-HA player, like a phone or something.
+
+## Do I need a fancy Sonos-type Speaker? Can't I just use a Raspberry Pi, etc?
+
+- You can use basically any device with audio hardware. You just need to allow Home Assistant to see it as a Media Player entity.
+- In Home Assistant, install the [VLC Telnet integration](https://www.home-assistant.io/integrations/vlc_telnet).
+- On your Device, install VLC, and start it in telnet mode, e.g.
+  `vlc -I telnet --telnet-password password --telnet-host 0.0.0.0:4212`
+- Add your device to the VLC Telnet integration.

amniotic-1.3.4/README.md

@@ -0,0 +1,73 @@
+# Amniotic
+
+A multi-output ambient sound mixer for Home Assistant.
+
+Amniotic lets you use a single device to create on-the-fly, custom ambient audio mixes - e.g. mixing Waterfall sounds with Birdsong on one media player entity, while playing Fireplace sounds from a second audio device - to suit your tastes and environment.
+
+The library integrates with Home Assistant via MQTT as a new device, allowing you to create and control ambient mixes from the Home Assistant interface.
+
+### Why Would I Want Such a Thing?
+
+I won't explain the general reasons for introducing non-musical sounds into one's environment, but if you find [sound masking](https://en.wikipedia.org/wiki/Sound_masking) helps you concentrate in noisy environments, if you're (as I am) slightly [misophonic](https://www.webmd.com/mental-health/what-is-misophonia), if you use [white noise machines](https://en.wikipedia.org/wiki/White_noise_machine) to induce sleep or relaxation, or if you just think sound is an important factor in setting a pleasant ambience, then you might find Amniotic useful.
+
+### Can't I do This with Spotify, Volumio, HifiBerry etc.?
+
+Since those systems are intended for music, they aren't designed for playing or mixing multiple streams simultaneously with a single device, even if set up in multi-room configurations. Also, the streaming services often won't allow a single account to play multiple streams, even
+_if_ multiple devices are used.
+
+Anyway, those limitations motivated this library.
+
+There are two ways to install and run Amniotic:
+
+- On the Home Assistant machine itself, as an add-on.
+- Install manually, on a separate machine.
+
+## Home Assistant Addon
+
+To add as an Addon, click here:
+
+[![Open your Home Assistant instance and show the add add-on repository dialog with the repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://fmtr.link/amniotic/addon-install)
+
+## Dashboard
+
+[Lovelace Dashboard](https://fmtr.link/amniotic/doc/dashboard)
+
+![Dashboard Screenshot](https://fmtr.link/amniotic/doc/dashboard/screenshot)
+
+## Getting Started
+
+Better documentation is coming soon. Currently, the easiest workflow is the following:
+
+- Install as an Addon, using the button above.
+- If you're using a non-default address for Home Assistant on your network (i.e. not
+  `homeassistant.local`), set that in the Addon configuration.
+- Add some audio files to the Home Assistant `/media/Amniotic` directory.
+
+#### Adding the Dashboard to Lovelace
+
+- Find the [Lovelace Dashboard View here](https://fmtr.link/amniotic/doc/dashboard).
+- Click on the Copy icon to "Copy raw file"
+- In your Home Assistant UI, navigate to a dashboard you'd like to add the View to.
+- Click on the Edit Dashboard icon.
+- Click the `+` to add a new View.
+- Click on the three dots in the top right corner of the new View editor, and select `Edit in YAML`.
+- Overwrite the _entire_ edit box with the contents of your clipboard.
+- Click `Save`.
+- Click `Done` in the dashboard editor.
+
+#### Using the Dashboard
+- Select a Recording from the dropdown.
+- Toggle to Enable the Recording.
+- Select a Media Player to stream the Theme to. Note: Your media player needs to support streaming from a basic HTTP stream, which most should.
+- Click Stream to Media Player.
+- Your Theme should start playing on your Media Player.
+- You can now Enable additional Recordings in the Theme, modify their volume, etc., to create a custom mix.
+- Note: there's also a Current Theme URL, for if you want to manually paste stream to a non-HA player, like a phone or something.
+
+## Do I need a fancy Sonos-type Speaker? Can't I just use a Raspberry Pi, etc?
+
+- You can use basically any device with audio hardware. You just need to allow Home Assistant to see it as a Media Player entity.
+- In Home Assistant, install the [VLC Telnet integration](https://www.home-assistant.io/integrations/vlc_telnet).
+- On your Device, install VLC, and start it in telnet mode, e.g.
+  `vlc -I telnet --telnet-password password --telnet-host 0.0.0.0:4212`
+- Add your device to the VLC Telnet integration.

amniotic-1.3.4/amniotic/api.py

@@ -0,0 +1,48 @@
+import logging
+from fastapi.responses import StreamingResponse
+from starlette.requests import Request
+
+from amniotic.obs import logger
+from amniotic.theme import ThemeDefinition
+from amniotic.version import __version__
+from fmtr.tools import api, mqtt
+
+for name in ["uvicorn.access", "uvicorn.error", "uvicorn"]:
+    lgr = logging.getLogger(name)
+    lgr.handlers.clear()
+    lgr.propagate = False
+
+
+
+class ApiAmniotic(api.Base):
+    TITLE = f'Amniotic {__version__} Streaming API'
+    URL_DOCS = '/'
+
+    def __init__(self, client: mqtt.Client):
+        super().__init__()
+
+        self.client = client
+
+    def get_endpoints(self):
+        endpoints = [
+            api.Endpoint(method_http=self.app.get, path='/stream/{id}', method=self.stream),
+
+        ]
+
+        return endpoints
+
+    async def stream(self, id: str, request: Request):
+        logger.info(f'Got streaming audio request {id=} {request.client=}')
+        theme_def: ThemeDefinition = self.client.device.themes.id[id]
+        stream = theme_def.get_stream()
+
+        if not stream.is_enabled:
+            logger.warning(f'Theme "{theme_def.name}" is streaming, but it has no recordings enabled. The stream will be silent. Enable some recordings to hear output.')
+
+        response = StreamingResponse(stream, media_type="audio/mpeg")
+        return response
+
+
+
+if __name__ == '__main__':
+    ApiAmniotic.launch()

amniotic-1.3.4/amniotic/client.py

@@ -0,0 +1,44 @@
+import asyncio
+
+from amniotic.api import ApiAmniotic
+from amniotic.device import Amniotic
+from amniotic.obs import logger
+from fmtr.tools import http
+from haco.client import ClientHaco
+
+
+class ClientAmniotic(ClientHaco):
+    """
+    Take an extra API argument, and gather with super.start
+    """
+
+    API_CLASS = ApiAmniotic
+
+    def __init__(self, device: Amniotic, *args, **kwargs):
+        super().__init__(device=device, *args, **kwargs)
+
+    @logger.instrument('Connecting MQTT client to {self._client.username}@{self._hostname}:{self._port}...')
+    async def start(self):
+        await asyncio.gather(
+            super().start(),
+            self.API_CLASS.launch_async(self)
+        )
+
+    @classmethod
+    @logger.instrument('Instantiating MQTT client from Supervisor API...')
+    def from_supervisor(cls, device: Amniotic, **kwargs):
+        from amniotic.settings import settings
+
+        with http.Client() as client:
+            response = client.get(
+                f"{settings.ha_supervisor_api}/services/mqtt",
+                headers={
+                    "Authorization": f"Bearer {settings.token}",
+                    "Content-Type": "application/json",
+                },
+            )
+
+        data = response.json().get("data", {})
+
+        self = cls(device=device, hostname=data['host'], port=data['port'], username=data['username'], password=data['password'], **kwargs)
+        return self

amniotic-1.3.4/amniotic/controls.py

@@ -0,0 +1,260 @@
+from dataclasses import dataclass
+
+from amniotic.obs import logger
+from amniotic.recording import RecordingThemeInstance
+from amniotic.theme import ThemeDefinition
+from fmtr.tools import http
+from haco.button import Button
+from haco.control import Control
+from haco.number import Number
+from haco.select import Select
+from haco.sensor import Sensor
+from haco.switch import Switch
+from haco.text import Text
+
+
+@dataclass(kw_only=True)
+class ThemeRelativeControl(Control):
+
+    @property
+    def themes(self):
+        return self.device.themes
+
+    @property
+    def theme(self):
+        return self.themes.current
+
+    @property
+    def instances(self):
+        return self.theme.instances
+
+    @property
+    def instance(self):
+        return self.instances.current
+
+
+@dataclass(kw_only=True)
+class SelectTheme(Select, ThemeRelativeControl):
+    icon: str = 'access-point'
+    name: str = 'Theme'
+
+    @logger.instrument('Setting Theme to "{value}"...')
+    async def command(self, value):
+        theme = self.themes.name[value]
+        self.themes.current = theme
+        return value
+
+
+    async def state(self, value=None):
+
+        if self.theme not in self.themes:
+            if self.themes:
+                self.themes.current = next(iter(self.themes))
+            else:
+                logger.warning('No themes exist. Creating default...')
+                theme = ThemeDefinition(amniotic=self.device, name="Default")
+                self.themes.append(theme)
+                self.themes.current = theme
+                self.themes.save()
+
+        options = sorted(self.themes.name.keys())
+        if self.options != options:
+            self.options = options
+            await self.announce()
+
+        name = self.theme.name
+
+        await self.device.select_recording.state()
+        await self.device.sns_url.state()
+        return name
+
+@dataclass(kw_only=True)
+class SelectRecording(Select, ThemeRelativeControl):
+    icon: str = 'waveform'
+    name: str = 'Recording'
+
+    @logger.instrument('Setting Theme "{self.theme.name}" current recording instance to "{value}"...')
+    async def command(self, value):
+
+        instance = self.instances.name.get(value)
+        if not instance:
+            logger.info(f'Creating new recording instance "{value}" for Theme "{self.theme.name}"...')
+            meta = self.device.metas.name[value]
+            instance = RecordingThemeInstance(path=meta.path_str, device=self.device)
+            self.instances.append(instance)
+
+        self.instances.current = instance
+        return value
+
+    async def state(self, value=None):
+
+        options = sorted(self.device.metas.name.keys())
+        if self.options != options:
+            self.options = options
+            await self.announce()
+
+        if not self.instance:
+            return None
+
+        await self.device.swt_play.state()
+        await self.device.nbr_volume.state()
+        return self.instance.name
+
+
+
+@dataclass(kw_only=True)
+class EnableRecording(Switch, ThemeRelativeControl):
+    icon: str = 'playlist-plus'
+    name: str = 'Enable Recording'
+
+    @logger.instrument('Toggling {value=} recording instance "{self.instances.current.name}" for Theme "{self.theme.name}"...')
+    async def command(self, value):
+
+        if not self.instance:
+            return None
+
+        self.instance.is_enabled = value
+        self.themes.save()
+
+
+    async def state(self, value=None):
+
+        if not self.instance:
+            return None
+
+        return self.instance.is_enabled
+
+
+
+@dataclass(kw_only=True)
+class NumberVolume(Number, ThemeRelativeControl):
+    icon: str = 'volume-medium'
+    name: str = 'Recording Volume'
+
+    @logger.instrument('Setting volume to {value} for recording instance "{self.instances.current.name}" for Theme "{self.theme.name}"...')
+    async def command(self, value):
+
+        if not self.instance:
+            return None
+
+        self.instance.volume = value / 100
+        self.themes.save()
+
+
+    async def state(self, value=None):
+
+        if not self.instance:
+            return None
+
+
+        return int(self.instance.volume * 100)
+
+
+
+@dataclass(kw_only=True)
+class SelectMediaPlayer(Select, ThemeRelativeControl):
+    icon: str = 'cast-audio'
+    name: str = 'Media Player'
+
+    @logger.instrument('Selecting Media Player "{value}" for Theme "{self.theme.name}"...')
+    async def command(self, value):
+        state = self.device.media_player_states.friendly_name[value]
+        self.device.media_player_states.current = state
+        return value
+
+    async def state(self, value):
+        player = self.device.media_player_states.current
+        if player:
+            return player.friendly_name
+        return None
+
+
+@dataclass(kw_only=True)
+class StreamURL(Sensor, ThemeRelativeControl):
+    icon: str = 'link-variant'
+    name: str = 'Stream URL'
+
+    async def state(self, value=None):
+        return self.theme.url
+
+
+@dataclass(kw_only=True)
+class PlayStreamButton(Button, ThemeRelativeControl):
+    icon: str = 'play-network'
+    name: str = 'Stream'
+
+    @property
+    def url_api(self):
+        from amniotic.settings import settings
+
+        return f"{settings.ha_core_api}/services/media_player/play_media"
+
+
+    async def command(self, value):
+
+        if not self.instance:
+            return None
+
+        state = self.device.media_player_states.current
+
+        if not state:
+            return
+
+        with logger.span(f'Posting request to HA API {self.url_api} {state.entity_id=} {self.theme.url=}') as span:
+            try:
+                await self.post(state)
+            except Exception as exception:
+                logger.error(f'Error posting to HA API: {repr(exception)}.')
+                span.record_exception(exception=exception)
+
+    async def post(self, state):
+        from amniotic.settings import settings
+
+        response = http.client.post(
+            self.url_api,
+            headers={
+                "Authorization": f"Bearer {settings.token}",
+                "Content-Type": "application/json",
+            },
+            json={
+                "entity_id": state.entity_id,
+                "media_content_id": self.theme.url,
+                "media_content_type": "music",
+            }
+        )
+
+        response.raise_for_status()
+
+
+@dataclass(kw_only=True)
+class NewTheme(Text, ThemeRelativeControl):
+    icon: str = 'access-point-plus'
+    name: str = 'New Theme'
+
+    @logger.instrument('Creating new Theme "{value}"...')
+    async def command(self, value):
+        if not value:
+            return
+
+        theme = ThemeDefinition(amniotic=self.device, name=value)
+        self.themes.append(theme)
+        self.themes.current = theme
+        self.themes.save()
+
+        await self.device.select_theme.state()
+
+    async def state(self, value=None):
+        return 'New'
+
+
+@dataclass(kw_only=True)
+class DeleteTheme(Button, ThemeRelativeControl):
+    icon: str = 'access-point-remove'
+    name: str = 'Delete Current Theme'
+
+    @logger.instrument('Deleting Theme "{self.theme.name}"...')
+    async def command(self, value):
+        self.themes.remove(self.theme)
+        self.themes.save()
+        await self.device.select_theme.state()
+        return value

amniotic-1.3.4/amniotic/device.py

@@ -0,0 +1,144 @@
+import asyncio
+from dataclasses import dataclass
+from dataclasses import field, fields
+from functools import cached_property
+from typing import Self
+
+import homeassistant_api
+
+from amniotic.controls import SelectTheme, SelectRecording, EnableRecording, NumberVolume, SelectMediaPlayer, PlayStreamButton, StreamURL, NewTheme, DeleteTheme
+from amniotic.obs import logger
+from amniotic.recording import RecordingMetadata
+from amniotic.theme import ThemeDefinition, IndexThemes
+from fmtr.tools import Path
+from fmtr.tools.iterator_tools import IndexList, IterDiffer
+from haco.device import Device
+
+
+@dataclass
+class MediaState:
+    entity_id: str
+    state: str
+    friendly_name: str | None = None
+    supported_features: int | None = None
+
+    def __post_init__(self):
+        self.friendly_name = self.friendly_name or self.entity_id
+
+    @classmethod
+    def from_state(cls, state) -> Self:
+        data = state.model_dump()
+        data |= data.pop('attributes')
+        allowed = {f.name for f in fields(cls)}
+        filtered = {k: v for k, v in data.items() if k in allowed}
+        self = cls(**filtered)
+        return self
+
+
+@dataclass(kw_only=True)
+class Amniotic(Device):
+    themes: IndexList[ThemeDefinition] = field(default_factory=IndexList, metadata=dict(exclude=True))
+    metas: IndexList[RecordingMetadata] = field(default_factory=IndexList, metadata=dict(exclude=True))
+
+    client_ha: homeassistant_api.Client | None = field(default=None, metadata=dict(exclude=True))
+
+    path_audio: Path = field(metadata=dict(exclude=True))
+    path_audio_schedule_duration: int = field(default=10, metadata=dict(exclude=True))
+
+    path_audio_schedule_task: asyncio.Task | None = field(default=None, metadata=dict(exclude=True))
+
+    def __post_init__(self):
+        if not self.path_audio.exists():
+            logger.warning(f'Audio path "{self.path_audio}" does not exist. Will be created.')
+            self.path_audio.mkdir()
+        self.metas = IndexList()
+        self.refresh_metas()
+
+        if not self.metas:
+            logger.warning(f'No audio files found in "{self.path_audio}". You will need to add some before you can stream anything.')
+
+        self.themes = IndexThemes.load(self)
+
+
+        media_players_data = [state for state in self.client_ha.get_states() if state.entity_id.startswith("media_player.")]
+        self.media_player_states = IndexList(MediaState.from_state(data) for data in media_players_data)
+
+        self.controls = [
+            self.select_theme,
+            self.select_recording,
+            self.btn_delete_theme,
+            self.txt_new_theme,
+            self.swt_play,
+            self.nbr_volume,
+            self.select_media_player,
+            self.btn_play,
+            self.sns_url
+        ]
+
+
+    @cached_property
+    def select_theme(self):
+        return SelectTheme(options=[str(defin.name) for defin in self.themes])
+
+    @cached_property
+    def select_recording(self):
+        return SelectRecording(options=sorted(self.metas.name.keys()))
+
+    @cached_property
+    def select_media_player(self):
+        return SelectMediaPlayer(options=list(self.media_player_states.friendly_name.keys()))
+
+    @cached_property
+    def swt_play(self):
+        return EnableRecording()
+
+    @cached_property
+    def btn_play(self):
+        return PlayStreamButton()
+
+    @cached_property
+    def sns_url(self):
+        return StreamURL()
+
+    @cached_property
+    def nbr_volume(self):
+        return NumberVolume()
+
+    @cached_property
+    def txt_new_theme(self):
+        return NewTheme()
+
+    @cached_property
+    def btn_delete_theme(self):
+        return DeleteTheme()
+
+    def refresh_metas(self) -> bool:
+
+        paths_existing = self.metas.path.keys()
+        paths_disk = {path for path in self.path_audio.iterdir() if path.is_file()}
+
+        diff = IterDiffer(paths_existing, paths_disk)
+
+        for path in diff.added:
+            logger.info(f'Adding new recording: "{path}"...')
+            meta = RecordingMetadata(path)
+            self.metas.append(meta)
+            if not self.metas.current:
+                self.metas.current = meta
+
+        return diff.is_changed
+
+    @logger.instrument('Starting audio file monitoring task. Duration: {self.path_audio_schedule_duration}. Directory: "{self.path_audio}"...')
+    async def refresh_metas_task(self):
+        while True:
+            await asyncio.sleep(self.path_audio_schedule_duration)
+
+            logger.debug(f'Syncing recordings in "{self.path_audio}"...')
+            is_changed = self.refresh_metas()
+            if is_changed:
+                await self.select_recording.state()
+
+    async def initialise(self):
+        await super().initialise()
+        if not self.path_audio_schedule_task:
+            self.path_audio_schedule_task = asyncio.create_task(self.refresh_metas_task())

amniotic-1.3.4/amniotic/entrypoint.py

@@ -0,0 +1,7 @@
+def main():
+    from amniotic.settings import settings
+    return settings.run()
+
+
+if __name__ == '__main__':
+    main()

amniotic-1.3.4/amniotic/obs.py

@@ -0,0 +1,15 @@
+import logging as logging_native
+
+from amniotic.paths import paths
+from amniotic.version import __version__
+from fmtr.tools import logging, debug, Constants
+from fmtr.tools.environment_tools import get_bool
+
+debug.trace()
+
+logger = logging.get_logger(
+    name=paths.name_ns,
+    stream=Constants.DEVELOPMENT,
+    version=__version__,
+    level=logging_native.DEBUG if get_bool(Constants.FMTR_DEV_KEY, default=False) else logging_native.INFO  # todo: fix runtime environment for addons
+)