buzz: initial mirror
This commit is contained in:
commit
8993f026d3
13 files changed
+536
No files matched your search
@@ -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"
|
||||
@@ -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"]
|
||||
@@ -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"]
|
||||
@@ -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"]
|
||||
@@ -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"]
|
||||
Reference in new issue
Block a user