dsh-plugin-wallpaper-engine-media-bridge 0.0.0-stage → 1.4.1

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# cordis.patch.yml — `media-bridge` 子包（P-D 阶段1 起承载壁纸域宿主/浏览器半边，包名不变）自己的行
+# （ADR-0014 S4.1 / S4.2 / S4.4）。
+#
+# ⚠️ 一次安装形态（主包 patch 用 name 引用子包，ADR-0014 S4.1）下，这一行由**主包**的
+# cordis.patch.yml 插入；只有把这个子包自己当成独立 bundle 时
+# （各自 dsh.bundle.patch + 各自进 dsh.profile.bundles，**不采纳**）本文件才生效。
+# 两处同时插同一个 id 会撞车 ⇒ 接线时以主包那份为准，本文件保持与它逐字一致（ADR-0014 S4.2）。
+#
+# 行名 = 真实包名（裸真名）：本版 DSH 不传 bareModuleBaseUrl ⇒ 行名一律从 <profile>/cordis.yml
+# 旁起算，裸名 → <profile>/node_modules/<name>；开发期靠 scripts/dev-link-subpackages.mjs 建的
+# junction 让这个名字出现在 profile/node_modules 里（ADR-0014 S4.4），发布期靠传递依赖 hoist。
+# ⚠️ P-D 阶段1：壁纸域的宿主路由族与浏览器半边并入本包，但**包名与行 id 维持
+# `media-bridge` 不变**（upstream 1.4.0 已按此名发布 npm 八包集；ADR-0014 §S4.3 的
+# id = `wallpaper-engine-<目录名>` 因此自然成立）。id 一旦定下不再改（ADR-0014 S4.3）。
+- insert:
+    - id: wallpaper-engine-media-bridge
+      name: 'dsh-plugin-wallpaper-engine-media-bridge'

package/lib/audio-tap.swift

