lowhum 1.0.0__tar.gz

lowhum-1.0.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Audio (generated at runtime)
+*.wav
+
+# IDE / OS
+.DS_Store
+.venv/
+.ruff_cache/
+
+# uv
+uv.lock
+CLAUDE.md
+MARKETING.md

lowhum-1.0.0/.python-version

@@ -0,0 +1 @@
+3.14

lowhum-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Markmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lowhum-1.0.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: lowhum
+Version: 1.0.0
+Summary: Deep Brown Noise for Focus as a MenuBar App & CLI Tool
+Project-URL: Repository, https://github.com/lmarkmann/lowhum
+Author: Luis Markmann
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,brown-noise,focus,macos,menu-bar
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2.0
+Requires-Dist: pillow>=11.0
+Requires-Dist: rumps>=0.4.0
+Requires-Dist: scipy>=1.14
+Requires-Dist: sounddevice>=0.5
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# LowHum
+
+**Deep brown noise for focus, right from the macOS menu bar.**
+
+No browser tabs. No subscriptions. No account. Fully offline.
+
+<!-- TODO: Add GIF demo here -->
+
+Brown noise is one of the most effective focus aids for people with ADHD and anyone who needs to block out distractions. Most options require keeping a YouTube tab open, paying for a subscription app, or relying on your phone. LowHum is a single-purpose menu bar app that generates deep brown noise locally and plays it on loop — install it, click play, forget about it.
+
+## Install
+
+```bash
+uv tool install lowhum          # recommended
+# or
+pip install lowhum
+```
+
+## Usage
+
+```bash
+lowhum                          # launch the menu-bar app
+lowhum start                    # play immediately in terminal (Ctrl+C to stop)
+lowhum start -d 3               # play on a specific output device
+lowhum devices                  # list output devices
+lowhum generate                 # pre-generate the audio file
+```
+
+`lhm` is a shorthand alias — all commands work with either name.
+
+### Menu-bar app
+
+- Play / Stop from the menu bar
+- **Output Device** submenu — pick any connected audio device
+- Auto-stops when headphones connect or disconnect
+
+## How it works
+
+1. **Generation** — On first run, a 10-minute WAV is synthesised locally: cumulative-sum brown noise, Butterworth bandpass (1–500 Hz + 20 Hz sub-bass HP), RMS-normalised per chunk, crossfaded at boundaries. Stored at `~/.lowhum/`.
+2. **Playback** — Memory-mapped streaming through PortAudio. No full-file RAM load. Loops seamlessly.
+3. **Device detection** — Polls audio devices every 2 seconds. Headphone unplug, Bluetooth disconnect — playback stops instantly.
+4. **Menu-bar icon** — Template icon; macOS handles dark/light mode automatically.
+
+## Requirements
+
+- macOS
+- Python >= 3.12
+
+## License
+
+MIT

lowhum-1.0.0/README.md

@@ -0,0 +1,51 @@
+# LowHum
+
+**Deep brown noise for focus, right from the macOS menu bar.**
+
+No browser tabs. No subscriptions. No account. Fully offline.
+
+<!-- TODO: Add GIF demo here -->
+
+Brown noise is one of the most effective focus aids for people with ADHD and anyone who needs to block out distractions. Most options require keeping a YouTube tab open, paying for a subscription app, or relying on your phone. LowHum is a single-purpose menu bar app that generates deep brown noise locally and plays it on loop — install it, click play, forget about it.
+
+## Install
+
+```bash
+uv tool install lowhum          # recommended
+# or
+pip install lowhum
+```
+
+## Usage
+
+```bash
+lowhum                          # launch the menu-bar app
+lowhum start                    # play immediately in terminal (Ctrl+C to stop)
+lowhum start -d 3               # play on a specific output device
+lowhum devices                  # list output devices
+lowhum generate                 # pre-generate the audio file
+```
+
+`lhm` is a shorthand alias — all commands work with either name.
+
+### Menu-bar app
+
+- Play / Stop from the menu bar
+- **Output Device** submenu — pick any connected audio device
+- Auto-stops when headphones connect or disconnect
+
+## How it works
+
+1. **Generation** — On first run, a 10-minute WAV is synthesised locally: cumulative-sum brown noise, Butterworth bandpass (1–500 Hz + 20 Hz sub-bass HP), RMS-normalised per chunk, crossfaded at boundaries. Stored at `~/.lowhum/`.
+2. **Playback** — Memory-mapped streaming through PortAudio. No full-file RAM load. Loops seamlessly.
+3. **Device detection** — Polls audio devices every 2 seconds. Headphone unplug, Bluetooth disconnect — playback stops instantly.
+4. **Menu-bar icon** — Template icon; macOS handles dark/light mode automatically.
+
+## Requirements
+
+- macOS
+- Python >= 3.12
+
+## License
+
+MIT

