buzzkit 0.1.2__tar.gz → 0.1.4__tar.gz

buzzkit-0.1.4/.cargo/config.toml

@@ -0,0 +1,12 @@
+# The `opus` crate (audiopus_sys) builds a vendored libopus whose CMakeLists
+# declares a pre-3.5 minimum; CMake 4 removed compatibility with those and
+# aborts configure. This env var is CMake's documented escape hatch and is a
+# no-op on older CMake. Applies to local builds, CI, and source installs alike.
+#
+# Deliberately NOT set here: CMAKE_TOOLCHAIN_FILE. cmake-rs skips its own
+# cross-compilation config whenever a toolchain file is present, which breaks
+# cross builds (aarch64 wheels compiled host-arch objects). The lib64 pin in
+# build-support/vendored-libopus.cmake is applied only where needed, by the
+# release workflow (native RPM-family manylinux containers).
+[env]
+CMAKE_POLICY_VERSION_MINIMUM = "3.5"

{buzzkit-0.1.2 → buzzkit-0.1.4}/.github/workflows/CI.yml

@@ -29,11 +29,20 @@ jobs:
       - name: Clippy
         run: cargo clippy --all-targets -- -D warnings
 
+      - name: Rust tests
+        run: cargo test
+
       - name: Install (editable) with dev deps
         run: pip install -e '.[dev]'
 
       - name: Ruff
         run: ruff check python tests examples
 
+      - name: Ruff format
+        run: ruff format --check python tests examples
+
+      - name: Type check (ty)
+        run: ty check python
+
       - name: Pytest
         run: pytest

{buzzkit-0.1.2 → buzzkit-0.1.4}/.github/workflows/release.yml

@@ -21,7 +21,9 @@ jobs:
         platform:
           - { os: ubuntu-latest, target: x86_64 }
           - { os: ubuntu-latest, target: aarch64 }
-          - { os: macos-13, target: x86_64 }
+          # Intel wheel is cross-compiled from the ARM runner: GitHub retired
+          # the macos-13 (Intel) runners — the label queues forever.
+          - { os: macos-14, target: x86_64 }
           - { os: macos-14, target: aarch64 }
           - { os: windows-latest, target: x64 }
     steps:
@@ -34,7 +36,23 @@ jobs:
         with:
           target: ${{ matrix.platform.target }}
           args: --release --out dist
-          manylinux: auto
+          # 2_28 (not auto): its cross toolchains are recent enough to compile
+          # the vendored libopus NEON intrinsics (manylinux2014's aarch64 gcc
+          # chokes on them).
+          manylinux: 2_28
+          # Static libopus so the wheel is self-contained; cmake for the
+          # vendored build when the container doesn't ship it. On RPM-family
+          # containers (native x86_64 manylinux) GNUInstallDirs installs to
+          # lib64 where audiopus_sys never looks — pin libdir via a toolchain
+          # file there. Never set it for the cross containers (Ubuntu-family,
+          # libdir is already "lib"): cmake-rs skips its own cross config when
+          # a toolchain file is present, producing host-arch objects.
+          before-script-linux: |
+            export LIBOPUS_STATIC=1
+            command -v cmake || yum install -y cmake || dnf install -y cmake || (apt-get update && apt-get install -y cmake)
+            if [ -f /etc/redhat-release ] || [ -f /etc/almalinux-release ]; then
+              export CMAKE_TOOLCHAIN_FILE="$(pwd)/build-support/vendored-libopus.cmake"
+            fi
       - uses: actions/upload-artifact@v4
         with:
           name: wheels-${{ matrix.platform.os }}-${{ matrix.platform.target }}
@@ -69,3 +87,7 @@ jobs:
           merge-multiple: true
           path: dist
       - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # API token (PYPI_API_TOKEN secret). Falls back to trusted
+          # publishing (OIDC) if the secret is ever removed.
+          password: ${{ secrets.PYPI_API_TOKEN }}

{buzzkit-0.1.2 → buzzkit-0.1.4}/.gitignore

@@ -8,3 +8,4 @@ __pycache__/
 agent.secret
 /dist
 owner.secret
+/tasks