@@ -0,0 +1,146 @@
+// dsh-wallpaper-engine — 系统音频频谱采集器（macOS 14.2+ CoreAudio Process Tap）
+//
+// 用途：把「系统正在播放的声音」（loopback，不经过麦克风）转成 64 段频谱，
+// 20fps 写到 stdout（每帧固定 64 字节，0-255 整数）—— 供插件宿主喂给
+// WebWallGL 渲染页，让壁纸的音频可视化 / registerAudioBuffers 跟随真实音乐。
+//
+// 权限：首次运行会请求「音频录制」（TCC）。未授权时 AudioHardwareCreateProcessTap
+// 返回错误码，本程序以 stderr 一行 `tap-create-failed <code>` 退出 —— 宿主据此
+// 在设置界面给出授权指引，并回落到模拟频谱。
+//
+// 设计取舍：
+//  - tap 的 IOProc 在实时线程：回调里只做「写环形缓冲」（无分配、无锁；单写单读
+//    的环形缓冲最坏读到半帧数据，频谱略微跳动，音频可视化完全可接受）。
+//  - FFT / 分箱 / 输出放在主线程 20fps 定时器里做（2048 点 vDSP real FFT，微秒级）。
+//  - 立体声 → 单声道（多声道取平均）：壁纸音条不强调声道差（上游对自带 BGM 也是
+//    同值喂左右）。
+import AudioToolbox
+import CoreAudio
+import Accelerate
+import Foundation
+
+let FFT_N = 2048
+let LOG2N = vDSP_Length(11) // 2^11 = 2048
+let BANDS = 64
+let FPS = 20
+let RING = 1 << 15 // 32768 样本（约 0.68s @48k），远大于 FFT 窗口
+
+private var ring = [Float](repeating: 0, count: RING)
+private var ringWrite = 0
+
+private func fail(_ msg: String, _ code: Int32) -> Never {
+  FileHandle.standardError.write((msg + "\n").data(using: .utf8)!)
+  exit(code)
+}
+
+// ── 1. Process Tap（系统全局音频；排除自身进程避免自采反馈）──────────────────
+let tapDesc = CATapDescription(stereoGlobalTapButExcludeProcesses: [])
+tapDesc.name = "dsh-we-audio-tap"
+tapDesc.isPrivate = true
+tapDesc.muteBehavior = .unmuted // 只监听，不影响系统输出
+
+var tapID = AudioObjectID(kAudioObjectUnknown)
+var err = AudioHardwareCreateProcessTap(tapDesc, &tapID)
+if err != noErr { fail("tap-create-failed \(err)", 2) }
+
+// ── 2. 聚合设备承载 tap ──────────────────────────────────────────────────────
+let aggDesc: [String: Any] = [
+  kAudioAggregateDeviceNameKey: "dsh-we-audio-tap-agg",
+  kAudioAggregateDeviceUIDKey: UUID().uuidString,
+  kAudioAggregateDeviceIsPrivateKey: true,
+  kAudioAggregateDeviceTapListKey: [[
+    kAudioSubTapUIDKey: tapDesc.uuid.uuidString,
+    kAudioSubTapDriftCompensationKey: true,
+  ]],
+]
+var aggID = AudioObjectID(kAudioObjectUnknown)
+err = AudioHardwareCreateAggregateDevice(aggDesc as CFDictionary, &aggID)
+if err != noErr { fail("agg-create-failed \(err)", 3) }
+
+// ── 3. IOProc：只写环形缓冲 ─────────────────────────────────────────────────
+var procID: AudioDeviceIOProcID?
+err = AudioDeviceCreateIOProcIDWithBlock(&procID, aggID, nil) { _, inData, _, _, _ in
+  let abl = UnsafeMutableAudioBufferListPointer(UnsafeMutablePointer(mutating: inData))
+  guard abl.count > 0 else { return }
+  let buf = abl[0]
+  guard let mData = buf.mData else { return }
+  let ch = max(1, Int(buf.mNumberChannels))
+  let total = Int(buf.mDataByteSize) / MemoryLayout<Float>.size
+  let ptr = mData.bindMemory(to: Float.self, capacity: total)
+  if ch == 1 {
+    for i in 0..<total {
+      ring[ringWrite] = ptr[i]
+      ringWrite = (ringWrite + 1) % RING
+    }
+  } else {
+    var i = 0
+    while i + ch <= total {
+      var s: Float = 0
+      for c in 0..<ch { s += ptr[i + c] }
+      ring[ringWrite] = s / Float(ch)
+      ringWrite = (ringWrite + 1) % RING
+      i += ch
+    }
+  }
+}
+if err != noErr { fail("ioproc-create-failed \(err)", 4) }
+err = AudioDeviceStart(aggID, procID)
+if err != noErr { fail("device-start-failed \(err)", 5) }
+FileHandle.standardError.write("ready\n".data(using: .utf8)!)
+
+// ── 4. 主线程 20fps：FFT → 64 段 → stdout ──────────────────────────────────
+let setup = vDSP_create_fftsetup(LOG2N, FFTRadix(kFFTRadix2))!
+var hann = [Float](repeating: 0, count: FFT_N)
+vDSP_hann_window(&hann, vDSP_Length(FFT_N), Int32(vDSP_HANN_NORM))
+var input = [Float](repeating: 0, count: FFT_N)
+var real = [Float](repeating: 0, count: FFT_N / 2)
+var imag = [Float](repeating: 0, count: FFT_N / 2)
+var mags = [Float](repeating: 0, count: FFT_N / 2)
+var out = [UInt8](repeating: 0, count: BANDS)
+let usable = Float(FFT_N / 2) * 0.72 // 截到 ~16kHz@48k：更高频段能量极微
+let lo = 2
+
+func emitFrame() {
+  let w = ringWrite
+  let start = (w - FFT_N + RING) % RING
+  for i in 0..<FFT_N { input[i] = ring[(start + i) % RING] }
+  vDSP_vmul(input, 1, hann, 1, &input, 1, vDSP_Length(FFT_N))
+  real.withUnsafeMutableBufferPointer { rp in
+    imag.withUnsafeMutableBufferPointer { ip in
+      var split = DSPSplitComplex(realp: rp.baseAddress!, imagp: ip.baseAddress!)
+      input.withUnsafeBufferPointer { inp in
+        inp.baseAddress!.withMemoryRebound(to: DSPComplex.self, capacity: FFT_N / 2) { cp in
+          vDSP_ctoz(cp, 2, &split, 1, vDSP_Length(FFT_N / 2))
+        }
+      }
+      vDSP_fft_zrip(setup, &split, 1, LOG2N, FFTDirection(FFT_FORWARD))
+      vDSP_zvabs(&split, 1, &mags, 1, vDSP_Length(FFT_N / 2))
+    }
+  }
+  let norm = 1.0 / Float(FFT_N) // real FFT 的幅度归一（相对值，标定足够）
+  for b in 0..<BANDS {
+    let f0 = lo + Int(Float(usable) * pow(Float(b) / Float(BANDS), 2))
+    let f1 = max(f0 + 1, lo + Int(Float(usable) * pow(Float(b + 1) / Float(BANDS), 2)))
+    var peak: Float = 0
+    var f = f0
+    while f < f1 && f < mags.count {
+      let v = mags[f] * norm
+      if v > peak { peak = v }
+      f += 1
+    }
+    // -70dB..0dB → 0..255（对数观感，安静段落接近 0 而不是恒亮）
+    let db = 20 * log10(max(peak, 1e-7))
+    let n = max(0, min(1, (db + 70) / 70))
+    out[b] = UInt8(n * 255)
+  }
+  FileHandle.standardOutput.write(Data(out))
+}
+
+let timer = Timer(timeInterval: 1.0 / Double(FPS), repeats: true) { _ in emitFrame() }
+RunLoop.main.add(timer, forMode: .common)
+
+// 信号兜底：宿主 kill 时安静退出（private 聚合设备随进程回收）
+signal(SIGTERM) { _ in exit(0) }
+signal(SIGINT) { _ in exit(0) }
+
+RunLoop.main.run()

