capturekit 0.1.0__py3-none-any.whl

capturekit/config.py

@@ -0,0 +1,85 @@
+"""Recording configuration."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+
+
+class AudioMixMode(enum.Enum):
+    #: One track per audio source (default).
+    SEPARATE = "separate"
+    #: A single track containing the sum of all sources.
+    MIXED = "mixed"
+    #: Separate tracks followed by a mixed track.
+    BOTH = "both"
+
+
+class TargetLostPolicy(enum.Enum):
+    #: Stop and finalise the recording, report via ``on_error``.
+    STOP = "stop"
+    #: Keep recording, repeating the last frame (window closed / device gone).
+    CONTINUE = "continue"
+
+
+class Container(enum.Enum):
+    MKV = "matroska"
+    MP4 = "mp4"
+
+
+@dataclass(frozen=True, slots=True)
+class EncoderConfig:
+    """Video/audio encoder settings.
+
+    ``encoder``: ``"auto"`` probes hardware encoders (NVENC → QSV → AMF) and
+    falls back to ``libx264``. Explicit FFmpeg encoder names are accepted
+    (``"h264_nvenc"``, ``"libx264"``, ...). ``fallback`` allows trying the next
+    candidate when an explicitly requested encoder fails validation.
+
+    ``bitrate`` in bits/s; ``None`` uses constant-quality mode with
+    ``quality`` (CRF/CQ, lower is better, default 23).
+    """
+
+    encoder: str = "auto"
+    codec: str = "h264"
+    bitrate: int | None = None
+    quality: int = 23
+    preset: str | None = None
+    keyframe_interval_s: float = 2.0
+    fallback: bool = True
+    audio_codec: str = "aac"
+    audio_bitrate: int = 192_000
+    ffmpeg_path: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordingConfig:
+    """Recording settings.
+
+    ``output_size``: fixed output resolution ``(w, h)``. ``None`` uses the
+    source size at start. When a window is resized during recording its
+    content is placed at the top-left and padded with black / cropped.
+    Odd sizes are rounded down to even (required for 4:2:0 encoding).
+
+    ``queue_frames`` bounds raw frames waiting for the encoder (memory ≈
+    ``queue_frames * w * h * 4`` bytes).
+    """
+
+    fps: float = 30.0
+    output_size: tuple[int, int] | None = None
+    container: Container | None = None
+    encoder: EncoderConfig = field(default_factory=EncoderConfig)
+    audio_mix: AudioMixMode = AudioMixMode.SEPARATE
+    audio_sample_rate: int = 48_000
+    queue_frames: int = 8
+    overwrite: bool = False
+    on_target_lost: TargetLostPolicy = TargetLostPolicy.STOP
+    start_timeout_s: float = 10.0
+
+    def __post_init__(self) -> None:
+        if not (1.0 <= self.fps <= 240.0):
+            raise ValueError(f"fps must be within 1..240, got {self.fps}")
+        if self.queue_frames < 2:
+            raise ValueError("queue_frames must be >= 2")
+        if self.output_size is not None and (self.output_size[0] < 2 or self.output_size[1] < 2):
+            raise ValueError(f"invalid output_size {self.output_size}")

capturekit/encoding/__init__.py

@@ -0,0 +1,5 @@
+"""Encoding through FFmpeg subprocesses."""
+
+from .ffmpeg import EncoderProbe, ffmpeg_version, find_ffmpeg, probe_encoder, select_encoder
+
+__all__ = ["EncoderProbe", "ffmpeg_version", "find_ffmpeg", "probe_encoder", "select_encoder"]

capturekit/encoding/ffmpeg.py

@@ -0,0 +1,356 @@
+"""FFmpeg discovery, encoder validation, command construction and process control."""
+
+from __future__ import annotations
+
+import collections
+import os
+import shutil
+import subprocess
+import sys
+import threading
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..config import Container, EncoderConfig
+from ..errors import EncoderError, EncoderNotAvailableError
+
+#: Order used by ``encoder="auto"`` (hardware first).
+AUTO_H264_ORDER = ("h264_nvenc", "h264_qsv", "h264_amf", "libx264", "h264_mf")
+HARDWARE_ENCODERS = {
+    "h264_nvenc",
+    "h264_qsv",
+    "h264_amf",
+    "h264_mf",
+    "h264_vaapi",
+    "hevc_nvenc",
+    "hevc_qsv",
+    "hevc_amf",
+}
+#: Encoders that accept BGRA input directly (colour conversion on the GPU).
+BGRA_INPUT_ENCODERS = {"h264_nvenc", "hevc_nvenc", "av1_nvenc", "libx264rgb"}
+
+_CREATE_NO_WINDOW = 0x08000000 if sys.platform == "win32" else 0
+
+
+def find_ffmpeg(explicit: str | None = None) -> str:
+    """Locate an FFmpeg executable.
+
+    Order: ``explicit`` → ``$CAPTUREKIT_FFMPEG`` → ``PATH`` → the optional
+    ``imageio-ffmpeg`` bundled binary.
+    """
+    for cand in (explicit, os.environ.get("CAPTUREKIT_FFMPEG")):
+        if cand:
+            if Path(cand).is_file():
+                return str(Path(cand).resolve())
+            raise EncoderNotAvailableError(f"FFmpeg not found at {cand!r}")
+    found = _which_no_cwd("ffmpeg")
+    if found:
+        return found
+    try:
+        import imageio_ffmpeg
+
+        exe = imageio_ffmpeg.get_ffmpeg_exe()
+        if exe and Path(exe).is_file():
+            return str(exe)
+    except Exception:
+        pass
+    raise EncoderNotAvailableError(
+        "FFmpeg executable not found: install FFmpeg, set CAPTUREKIT_FFMPEG, or "
+        "`pip install capturekit[ffmpeg]`"
+    )
+
+
+def _which_no_cwd(name: str) -> str | None:
+    """``shutil.which`` restricted to absolute PATH entries.
+
+    On Windows ``shutil.which`` also searches the current directory first,
+    which would execute a planted ``ffmpeg.exe`` from e.g. a downloads folder.
+    """
+    cwd = os.path.normcase(os.path.abspath(os.getcwd()))
+    dirs = [
+        d
+        for d in os.environ.get("PATH", "").split(os.pathsep)
+        if d and os.path.isabs(d) and os.path.normcase(os.path.abspath(d)) != cwd
+    ]
+    found = shutil.which(name, path=os.pathsep.join(dirs)) if dirs else None
+    if found and os.path.normcase(os.path.dirname(os.path.abspath(found))) == cwd:
+        return None
+    return str(Path(found).resolve()) if found else None
+
+
+def _run(args: Sequence[str], timeout: float) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        list(args), capture_output=True, text=True, timeout=timeout,
+        stdin=subprocess.DEVNULL, creationflags=_CREATE_NO_WINDOW, check=False,
+    )  # fmt: skip
+
+
+def ffmpeg_version(ffmpeg: str) -> str:
+    out = _run([ffmpeg, "-hide_banner", "-version"], 15).stdout
+    return out.splitlines()[0] if out else "unknown"
+
+
+@dataclass(frozen=True, slots=True)
+class EncoderProbe:
+    name: str
+    usable: bool
+    hardware: bool
+    reason: str = ""
+
+
+_probe_cache: dict[tuple[str, float, str], EncoderProbe] = {}
+_probe_lock = threading.Lock()
+
+
+def probe_encoder(ffmpeg: str, encoder: str) -> EncoderProbe:
+    """Validate an encoder by actually initialising it (a 3-frame encode).
+
+    ``-encoders`` listing is not enough: e.g. ``h264_qsv`` is listed in most
+    Windows builds but fails without an Intel GPU.
+    """
+    key = (ffmpeg, os.path.getmtime(ffmpeg), encoder)
+    with _probe_lock:
+        if key in _probe_cache:
+            return _probe_cache[key]
+    pix = (
+        "bgra"
+        if encoder in BGRA_INPUT_ENCODERS
+        else ("nv12" if encoder in HARDWARE_ENCODERS else "yuv420p")
+    )
+    args = [
+        ffmpeg, "-hide_banner", "-nostdin", "-loglevel", "error",
+        "-f", "lavfi", "-i", "color=c=black:s=256x256:r=30",
+        "-frames:v", "3", "-pix_fmt", pix, "-c:v", encoder, "-f", "null", "-",
+    ]  # fmt: skip
+    try:
+        res = _run(args, 30)
+        ok = res.returncode == 0
+        reason = "" if ok else (res.stderr.strip().splitlines() or ["failed"])[-1]
+    except subprocess.TimeoutExpired:
+        ok, reason = False, "probe timed out"
+    probe = EncoderProbe(encoder, ok, encoder in HARDWARE_ENCODERS, reason)
+    with _probe_lock:
+        _probe_cache[key] = probe
+    return probe
+
+
+def select_encoder(ffmpeg: str, cfg: EncoderConfig, size: tuple[int, int]) -> str:
+    """Choose a validated encoder according to ``cfg``.
+
+    Raises :class:`EncoderNotAvailableError` with every rejection reason when
+    nothing works (never silently picks something the caller excluded).
+    """
+    if cfg.encoder == "auto":
+        candidates: list[str] = list(AUTO_H264_ORDER)
+    else:
+        candidates = [cfg.encoder]
+        if cfg.fallback:
+            candidates += [e for e in AUTO_H264_ORDER if e != cfg.encoder]
+    reasons = []
+    for enc in candidates:
+        # NVENC rejects tiny frames on some GPU generations.
+        if enc.endswith("_nvenc") and (size[0] < 160 or size[1] < 64):
+            reasons.append(f"{enc}: frame {size} below NVENC minimum")
+            continue
+        probe = probe_encoder(ffmpeg, enc)
+        if probe.usable:
+            return enc
+        reasons.append(f"{enc}: {probe.reason}")
+    raise EncoderNotAvailableError("no usable video encoder:\n  " + "\n  ".join(reasons))
+
+
+@dataclass(frozen=True, slots=True)
+class AudioInput:
+    path: str  # pipe path FFmpeg reads from
+    sample_rate: int
+    channels: int
+    title: str
+
+
+def container_for(output: str, explicit: Container | None) -> Container:
+    if explicit is not None:
+        return explicit
+    ext = Path(output).suffix.lower()
+    if ext in (".mp4", ".m4v", ".mov"):
+        return Container.MP4
+    return Container.MKV
+
+
+def _video_codec_args(encoder: str, cfg: EncoderConfig, fps: float) -> list[str]:
+    gop = max(1, round(cfg.keyframe_interval_s * fps))
+    args = ["-c:v", encoder, "-g", str(gop)]
+    br = cfg.bitrate
+    if encoder.endswith("_nvenc"):
+        args += ["-preset", cfg.preset or "p4"]
+        if br:
+            args += [
+                "-rc",
+                "vbr",
+                "-b:v",
+                str(br),
+                "-maxrate",
+                str(int(br * 1.5)),
+                "-bufsize",
+                str(br * 2),
+            ]
+        else:
+            args += ["-rc", "vbr", "-cq", str(cfg.quality), "-b:v", "0"]
+    elif encoder.endswith("_qsv"):
+        args += ["-pix_fmt", "nv12", "-preset", cfg.preset or "veryfast"]
+        args += ["-b:v", str(br)] if br else ["-global_quality", str(cfg.quality)]
+    elif encoder.endswith("_amf"):
+        args += ["-pix_fmt", "nv12", "-quality", cfg.preset or "balanced"]
+        if br:
+            args += ["-rc", "vbr_peak", "-b:v", str(br), "-maxrate", str(int(br * 1.5))]
+        else:
+            args += ["-rc", "cqp", "-qp_i", str(cfg.quality), "-qp_p", str(cfg.quality)]
+    elif encoder == "h264_mf":
+        args += ["-pix_fmt", "nv12", "-b:v", str(br or 8_000_000)]
+    else:  # libx264 and other software encoders
+        args += ["-pix_fmt", "yuv420p", "-preset", cfg.preset or "veryfast"]
+        if br:
+            args += ["-b:v", str(br), "-maxrate", str(int(br * 1.5)), "-bufsize", str(br * 2)]
+        else:
+            args += ["-crf", str(cfg.quality)]
+    return args
+
+
+def build_command(
+    ffmpeg: str,
+    *,
+    output: str,
+    container: Container,
+    encoder: str | None,
+    cfg: EncoderConfig,
+    video_size: tuple[int, int] | None,
+    fps: float,
+    audio_inputs: Sequence[AudioInput] = (),
+    overwrite: bool = False,
+) -> list[str]:
+    """Build the FFmpeg argument list (never passed through a shell).
+
+    The output is given as ``file:<absolute path>`` so names starting with
+    ``-`` or containing ``proto:`` prefixes cannot be misinterpreted.
+    """
+    args = [ffmpeg, "-hide_banner", "-nostdin", "-loglevel", "warning", "-nostats"]
+    args.append("-y" if overwrite else "-n")
+    inputs = 0
+    if video_size is not None:
+        w, h = video_size
+        args += [
+            "-thread_queue_size", "64", "-probesize", "32", "-analyzeduration", "0",
+            "-f", "rawvideo", "-pix_fmt", "bgra", "-video_size", f"{w}x{h}",
+            "-framerate", _fps_str(fps), "-i", "pipe:0",
+        ]  # fmt: skip
+        inputs += 1
+    for a in audio_inputs:
+        args += [
+            "-thread_queue_size", "1024", "-probesize", "32", "-analyzeduration", "0",
+            "-f", "f32le", "-ar", str(a.sample_rate), "-ac", str(a.channels), "-i", a.path,
+        ]  # fmt: skip
+        inputs += 1
+    for i in range(inputs):
+        args += ["-map", f"{i}"]
+    if video_size is not None:
+        assert encoder is not None
+        # No colour-space override: NVENC's internal RGB->YUV and swscale's
+        # default both use BT.601, which is what the encoders tag.
+        args += _video_codec_args(encoder, cfg, fps)
+    if audio_inputs:
+        acodec = cfg.audio_codec
+        args += ["-c:a", acodec]
+        if acodec not in ("flac", "pcm_f32le", "pcm_s16le"):
+            args += ["-b:a", str(cfg.audio_bitrate)]
+        for i, a in enumerate(audio_inputs):
+            args += [f"-metadata:s:a:{i}", f"title={a.title}"]
+    if container is Container.MP4:
+        # Fragmented MP4 stays playable if the process dies mid-recording.
+        args += ["-f", "mp4", "-movflags", "+frag_keyframe+empty_moov+default_base_moof"]
+    else:
+        args += ["-f", "matroska"]
+    args.append("file:" + str(Path(output).resolve()))
+    return args
+
+
+def _fps_str(fps: float) -> str:
+    if abs(fps - round(fps)) < 1e-9:
+        return str(round(fps))
+    # NTSC-style rates such as 29.97 → 30000/1001
+    for base in (24, 30, 60, 120):
+        if abs(fps - base * 1000 / 1001) < 1e-3:
+            return f"{base * 1000}/1001"
+    return f"{fps:.6f}"
+
+
+class FFmpegProcess:
+    """A running FFmpeg process with continuous stderr draining."""
+
+    def __init__(self, args: list[str]) -> None:
+        self.args = args
+        self._stderr_tail: collections.deque[str] = collections.deque(maxlen=200)
+        try:
+            self.proc = subprocess.Popen(
+                args,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.PIPE,
+                creationflags=_CREATE_NO_WINDOW,
+                bufsize=0,
+            )
+        except OSError as exc:
+            raise EncoderNotAvailableError(f"failed to start FFmpeg: {exc}") from exc
+        self._stderr_thread = threading.Thread(
+            target=self._drain, name="capturekit-ffmpeg-stderr", daemon=True
+        )
+        self._stderr_thread.start()
+
+    def _drain(self) -> None:
+        assert self.proc.stderr is not None
+        for raw in iter(self.proc.stderr.readline, b""):
+            self._stderr_tail.append(raw.decode("utf-8", "replace").rstrip())
+
+    @property
+    def stderr_tail(self) -> str:
+        return "\n".join(self._stderr_tail)
+
+    def write(self, data: memoryview | bytes) -> None:
+        """Write all of ``data`` to stdin (raises EncoderError if FFmpeg died)."""
+        stdin = self.proc.stdin
+        assert stdin is not None
+        mv = memoryview(data).cast("B")
+        try:
+            while mv:
+                mv = mv[stdin.write(mv) :]
+        except (BrokenPipeError, OSError, ValueError) as exc:
+            self.proc.poll()
+            raise EncoderError(
+                f"FFmpeg stopped accepting video ({exc})",
+                stderr_tail=self.stderr_tail,
+                returncode=self.proc.returncode,
+            ) from exc
+
+    def close_stdin(self) -> None:
+        if self.proc.stdin is not None and not self.proc.stdin.closed:
+            try:
+                self.proc.stdin.close()
+            except OSError:
+                pass
+
+    def wait(self, timeout: float) -> int:
+        """Wait for exit; terminate/kill on timeout. Returns the exit code."""
+        try:
+            return self.proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            self.proc.terminate()
+            try:
+                return self.proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                self.proc.kill()
+                return self.proc.wait(timeout=5)
+        finally:
+            self._stderr_thread.join(timeout=2)
+
+    def kill(self) -> None:
+        if self.proc.poll() is None:
+            self.proc.kill()

capturekit/encoding/pipes.py

@@ -0,0 +1,212 @@
+"""Extra FFmpeg inputs: Windows named pipes and POSIX FIFOs.
+
+The pipe is created before FFmpeg starts; a writer thread connects (blocking
+until FFmpeg opens it) and streams data. ``abort()`` unblocks a writer stuck in
+connect by connecting to the pipe ourselves.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+import threading
+import uuid
+
+from ..errors import EncoderError
+
+
+class OutputPipe:
+    path: str
+
+    def connect(self) -> None:
+        raise NotImplementedError
+
+    def write(self, data: bytes | memoryview) -> None:
+        raise NotImplementedError
+
+    def close(self) -> None:
+        raise NotImplementedError
+
+    def abort(self) -> None:
+        raise NotImplementedError
+
+
+if sys.platform == "win32":
+    import ctypes
+    from ctypes import byref, c_void_p
+    from ctypes import wintypes as wt
+
+    _k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    _adv = ctypes.WinDLL("advapi32", use_last_error=True)
+    _k32.CreateNamedPipeW.argtypes = (
+        wt.LPCWSTR,
+        wt.DWORD,
+        wt.DWORD,
+        wt.DWORD,
+        wt.DWORD,
+        wt.DWORD,
+        wt.DWORD,
+        c_void_p,
+    )
+    _k32.CreateNamedPipeW.restype = wt.HANDLE
+    _k32.ConnectNamedPipe.argtypes = (wt.HANDLE, c_void_p)
+    _k32.ConnectNamedPipe.restype = wt.BOOL
+    _k32.WriteFile.argtypes = (wt.HANDLE, c_void_p, wt.DWORD, ctypes.POINTER(wt.DWORD), c_void_p)
+    _k32.WriteFile.restype = wt.BOOL
+    _k32.FlushFileBuffers.argtypes = (wt.HANDLE,)
+    _k32.DisconnectNamedPipe.argtypes = (wt.HANDLE,)
+    _k32.CloseHandle.argtypes = (wt.HANDLE,)
+    _k32.CreateFileW.argtypes = (
+        wt.LPCWSTR,
+        wt.DWORD,
+        wt.DWORD,
+        c_void_p,
+        wt.DWORD,
+        wt.DWORD,
+        wt.HANDLE,
+    )
+    _k32.CreateFileW.restype = wt.HANDLE
+    _k32.LocalFree.argtypes = (c_void_p,)
+    _adv.ConvertStringSecurityDescriptorToSecurityDescriptorW.argtypes = (
+        wt.LPCWSTR,
+        wt.DWORD,
+        ctypes.POINTER(c_void_p),
+        c_void_p,
+    )
+    _adv.ConvertStringSecurityDescriptorToSecurityDescriptorW.restype = wt.BOOL
+
+    class SECURITY_ATTRIBUTES(ctypes.Structure):
+        _fields_ = [
+            ("nLength", wt.DWORD),
+            ("lpSecurityDescriptor", c_void_p),
+            ("bInheritHandle", wt.BOOL),
+        ]
+
+    INVALID_HANDLE_VALUE = wt.HANDLE(-1).value
+    PIPE_ACCESS_OUTBOUND = 0x2
+    FILE_FLAG_FIRST_PIPE_INSTANCE = 0x00080000
+    PIPE_TYPE_BYTE = 0x0
+    PIPE_WAIT = 0x0
+    PIPE_REJECT_REMOTE_CLIENTS = 0x8
+    ERROR_PIPE_CONNECTED = 535
+    GENERIC_READ = 0x80000000
+    OPEN_EXISTING = 3
+    #: Owner (current user), SYSTEM and Administrators only — other local
+    #: users cannot connect and read the recorded audio.
+    _PIPE_SDDL = "D:P(A;;GA;;;OW)(A;;GA;;;SY)(A;;GA;;;BA)"
+
+    class NamedPipe(OutputPipe):
+        def __init__(self, label: str, buffer_size: int = 1 << 20) -> None:
+            self.path = rf"\\.\pipe\capturekit-{uuid.uuid4().hex}-{label}"
+            sd = c_void_p()
+            if not _adv.ConvertStringSecurityDescriptorToSecurityDescriptorW(
+                self._sddl(), 1, byref(sd), None
+            ):
+                raise EncoderError(f"security descriptor failed ({ctypes.get_last_error()})")
+            sa = SECURITY_ATTRIBUTES(ctypes.sizeof(SECURITY_ATTRIBUTES), sd, False)
+            try:
+                self._h = _k32.CreateNamedPipeW(
+                    self.path,
+                    PIPE_ACCESS_OUTBOUND | FILE_FLAG_FIRST_PIPE_INSTANCE,
+                    PIPE_TYPE_BYTE | PIPE_WAIT | PIPE_REJECT_REMOTE_CLIENTS,
+                    1, buffer_size, buffer_size, 0, byref(sa),
+                )  # fmt: skip
+            finally:
+                _k32.LocalFree(sd)
+            if self._h in (None, INVALID_HANDLE_VALUE):
+                raise EncoderError(f"CreateNamedPipe failed ({ctypes.get_last_error()})")
+            self._lock = threading.Lock()
+            self._connected = False
+            self._closed = False
+
+        @staticmethod
+        def _sddl() -> str:
+            return _PIPE_SDDL
+
+        def connect(self) -> None:
+            ok = _k32.ConnectNamedPipe(self._h, None)
+            if not ok:
+                err = ctypes.get_last_error()
+                if err != ERROR_PIPE_CONNECTED:
+                    raise EncoderError(f"ConnectNamedPipe failed ({err})")
+            self._connected = True
+
+        def write(self, data: bytes | memoryview) -> None:
+            mv = memoryview(data).cast("B")
+            written = wt.DWORD()
+            while mv:
+                chunk = mv[: 1 << 20]
+                buf = (
+                    (ctypes.c_char * len(chunk)).from_buffer_copy(chunk)
+                    if chunk.readonly
+                    else (ctypes.c_char * len(chunk)).from_buffer(chunk)
+                )
+                if not _k32.WriteFile(self._h, buf, len(chunk), byref(written), None):
+                    raise EncoderError(
+                        f"audio pipe write failed ({ctypes.get_last_error()}); "
+                        "FFmpeg closed its input"
+                    )
+                mv = mv[written.value :]
+
+        def close(self) -> None:
+            with self._lock:
+                if self._closed:
+                    return
+                self._closed = True
+                # Plain CloseHandle: the client still reads buffered data, then
+                # gets EOF. FlushFileBuffers would block until FFmpeg reads
+                # everything (forever if FFmpeg is stalled).
+                _k32.CloseHandle(self._h)
+
+        def abort(self) -> None:
+            """Unblock a pending ``connect()`` by connecting as a client."""
+            h = _k32.CreateFileW(self.path, GENERIC_READ, 0, None, OPEN_EXISTING, 0, None)
+            if h not in (None, INVALID_HANDLE_VALUE):
+                _k32.CloseHandle(h)
+
+    def create_pipe(label: str) -> OutputPipe:
+        return NamedPipe(label)
+
+else:
+
+    class Fifo(OutputPipe):
+        _dir: str | None = None
+
+        def __init__(self, label: str) -> None:
+            if Fifo._dir is None or not os.path.isdir(Fifo._dir):
+                Fifo._dir = tempfile.mkdtemp(prefix="capturekit-")  # mode 0700
+            self.path = os.path.join(Fifo._dir, f"{uuid.uuid4().hex}-{label}.f32")
+            os.mkfifo(self.path, 0o600)
+            self._fd: int | None = None
+
+        def connect(self) -> None:
+            self._fd = os.open(self.path, os.O_WRONLY)  # blocks until FFmpeg opens it
+
+        def write(self, data: bytes | memoryview) -> None:
+            assert self._fd is not None
+            mv = memoryview(data).cast("B")
+            try:
+                while mv:
+                    mv = mv[os.write(self._fd, mv) :]
+            except BrokenPipeError as exc:
+                raise EncoderError("FFmpeg closed its audio input") from exc
+
+        def close(self) -> None:
+            if self._fd is not None:
+                os.close(self._fd)
+                self._fd = None
+            try:
+                os.unlink(self.path)
+            except FileNotFoundError:
+                pass
+
+        def abort(self) -> None:
+            try:
+                fd = os.open(self.path, os.O_RDONLY | os.O_NONBLOCK)
+                os.close(fd)
+            except OSError:
+                pass
+
+    def create_pipe(label: str) -> OutputPipe:
+        return Fifo(label)