player_status

Instructions

Implementation Reference

• index.js:408-413 (registration)

  Tool registration for 'player_status' in the TOOLS array. Defines the tool name, description, and empty input schema (no parameters required).

  {
    name: "player_status",
    description:
      "Get current playback status: file name, position, duration, volume, speed, pause state.",
    inputSchema: { type: "object", properties: {} },
  },

• index.js:589-614 (handler)

  Handler implementation for 'player_status'. Checks if mpv is running, then queries mpv IPC for media-title, time-pos, duration, pause, volume, speed, playlist-pos, and playlist-count. Formats all data into a human-readable status message.

  case "player_status": {
    const running = await isMpvRunning();
    if (!running) return info("mpv is not running.");
  
    const [filename, pos, dur, paused, vol, speed, plPos, plCount] =
      await Promise.all([
        getProperty("media-title").catch(() => null),
        getProperty("time-pos").catch(() => null),
        getProperty("duration").catch(() => null),
        getProperty("pause").catch(() => null),
        getProperty("volume").catch(() => null),
        getProperty("speed").catch(() => null),
        getProperty("playlist-pos").catch(() => null),
        getProperty("playlist-count").catch(() => null),
      ]);
  
    const lines = [
      `🎵 **Now playing:** ${filename || "N/A"}`,
      `⏱  **Position:** ${formatTime(pos)} / ${formatTime(dur)}`,
      `${paused ? "⏸" : "▶️"}  **State:** ${paused ? "Paused" : "Playing"}`,
      `🔊 **Volume:** ${vol != null ? Math.round(vol) : "N/A"}`,
      `⚡ **Speed:** ${speed != null ? speed + "x" : "N/A"}`,
      `📋 **Playlist:** ${plPos != null ? plPos + 1 : "N/A"} / ${plCount ?? "N/A"}`,
    ];
    return info(lines.join("\n"));
  }

• index.js:235-241 (helper)

  Helper used in the player_status handler to check if mpv process is currently running by attempting a TCP connection to the IPC pipe.

  function isMpvRunning() {
    return new Promise((resolve) => {
      const client = net.createConnection(PIPE_PATH);
      client.on("connect", () => { client.destroy(); resolve(true); });
      client.on("error", () => resolve(false));
    });
  }

• index.js:300-308 (helper)

  Helper used in the player_status handler to format time values (position and duration) into human-readable HH:MM:SS or MM:SS format.

  function formatTime(secs) {
    if (secs == null) return "N/A";
    const h = Math.floor(secs / 3600);
    const m = Math.floor((secs % 3600) / 60);
    const s = Math.floor(secs % 60);
    return h > 0
      ? `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`
      : `${m}:${String(s).padStart(2, "0")}`;
  }

• index.js:313-315 (helper)

  Helper used in the player_status handler to wrap the status message into an MCP response with text content.

  function info(msg) {
    return { content: [{ type: "text", text: msg }] };
  }