@llblab/pi-actors 0.48.1 → 0.49.1

package/dist/skills/music-player/genapps/music-player.mjs

@@ -0,0 +1,360 @@
+import { basename, dirname, isAbsolute } from "node:path";
+
+const ACTIONS = new Set([
+  "play",
+  "pause",
+  "resume",
+  "toggle",
+  "next",
+  "previous",
+  "stop",
+]);
+
+function requireAdapter(argument) {
+  if (!argument || typeof argument !== "object" || Array.isArray(argument)) {
+    throw new Error("music-player init requires an object argument");
+  }
+  const control = typeof argument.control === "string" ? argument.control : "";
+  const stateDir = typeof argument.stateDir === "string" ? argument.stateDir : "";
+  const node = typeof argument.node === "string" ? argument.node : process.execPath;
+  if (!isAbsolute(control) || !control.endsWith("playback.mjs")) {
+    throw new Error("music-player control must be an absolute playback.mjs path");
+  }
+  if (!isAbsolute(stateDir)) {
+    throw new Error("music-player stateDir must be an absolute path");
+  }
+  if (!isAbsolute(node)) {
+    throw new Error("music-player node executable must be an absolute path");
+  }
+  return { control, node, stateDir };
+}
+
+function inline(value) {
+  return String(value ?? "").replaceAll("`", "'");
+}
+
+function normalizePlayback(status) {
+  const actorAvailable = status.actor_available === true;
+  if (!actorAvailable) {
+    return {
+      actorAvailable: false,
+      count: null,
+      index: null,
+      pid: "",
+      player: "",
+      progressPercent: null,
+      seekPercent: 0,
+      state: "inactive",
+      track: "",
+      updatedAt: typeof status.updated_at === "string" ? status.updated_at : "",
+      volume: null,
+    };
+  }
+  return {
+    actorAvailable: true,
+    state: typeof status.state === "string" ? status.state : "unknown",
+    index: Number.isInteger(status.index) ? status.index : null,
+    count: Number.isInteger(status.count) ? status.count : null,
+    track: typeof status.track === "string" ? status.track : "",
+    player: typeof status.player === "string" ? status.player : "",
+    volume: Number.isInteger(status.volume) ? status.volume : null,
+    seekPercent: Number.isInteger(status.seek_percent) ? status.seek_percent : 0,
+    progressPercent: Number.isInteger(status.progress_percent) ? status.progress_percent : null,
+    pid: typeof status.pid === "string" || typeof status.pid === "number"
+      ? String(status.pid)
+      : "",
+    updatedAt: typeof status.updated_at === "string" ? status.updated_at : "",
+  };
+}
+
+async function readPlayback(adapter, run) {
+  const result = await run({
+    command: adapter.node,
+    args: [adapter.control, "status", adapter.stateDir],
+    cwd: dirname(adapter.control),
+    timeoutMs: 5_000,
+  });
+  if (result.code !== 0) {
+    throw new Error(`music-player status failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+  }
+  let status;
+  try {
+    status = JSON.parse(result.stdout);
+  } catch {
+    throw new Error("music-player status returned invalid JSON");
+  }
+  if (!status || typeof status !== "object" || Array.isArray(status)) {
+    throw new Error("music-player status returned an invalid object");
+  }
+  return normalizePlayback(status);
+}
+
+function withPlayback(state, playback) {
+  return { version: 1, adapter: state.adapter, playback };
+}
+
+function mainControls(playback) {
+  if (!playback.actorAvailable || playback.state === "stopped" || playback.state === "unknown") {
+    return [
+      [{ label: "▶ Start", prompt: "Start the music player", selected_style: "success" }],
+      [{ label: "🔄 Status", prompt: "music-player::status", selected_style: "primary" }],
+    ];
+  }
+  const primary = playback.state === "paused"
+    ? { label: "▶ Play", prompt: "music-player::resume", selected_style: "success" }
+    : { label: "⏸ Pause", prompt: "music-player::pause", selected_style: "primary" };
+  const percentages = [0, 15, 30, 45, 60, 75, 90];
+  const seek = percentages.map((percent) => ({
+    label: percent === 0 ? "P0" : String(percent),
+    prompt: `music-player::seek_percent(${percent})`,
+    selected_style: percent === 0 ? "primary" : "success",
+  }));
+  const volume = percentages.map((percent) => ({
+    label: percent === 0 ? "V0" : String(percent),
+    prompt: `music-player::volume(${percent})`,
+    selected_style: percent === 0 ? "primary" : "success",
+  }));
+  return [
+    seek,
+    volume,
+    [
+      { label: "⏮ Previous", prompt: "music-player::previous", selected_style: "primary" },
+      primary,
+      { label: "⏭ Next", prompt: "music-player::next", selected_style: "success" },
+    ],
+    [
+      { label: "⏹ Stop", prompt: "music-player::stop", selected_style: "danger" },
+      { label: "🔄 Status", prompt: "music-player::status", selected_style: "primary" },
+    ],
+  ];
+}
+
+function playbackLines(playback) {
+  const track = playback.track ? basename(playback.track) : "—";
+  const index = playback.index === null ? "—" : playback.index + 1;
+  const count = playback.count === null ? "—" : playback.count;
+  return [
+    `- **Actor:** \`${playback.actorAvailable ? "available" : "unavailable"}\``,
+    `- **State:** \`${inline(playback.state)}\``,
+    `- **Progress:** \`${playback.progressPercent === null ? "—" : `${playback.progressPercent}%`}\``,
+    `- **Volume:** \`${playback.volume === null ? "—" : `${playback.volume}%`}\``,
+    `- **Backend:** \`${inline(playback.player || "—")}\``,
+    `- **Queue:** \`${index}/${count}\``,
+    `- **Track:** \`${inline(track)}\``,
+  ];
+}
+
+function render(playback) {
+  return [
+    "**🎵 Music Player**",
+    "",
+    ...playbackLines(playback),
+    "",
+    `<!-- telegram_button ${JSON.stringify(mainControls(playback))} -->`,
+  ].join("\n");
+}
+
+async function waitForTransition(adapter, run, before, action) {
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    const playback = await readPlayback(adapter, run);
+    const changed = action === "stop"
+      ? playback.state === "stopped"
+      : action === "pause"
+        ? playback.state === "paused"
+        : action === "play" || action === "resume"
+          ? playback.state === "playing"
+          : action === "toggle"
+            ? playback.state !== before.state
+            : playback.index !== before.index || playback.track !== before.track;
+    if (changed) return playback;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return await readPlayback(adapter, run);
+}
+
+function normalizeAbsoluteVolume(argument) {
+  const candidate =
+    argument && typeof argument === "object" && !Array.isArray(argument)
+      ? argument.percent
+      : argument;
+  if (!Number.isInteger(candidate) || candidate < 0 || candidate > 100) {
+    throw new Error("music-player volume requires an integer percent 0..100");
+  }
+  return candidate;
+}
+
+async function applyVolume(percent, context) {
+  const result = await context.run({
+    command: context.state.adapter.node,
+    args: [
+      context.state.adapter.control,
+      "volume",
+      context.state.adapter.stateDir,
+      String(percent),
+    ],
+    cwd: dirname(context.state.adapter.control),
+    timeoutMs: 5_000,
+  });
+  if (result.code !== 0) {
+    throw new Error(`music-player volume failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+  }
+  let playback;
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    playback = await readPlayback(context.state.adapter, context.run);
+    if (playback.volume === percent) break;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  playback ??= await readPlayback(context.state.adapter, context.run);
+  return {
+    state: withPlayback(context.state, playback),
+    output: render(playback),
+    viewMode: "edit",
+  };
+}
+
+function normalizeSeekPercent(argument) {
+  if (!Number.isInteger(argument) || argument < 0 || argument > 100) {
+    throw new Error("music-player seek requires an integer percent 0..100");
+  }
+  return argument;
+}
+
+async function applySeek(percent, context) {
+  const result = await context.run({
+    command: context.state.adapter.node,
+    args: [
+      context.state.adapter.control,
+      "seek",
+      context.state.adapter.stateDir,
+      String(percent),
+    ],
+    cwd: dirname(context.state.adapter.control),
+    timeoutMs: 5_000,
+  });
+  if (result.code !== 0) {
+    throw new Error(`music-player seek failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+  }
+  let playback;
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    playback = await readPlayback(context.state.adapter, context.run);
+    if (playback.seekPercent === percent && playback.pid) break;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  playback ??= await readPlayback(context.state.adapter, context.run);
+  return {
+    state: withPlayback(context.state, playback),
+    output: render(playback),
+    viewMode: "edit",
+  };
+}
+
+async function apply(action, context) {
+  if (!ACTIONS.has(action)) throw new Error(`unsupported music-player action: ${action}`);
+  const before = await readPlayback(context.state.adapter, context.run);
+  const result = await context.run({
+    command: context.state.adapter.node,
+    args: [context.state.adapter.control, action, context.state.adapter.stateDir],
+    cwd: dirname(context.state.adapter.control),
+    timeoutMs: 5_000,
+  });
+  if (result.code !== 0) {
+    throw new Error(`music-player ${action} failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+  }
+  const playback = await waitForTransition(
+    context.state.adapter,
+    context.run,
+    before,
+    action,
+  );
+  return {
+    state: withPlayback(context.state, playback),
+    output: render(playback),
+    viewMode: "edit",
+  };
+}
+
+export async function init({ argument, run }) {
+  const adapter = requireAdapter(argument);
+  const playback = await readPlayback(adapter, run);
+  return {
+    state: { version: 1, adapter, playback },
+    output: render(playback),
+  };
+}
+
+export async function status({ state, run }) {
+  const playback = await readPlayback(state.adapter, run);
+  const changed = JSON.stringify(playback) !== JSON.stringify(state.playback);
+  return {
+    ...(changed ? { state: withPlayback(state, playback) } : {}),
+    output: render(playback),
+    viewMode: "edit",
+  };
+}
+
+export async function refresh({ state, run }) {
+  const playback = await readPlayback(state.adapter, run);
+  const changed = JSON.stringify(playback) !== JSON.stringify(state.playback);
+  return {
+    ...(changed ? { state: withPlayback(state, playback) } : {}),
+    output: render(playback),
+  };
+}
+
+export async function main({ state, run }) {
+  const playback = await readPlayback(state.adapter, run);
+  const changed = JSON.stringify(playback) !== JSON.stringify(state.playback);
+  return {
+    ...(changed ? { state: withPlayback(state, playback) } : {}),
+    output: render(playback),
+    viewMode: "edit",
+  };
+}
+
+export async function play(context) {
+  return await apply("resume", context);
+}
+
+export async function pause(context) {
+  return await apply("pause", context);
+}
+
+export async function resume(context) {
+  return await apply("resume", context);
+}
+
+export async function toggle(context) {
+  return await apply("toggle", context);
+}
+
+export async function next(context) {
+  return await apply("next", context);
+}
+
+export async function previous(context) {
+  return await apply("previous", context);
+}
+
+export async function seek_percent({ argument, ...context }) {
+  return await applySeek(normalizeSeekPercent(argument), context);
+}
+
+export async function volume({ argument, ...context }) {
+  return await applyVolume(normalizeAbsoluteVolume(argument), context);
+}
+
+export async function volume_delta({ argument, ...context }) {
+  if (!Number.isInteger(argument) || argument < -100 || argument > 100) {
+    throw new Error("music-player volume_delta requires an integer -100..100");
+  }
+  const playback = await readPlayback(context.state.adapter, context.run);
+  const current = playback.volume;
+  if (!Number.isInteger(current)) {
+    throw new Error("music-player current volume is unavailable");
+  }
+  return await applyVolume(Math.max(0, Math.min(100, current + argument)), context);
+}
+
+export async function stop(context) {
+  return await apply("stop", context);
+}

package/{skills/media/recipes/player.json → dist/skills/music-player/recipes/playback.json}

@@ -1,7 +1,7 @@
 {
   "async": true,
+  "singleton": true,
   "args": [
-    "command:enum(play,pause,resume,toggle,next,previous,stop,status)",
     "source:string",
     "loop:bool",
     "volume:int",
@@ -9,7 +9,6 @@
     "state_dir:path"
   ],
   "defaults": {
-    "command": "play",
     "loop": "true",
     "volume": "70",
     "player": "auto"
@@ -21,8 +20,10 @@
     "toggle",
     "next",
     "previous",
+    "seek",
+    "volume",
     "stop",
     "status"
   ],
-  "template": "{skill_dir}/scripts/music-player.mjs {command} {source} {loop} {volume} {player} {state_dir}"
+  "template": "{skill_dir}/scripts/playback.mjs play {source} {loop} {volume} {player} {state_dir}"
 }

package/dist/skills/music-player/scripts/playback-client.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+/**
+ * Actor-neutral client for the local Music Player playback protocol.
+ *
+ * Reads portable JSON status and sends bounded generation-fenced commands to
+ * the playback service endpoint without reading pi-actors Run or Control state.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { createConnection } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const ACTIONS = new Set([
+  "play",
+  "resume",
+  "pause",
+  "toggle",
+  "next",
+  "previous",
+  "seek",
+  "volume",
+  "stop",
+  "status",
+]);
+
+function fail(message, code = 1) {
+  console.error(`music-player: ${message}`);
+  process.exit(code);
+}
+
+function expandPath(value) {
+  if (value === "~") return homedir();
+  if (value.startsWith("~/")) return join(homedir(), value.slice(2));
+  return value;
+}
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function parsePercent(value, label) {
+  if (!/^\d+$/.test(String(value))) {
+    fail(`${label} percent must be an integer 0..100`, 2);
+  }
+  const percent = Number(value);
+  if (percent < 0 || percent > 100) {
+    fail(`${label} percent must be an integer 0..100`, 2);
+  }
+  return percent;
+}
+
+function projectCurrentProgress(status, nowMs = Date.now()) {
+  const duration = Number(status.duration_seconds);
+  let position = Number(status.position_seconds);
+  const updatedAtMs = Number(status.position_updated_at_ms);
+  if (!Number.isFinite(position)) position = 0;
+  if (status.state === "playing" && Number.isFinite(updatedAtMs)) {
+    position += Math.max(0, nowMs - updatedAtMs) / 1000;
+  }
+  if (!Number.isFinite(duration) || duration <= 0) {
+    return { ...status, progress_percent: null };
+  }
+  position = Math.min(Math.max(position, 0), duration);
+  return {
+    ...status,
+    progress_percent: Math.round((position / duration) * 100),
+    position_seconds: position,
+    position_updated_at_ms: nowMs,
+  };
+}
+
+async function sendCommand(endpoint, action, input) {
+  const payload = `${JSON.stringify({
+    action,
+    ...(input !== undefined ? { input } : {}),
+    service_instance_id: endpoint.service_instance_id,
+  })}\n`;
+  const response = await new Promise((resolveResponse, rejectResponse) => {
+    const socket = createConnection(endpoint.path);
+    let content = "";
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      rejectResponse(new Error("playback service command timed out"));
+    }, 5_000);
+    timeout.unref?.();
+    socket.setEncoding("utf8");
+    socket.on("connect", () => socket.write(payload));
+    socket.on("data", (chunk) => {
+      content += chunk;
+      if (Buffer.byteLength(content, "utf8") > 4096) {
+        socket.destroy(new Error("playback service response is too large"));
+      }
+    });
+    socket.on("error", rejectResponse);
+    socket.on("end", () => {
+      clearTimeout(timeout);
+      try {
+        resolveResponse(JSON.parse(content.trim()));
+      } catch {
+        rejectResponse(new Error("playback service returned invalid JSON"));
+      }
+    });
+  });
+  if (!response?.ok) {
+    throw new Error(response?.error || "playback service rejected the command");
+  }
+}
+
+const [action = "status", rawStateDir, ...actionArgs] = process.argv.slice(2);
+if (!ACTIONS.has(action) || !rawStateDir) {
+  fail("usage: playback-client.mjs <status|play|resume|pause|toggle|next|previous|seek|volume|stop> <state-dir> [action args]", 2);
+}
+const stateDir = expandPath(rawStateDir);
+if (action === "status") {
+  const status = readJson(join(stateDir, "player.json"), { state: "unknown" });
+  process.stdout.write(`${JSON.stringify(projectCurrentProgress(status))}\n`);
+  process.exit(0);
+}
+const endpointPath = join(stateDir, "playback-endpoint.json");
+if (!existsSync(endpointPath)) fail(`playback service is not active: ${stateDir}`, 3);
+const endpoint = readJson(endpointPath, {});
+if (
+  typeof endpoint.path !== "string" ||
+  !endpoint.path ||
+  typeof endpoint.service_instance_id !== "string" ||
+  !endpoint.service_instance_id
+) fail(`playback service endpoint is invalid: ${stateDir}`, 3);
+let input;
+if (action === "seek" || action === "volume") {
+  input = { percent: parsePercent(actionArgs[0], action) };
+}
+try {
+  await sendCommand(endpoint, action === "resume" ? "play" : action, input);
+  console.log(`music-player: command=${action} handled state_dir=${stateDir}`);
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error), 3);
+}