{buzzkit-0.1.2 → buzzkit-0.1.4}/Cargo.lock

@@ -27,6 +27,17 @@ version = "0.7.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56"
 
+[[package]]
+name = "audiopus_sys"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "62314a1546a2064e033665d658e88c620a62904be945f8147e6b16c3db9f8651"
+dependencies = [
+ "cmake",
+ "log",
+ "pkg-config",
+]
+
 [[package]]
 name = "autocfg"
 version = "1.5.1"
@@ -168,13 +179,14 @@ dependencies = [
 
 [[package]]
 name = "buzzkit"
-version = "0.1.2"
+version = "0.1.4"
 dependencies = [
  "base64",
  "buzz-core",
  "buzz-sdk",
  "hex",
  "nostr",
+ "opus",
  "pyo3",
  "sha2 0.10.9",
  "uuid",
@@ -265,6 +277,15 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "cmake"
+version = "0.1.58"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0f78a02292a74a88ac736019ab962ece0bc380e3f977bf72e376c5d78ff0678"
+dependencies = [
+ "cc",
+]
+
 [[package]]
 name = "cmov"
 version = "0.5.4"
@@ -748,6 +769,15 @@ version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
 
+[[package]]
+name = "opus"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4d3809943dff6fbad5f0484449ea26bdb9cb7d8efdf26ed50d3c7f227f69eb5c"
+dependencies = [
+ "audiopus_sys",
+]
+
 [[package]]
 name = "password-hash"
 version = "0.5.0"
@@ -781,6 +811,12 @@ version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
+[[package]]
+name = "pkg-config"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
+
 [[package]]
 name = "poly1305"
 version = "0.8.0"

{buzzkit-0.1.2 → buzzkit-0.1.4}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "buzzkit"
-version = "0.1.2"
+version = "0.1.4"
 edition = "2021"
 publish = false
 description = "PyO3 bindings over Block's Buzz zero-I/O crates (buzz-core / buzz-sdk)"
@@ -13,7 +13,9 @@ name = "_native"
 crate-type = ["cdylib"]
 
 [dependencies]
-pyo3 = { version = "0.24", features = ["extension-module", "abi3-py312"] }
+# extension-module is enabled by maturin via pyproject.toml, not here, so
+# plain `cargo build` / `cargo test` can link against libpython.
+pyo3 = { version = "0.24", features = ["abi3-py312"] }
 # Must match the `nostr` version buzz-core/buzz-sdk resolve to so the
 # Event/Keys/EventBuilder types unify across crate boundaries.
 nostr = { version = "0.44", features = ["nip44", "nip98"] }
@@ -24,3 +26,4 @@ uuid = { version = "1", features = ["v4"] }
 sha2 = "0.10"
 hex = "0.4"
 base64 = "0.22"
+opus = "0.3"

{buzzkit-0.1.2 → buzzkit-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buzzkit
-Version: 0.1.2
+Version: 0.1.4
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -16,6 +16,7 @@ Requires-Dist: websockets>=13
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
 Requires-Dist: ruff>=0.6 ; extra == 'dev'
+Requires-Dist: ty>=0.0.60 ; extra == 'dev'
 Requires-Dist: maturin>=1.7,<2 ; extra == 'dev'
 Provides-Extra: dev
 License-File: LICENSE
@@ -86,6 +87,32 @@ async def main():
 asyncio.run(main())
 ```
 
+### Huddle audio (voice)
+
+Buzz huddles are ephemeral voice channels; audio is Opus (48 kHz mono, 20 ms
+frames) over a dedicated WebSocket. `HuddleClient` handles the handshake,
+Opus encode/decode (in Rust), and real-time outbound pacing — you deal in raw
+PCM (s16le mono 48 kHz):
+
+```python
+from buzzkit import BuzzClient, HuddleAudio, HuddleClient
+
+# Huddles announce themselves as kind 48100 on their parent channel:
+async with BuzzClient(relay_url, nsec) as bz:
+    async for ev in bz.subscribe_channel(parent_id, kinds=[buzzkit.KIND_HUDDLE_STARTED]):
+        huddle_id = json.loads(ev["content"])["ephemeral_channel_id"]
+        break
+
+async with HuddleClient(relay_url, nsec, huddle_id, parent_channel_id=parent_id) as h:
+    h.send_pcm(pcm_s16le_48k)              # queued, paced at 50 frames/s
+    async for ev in h.events():
+        if isinstance(ev, HuddleAudio):    # decoded remote audio
+            print(ev.pubkey, len(ev.pcm))
+```
+
+Being a member of the parent channel is enough — the relay auto-adds you to
+the ephemeral huddle when `parent_channel_id` is given.
+
 ## Joining a community (relay onboarding)
 
 Hosted Buzz communities are **closed relays**: an identity must be a relay member
@@ -114,6 +141,8 @@ claiming. After joining, `set_profile(...)` gives the agent a display name.
 | `verify_event(json)` | check id + Schnorr signature |
 | `BuzzClient.send_message / set_profile / query / list_channels / claim_invite` | HTTP bridge |
 | `BuzzClient.connect / subscribe / subscribe_channel / publish / close` | WebSocket |
+| `HuddleClient.connect / send_pcm / events / clear_queue / leave` | huddle voice (Opus) |
+| `HuddleEncoder` / `HuddleDecoder` | raw huddle wire frames ↔ PCM |
 
 ## Build from source
 

{buzzkit-0.1.2 → buzzkit-0.1.4}/README.md

@@ -53,6 +53,32 @@ async def main():
 asyncio.run(main())
 ```
 
+### Huddle audio (voice)
+
+Buzz huddles are ephemeral voice channels; audio is Opus (48 kHz mono, 20 ms
+frames) over a dedicated WebSocket. `HuddleClient` handles the handshake,
+Opus encode/decode (in Rust), and real-time outbound pacing — you deal in raw
+PCM (s16le mono 48 kHz):
+
+```python
+from buzzkit import BuzzClient, HuddleAudio, HuddleClient
+
+# Huddles announce themselves as kind 48100 on their parent channel:
+async with BuzzClient(relay_url, nsec) as bz:
+    async for ev in bz.subscribe_channel(parent_id, kinds=[buzzkit.KIND_HUDDLE_STARTED]):
+        huddle_id = json.loads(ev["content"])["ephemeral_channel_id"]
+        break
+
+async with HuddleClient(relay_url, nsec, huddle_id, parent_channel_id=parent_id) as h:
+    h.send_pcm(pcm_s16le_48k)              # queued, paced at 50 frames/s
+    async for ev in h.events():
+        if isinstance(ev, HuddleAudio):    # decoded remote audio
+            print(ev.pubkey, len(ev.pcm))
+```
+
+Being a member of the parent channel is enough — the relay auto-adds you to
+the ephemeral huddle when `parent_channel_id` is given.
+
 ## Joining a community (relay onboarding)
 
 Hosted Buzz communities are **closed relays**: an identity must be a relay member
@@ -81,6 +107,8 @@ claiming. After joining, `set_profile(...)` gives the agent a display name.
 | `verify_event(json)` | check id + Schnorr signature |
 | `BuzzClient.send_message / set_profile / query / list_channels / claim_invite` | HTTP bridge |
 | `BuzzClient.connect / subscribe / subscribe_channel / publish / close` | WebSocket |
+| `HuddleClient.connect / send_pcm / events / clear_queue / leave` | huddle voice (Opus) |
+| `HuddleEncoder` / `HuddleDecoder` | raw huddle wire frames ↔ PCM |
 
 ## Build from source
 

buzzkit-0.1.4/build-support/vendored-libopus.cmake

@@ -0,0 +1,11 @@
+# Toolchain file for building the vendored libopus (audiopus_sys) via cmake-rs.
+#
+# audiopus_sys's build script adds only `<out>/lib` to the linker search path,
+# but GNUInstallDirs installs to `lib64` on RPM-family hosts (manylinux,
+# Fedora, RHEL) — the link then fails with `unable to find library -lopus`.
+# Pinning the classic layout keeps the library where the build script looks.
+#
+# Applied by the release workflow ONLY on native RPM-family containers.
+# Do not export CMAKE_TOOLCHAIN_FILE globally: cmake-rs skips its own
+# cross-compilation config when a toolchain file is present.
+set(CMAKE_INSTALL_LIBDIR "lib" CACHE PATH "installation libdir pinned for audiopus_sys" FORCE)

buzzkit-0.1.4/examples/analyze_audio_tap.py

@@ -0,0 +1,218 @@
+"""Analyze audio tap captures and point at the failing link.
+
+Reads a capture directory produced by either (or both):
+  * roomkit's ``examples/buzz_voice_agent.py`` run with ``BUZZ_TAP_DIR=...``
+    (sender-side taps: provider_out_24k.raw, pacer_in_48k.raw,
+    wire_out_48k.raw, wire_send.csv, events.csv), or
+  * ``examples/huddle_wire_recorder.py`` (receiver-side: recv_frames.csv,
+    peer<N>_48k.raw).
+
+and reports, per stage: send/arrival timing (stalls, bursts), silence frames
+spliced into speech, wire sequence gaps, and audible holes inside the PCM.
+
+    python examples/analyze_audio_tap.py <capture_dir>
+
+Reading the verdict:
+  * holes in wire_out_48k.raw but not in pacer_in_48k.raw
+        -> the pacer inserted silence / dropped audio (sender side).
+  * clean wire_out but recv_frames.csv shows seq gaps or heavy arrival jitter
+        -> frames lost or bunched between agent and relay fan-out.
+  * clean + smooth arrivals at the recorder, but the app still sounds choppy
+        -> receiver side (NetEq/playout in the desktop app).
+"""
+
+from __future__ import annotations
+
+import csv
+import pathlib
+import sys
+
+FRAME_MS = 20.0
+NS = 1_000_000  # ns per ms
+
+
+def fmt_ts(ms: float) -> str:
+    return f"{int(ms // 60000):02d}:{ms % 60000 / 1000:06.3f}"
+
+
+# ---------------------------------------------------------------- timing CSVs
+
+
+def analyze_send_timing(rows: list[dict], t_key: str, label: str) -> None:
+    """Inter-send/arrival timing: stalls (>2x frame) and bursts (<2 ms)."""
+    times = [int(r[t_key]) for r in rows]
+    if len(times) < 2:
+        print(f"  {label}: not enough rows")
+        return
+    deltas = [(b - a) / NS for a, b in zip(times, times[1:])]
+    span_s = (times[-1] - times[0]) / NS / 1000
+    stalls = [(i, d) for i, d in enumerate(deltas) if d > 2 * FRAME_MS]
+    bursts = sum(1 for d in deltas if d < 2.0)
+    print(
+        f"  {label}: {len(times)} frames over {span_s:.1f}s "
+        f"(mean {sum(deltas) / len(deltas):.1f} ms/frame, max gap {max(deltas):.0f} ms)"
+    )
+    print(f"    gaps >{2 * FRAME_MS:.0f} ms: {len(stalls)}   sends <2 ms apart (bursts): {bursts}")
+    t0 = times[0]
+    for i, d in stalls[:10]:
+        print(f"      gap {d:6.0f} ms at t+{fmt_ts((times[i] - t0) / NS)}")
+    if len(stalls) > 10:
+        print(f"      … and {len(stalls) - 10} more")
+
+
+def analyze_wire_csv(path: pathlib.Path) -> None:
+    rows = list(csv.DictReader(path.open()))
+    if not rows:
+        print("  wire_send.csv: empty")
+        return
+    print("wire_send.csv — pacer output timing (what buzzkit is asked to send):")
+    analyze_send_timing(rows, "t_mono_ns", "pacer->send_pcm")
+
+    # Silence frames spliced into speech: an all-zero send whose neighbours
+    # within 300 ms on both sides contain non-zero audio.
+    times = [int(r["t_mono_ns"]) for r in rows]
+    zero = [r["all_zero"] == "1" for r in rows]
+    t0 = times[0]
+    nonzero_times = [t for t, z in zip(times, zero) if not z]
+    spliced = []
+    for t, z in zip(times, zero):
+        if not z or not nonzero_times:
+            continue
+        # nearest real-audio sends before/after this silence frame
+        before = any(0 < t - u <= 300 * NS for u in nonzero_times)
+        after = any(0 < u - t <= 300 * NS for u in nonzero_times)
+        if before and after:
+            spliced.append(t)
+    n_zero = sum(zero)
+    print(f"    all-zero frames: {n_zero} total, {len(spliced)} spliced mid-speech")
+    for t in spliced[:10]:
+        print(f"      silence splice at t+{fmt_ts((t - t0) / NS)}")
+    if len(spliced) > 10:
+        print(f"      … and {len(spliced) - 10} more")
+
+
+def analyze_recv_csv(path: pathlib.Path) -> None:
+    rows = list(csv.DictReader(path.open()))
+    if not rows:
+        print("  recv_frames.csv: empty")
+        return
+    print("recv_frames.csv — wire arrivals at the recorder (per peer):")
+    peers: dict[str, list[dict]] = {}
+    for r in rows:
+        peers.setdefault(r["peer_index"], []).append(r)
+    for peer, frames in sorted(peers.items()):
+        speech = [f for f in frames if f["is_dtx"] == "0"]
+        dtx = len(frames) - len(speech)
+        print(f"  peer {peer}: {len(speech)} speech frames, {dtx} DTX")
+        if len(speech) < 2:
+            continue
+        analyze_send_timing(speech, "t_mono_ns", f"peer {peer} arrivals")
+        # Wire continuity over ALL frames (DTX included — every wire packet
+        # consumes one seq and 960 ts): dseq != 1 means frames were lost or
+        # reordered between the sender and us; dts != dseq*960 means the
+        # sender's own media timeline jumped (encoder restart / bug).
+        lost = jumps = 0
+        for a, b in zip(frames, frames[1:]):
+            dseq = (int(b["seq"]) - int(a["seq"])) % 65536
+            dts = (int(b["ts_48k"]) - int(a["ts_48k"])) % (1 << 32)
+            if dseq != 1:
+                lost += 1
+                if lost <= 10:
+                    print(f"      lost/reordered: seq {a['seq']}->{b['seq']} ({dseq - 1} missing)")
+            elif dts != 960:
+                jumps += 1
+                if jumps <= 10:
+                    print(f"      sender ts jump at seq {b['seq']}: +{dts} (expected +960)")
+        print(f"    lost/reordered frames: {lost}   sender ts jumps: {jumps}")
+
+
+# ------------------------------------------------------------------ PCM scans
+
+
+def analyze_raw(path: pathlib.Path, rate: int) -> None:
+    """Find near-silent runs >=15 ms that sit inside speech (audible holes)."""
+    data = path.read_bytes()
+    samples = memoryview(data).cast("h")
+    n = len(samples)
+    if n == 0:
+        print(f"  {path.name}: empty")
+        return
+    ms = 1000.0 / rate
+    win = rate // 100  # 10 ms windows
+    # Classify 10 ms windows as silent/speech, then find silent runs
+    # bordered by speech within 200 ms on each side.
+    n_win = n // win
+    loud = []
+    for w in range(n_win):
+        seg = samples[w * win : (w + 1) * win]
+        peak = max(abs(min(seg)), abs(max(seg)))
+        loud.append(peak > 400)
+    holes: list[tuple[int, int]] = []
+    w = 0
+    while w < n_win:
+        if loud[w]:
+            w += 1
+            continue
+        start = w
+        while w < n_win and not loud[w]:
+            w += 1
+        run_ms = (w - start) * 10
+        ctx = 20  # 200 ms of context windows
+        speech_before = any(loud[max(0, start - ctx) : start])
+        speech_after = any(loud[w : w + ctx])
+        if run_ms >= 15 and run_ms <= 2000 and speech_before and speech_after:
+            holes.append((start, run_ms))
+    dur_s = n * ms / 1000
+    print(f"  {path.name}: {dur_s:.1f}s of audio, {len(holes)} hole(s) inside speech")
+    for start, run_ms in holes[:15]:
+        print(f"      {run_ms:4d} ms hole at {fmt_ts(start * 10.0)}")
+    if len(holes) > 15:
+        print(f"      … and {len(holes) - 15} more")
+
+
+RAW_RATES = {"24k": 24_000, "48k": 48_000, "16k": 16_000}
+
+
+def main() -> None:
+    if len(sys.argv) != 2:
+        raise SystemExit("usage: analyze_audio_tap.py <capture_dir>")
+    cap = pathlib.Path(sys.argv[1])
+    if not cap.is_dir():
+        raise SystemExit(f"not a directory: {cap}")
+
+    found = False
+    wire_csv = cap / "wire_send.csv"
+    if wire_csv.exists():
+        found = True
+        analyze_wire_csv(wire_csv)
+        print()
+    recv_csv = cap / "recv_frames.csv"
+    if recv_csv.exists():
+        found = True
+        analyze_recv_csv(recv_csv)
+        print()
+    events_csv = cap / "events.csv"
+    if events_csv.exists():
+        rows = list(csv.DictReader(events_csv.open()))
+        interesting = [r for r in rows if r.get("event") not in (None, "")]
+        if interesting:
+            print(f"events.csv: {len(interesting)} event(s)")
+            for r in interesting[:20]:
+                print(f"  {r}")
+            print()
+    raws = sorted(cap.glob("*.raw"))
+    if raws:
+        found = True
+        print("PCM hole scan (near-silence >=15 ms surrounded by speech):")
+        for raw in raws:
+            rate = next(
+                (hz for tag, hz in RAW_RATES.items() if tag in raw.name),
+                48_000,
+            )
+            analyze_raw(raw, rate)
+    if not found:
+        raise SystemExit(f"no tap files found in {cap}")
+
+
+if __name__ == "__main__":
+    main()

buzzkit-0.1.4/examples/huddle_echo.py

@@ -0,0 +1,58 @@
+"""Echo agent for Buzz huddles — repeats back everything it hears.
+
+Joins a huddle and echoes remote audio with a short delay. Useful for
+verifying the audio path end-to-end (desktop → relay → agent → relay →
+desktop) without any AI provider.
+
+    BUZZ_RELAY_URL=wss://... python examples/huddle_echo.py <parent_channel_id>
+
+Watches the parent channel for huddle announcements (kind 48100) and joins
+each one; pass a second argument to join a known huddle directly:
+
+    python examples/huddle_echo.py <parent_channel_id> <huddle_channel_id>
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import time
+
+from _shared import agent_secret, relay_url
+from buzzkit import KIND_HUDDLE_STARTED, BuzzClient, HuddleAudio, HuddleClient
+
+
+async def echo_in_huddle(relay: str, secret: str, huddle_id: str, parent_id: str) -> None:
+    async with HuddleClient(relay, secret, huddle_id, parent_channel_id=parent_id) as huddle:
+        print(f"joined huddle {huddle_id} — echoing (peers: {len(huddle.peers) - 1})")
+        async for ev in huddle.events():
+            if isinstance(ev, HuddleAudio):
+                huddle.send_pcm(ev.pcm)
+            else:
+                print(f"  {type(ev).__name__}: {ev.pubkey[:12]}…")
+        print(f"huddle {huddle_id} ended")
+
+
+async def main() -> None:
+    if len(sys.argv) < 2:
+        raise SystemExit("usage: huddle_echo.py <parent_channel_id> [huddle_channel_id]")
+    parent_id = sys.argv[1]
+    relay, secret = relay_url(), agent_secret()
+
+    if len(sys.argv) > 2:
+        await echo_in_huddle(relay, secret, sys.argv[2], parent_id)
+        return
+
+    print(f"watching {parent_id} for huddles…")
+    async with BuzzClient(relay, secret) as bz:
+        live = {"kinds": [KIND_HUDDLE_STARTED], "#h": [parent_id], "since": int(time.time())}
+        async for event in bz.subscribe([live]):
+            huddle_id = json.loads(event["content"]).get("ephemeral_channel_id")
+            if huddle_id:
+                await echo_in_huddle(relay, secret, huddle_id, parent_id)
+                print(f"watching {parent_id} for the next huddle…")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())