echotools 2.4.6__tar.gz → 2.4.8__tar.gz

{echotools-2.4.6 → echotools-2.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echotools
-Version: 2.4.6
+Version: 2.4.8
 Summary: 通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链
 Home-page: https://github.com/nichengfuben/echotools
 Author: nichengfuben
@@ -58,7 +58,7 @@ Requires-Dist: ruff>=0.4.0; extra == "dev"
 
 通用基础设施 SDK：配置、日志、事件、调度、插件、调用链，以及 **entml** LLM 工具调用协议与终端 Console UI。
 
-完全项目无关，兼容 Python 3.8–3.14。当前版本：**2.4.6**（详见 [CHANGELOG](docs/CHANGELOG.md)）。
+完全项目无关，兼容 Python 3.8–3.14。当前版本：**2.4.8**（详见 [CHANGELOG](docs/CHANGELOG.md)）。
 
 ## 安装
 
@@ -174,6 +174,7 @@ choice = run_select(ui, "选择主题", ["ocean", "forest", "sunset"])
 | `LocalTerminal` / `SSHTerminal` | 终端会话（需 `[terminal]` / `[ssh]`） |
 | `AutoUpdater` | git 自动更新 |
 | `FileWatcher` | 轮询文件监视 |
+| `plat.capture` | 跨平台音频监控/录音/截图（纯 ctypes，零第三方依赖） |
 
 ## 开发
 

{echotools-2.4.6 → echotools-2.4.8}/README.md

@@ -2,7 +2,7 @@
 
 通用基础设施 SDK：配置、日志、事件、调度、插件、调用链，以及 **entml** LLM 工具调用协议与终端 Console UI。
 
-完全项目无关，兼容 Python 3.8–3.14。当前版本：**2.4.6**（详见 [CHANGELOG](docs/CHANGELOG.md)）。
+完全项目无关，兼容 Python 3.8–3.14。当前版本：**2.4.8**（详见 [CHANGELOG](docs/CHANGELOG.md)）。
 
 ## 安装
 
@@ -118,6 +118,7 @@ choice = run_select(ui, "选择主题", ["ocean", "forest", "sunset"])
 | `LocalTerminal` / `SSHTerminal` | 终端会话（需 `[terminal]` / `[ssh]`） |
 | `AutoUpdater` | git 自动更新 |
 | `FileWatcher` | 轮询文件监视 |
+| `plat.capture` | 跨平台音频监控/录音/截图（纯 ctypes，零第三方依赖） |
 
 ## 开发
 

{echotools-2.4.6 → echotools-2.4.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "echotools"
-version = "2.4.6"
+version = "2.4.8"
 description = "通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -142,6 +142,23 @@ omit = [
     "*/web/application.py",
     "*/web/middleware.py",
     "*/web/utils.py",
+    "*/plat/capture/shared/win_com.py",
+    "*/plat/capture/audio_monitor/api.py",
+    "*/plat/capture/audio_record/api.py",
+    "*/plat/capture/screenshot/api.py",
+    "*/plat/capture/audio_monitor/win.py",
+    "*/plat/capture/audio_monitor/mac.py",
+    "*/plat/capture/audio_monitor/linux.py",
+    "*/plat/capture/audio_record/win.py",
+    "*/plat/capture/audio_record/win_wasapi.py",
+    "*/plat/capture/audio_record/win_winmm.py",
+    "*/plat/capture/audio_record/mac.py",
+    "*/plat/capture/audio_record/linux.py",
+    "*/plat/capture/screenshot/win.py",
+    "*/plat/capture/screenshot/win_dxgi.py",
+    "*/plat/capture/screenshot/win_gdi.py",
+    "*/plat/capture/screenshot/mac.py",
+    "*/plat/capture/screenshot/linux.py",
 ]
 
 [tool.coverage.report]

{echotools-2.4.6 → echotools-2.4.8}/src/echotools/__init__.py

@@ -105,6 +105,14 @@ __all__ = [
     "ProtocolError",
     "classify_http_error",
     "Spinner",
+    "AudioProcess",
+    "AudioMonitorConfig",
+    "get_playing_processes",
+    "run_audio_monitor",
+    "AudioRecordConfig",
+    "record_audio_session",
+    "ScreenshotConfig",
+    "capture_screenshots",
 ]
 
 _EXPORTS: dict[str, tuple[str, str]] = {
@@ -131,7 +139,7 @@ _EXPORTS: dict[str, tuple[str, str]] = {
     "make_id": ("echotools.exec.dispatch", "make_id"),
     "AdaptiveSelector": ("echotools.exec.dispatch", "AdaptiveSelector"),
     "TaskDispatcher": ("echotools.exec.dispatch", "TaskDispatcher"),
-    "TaskScheduler": ("echotools.plat.scheduler", "TaskScheduler"),
+    "TaskScheduler": ("echotools.plat.sdk.scheduler", "TaskScheduler"),
     "ProxySelector": ("echotools.exec.dispatch", "ProxySelector"),
     "ProxyRecord": ("echotools.exec.dispatch", "ProxyRecord"),
     "Plugin": ("echotools.plat.plugin", "Plugin"),
@@ -147,7 +155,7 @@ _EXPORTS: dict[str, tuple[str, str]] = {
     "ProxyManager": ("echotools.plat.proxy", "ProxyManager"),
     "PortReleaseResult": ("echotools.exec.process", "PortReleaseResult"),
     "ensure_port_available": ("echotools.exec.process", "ensure_port_available"),
-    "RuntimeCollector": ("echotools.plat.runtime", "RuntimeCollector"),
+    "RuntimeCollector": ("echotools.plat.sdk.runtime", "RuntimeCollector"),
     "WebApplication": ("echotools.media.web.application", "WebApplication"),
     "json_body": ("echotools.media.web.utils", "json_body"),
     "safe_flush": ("echotools.media.web.utils", "safe_flush"),
@@ -197,6 +205,14 @@ _EXPORTS: dict[str, tuple[str, str]] = {
     "ProtocolError": ("echotools.base.errors", "ProtocolError"),
     "classify_http_error": ("echotools.base.errors", "classify_http_error"),
     "Spinner": ("echotools.media.spinner", "Spinner"),
+    "AudioProcess": ("echotools.plat.capture", "AudioProcess"),
+    "AudioMonitorConfig": ("echotools.plat.capture", "AudioMonitorConfig"),
+    "get_playing_processes": ("echotools.plat.capture", "get_playing_processes"),
+    "run_audio_monitor": ("echotools.plat.capture", "run_audio_monitor"),
+    "AudioRecordConfig": ("echotools.plat.capture", "AudioRecordConfig"),
+    "record_audio_session": ("echotools.plat.capture", "record_audio_session"),
+    "ScreenshotConfig": ("echotools.plat.capture", "ScreenshotConfig"),
+    "capture_screenshots": ("echotools.plat.capture", "capture_screenshots"),
 }
 
 

{echotools-2.4.6 → echotools-2.4.8}/src/echotools/exec/fncall/protocols/entml_schema/validate.py

@@ -5,8 +5,6 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Any, Dict, List, Optional, Sequence
 
-from echotools.exec.fncall.shared.coercion import is_null_literal, schema_allows_null
-
 _SCALAR_CHECK = {
     "string": lambda v: isinstance(v, str),
     "integer": lambda v: isinstance(v, int) and not isinstance(v, bool),

{echotools-2.4.6 → echotools-2.4.8}/src/echotools/exec/fncall/shared/coercion.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 import json
-from typing import Any, Dict, List, Optional, Sequence
+from typing import Any, Dict, List, Optional
 
 from echotools.base.logger.manager import get_logger
 

echotools-2.4.8/src/echotools/plat/capture/__init__.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+"""Cross-platform audio/screenshot capture (ctypes + stdlib only)."""
+
+from echotools.plat.capture.audio_monitor.api import (
+    get_playing_processes,
+    run_audio_monitor,
+)
+from echotools.plat.capture.audio_monitor.config import AudioMonitorConfig
+from echotools.plat.capture.audio_monitor.types import AudioProcess
+from echotools.plat.capture.audio_record.api import record_audio_session
+from echotools.plat.capture.audio_record.config import AudioRecordConfig
+from echotools.plat.capture.screenshot.api import capture_screenshots
+from echotools.plat.capture.screenshot.config import ScreenshotConfig
+
+__all__ = [
+    "AudioMonitorConfig",
+    "AudioProcess",
+    "AudioRecordConfig",
+    "ScreenshotConfig",
+    "capture_screenshots",
+    "get_playing_processes",
+    "record_audio_session",
+    "run_audio_monitor",
+]

echotools-2.4.8/src/echotools/plat/capture/audio_monitor/api.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+"""Portable audio session monitor API."""
+
+import sys
+import time
+
+from echotools.plat.capture.audio_monitor.config import AudioMonitorConfig
+from echotools.plat.capture.audio_monitor.types import AudioProcess
+from echotools.plat.capture.shared.platform import _OS, IS_LINUX, IS_MACOS, IS_WINDOWS
+
+if IS_WINDOWS:
+    from echotools.plat.capture.audio_monitor.win import win_get_playing
+elif IS_MACOS:
+    from echotools.plat.capture.audio_monitor.mac import mac_get_playing
+elif IS_LINUX:
+    from echotools.plat.capture.audio_monitor.linux import linux_get_playing
+
+
+def get_playing_processes(
+    config: AudioMonitorConfig | None = None,
+) -> list[AudioProcess]:
+    """Return processes currently playing audio."""
+    cfg = config or AudioMonitorConfig()
+    try:
+        if IS_WINDOWS:
+            return win_get_playing(cfg)
+        if IS_MACOS:
+            return mac_get_playing()
+        if IS_LINUX:
+            return linux_get_playing(cfg)
+        raise RuntimeError(f"不支持的平台: {_OS}")
+    except Exception as exc:
+        print(f"[!] get_playing_processes 异常: {exc}")
+        return []
+
+
+def _format_process(ap: AudioProcess, cfg: AudioMonitorConfig) -> str:
+    parts = [f"📢 {ap.name}"]
+    if cfg.show_pid and ap.pid > 0:
+        parts.append(f"PID={ap.pid}")
+    if ap.volume >= 0:
+        parts.append(f"vol={ap.volume:.0%}")
+    return "  " + " | ".join(parts)
+
+
+def _print_monitor_update(
+    procs: list[AudioProcess],
+    cfg: AudioMonitorConfig,
+    last_set: set[AudioProcess],
+) -> set[AudioProcess]:
+    cur_set = set(procs)
+    if cfg.print_on_change and cur_set == last_set:
+        return last_set
+    ts = (
+        f"  时间: {time.strftime('%Y-%m-%d %H:%M:%S')}"
+        if cfg.show_timestamp
+        else ""
+    )
+    print(f"\n{'=' * cfg.banner_width}")
+    if ts:
+        print(ts)
+    if cur_set:
+        for ap in sorted(cur_set, key=lambda x: x.name):
+            print(_format_process(ap, cfg))
+    else:
+        print("  🔇 当前没有进程在播放声音")
+    return cur_set
+
+
+def run_audio_monitor(config: AudioMonitorConfig | None = None) -> None:
+    """Poll and print playing audio processes until KeyboardInterrupt."""
+    cfg = config or AudioMonitorConfig()
+    py_ver = sys.version_info
+    print("=" * cfg.banner_width)
+    print(f"  跨平台音频进程监控器  [{_OS} / Python {py_ver.major}.{py_ver.minor}]")
+    print("  实时显示正在播放声音的进程")
+    print("  按 Ctrl+C 退出")
+    print("=" * cfg.banner_width)
+
+    last_set: set[AudioProcess] = set()
+    try:
+        while True:
+            procs = get_playing_processes(cfg)
+            last_set = _print_monitor_update(procs, cfg, last_set)
+            time.sleep(cfg.poll_interval_sec)
+    except KeyboardInterrupt:
+        print("\n\n  监控结束。")

echotools-2.4.8/src/echotools/plat/capture/audio_monitor/config.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class AudioMonitorConfig:
+    """Configuration for audio session monitoring."""
+
+    poll_interval_sec: float = 0.2
+    print_on_change: bool = True
+    show_timestamp: bool = True
+    show_pid: bool = True
+    active_state_only: bool = True
+    banner_width: int = 60

echotools-2.4.8/src/echotools/plat/capture/audio_monitor/linux.py

@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+"""Linux PulseAudio/ALSA audio session monitor with multi-tier fallback."""
+
+import ctypes
+import os
+import re
+import subprocess
+import time
+from ctypes import (
+    CFUNCTYPE,
+    POINTER,
+    Structure,
+    byref,
+    c_char_p,
+    c_int,
+    c_uint,
+    c_void_p,
+)
+
+from echotools.plat.capture.audio_monitor.config import AudioMonitorConfig
+from echotools.plat.capture.audio_monitor.types import AudioProcess
+from echotools.plat.capture.shared.platform import load_lib
+
+_pulse = load_lib("pulse", "libpulse.so.0", "libpulse.so")
+_linux_backend = "pulse_lib"
+
+PA_CONTEXT_READY = 4
+PA_CONTEXT_FAILED = 6
+PA_CONTEXT_TERMINATED = 7
+
+
+if _pulse:
+    class pa_sample_spec(Structure):
+        _fields_ = [("format", c_int), ("rate", c_uint), ("channels", ctypes.c_ubyte)]
+
+    _pulse.pa_mainloop_new.restype = c_void_p
+    _pulse.pa_mainloop_get_api.restype = c_void_p
+    _pulse.pa_mainloop_get_api.argtypes = [c_void_p]
+    _pulse.pa_mainloop_iterate.restype = c_int
+    _pulse.pa_mainloop_iterate.argtypes = [c_void_p, c_int, POINTER(c_int)]
+    _pulse.pa_mainloop_free.argtypes = [c_void_p]
+    _pulse.pa_context_new.restype = c_void_p
+    _pulse.pa_context_new.argtypes = [c_void_p, c_char_p]
+    _pulse.pa_context_connect.restype = c_int
+    _pulse.pa_context_connect.argtypes = [c_void_p, c_char_p, c_int, c_void_p]
+    _pulse.pa_context_get_state.restype = c_int
+    _pulse.pa_context_get_state.argtypes = [c_void_p]
+    _pulse.pa_context_get_sink_input_info_list.restype = c_void_p
+    _pulse.pa_context_get_sink_input_info_list.argtypes = [c_void_p, c_void_p, c_void_p]
+    _pulse.pa_operation_unref.argtypes = [c_void_p]
+    _pulse.pa_context_disconnect.argtypes = [c_void_p]
+    _pulse.pa_context_unref.argtypes = [c_void_p]
+
+
+def _pactl_sink_input_pids() -> list[int]:
+    out = subprocess.check_output(
+        ["pactl", "list", "sink-inputs"],
+        stderr=subprocess.DEVNULL,
+        timeout=3,
+    )
+    pids: list[int] = []
+    for line in out.decode(errors="replace").splitlines():
+        m = re.search(r'application\.process\.id\s*=\s*"(\d+)"', line)
+        if m:
+            pids.append(int(m.group(1)))
+    return pids
+
+
+def _wait_pulse_ready(ml, ctx) -> None:
+    if _pulse is None:
+        raise OSError("libpulse 不可用")
+    deadline = time.time() + 5.0
+    while time.time() < deadline:
+        ret = c_int(0)
+        _pulse.pa_mainloop_iterate(ml, 0, byref(ret))
+        st = _pulse.pa_context_get_state(ctx)
+        if st == PA_CONTEXT_READY:
+            return
+        if st in (PA_CONTEXT_FAILED, PA_CONTEXT_TERMINATED):
+            raise OSError(f"pa_context 失败 state={st}")
+    raise OSError("pa_context 超时")
+
+
+def _parse_sink_input(info_ptr: int) -> AudioProcess | None:
+    try:
+        idx = c_uint.from_address(info_ptr).value
+        off = ctypes.sizeof(c_uint) + (4 if ctypes.sizeof(c_void_p) == 8 else 0)
+        name_ptr = c_char_p.from_address(info_ptr + off).value
+        name = name_ptr.decode("utf-8", errors="replace") if name_ptr else f"stream_{idx}"
+        return AudioProcess(-1, name, "active")
+    except Exception:
+        return None
+
+
+def _make_sink_input_cb(result: list[AudioProcess], done_flag: list[bool]):
+    SI_CB = CFUNCTYPE(None, c_void_p, c_void_p, c_int, c_void_p)
+
+    def _si_callback(ctx_ptr, info_ptr, eol, userdata):
+        if eol:
+            done_flag[0] = True
+            return
+        if not info_ptr:
+            return
+        ap = _parse_sink_input(info_ptr)
+        if ap:
+            result.append(ap)
+
+    return SI_CB(_si_callback)
+
+
+def _poll_mainloop(ml, done_flag: list[bool], timeout: float) -> None:
+    if _pulse is None:
+        raise OSError("libpulse 不可用")
+    deadline = time.time() + timeout
+    while not done_flag[0] and time.time() < deadline:
+        ret = c_int(0)
+        _pulse.pa_mainloop_iterate(ml, 0, byref(ret))
+
+
+def _enrich_pulse_pids(result: list[AudioProcess]) -> None:
+    try:
+        pids = _pactl_sink_input_pids()
+    except Exception:
+        return
+    for i, ap in enumerate(result):
+        if i >= len(pids):
+            break
+        ap.pid = pids[i]
+        if ap.pid <= 0:
+            continue
+        try:
+            with open(f"/proc/{ap.pid}/comm") as f:
+                ap.name = f.read().strip()
+        except OSError:
+            pass
+
+
+def _pulse_get_playing() -> list[AudioProcess]:
+    if not _pulse:
+        raise OSError("libpulse 不可用")
+    ml = _pulse.pa_mainloop_new()
+    api = _pulse.pa_mainloop_get_api(ml)
+    ctx = _pulse.pa_context_new(api, b"audio_monitor")
+    _pulse.pa_context_connect(ctx, None, 0, None)
+    _wait_pulse_ready(ml, ctx)
+
+    result: list[AudioProcess] = []
+    done_flag = [False]
+    c_cb = _make_sink_input_cb(result, done_flag)
+    op = _pulse.pa_context_get_sink_input_info_list(ctx, c_cb, None)
+    _poll_mainloop(ml, done_flag, 3.0)
+    if op:
+        _pulse.pa_operation_unref(op)
+    _pulse.pa_context_disconnect(ctx)
+    _pulse.pa_context_unref(ctx)
+    _pulse.pa_mainloop_free(ml)
+    _enrich_pulse_pids(result)
+    return result
+
+
+def _pactl_get_playing(cfg: AudioMonitorConfig) -> list[AudioProcess]:
+    try:
+        out = subprocess.check_output(
+            ["pactl", "list", "sink-inputs"],
+            stderr=subprocess.DEVNULL,
+            timeout=3,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired, subprocess.CalledProcessError) as exc:
+        raise OSError("pactl 不可用") from exc
+
+    result: list[AudioProcess] = []
+    pid, name, muted = -1, "", False
+    for line in out.decode(errors="replace").splitlines():
+        line = line.strip()
+        m = re.search(r'application\.process\.id\s*=\s*"(\d+)"', line)
+        if m:
+            pid = int(m.group(1))
+        m = re.search(r'application\.name\s*=\s*"(.+)"', line)
+        if m:
+            name = m.group(1)
+        m = re.search(r"Mute:\s*(yes|no)", line)
+        if m:
+            muted = m.group(1) == "yes"
+        if pid > 0 and name:
+            proc_name = name
+            try:
+                with open(f"/proc/{pid}/comm") as f:
+                    proc_name = f.read().strip()
+            except OSError:
+                pass
+            state = "inactive" if muted else "active"
+            if not cfg.active_state_only or state == "active":
+                result.append(AudioProcess(pid, proc_name, state))
+            pid, name, muted = -1, "", False
+    return result
+
+
+def _lsof_snd_get_playing() -> list[AudioProcess]:
+    try:
+        out = subprocess.check_output(
+            ["lsof", "+D", "/dev/snd"],
+            stderr=subprocess.DEVNULL,
+            timeout=3,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired, subprocess.CalledProcessError) as exc:
+        raise OSError("lsof /dev/snd 失败") from exc
+    result: list[AudioProcess] = []
+    seen: set[int] = set()
+    for line in out.decode(errors="replace").splitlines()[1:]:
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        try:
+            pid = int(parts[1])
+        except ValueError:
+            continue
+        if pid in seen:
+            continue
+        seen.add(pid)
+        try:
+            with open(f"/proc/{pid}/comm") as f:
+                name = f.read().strip()
+        except OSError:
+            name = parts[0]
+        result.append(AudioProcess(pid, name, "unknown"))
+    return result
+
+
+def _read_running_pid(status_path: str) -> AudioProcess | None:
+    try:
+        with open(status_path) as f:
+            content = f.read()
+    except OSError:
+        return None
+    if "RUNNING" not in content:
+        return None
+    m = re.search(r"owner_pid\s*:\s*(\d+)", content)
+    if not m:
+        return None
+    pid = int(m.group(1))
+    try:
+        with open(f"/proc/{pid}/comm") as f:
+            name = f.read().strip()
+    except OSError:
+        name = f"pid_{pid}"
+    return AudioProcess(pid, name, "active")
+
+
+def _scan_pcm_dir(pcm_path: str, result: list[AudioProcess]) -> None:
+    for sub_entry in os.listdir(pcm_path):
+        status_path = os.path.join(pcm_path, sub_entry, "status")
+        if not os.path.isfile(status_path):
+            continue
+        ap = _read_running_pid(status_path)
+        if ap:
+            result.append(ap)
+
+
+def _proc_snd_get_playing() -> list[AudioProcess]:
+    result: list[AudioProcess] = []
+    asound = "/proc/asound"
+    if not os.path.isdir(asound):
+        return result
+    for card_entry in os.listdir(asound):
+        card_path = os.path.join(asound, card_entry)
+        if not (card_entry.startswith("card") and os.path.isdir(card_path)):
+            continue
+        for pcm_entry in os.listdir(card_path):
+            pcm_path = os.path.join(card_path, pcm_entry)
+            if not (pcm_entry.startswith("pcm") and os.path.isdir(pcm_path)):
+                continue
+            _scan_pcm_dir(pcm_path, result)
+    return result
+
+
+def linux_get_playing(cfg: AudioMonitorConfig) -> list[AudioProcess]:
+    global _linux_backend
+    if _linux_backend == "pulse_lib":
+        try:
+            return _pulse_get_playing()
+        except Exception as exc:
+            print(f"[!] libpulse 失败: {exc}  => 切换 pactl")
+            _linux_backend = "pactl"
+    if _linux_backend == "pactl":
+        try:
+            return _pactl_get_playing(cfg)
+        except Exception as exc:
+            print(f"[!] pactl 失败: {exc}  => 切换 lsof")
+            _linux_backend = "lsof"
+    if _linux_backend == "lsof":
+        try:
+            return _lsof_snd_get_playing()
+        except Exception as exc:
+            print(f"[!] lsof 失败: {exc}  => 切换 /proc/asound")
+            _linux_backend = "proc"
+    return _proc_snd_get_playing()