package/lib/backend.js

@@ -0,0 +1,144 @@
+/**
+ * backend.js — 媒体桥的**媒体后端门面**：**首选 media-bridge 子进程，失败自动回落内置实现**。
+ *
+ * 对宿主只暴露一小组方法（start/stop/spectrum/nowPlaying/artworkFile/artworkMime/status
+ * 与内置实现同名，另有中间件专供的 usingBridge/bridgeInfo/control），所以同目录的路由族
+ * （`now-playing.js`）不需要知道底下是谁在供数 —— 这是刻意留的接缝：换后端不动路由形状，
+ * 回滚也不需要改路由。
+ *
+ * 选择逻辑（每次会话只决定一次，之后靠 bridge.ready() 判断中间件是否还活着）：
+ *   1. `DSH_WE_MEDIA_LEGACY=1`            → 直接用内置实现（排查/对比用）
+ *   2. 产物解析成功 + spawn + 握手通过     → 中间件（三平台同一套能力）
+ *   3. 任一步失败（取不到产物/起不来/协议不符/连续崩溃）→ 内置实现 + 原因进 status
+ *
+ * 日志注入契约：本目录只调用注入的 `log(msg, level?)`，**不自己写终端**（终端与落档的唯一
+ * 入口是 `lib/log.js`，见其文件头）。级别缺省 `info`；判据是"影响显示效果的非正常表现
+ * ⇒ `warn`"：回落、启动失败、中间件报错与重启都是 `warn`，成功事实与运行信息是 `info`。
+ */
+import { join } from 'node:path';
+import { createMediaBridge as createLegacy } from './legacy.js';
+import { createBridgeSupervisor } from './supervisor.js';
+import { provisionMediaBridge } from './provision.js';
+
+/**
+ * @param {object} o
+ * @param {string} o.dataDir 插件数据目录（**不是**缓存根）：中间件产物 `<dataDir>/bin/media-bridge/`
+ *   与 macOS 音频 tap 的编译产物 `<dataDir>/bin/we-audio-tap` 都落这里 —— 它们属**工具链**，
+ *   和 ffmpeg 一样不随「缓存位置」走（挪了要重下 / 重编译，那是另一件事）。
+ * @param {string|(() => string)} [o.cacheBaseDir] 缓存根（见 `lib/kernel/data-dir.js` 的 `cacheBaseDir()`）：中间件的
+ *   运行时缓存（`--cache-dir`）与内置实现的封面缓存都在它下面。缺省 `<dataDir>/cache` ——
+ *   与默认布局逐字一致，所以只传 `dataDir` 的老调用点行为不变。**可以传访问器**（推荐，
+ *   路由就这么传）：那样「缓存位置」改完，中间件下一次起动 / 下一张封面就走新根，不必重启宿主。
+ * @param {(text: any, level?: string) => void} [o.log] 日志被调用面（`log(msg, level?)`）；缺省空实现。
+ * @param {(name:string, data?:any) => void} [o.diag] 诊断上报（宿主注入 `appendDiagLine` 包装）。
+ */
+export function createMediaBackend({ dataDir, cacheBaseDir = join(dataDir, 'cache'), log = () => {}, diag = () => {} }) {
+  // 缓存根**每次现问**（同 `cacheBaseDir()` 的理由）：传进来是访问器就现算，是字符串就照用。
+  // 在这里存值快照会让"改完缓存位置、新缓存又写回旧盘"悄悄发生 —— 正是本轮要修的那类 bug。
+  const cacheRoot = () => (typeof cacheBaseDir === 'function' ? cacheBaseDir() : cacheBaseDir);
+
+  let started = false;
+  let useBridge = false;         // 中间件可用（握手通过且没被判死）
+  let fallback = '';             // 回落原因（空 = 没回落）
+  let note = '';                 // 准备中的说明（设置界面可见）
+  let booting = null;
+  let sup = null;
+  let legacy = null;
+  const optsRef = { audio: true, online: false };
+  const forceLegacy = String(process.env.DSH_WE_MEDIA_LEGACY || '').trim() === '1';
+
+  /** 内置实现按需构造（音频开关要跟着用户设置走，不能构造时就定死）。 */
+  function legacyBackend() {
+    if (!legacy) legacy = createLegacy({ dataDir, cacheBaseDir: cacheRoot, log, audio: optsRef.audio });
+    return legacy;
+  }
+
+  /** 当前真正在供数的后端（中间件没就绪/已判死时都落到内置实现）。 */
+  function active() {
+    if (useBridge && sup && sup.ready()) return sup;
+    return legacyBackend();
+  }
+
+  function fallBackTo(reason) {
+    if (fallback) return;
+    fallback = reason || '中间件不可用';
+    useBridge = false;
+    note = '';
+    log('回落到内置媒体实现：' + fallback, 'warn');
+    diag('media-fallback', { reason: String(fallback).slice(0, 200) });
+    try { legacyBackend().start(); } catch (err) { log('内置媒体实现启动失败：' + err, 'warn'); }
+  }
+
+  function bootBridge() {
+    if (booting) return booting;
+    booting = (async () => {
+      note = '正在准备系统媒体中间件…';
+      const prov = await provisionMediaBridge({ dataDir, log });
+      if (!prov.path) { fallBackTo(prov.error || '中间件产物不可用'); return; }
+      sup = createBridgeSupervisor({
+        binPath: prov.path,
+        cacheDir: join(cacheRoot(), 'media-bridge'),
+        log,
+        diag,
+        onFatal: (why) => fallBackTo(why),
+      });
+      const ok = await sup.start({ audio: optsRef.audio, online: optsRef.online });
+      if (!ok) { fallBackTo(sup.lastError() || '中间件启动失败'); return; }
+      useBridge = true;
+      note = '';
+      log(`媒体数据源：系统媒体中间件（${prov.source}${prov.tag ? ', ' + prov.tag : ''}）`, 'info');
+    })().catch((err) => {
+      fallBackTo('中间件准备出错：' + String(err && err.message ? err.message : err));
+    }).finally(() => { booting = null; });
+    return booting;
+  }
+
+  return {
+    /** 懒启动（由路由第一次被访问时触发；重复调用无副作用）。 */
+    start(opts = {}) {
+      if (started) return;
+      started = true;
+      Object.assign(optsRef, { audio: opts.audio !== false, online: opts.online === true });
+      if (forceLegacy) {
+        fallback = '按 DSH_WE_MEDIA_LEGACY=1 使用内置实现';
+        log('媒体数据源：内置实现（DSH_WE_MEDIA_LEGACY=1）', 'info');
+        legacyBackend().start();
+        return;
+      }
+      bootBridge();
+    },
+    stop() {
+      try { if (sup) sup.stop(); } catch { /* ignore */ }
+      try { if (legacy) legacy.stop(); } catch { /* ignore */ }
+    },
+    spectrum: () => active().spectrum(),
+    nowPlaying: () => active().nowPlaying(),
+    artworkFile: () => active().artworkFile(),
+    artworkMime: () => active().artworkMime(),
+    /**
+     * 反向控制（壁纸里的播放按钮 / 宿主面板 → 真实播放器）：**只有中间件能做**
+     * —— 内置实现是纯读取。中间件没就绪（还没启动 / 已判死回落）时统一回不可用，
+     * 不在此处触发启动：控制是用户点一下的交互，不该顺带把产物下载与子进程
+     * 拉起来（启动仍由取数那四条路由的懒启动决定）。
+     *
+     * 返回值一律是 `{ ok, … }`（不抛），路由按它决定状态码。
+     */
+    async control(action) {
+      if (useBridge && sup && sup.ready()) return sup.control(action);
+      return { ok: false, error: fallback ? 'control-unsupported' : 'media-backend-not-ready' };
+    },
+    status() {
+      const live = useBridge && sup && sup.ready();
+      const st = active().status();
+      return {
+        ...st,
+        backend: live ? 'bridge' : st.backend,
+        fallback,
+        note,
+      };
+    },
+    /** 当前是否中间件在供数（自检与设置界面用）。 */
+    usingBridge: () => Boolean(useBridge && sup && sup.ready()),
+    bridgeInfo: () => (sup ? sup.info() : null),
+  };
+}