lowhum-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "lowhum"
+version = "1.0.0"
+description = "Deep Brown Noise for Focus as a MenuBar App & CLI Tool"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Luis Markmann" }]
+requires-python = ">=3.12"
+keywords = ["brown-noise", "focus", "audio", "macos", "menu-bar"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: MacOS X",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Sound/Audio",
+]
+dependencies = [
+    "numpy>=2.0",
+    "pillow>=11.0",
+    "rumps>=0.4.0",
+    "scipy>=1.14",
+    "sounddevice>=0.5",
+    "typer>=0.12",
+]
+
+[project.scripts]
+lowhum = "lowhum.cli:app"
+lhm = "lowhum.cli:app"
+
+[project.urls]
+Repository = "https://github.com/lmarkmann/lowhum"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lowhum"]
+exclude = ["*.wav"]
+
+[dependency-groups]
+dev = ["ruff>=0.9"]

lowhum-1.0.0/src/lowhum/__init__.py

@@ -0,0 +1,3 @@
+"""LowHum — deep brown noise for focus."""
+
+__version__ = "1.0.0"

lowhum-1.0.0/src/lowhum/app.py

@@ -0,0 +1,124 @@
+"""LowHum — macOS menu-bar application for brown noise playback."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import rumps
+import sounddevice as sd
+
+from .audio import AudioPlayer, list_output_devices
+from .generator import AUDIO_FILE
+from .icons import ensure_template_icon
+
+_APP_ICON = Path(__file__).parent / "icon.png"
+
+
+def _set_dock_icon() -> None:
+    """Set the macOS dock icon if icon.png is bundled."""
+    if not _APP_ICON.exists():
+        return
+    try:
+        from AppKit import NSApplication, NSImage  # type: ignore[import-untyped]
+
+        ns_image = NSImage.alloc().initByReferencingFile_(str(_APP_ICON))
+        NSApplication.sharedApplication().setApplicationIconImage_(ns_image)
+    except ImportError:
+        pass
+
+
+class LowHumApp(rumps.App):
+    """Menu-bar app: play / stop / select output device."""
+
+    def __init__(self) -> None:
+        icon_path = str(ensure_template_icon())
+        super().__init__("LowHum", icon=icon_path, template=True, quit_button=None)  # type: ignore
+        _set_dock_icon()
+
+        self._player = AudioPlayer()
+        self._selected_device: int | None = None
+        self._known_device_names: set[str] = set()
+
+        # --- static menu items ---
+        self._play_item = rumps.MenuItem("Play", callback=self._on_play)
+        self._stop_item = rumps.MenuItem("Stop", callback=self._on_stop)
+        self._device_menu = rumps.MenuItem("Output Device")
+
+        self.menu = [
+            self._play_item,
+            self._stop_item,
+            None,
+            self._device_menu,
+            None,
+            rumps.MenuItem("Quit", callback=self._on_quit),
+        ]
+
+        self._refresh_devices()
+
+        # Poll for audio-device changes every 2 s
+        self._device_timer = rumps.Timer(self._check_devices, 2)
+        self._device_timer.start()
+
+    # Device management
+
+    def _refresh_devices(self) -> None:
+        devices = list_output_devices()
+        self._known_device_names = {name for _, name in devices}
+
+        # Clear submenu
+        for key in list(self._device_menu.keys()):
+            del self._device_menu[key]
+
+        # "System Default" entry
+        sys_item = rumps.MenuItem(
+            "System Default",
+            callback=lambda _: self._select_device(None),
+        )
+        sys_item.state = self._selected_device is None
+        self._device_menu["System Default"] = sys_item
+
+        for idx, name in devices:
+            item = rumps.MenuItem(
+                name,
+                callback=lambda _, d=idx: self._select_device(d),
+            )
+            item.state = self._selected_device == idx
+            self._device_menu[name] = item
+
+    def _select_device(self, device_id: int | None) -> None:
+        was_playing = self._player.playing
+        if was_playing:
+            self._player.stop()
+
+        self._selected_device = device_id
+        self._refresh_devices()
+
+        if was_playing:
+            self._player.play(AUDIO_FILE, device=self._selected_device, loop=True)
+
+    def _check_devices(self, _: rumps.Timer) -> None:
+        """Detect connects / disconnects and stop playback immediately."""
+        try:
+            current = {name for _, name in list_output_devices()}
+        except sd.PortAudioError:
+            return
+
+        if current != self._known_device_names:
+            if self._player.playing:
+                self._player.stop()
+                rumps.notification("LowHum", "", "Audio stopped — output device changed.")
+            self._refresh_devices()
+
+    # Menu callbacks
+
+    def _on_play(self, _: rumps.MenuItem) -> None:
+        if self._player.playing:
+            return
+        self._player.play(AUDIO_FILE, device=self._selected_device, loop=True)
+
+    def _on_stop(self, _: rumps.MenuItem) -> None:
+        self._player.stop()
+
+    def _on_quit(self, _: rumps.MenuItem) -> None:
+        self._player.stop()
+        rumps.quit_application()

lowhum-1.0.0/src/lowhum/audio.py

@@ -0,0 +1,221 @@
+"""Audio playback engine — sounddevice streaming with device selection."""
+
+from __future__ import annotations
+
+import contextlib
+import struct
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import sounddevice as sd
+
+# ---------------------------------------------------------------------------
+# WAV header parsing (avoids loading the full file into memory)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class WavInfo:
+    sample_rate: int
+    channels: int
+    bits_per_sample: int
+    data_offset: int
+    data_size: int
+
+
+def parse_wav_header(file_path: Path) -> WavInfo:
+    """Parse a RIFF/WAV header and return metadata + data offset."""
+    with open(file_path, "rb") as f:
+        if f.read(4) != b"RIFF":
+            raise ValueError("Not a RIFF file")
+        f.read(4)  # file size
+        if f.read(4) != b"WAVE":
+            raise ValueError("Not a WAVE file")
+
+        sample_rate = channels = bits_per_sample = 0
+        data_offset = data_size = 0
+
+        while True:
+            chunk_id = f.read(4)
+            if len(chunk_id) < 4:
+                break
+            (chunk_size,) = struct.unpack("<I", f.read(4))
+
+            if chunk_id == b"fmt ":
+                fmt = f.read(min(chunk_size, 16))
+                _audio_fmt, channels, sample_rate = struct.unpack("<HHI", fmt[:8])
+                bits_per_sample = struct.unpack("<H", fmt[14:16])[0]
+                remaining = chunk_size - 16
+                if remaining > 0:
+                    f.read(remaining)
+            elif chunk_id == b"data":
+                data_offset = f.tell()
+                data_size = chunk_size
+                break
+            else:
+                f.seek(chunk_size, 1)
+
+    return WavInfo(
+        sample_rate=sample_rate,
+        channels=channels,
+        bits_per_sample=bits_per_sample,
+        data_offset=data_offset,
+        data_size=data_size,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Device helpers
+# ---------------------------------------------------------------------------
+
+
+def list_output_devices() -> list[tuple[int, str]]:
+    """Return ``[(index, name), ...]`` for every output-capable device."""
+    devices = sd.query_devices()
+    return [(i, d["name"]) for i, d in enumerate(devices) if d["max_output_channels"] > 0]
+
+
+def get_default_output_device() -> int:
+    """Index of the current default output device."""
+    return sd.default.device[1]  # type: ignore[index]
+
+
+# ---------------------------------------------------------------------------
+# Player
+# ---------------------------------------------------------------------------
+
+
+class AudioPlayer:
+    """Streams a WAV file through sounddevice with device selection."""
+
+    def __init__(self) -> None:
+        self._stop_event = threading.Event()
+        self._stream: sd.OutputStream | None = None
+        self._playing = False
+        self._lock = threading.Lock()
+        self._thread: threading.Thread | None = None
+
+    @property
+    def playing(self) -> bool:
+        return self._playing
+
+    # -- public API ---------------------------------------------------------
+
+    def play(
+        self,
+        file_path: Path,
+        device: int | None = None,
+        loop: bool = True,
+    ) -> None:
+        """Start streaming *file_path* (non-blocking)."""
+        self.stop()
+        self._stop_event.clear()
+        self._thread = threading.Thread(
+            target=self._run,
+            args=(file_path, device, loop),
+            daemon=True,
+        )
+        self._thread.start()
+
+    def play_blocking(
+        self,
+        file_path: Path,
+        device: int | None = None,
+        loop: bool = True,
+    ) -> None:
+        """Play audio, blocking until stopped or file ends."""
+        self._stop_event.clear()
+        self._run(file_path, device, loop)
+
+    def stop(self) -> None:
+        """Stop playback immediately."""
+        self._stop_event.set()
+        with self._lock:
+            if self._stream is not None:
+                with contextlib.suppress(Exception):
+                    self._stream.abort()
+                self._stream = None
+            self._playing = False
+        if self._thread is not None:
+            self._thread.join(timeout=2)
+            self._thread = None
+
+    # -- internals ----------------------------------------------------------
+
+    def _run(
+        self,
+        file_path: Path,
+        device: int | None,
+        loop: bool,
+    ) -> None:
+        info = parse_wav_header(file_path)
+        n_samples = info.data_size // (info.bits_per_sample // 8)
+
+        data = np.memmap(
+            file_path,
+            dtype=np.int16,
+            mode="r",
+            offset=info.data_offset,
+            shape=(n_samples,),
+        )
+
+        pos = [0]  # mutable for callback closure
+        stop_evt = self._stop_event
+
+        def _callback(
+            outdata: np.ndarray,
+            frames: int,
+            _time: object,
+            _status: sd.CallbackFlags,
+        ) -> None:
+            current = pos[0]
+            end = current + frames
+
+            if end <= n_samples:
+                outdata[:, 0] = data[current:end]
+                pos[0] = end
+            elif loop:
+                first = n_samples - current
+                outdata[:first, 0] = data[current:]
+                remaining = frames - first
+                outdata[first:, 0] = data[:remaining]
+                pos[0] = remaining
+            else:
+                first = n_samples - current
+                outdata[:first, 0] = data[current:]
+                outdata[first:] = 0
+                raise sd.CallbackStop
+
+            if stop_evt.is_set():
+                raise sd.CallbackAbort
+
+        try:
+            stream = sd.OutputStream(
+                samplerate=info.sample_rate,
+                channels=info.channels,
+                dtype="int16",
+                device=device,
+                blocksize=2048,
+                callback=_callback,
+            )
+            with self._lock:
+                self._stream = stream
+                self._playing = True
+
+            stream.start()
+            while stream.active and not stop_evt.is_set():
+                sd.sleep(100)
+        except sd.PortAudioError as exc:
+            print(f"Audio error: {exc}")
+        finally:
+            with self._lock:
+                if self._stream is not None:
+                    try:
+                        self._stream.stop()
+                        self._stream.close()
+                    except Exception:
+                        pass
+                    self._stream = None
+                self._playing = False

lowhum-1.0.0/src/lowhum/cli.py

@@ -0,0 +1,77 @@
+"""CLI entry point for LowHum — ``lhm`` and ``lowhum`` resolve here."""
+
+from __future__ import annotations
+
+import signal
+import sys
+
+import typer
+
+app = typer.Typer(
+    name="lowhum",
+    help="LowHum — deep brown noise for focus.",
+    invoke_without_command=True,
+    no_args_is_help=False,
+)
+
+
+@app.callback(invoke_without_command=True)
+def _default(ctx: typer.Context) -> None:
+    """Launch the menu-bar app (default when no subcommand given)."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    from .app import LowHumApp
+    from .generator import ensure_audio
+
+    ensure_audio()
+    LowHumApp().run()
+
+
+@app.command()
+def start(
+    device: int | None = typer.Option(
+        None, "--device", "-d", help="Output device index (see `lhm devices`)."
+    ),
+) -> None:
+    """Play brown noise immediately in the terminal (Ctrl+C to stop)."""
+    from .audio import AudioPlayer
+    from .generator import AUDIO_FILE, ensure_audio
+
+    ensure_audio()
+
+    player = AudioPlayer()
+
+    def _sigint(_sig: int, _frame: object) -> None:
+        player.stop()
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, _sigint)
+
+    typer.echo("Playing brown noise … (Ctrl+C to stop)")
+    player.play_blocking(AUDIO_FILE, device=device, loop=True)
+
+
+@app.command()
+def devices() -> None:
+    """List available audio output devices."""
+    from .audio import get_default_output_device, list_output_devices
+
+    default_idx = get_default_output_device()
+    for idx, name in list_output_devices():
+        marker = " (default)" if idx == default_idx else ""
+        typer.echo(f"  [{idx}] {name}{marker}")
+
+
+@app.command()
+def generate() -> None:
+    """Pre-generate the brown noise audio file."""
+    from .generator import AUDIO_FILE, generate_brown_noise
+
+    if AUDIO_FILE.exists():
+        typer.echo(f"Audio file already exists at {AUDIO_FILE}")
+        if not typer.confirm("Regenerate?"):
+            raise typer.Abort()
+
+    generate_brown_noise()
+    typer.echo(f"Saved to {AUDIO_FILE}")

