lowhum 0.4.0__tar.gz

lowhum-0.4.0/.gitignore

@@ -0,0 +1,15 @@
+*.wav
+.DS_Store
+
+.venv/
+.ruff_cache/
+.claude/
+CLAUDE.md
+
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+
+dist/
+build/

lowhum-0.4.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-0.4.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: lowhum
+Version: 0.4.0
+Summary: Deep Brown Noise for Focus as a MenuBar App & CLI Tool
+Project-URL: Homepage, https://lmarkmann.github.io/lowhum/
+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 :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: End Users/Desktop
+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
+
+<div align="center">
+<pre>
+               _.-````'-,_
+     _,.,_ ,-'           `'-.,_
+   /)     (\                   '`-.
+  ((      ) )                      `\
+   \)    (_/                        )\
+    |       /)           '    ,'    / \
+    `\    ^'            '     (    /  ))
+      |      _/\ ,     /    ,,`\   (  "`
+       \Y,   |  \  \  | ``````| / \_ \
+         `)_/    \  \  )    ( >  ( >
+                  \( \(     |/   |/
+                 /_(/_(    /_(  /_(
+</pre>
+</div>
+
+# LowHum
+
+[![PyPI](https://img.shields.io/pypi/v/lowhum)](https://pypi.org/project/lowhum/)
+[![Python](https://img.shields.io/pypi/pyversions/lowhum)](https://pypi.org/project/lowhum/)
+[![License](https://img.shields.io/github/license/lmarkmann/lowhum)](LICENSE)
+[![Downloads](https://img.shields.io/pypi/dm/lowhum)](https://pypi.org/project/lowhum/)
+
+Deep brown noise for focus, for macOS menu bar. Requires macOS and Python 3.12+.
+
+Single-purpose menu bar app that generates deep brown noise locally and plays it on loop. Install it, click play, forget about it.
+
+## Install
+
+**pip / uv** (requires Python 3.12+):
+
+```bash
+uv tool install lowhum
+```
+
+**Standalone .app** — download `LowHum.app` from [the latest release](https://github.com/lmarkmann/lowhum/releases/latest). The app is not notarized, so macOS will block it on first launch. To allow it:
+
+```bash
+xattr -cr /Applications/LowHum.app
+```
+
+## Usage
+
+```bash
+lowhum                          # launch the menu-bar app (runs in background)
+lowhum devices                  # list output devices
+lowhum generate                 # pre-generate the audio file
+```
+
+`lhm` is a shorthand alias for all commands.
+
+### Menu bar controls
+
+- Play / Stop from the menu bar
+- Pick any connected audio device from the Output Device submenu
+- Binaural beats overlay (Theta, Alpha, Beta, Gamma)
+- Noise color selection (brown, pink, white)
+- Auto-stops when headphones connect or disconnect
+
+## How it works
+
+On first launch, a 10-minute WAV is synthesized locally for every noise color and binaural combination. Cumulative-sum brown noise through a Butterworth bandpass (1 to 500 Hz, 20 Hz sub-bass highpass), RMS-normalized per chunk, crossfaded at boundaries. Everything is stored in `~/.lowhum/`.
+
+Playback streams through PortAudio via memory-mapped files, so the full WAV never sits in RAM. The app polls audio devices every 2 seconds and stops instantly if headphones disconnect or a Bluetooth device drops.
+
+The menu bar icon is a template image, so macOS handles dark/light mode automatically.
+
+## License
+
+MIT

lowhum-0.4.0/README.md

@@ -0,0 +1,71 @@
+<div align="center">
+<pre>
+               _.-````'-,_
+     _,.,_ ,-'           `'-.,_
+   /)     (\                   '`-.
+  ((      ) )                      `\
+   \)    (_/                        )\
+    |       /)           '    ,'    / \
+    `\    ^'            '     (    /  ))
+      |      _/\ ,     /    ,,`\   (  "`
+       \Y,   |  \  \  | ``````| / \_ \
+         `)_/    \  \  )    ( >  ( >
+                  \( \(     |/   |/
+                 /_(/_(    /_(  /_(
+</pre>
+</div>
+
+# LowHum
+
+[![PyPI](https://img.shields.io/pypi/v/lowhum)](https://pypi.org/project/lowhum/)
+[![Python](https://img.shields.io/pypi/pyversions/lowhum)](https://pypi.org/project/lowhum/)
+[![License](https://img.shields.io/github/license/lmarkmann/lowhum)](LICENSE)
+[![Downloads](https://img.shields.io/pypi/dm/lowhum)](https://pypi.org/project/lowhum/)
+
+Deep brown noise for focus, for macOS menu bar. Requires macOS and Python 3.12+.
+
+Single-purpose menu bar app that generates deep brown noise locally and plays it on loop. Install it, click play, forget about it.
+
+## Install
+
+**pip / uv** (requires Python 3.12+):
+
+```bash
+uv tool install lowhum
+```
+
+**Standalone .app** — download `LowHum.app` from [the latest release](https://github.com/lmarkmann/lowhum/releases/latest). The app is not notarized, so macOS will block it on first launch. To allow it:
+
+```bash
+xattr -cr /Applications/LowHum.app
+```
+
+## Usage
+
+```bash
+lowhum                          # launch the menu-bar app (runs in background)
+lowhum devices                  # list output devices
+lowhum generate                 # pre-generate the audio file
+```
+
+`lhm` is a shorthand alias for all commands.
+
+### Menu bar controls
+
+- Play / Stop from the menu bar
+- Pick any connected audio device from the Output Device submenu
+- Binaural beats overlay (Theta, Alpha, Beta, Gamma)
+- Noise color selection (brown, pink, white)
+- Auto-stops when headphones connect or disconnect
+
+## How it works
+
+On first launch, a 10-minute WAV is synthesized locally for every noise color and binaural combination. Cumulative-sum brown noise through a Butterworth bandpass (1 to 500 Hz, 20 Hz sub-bass highpass), RMS-normalized per chunk, crossfaded at boundaries. Everything is stored in `~/.lowhum/`.
+
+Playback streams through PortAudio via memory-mapped files, so the full WAV never sits in RAM. The app polls audio devices every 2 seconds and stops instantly if headphones disconnect or a Bluetooth device drops.
+
+The menu bar icon is a template image, so macOS handles dark/light mode automatically.
+
+## License
+
+MIT

lowhum-0.4.0/docs/index.html

@@ -0,0 +1,197 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>LowHum</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+
+  :root {
+    --bg: #0d0d0d;
+    --fg: #e0e0e0;
+    --mute: #7a7a7a;
+    --accent: #c8b88a;
+    --card: #1a1a1a;
+    --border: #2a2a2a;
+    --ok: #5a8a5a;
+  }
+  .light {
+    --bg: #ede8d8;
+    --fg: #2a2418;
+    --mute: #8a7e6a;
+    --accent: #6b5c3a;
+    --card: #ddd6c2;
+    --border: #c8c0aa;
+    --ok: #4a7a3a;
+  }
+
+  body {
+    background: var(--bg);
+    color: var(--fg);
+    font-family: 'SF Mono', 'Fira Code', 'JetBrains Mono', monospace;
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    padding: 2rem;
+    transition: background 0.3s, color 0.3s;
+  }
+
+  .theme-toggle {
+    position: fixed;
+    top: 1.2rem;
+    right: 1.4rem;
+    background: none;
+    border: none;
+    cursor: pointer;
+    color: var(--mute);
+    transition: color 0.2s;
+    padding: 0.4rem;
+  }
+  .theme-toggle:hover { color: var(--accent); }
+  .theme-toggle svg { display: block; }
+
+  a.bison-link {
+    text-decoration: none;
+    color: var(--accent);
+    cursor: default;
+    transition: color 0.3s;
+  }
+  a.bison-link:hover { color: var(--fg); }
+
+  pre.bison {
+    font-size: clamp(0.45rem, 1.8vw, 0.95rem);
+    line-height: 1.3;
+    white-space: pre;
+    text-align: left;
+    margin-bottom: 0.5rem;
+  }
+
+  .tagline {
+    color: var(--mute);
+    font-size: 0.95rem;
+    margin-bottom: 2.5rem;
+    letter-spacing: 0.05em;
+    transition: color 0.3s;
+  }
+
+  .install-row {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin-bottom: 0.75rem;
+  }
+  .install-cmd {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    padding: 0.6rem 1rem;
+    color: var(--accent);
+    font-size: 0.85rem;
+    font-family: inherit;
+    min-width: 280px;
+    transition: background 0.3s, border-color 0.3s, color 0.3s;
+  }
+  .copy-btn {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    width: 36px;
+    height: 36px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    color: var(--mute);
+    transition: border-color 0.2s, color 0.2s, background 0.3s;
+  }
+  .copy-btn:hover { border-color: var(--accent); color: var(--accent); }
+  .copy-btn.copied { border-color: var(--ok); color: var(--ok); }
+  .copy-btn svg { display: block; }
+</style>
+</head>
+<body>
+
+<button class="theme-toggle" onclick="toggleTheme()" aria-label="Toggle theme">
+  <svg id="icon-sun" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+    <circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/>
+  </svg>
+  <svg id="icon-moon" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:none">
+    <path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/>
+  </svg>
+</button>
+
+<a class="bison-link" href="https://github.com/lmarkmann/lowhum" target="_blank" rel="noopener">
+<pre class="bison">
+               _.-````'-,_
+     _,.,_ ,-'           `'-.,_
+   /)     (\                   '`-.
+  ((      ) )                      `\
+   \)    (_/                        )\
+    |       /)           '    ,'    / \
+    `\    ^'            '     (    /  ))
+      |      _/\ ,     /    ,,`\   (  "`
+       \Y,   |  \  \  | ``````| / \_ \
+         `)_/    \  \  )    ( >  ( >
+                  \( \(     |/   |/
+                 /_(/_(    /_(  /_(
+</pre>
+</a>
+
+<p class="tagline">deep brown noise for focus</p>
+
+<div class="install-row">
+  <code class="install-cmd" id="cmd-uv">uv tool install -U lowhum</code>
+  <button class="copy-btn" onclick="copy('cmd-uv', this)" aria-label="Copy">
+    <svg class="ico-clip" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="14" height="14" x="8" y="8" rx="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/></svg>
+    <svg class="ico-check" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:none"><path d="M20 6 9 17l-5-5"/></svg>
+  </button>
+</div>
+
+<div class="install-row">
+  <code class="install-cmd" id="cmd-pip">pip install -U lowhum</code>
+  <button class="copy-btn" onclick="copy('cmd-pip', this)" aria-label="Copy">
+    <svg class="ico-clip" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="14" height="14" x="8" y="8" rx="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/></svg>
+    <svg class="ico-check" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:none"><path d="M20 6 9 17l-5-5"/></svg>
+  </button>
+</div>
+
+<script>
+function copy(id, btn) {
+  navigator.clipboard.writeText(document.getElementById(id).textContent);
+  btn.querySelector('.ico-clip').style.display = 'none';
+  btn.querySelector('.ico-check').style.display = 'block';
+  btn.classList.add('copied');
+  setTimeout(() => {
+    btn.querySelector('.ico-clip').style.display = 'block';
+    btn.querySelector('.ico-check').style.display = 'none';
+    btn.classList.remove('copied');
+  }, 1500);
+}
+
+function applyTheme(light) {
+  document.body.classList.toggle('light', light);
+  document.getElementById('icon-sun').style.display = light ? 'none' : 'block';
+  document.getElementById('icon-moon').style.display = light ? 'block' : 'none';
+}
+
+function toggleTheme() {
+  var light = !document.body.classList.contains('light');
+  applyTheme(light);
+  localStorage.setItem('theme', light ? 'light' : 'dark');
+}
+
+(function() {
+  var saved = localStorage.getItem('theme');
+  if (saved) {
+    applyTheme(saved === 'light');
+  } else if (window.matchMedia('(prefers-color-scheme: light)').matches) {
+    applyTheme(true);
+  }
+})()
+</script>
+
+</body>
+</html>

lowhum-0.4.0/info_about_dock_icon.md

@@ -0,0 +1,38 @@
+    Basic usage:
+
+     1 import rumps
+     2
+     3 class MyApp(rumps.App):
+     4     def __init__(self):
+     5         super().__init__("My App")
+     6         # Set dock icon from image file
+     7         self.dock_icon = "path/to/icon.png"
+
+    Key points:
+
+     - dock_icon accepts a path to an image file (PNG, ICNS, etc.)
+     - You can change it dynamically at runtime
+     - Set to None to hide the dock icon entirely
+     - Useful for status bar apps that want to optionally show/hide their dock presence
+
+    Example - toggling dock icon:
+
+      1 import rumps
+      2
+      3 class MyApp(rumps.App):
+      4     def __init__(self):
+      5         super().__init__("My App")
+      6         self.menu = ["Toggle Dock Icon", "Quit"]
+      7
+      8     @rumps.clicked("Toggle Dock Icon")
+      9     def toggle(self, _):
+     10         if self.dock_icon:
+     11             self.dock_icon = None  # Hide
+     12         else:
+     13             self.dock_icon = "icon.png"  # Show
+     14
+     15 if __name__ == "__main__":
+     16     MyApp().run()
+
+    This is separate from the status bar icon - you can have both, one, or neither
+    depending on your app's needs.

lowhum-0.4.0/justfile

@@ -0,0 +1,14 @@
+version := `python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])"`
+
+build:
+    uv run python setup.py py2app
+
+archive: build
+    cd dist && zip -r "LowHum-{{version}}-macOS-arm64.zip" LowHum.app
+
+clean:
+    rm -rf .venv build dist .ruff_cache .pytest_cache .mypy_cache
+    find . -type d -name "__pycache__" -prune -exec rm -rf {} +
+
+sha256:
+    shasum -a 256 dist/LowHum-{{version}}-macOS-arm64.zip

