buzzkit 0.1.3__tar.gz → 0.1.4__tar.gz

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

@@ -38,5 +38,11 @@ jobs:
       - 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.3 → buzzkit-0.1.4}/.github/workflows/release.yml

@@ -87,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.3 → buzzkit-0.1.4}/Cargo.lock

@@ -179,7 +179,7 @@ dependencies = [
 
 [[package]]
 name = "buzzkit"
-version = "0.1.3"
+version = "0.1.4"
 dependencies = [
  "base64",
  "buzz-core",

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

@@ -1,6 +1,6 @@
 [package]
 name = "buzzkit"
-version = "0.1.3"
+version = "0.1.4"
 edition = "2021"
 publish = false
 description = "PyO3 bindings over Block's Buzz zero-I/O crates (buzz-core / buzz-sdk)"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buzzkit
-Version: 0.1.3
+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

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_wire_recorder.py

@@ -0,0 +1,123 @@
+"""Wire-side recorder for Buzz huddles — capture exactly what receivers get.
+
+Joins a huddle as a silent peer (sends nothing) and records every inbound
+audio frame with its arrival time and wire header. This is the ground truth
+for "what does the desktop app's jitter buffer actually see": if the audio
+is already choppy here, the sender (e.g. the roomkit agent) is at fault; if
+it is clean here but choppy in the app, the receiver side is at fault.
+
+Watch mode (recommended): give it only the parent channel — the one in your
+BUZZ_CHANNEL_ID — and it records every huddle announced there (kind 48100),
+one output directory per huddle:
+
+    BUZZ_RELAY_URL=wss://... python examples/huddle_wire_recorder.py \
+        <parent_channel_id>
+
+Direct mode, when you already know the ephemeral huddle id (the agent logs
+it as "Joined huddle <uuid>"):
+
+    python examples/huddle_wire_recorder.py <parent_channel_id> \
+        <huddle_channel_id> [out_dir]
+
+Output (out_dir, default ./wire-tap-<huddle>):
+    recv_frames.csv    one row per wire frame:
+                       t_mono_ns,peer_index,seq,ts_48k,level_dbov,is_dtx,pcm_bytes
+    events.csv         roster events: t_mono_ns,event,pubkey
+    peer<N>_48k.raw    decoded s16le mono 48 kHz PCM per peer (non-DTX frames,
+                       concatenated in arrival order — listen with:
+                       ffplay -f s16le -ar 48000 -ch_layout mono peer<N>_48k.raw)
+
+Analyze the capture with examples/analyze_audio_tap.py.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import pathlib
+import sys
+import time
+
+from _shared import agent_secret, relay_url
+from buzzkit import KIND_HUDDLE_STARTED, BuzzClient, HuddleAudio, HuddleClient
+
+
+async def record(
+    relay: str, secret: str, huddle_id: str, parent_id: str, out: pathlib.Path
+) -> None:
+    out.mkdir(parents=True, exist_ok=True)
+    frames_csv = (out / "recv_frames.csv").open("w")
+    frames_csv.write("t_mono_ns,peer_index,seq,ts_48k,level_dbov,is_dtx,pcm_bytes\n")
+    events_csv = (out / "events.csv").open("w")
+    events_csv.write("t_mono_ns,event,pubkey\n")
+    pcm_files: dict[int, object] = {}
+    n_frames = 0
+
+    # paced=False: the client never sends anything on its own (no silence
+    # stream), so this peer is acoustically invisible in the huddle.
+    client = HuddleClient(relay, secret, huddle_id, parent_channel_id=parent_id, paced=False)
+    async with client:
+        print(f"recording huddle {huddle_id} -> {out} (Ctrl+C to stop)")
+        try:
+            async for ev in client.events():
+                now = time.monotonic_ns()
+                if isinstance(ev, HuddleAudio):
+                    frames_csv.write(
+                        f"{now},{ev.peer_index},{ev.seq},{ev.ts_48k},"
+                        f"{ev.level_dbov},{int(ev.is_dtx)},{len(ev.pcm)}\n"
+                    )
+                    if not ev.is_dtx:
+                        f = pcm_files.get(ev.peer_index)
+                        if f is None:
+                            f = (out / f"peer{ev.peer_index}_48k.raw").open("wb")
+                            pcm_files[ev.peer_index] = f
+                        f.write(ev.pcm)
+                    n_frames += 1
+                    if n_frames % 500 == 0:
+                        frames_csv.flush()
+                        print(f"  {n_frames} frames…")
+                else:
+                    events_csv.write(f"{now},{type(ev).__name__},{ev.pubkey}\n")
+                    events_csv.flush()
+        finally:
+            frames_csv.close()
+            events_csv.close()
+            for f in pcm_files.values():
+                f.close()
+            print(f"done: {n_frames} frames from {len(pcm_files)} speaking peer(s)")
+            print(f"analyze with: python examples/analyze_audio_tap.py {out}")
+
+
+async def watch_and_record(relay: str, secret: str, parent_id: str) -> None:
+    """Record every huddle announced on the parent channel from now on."""
+    print(f"watching {parent_id} for huddles (kind {KIND_HUDDLE_STARTED})…")
+    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 not huddle_id:
+                continue
+            out = pathlib.Path(f"wire-tap-{huddle_id[:8]}")
+            await record(relay, secret, huddle_id, parent_id, out)
+            print(f"watching {parent_id} for the next huddle…")
+
+
+async def main() -> None:
+    if len(sys.argv) < 2:
+        raise SystemExit(
+            "usage: huddle_wire_recorder.py <parent_channel_id> [huddle_channel_id] [out_dir]"
+        )
+    parent_id = sys.argv[1]
+    if len(sys.argv) < 3:
+        await watch_and_record(relay_url(), agent_secret(), parent_id)
+        return
+    huddle_id = sys.argv[2]
+    out = pathlib.Path(sys.argv[3] if len(sys.argv) > 3 else f"wire-tap-{huddle_id[:8]}")
+    await record(relay_url(), agent_secret(), huddle_id, parent_id, out)
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass

{buzzkit-0.1.3 → buzzkit-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "buzzkit"
-version = "0.1.3"
+version = "0.1.4"
 description = "Python bindings + async client for Block's Buzz (Nostr) protocol, backed by Rust buzz-core/buzz-sdk"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -34,6 +34,7 @@ dev = [
     "pytest>=8",
     "pytest-asyncio>=0.24",
     "ruff>=0.6",
+    "ty>=0.0.60",
     "maturin>=1.7,<2",
 ]
 

{buzzkit-0.1.3 → buzzkit-0.1.4}/python/buzzkit/client.py

@@ -153,9 +153,7 @@ class BuzzClient:
         result = await self.publish(create_ev)
         if not result["accepted"]:
             raise RuntimeError(f"huddle channel rejected: {result['message']}")
-        started_ev = _native.build_huddle_started_event(
-            self._secret, parent_channel_id, huddle_id
-        )
+        started_ev = _native.build_huddle_started_event(self._secret, parent_channel_id, huddle_id)
         result = await self.publish(started_ev)
         if not result["accepted"]:
             raise RuntimeError(f"huddle announcement rejected: {result['message']}")