lowhum-1.0.0/src/lowhum/generator.py

@@ -0,0 +1,74 @@
+"""Brown noise generator — generates audio on first use, caches to disk."""
+
+from pathlib import Path
+
+import numpy as np
+from scipy.io.wavfile import write as wav_write
+from scipy.signal import butter, sosfilt
+
+SAMPLE_RATE = 44_100
+DURATION = 600  # seconds (10 minutes)
+DATA_DIR = Path.home() / ".lowhum"
+AUDIO_FILE = DATA_DIR / "deep_brown_noise_10m.wav"
+
+
+def generate_brown_noise(output_path: Path | None = None) -> Path:
+    """Generate 10 minutes of deep brown noise and save as WAV.
+
+    Uses cumulative-sum brown noise with Butterworth bandpass (1–500 Hz)
+    and a sub-bass high-pass at 20 Hz. Chunks are crossfaded to avoid clicks.
+    """
+    if output_path is None:
+        output_path = AUDIO_FILE
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    chunk_size = SAMPLE_RATE * 300  # 5-minute chunks
+    n_chunks = DURATION * SAMPLE_RATE // chunk_size
+
+    # Filter design (done once)
+    hp_sos = butter(2, 1.0, btype="high", fs=SAMPLE_RATE, output="sos")
+    lp_sos = butter(2, 500, btype="low", fs=SAMPLE_RATE, output="sos")
+    sub_sos = butter(1, 20, btype="high", fs=SAMPLE_RATE, output="sos")
+
+    chunks: list[np.ndarray] = []
+
+    for _ in range(n_chunks):
+        white = np.random.randn(chunk_size)
+        brown = np.cumsum(white)
+
+        brown = sosfilt(hp_sos, brown)
+        brown = sosfilt(lp_sos, brown)
+        brown = sosfilt(sub_sos, brown)
+
+        # Per-chunk RMS normalisation keeps volume consistent
+        rms = np.sqrt(np.mean(brown**2))
+        brown = brown * (0.3 / rms)
+        brown = np.clip(brown, -1.0, 1.0)
+
+        chunks.append(brown)
+
+    # Crossfade between chunks (1 s) to eliminate boundary clicks
+    xfade = SAMPLE_RATE
+    for i in range(1, len(chunks)):
+        fade_out = np.linspace(1, 0, xfade)
+        fade_in = np.linspace(0, 1, xfade)
+        chunks[i - 1][-xfade:] *= fade_out
+        chunks[i][:xfade] *= fade_in
+        chunks[i][:xfade] += chunks[i - 1][-xfade:]
+        chunks[i - 1] = chunks[i - 1][:-xfade]
+
+    final = np.concatenate(chunks)
+    audio_data = (final * 32_767).astype(np.int16)
+    wav_write(str(output_path), SAMPLE_RATE, audio_data)
+
+    return output_path
+
+
+def ensure_audio() -> Path:
+    """Return the path to the audio file, generating it on first call."""
+    if AUDIO_FILE.exists():
+        return AUDIO_FILE
+
+    print("Generating brown noise audio (first run — takes ~5 s) …")
+    return generate_brown_noise()

