buzz: initial mirror

This commit is contained in:
Hermenix committed 2026-09-28 05:01:41 +00:00
commit 8993f026d3
13 files changed
+536

No files matched your search

+9
View File
@@ -0,0 +1,9 @@
"""hhstream -- publish a headless Hyprland session's frames on a Unix socket.
The wire format is specified in docs/CONTRACT.md; that document is authoritative
and this package must not drift from it.
"""
__version__ = "0.1.0"
MAGIC = "HHS1"
+38
View File
@@ -0,0 +1,38 @@
"""Capture backends: how one frame is obtained from the running compositor.
The backend is injected so tests never need a real compositor: the module option
`captureCommand` (see docs/CONTRACT.md) picks the program, and a fake command
produces frames in a unit test.
"""
from __future__ import annotations
import subprocess
from typing import Protocol
class CaptureBackend(Protocol):
def grab(self) -> bytes:
"""Return one complete encoded frame. Raise on failure."""
...
def size(self) -> tuple[int, int]:
"""Pixel size of the captured output, for the Hello."""
...
class CommandCapture:
"""Runs a helper that writes one frame to stdout (default: grim)."""
def __init__(self, argv: list[str], env: dict[str, str] | None = None,
timeout: float = 5.0) -> None:
raise NotImplementedError
def grab(self) -> bytes:
raise NotImplementedError
def size(self) -> tuple[int, int]:
raise NotImplementedError
__all__ = ["CaptureBackend", "CommandCapture", "subprocess"]
+24
View File
@@ -0,0 +1,24 @@
"""The client: connect, read the Hello, then read frames."""
from __future__ import annotations
import argparse
from typing import Iterable
DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
def fetch(socket_path: str, count: int = 1, timeout: float = 10.0) -> list[bytes]:
"""Connect and return up to `count` frame payloads (Hello consumed)."""
raise NotImplementedError
def build_parser() -> argparse.ArgumentParser:
raise NotImplementedError
def main(argv: Iterable[str] | None = None) -> int:
raise NotImplementedError
__all__ = ["fetch", "DEFAULT_SOCKET", "build_parser", "main"]
+46
View File
@@ -0,0 +1,46 @@
"""Framing: the bytes on the socket. See docs/CONTRACT.md.
Pure functions, no I/O -- this is the part that earns unit tests.
"""
from __future__ import annotations
import json
from typing import BinaryIO
from . import MAGIC
def hello(width: int, height: int, fmt: str, fps: int) -> bytes:
"""The one-line JSON Hello, `\\n`-terminated.
`fmt` is a MIME type ("image/png" / "image/jpeg").
"""
raise NotImplementedError
def parse_hello(line: bytes) -> dict:
"""Inverse of `hello`: validate `magic` and required fields, or raise."""
raise NotImplementedError
def frame(payload: bytes) -> bytes:
"""`<ascii length>\\n<payload>` for one complete image."""
raise NotImplementedError
def read_frame(stream: BinaryIO) -> bytes | None:
"""Read one framed payload from `stream`.
Returns None on a clean EOF before any byte of the next frame. Raises
ValueError on a malformed length prefix and EOFError on a truncated payload.
"""
raise NotImplementedError
def read_hello(stream: BinaryIO) -> dict:
"""Read and parse the Hello line from `stream`."""
raise NotImplementedError
__all__ = ["json", "hello", "parse_hello", "frame", "read_frame", "read_hello", "MAGIC"]
+38
View File
@@ -0,0 +1,38 @@
"""The frame server: catches each client up, then feeds it every frame.
One thread per client is the simple design that satisfies the contract ("a
stalled client is slowed, not queued"): a client's socket is written to
synchronously, and a slow write blocks only that client.
"""
from __future__ import annotations
import argparse
import socket
from typing import Iterable
from .capture import CaptureBackend, CommandCapture
DEFAULT_SOCKET = "/run/hyprland-headless-stream/stream.sock"
class FrameServer:
def __init__(self, socket_path: str, capture: CaptureBackend, fps: int,
fmt: str = "image/png") -> None:
raise NotImplementedError
def serve_forever(self) -> None:
"""Bind, then serve until stopped. A stale socket file is replaced."""
raise NotImplementedError
def build_parser() -> argparse.ArgumentParser:
raise NotImplementedError
def main(argv: Iterable[str] | None = None) -> int:
raise NotImplementedError
__all__ = ["FrameServer", "DEFAULT_SOCKET", "CaptureBackend", "CommandCapture",
"socket", "build_parser", "main"]