lowhum-0.4.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "lowhum"
+version = "0.4.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 :: 3 - Alpha",
+    "Environment :: MacOS X",
+    "Intended Audience :: End Users/Desktop",
+    "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",
+]
+
+[dependency-groups]
+dev = [
+    "ty>=0.0.1a7",
+    "py2app>=0.28",
+    "pytest>=8.0",
+    "ruff>=0.9",
+    "setuptools>=82",
+]
+
+
+[project.scripts]
+lowhum = "lowhum.cli:app"
+lhm = "lowhum.cli:app"
+
+[project.urls]
+Homepage = "https://lmarkmann.github.io/lowhum/"
+Repository = "https://github.com/lmarkmann/lowhum"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lowhum"]
+exclude = ["*.wav"]
+
+[tool.ruff]
+line-length = 80
+
+[tool.mypy]
+ignore_missing_imports = true

lowhum-0.4.0/setup.py

@@ -0,0 +1,85 @@
+"""py2app build configuration for LowHum.app.
+
+Usage:
+    uv run python setup.py py2app
+"""
+
+import importlib.metadata
+import sys
+from pathlib import Path
+
+# Ensure py2app can find the lowhum package from src/ layout,
+# even when the editable install .pth file isn't processed.
+sys.path.insert(0, str(Path(__file__).parent / "src"))
+
+from setuptools import setup
+
+try:
+    _VERSION = importlib.metadata.version("lowhum")
+except Exception:
+    _VERSION = "0.0.0"
+
+# py2app 0.28 rejects install_requires, but setuptools auto-populates
+# it from pyproject.toml [project].dependencies. Patch the check out.
+import py2app.build_app as _build_app  # noqa: E402
+
+_orig_finalize = _build_app.py2app.finalize_options
+
+
+def _finalize_no_install_requires(self):
+    self.distribution.install_requires = []
+    _orig_finalize(self)
+
+
+_build_app.py2app.finalize_options = _finalize_no_install_requires
+
+APP = ["src/lowhum/cli.py"]
+
+OPTIONS = {
+    "argv_emulation": False,
+    # Avoid py2app's Tk/Tcl recipe (we don't ship/use tkinter).
+    # This prevents flaky builds caused by environment-dependent Tk checks.
+    "excludes": [
+        "tkinter",
+        "_tkinter",
+        "tk",
+        "tcl",
+        "Tkinter",
+        "Tix",
+        "ttk",
+    ],
+    "plist": {
+        "CFBundleName": "LowHum",
+        "CFBundleDisplayName": "LowHum",
+        "CFBundleIdentifier": "com.lowhum.app",
+        "CFBundleVersion": _VERSION,
+        "CFBundleShortVersionString": _VERSION,
+        # LSUIElement=False so app appears in Force Quit (Cmd+Option+Esc).
+        # Dock visibility is controlled at runtime via setActivationPolicy.
+        "LSUIElement": False,
+    },
+    "packages": [
+        "lowhum",
+        "numpy",
+        "scipy",
+        "sounddevice",
+        "rumps",
+        "typer",
+        "click",
+        "rich",
+        "pygments",
+        "markdown_it",
+        "mdurl",
+        "PIL",
+        "_sounddevice_data",
+    ],
+    "includes": ["typing_extensions"],
+    "iconfile": "LowHum.icns",
+}
+
+setup(
+    app=APP,
+    name="LowHum",
+    options={"py2app": OPTIONS},
+    setup_requires=["py2app"],
+)

lowhum-0.4.0/src/lowhum/__init__.py

@@ -0,0 +1,19 @@
+"""LowHum: deep brown noise for focus."""
+
+try:
+    from importlib.metadata import metadata as _metadata
+
+    _meta = _metadata("lowhum")
+    __version__ = _meta["Version"]
+    __title__ = _meta["Name"]
+    __author__ = _meta["Author"]
+    __license__ = _meta["License-Expression"]
+    __summary__ = _meta["Summary"]
+    __url__ = _meta["Project-URL"].split(", ", 1)[1]  # "Homepage, https://..."
+except Exception:
+    __version__ = "0.4.0"
+    __title__ = "lowhum"
+    __author__ = "Luis Markmann"
+    __license__ = "MIT"
+    __summary__ = "Deep Brown Noise for Focus as a MenuBar App & CLI Tool"
+    __url__ = "https://lmarkmann.github.io/lowhum/"