lowhum-1.0.0/src/lowhum/icons.py

@@ -0,0 +1,48 @@
+"""Icon generation — creates a filled template icon for the macOS menu bar."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+_SOURCE_ICON_DARK = Path(__file__).parent / "menubar_dark.png"
+_SOURCE_ICON_LIGHT = Path(__file__).parent / "menubar_light.png"
+_DATA_DIR = Path.home() / ".lowhum"
+_TEMPLATE_ICON = _DATA_DIR / "icon_template.png"
+
+# Menu bar icon: 22 pt = 44 px @2x retina
+_ICON_SIZE = 44
+
+
+def ensure_template_icon() -> Path:
+    """Return path to a filled template icon, creating it if needed.
+
+    Loads the bundled buffalo artwork, thresholds every non-transparent
+    pixel to solid black, resizes to 44x44, and saves.  macOS renders
+    template icons automatically in dark/light mode.
+    """
+    if _TEMPLATE_ICON.exists():
+        return _TEMPLATE_ICON
+
+    _DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Try to load dark mode icon first, fall back to light mode
+    if _SOURCE_ICON_DARK.exists():
+        img = Image.open(_SOURCE_ICON_DARK).convert("RGBA")
+    elif _SOURCE_ICON_LIGHT.exists():
+        img = Image.open(_SOURCE_ICON_LIGHT).convert("RGBA")
+    else:
+        raise FileNotFoundError(f"Neither {_SOURCE_ICON_DARK} nor {_SOURCE_ICON_LIGHT} found")
+    img = img.resize((_ICON_SIZE, _ICON_SIZE), Image.LANCZOS)  # type: ignore
+
+    pixels = np.array(img)
+
+    # Threshold: any pixel with alpha > 30 → solid black; else transparent
+    mask = pixels[:, :, 3] > 30
+    pixels[mask] = [0, 0, 0, 255]
+    pixels[~mask] = [0, 0, 0, 0]
+
+    Image.fromarray(pixels).save(_TEMPLATE_ICON)
+    return _TEMPLATE_ICON

lowhum-1.0.0/src/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lowhum"
+version = "1.0.0"
+description = "LowHum — deep brown noise for focus"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Your Name", email = "your.email@example.com" },
+]
+keywords = ["brown-noise", "focus", "ambient", "macos", "menu-bar", "audio"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio :: Players",
+]
+dependencies = [
+    "rumps>=0.4.0",
+    "sounddevice>=0.4.6",
+    "numpy>=1.24.0",
+    "scipy>=1.10.0",
+    "Pillow>=10.0.0",
+    "typer>=0.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.scripts]
+lhm = "lowhum.cli:app"
+lowhum = "lowhum.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/yourusername/lowhum"
+Repository = "https://github.com/yourusername/lowhum"
+Issues = "https://github.com/yourusername/lowhum/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["lowhum"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4", "SIM"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_configs = true