player_seek
Seek to a specific position in the current media using relative or absolute seconds, or percentage.
Instructions
Seek within the current media.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | Seconds to seek (positive = forward, negative = backward) when mode=relative. Absolute second when mode=absolute. 0-100 when mode=percent. | |
| mode | No | Seek mode | relative |
Implementation Reference
- index.js:569-575 (handler)Handler for the player_seek tool. Ensures mpv is running, sends a seek command with the given value and mode (relative/absolute/percent), then returns the new playback position formatted as a time string.
case "player_seek": { await ensureMpv(); const mode = args.mode || "relative"; await mpv("seek", [args.value, mode]); const pos = await getProperty("time-pos"); return ok(`Seeked → ${formatTime(pos)}`); } - index.js:362-381 (schema)Input schema definition for the player_seek tool. It requires a number 'value' and accepts an optional 'mode' parameter with enum values 'relative', 'absolute', or 'percent' (defaulting to 'relative').
{ name: "player_seek", description: "Seek within the current media.", inputSchema: { type: "object", properties: { value: { type: "number", description: "Seconds to seek (positive = forward, negative = backward) when mode=relative. Absolute second when mode=absolute. 0-100 when mode=percent.", }, mode: { type: "string", enum: ["relative", "absolute", "percent"], default: "relative", description: "Seek mode", }, }, required: ["value"], }, - index.js:321-498 (registration)The TOOLS array registers all available tools, including player_seek (line 362-381). This array is served via ListToolsRequestSchema handler.
const TOOLS = [ { name: "player_play", description: "Open and play a media file or URL. If mpv is not running, it will be launched automatically.", inputSchema: { type: "object", properties: { path: { type: "string", description: "Absolute file path or URL (http/https/rtmp etc.)", }, append: { type: "boolean", description: "Append to current playlist instead of replacing it", default: false, }, }, required: ["path"], }, }, { name: "player_pause", description: "Toggle pause / resume playback.", inputSchema: { type: "object", properties: {} }, }, { name: "player_stop", description: "Stop playback and clear the current file.", inputSchema: { type: "object", properties: {} }, }, { name: "player_next", description: "Skip to the next item in the playlist.", inputSchema: { type: "object", properties: {} }, }, { name: "player_prev", description: "Go back to the previous item in the playlist.", inputSchema: { type: "object", properties: {} }, }, { name: "player_seek", description: "Seek within the current media.", inputSchema: { type: "object", properties: { value: { type: "number", description: "Seconds to seek (positive = forward, negative = backward) when mode=relative. Absolute second when mode=absolute. 0-100 when mode=percent.", }, mode: { type: "string", enum: ["relative", "absolute", "percent"], default: "relative", description: "Seek mode", }, }, required: ["value"], }, }, { name: "player_set_volume", description: "Set playback volume (0–130). 100 is default.", inputSchema: { type: "object", properties: { volume: { type: "number", description: "Volume level 0–130" }, }, required: ["volume"], }, }, { name: "player_set_speed", description: "Set playback speed multiplier. 1.0 = normal speed.", inputSchema: { type: "object", properties: { speed: { type: "number", description: "Speed multiplier e.g. 0.5, 1.0, 1.5, 2.0", }, }, required: ["speed"], }, }, { name: "player_status", description: "Get current playback status: file name, position, duration, volume, speed, pause state.", inputSchema: { type: "object", properties: {} }, }, { name: "player_shuffle", description: "Randomly shuffle the current playlist and start playing from the first track.", inputSchema: { type: "object", properties: {} }, }, { name: "playlist_load", description: "Load a saved playlist by name and start playing it.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Playlist name (without .m3u)" }, }, required: ["name"], }, }, { name: "playlist_create", description: "Create a new playlist with a list of file paths.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Playlist name" }, files: { type: "array", items: { type: "string" }, description: "Array of absolute file paths or URLs", }, }, required: ["name", "files"], }, }, { name: "playlist_add", description: "Add files to an existing playlist.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Playlist name" }, files: { type: "array", items: { type: "string" }, description: "Files to append", }, }, required: ["name", "files"], }, }, { name: "playlist_remove", description: "Remove a file from a saved playlist by index (0-based).", inputSchema: { type: "object", properties: { name: { type: "string", description: "Playlist name" }, index: { type: "number", description: "0-based index to remove" }, }, required: ["name", "index"], }, }, { name: "playlist_list", description: "List all saved playlists or show contents of a specific playlist.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Playlist name to inspect (omit to list all playlists)", }, }, }, }, { name: "playlist_delete", description: "Delete a saved playlist file.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Playlist name to delete" }, }, required: ["name"], }, }, ]; - index.js:300-308 (helper)Helper function used by player_seek handler to format the seconds value returned by mpv into a human-readable time string (e.g., '5:30' or '1:05:30').
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")}`; }