Create a new ASS subtitle template file with Default, Title, and Note styles. @remarks Writes a valid ASS v4.00+ file with pre-configured styles for general subtitles, title overlays, and note text. Fails if the output file already exists unless overwrite=true. @param output_path Destination path for the generated .ass file. @param output_dir Optional output directory fallback for relative output_path. Falls back to ASS_OUTPUT_DIR or SHELL_AS_MCP_OUTPUT_DIR. @param title Script title embedded in [Script Info] section. Default: "Untitled". @param play_res_x Virtual canvas width in pixels. Default: 1920. @param play_res_y Virtual canvas height in pixels. Default: 1080. @param overwrite If true, overwrite the file when it already exists. Default: false. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Returns the ASS (Advanced SubStation Alpha) subtitle format specification. @remarks Read-only reference tool. Returns structured spec content for the requested section. No external files or network access required; content is fully embedded in the script. @param section Which section of the ASS spec to return. Default "all". Allowed values: all | script_info | v4_styles | events | tags | colors | example @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Check whether the ASS tool bundle runtime dependencies are available. @remarks Validates ffmpeg presence and returns a small JSON health report. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Lint and validate an ASS (Advanced SubStation Alpha) subtitle file. @remarks Checks 16 structural rules including section headers, ScriptType, PlayRes fields, Format/Style/Dialogue line presence, time format validity, and color field format. Returns a JSON report with per-check results. In strict mode, also validates field counts per Dialogue (>=10) and Style (=23). @param ass_file_path Absolute or relative path to the .ass file to lint. @param strict When true, enables additional field-count checks (checks 15 & 16). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Render a short test video from an ASS subtitle file to verify renderability. @remarks Uses ffmpeg lavfi virtual color source to generate a background, then overlays the ASS subtitles via the subtitles filter (requires libass support in ffmpeg). Outputs a JSON summary on success or an error payload on failure. @param ass_file_path Path to the ASS subtitle file to render. @param output_path Path for the output MP4 video file. @param output_dir Optional output directory fallback for relative output_path. Falls back to ASS_OUTPUT_DIR or SHELL_AS_MCP_OUTPUT_DIR. @param duration_sec Duration of the test video in seconds (1-300). Default: 10. @param resolution Output video resolution in WxH format. Default: 1920x1080. @param background_color Background color for the test video (ffmpeg color name or hex). Default: black. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Add fade-in and/or fade-out transitions to a video clip. @remarks At least one of fade_in_duration or fade_out_duration must be greater than zero. Audio fade is applied simultaneously when include_audio is true. Returns JSON in stdout with output_path and applied parameters. @param input_path Source video path. @param output_path Destination video path with fade transitions. @param fade_in_duration Fade-in duration in seconds. Default 0 (no fade in). @param fade_out_duration Fade-out duration in seconds. Default 0 (no fade out). @param fade_color Fade transition color: black or white. Default black. @param include_audio Whether to apply afade filter synchronously with the video fade. Default true. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Apply a .cube format 3D color Look-Up Table (LUT) to a video for color grading. @remarks Uses the ffmpeg lut3d filter. Returns JSON in stdout with output_path and lut_path. @param input_path Source video path. @param lut_path Path to a .cube format LUT file. @param output_path Destination color-graded video path. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Hard-burn SRT or ASS subtitle file into a video using the ffmpeg subtitles filter. @remarks Consumes .ass files produced by the ass bundle (ass__create_template). Re-encodes the video track. Returns JSON in stdout with output_path and applied parameters. @param input_path Source video path. @param subtitle_path Subtitle file path (.srt or .ass). @param output_path Destination video path with burned-in subtitles. @param force_style Optional ASS/SSA style override string (for example Fontsize=24,PrimaryColour=&HFFFFFF&). Applies to both SRT and ASS inputs. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Concatenate multiple video clips in sequence using the ffmpeg concat demuxer. @remarks input_paths accepts a comma or newline-separated list of clip paths. Returns JSON in stdout with output_path and clip_count. Use reencode=true when clips have different codecs or parameters. @param input_paths Comma or newline-separated list of clip file paths in playback order. @param output_path Destination video path. @param reencode Whether to re-encode during concat (required for clips with different codecs), default false. @param video_codec Video codec when re-encoding, default libx264. @param audio_codec Audio codec when re-encoding, default aac. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Create a montage-style summary clip from one or more videos. @remarks input_paths accepts one path or a comma/newline-separated list. Returns JSON in stdout with output_path and sampled clip_count. @param input_paths One path or a comma/newline-separated list of source video paths. @param output_path Destination summary video path. @param interval_sec Sampling interval in seconds, default 300. @param clip_duration_sec Duration of each sampled clip in seconds, default 2. @param merge_audio Whether to keep audio in sampled clips, default true. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Transcode a video to a delivery-grade output with full codec and quality control. @remarks Supports H.264, H.265, and VP9. Use crf for quality-based encoding or bitrate for target-bitrate mode (mutually exclusive; bitrate takes precedence). Returns JSON in stdout with output_path and applied parameters. @param input_path Source video path. @param output_path Destination video path. @param video_codec Output video codec: libx264, libx265, or libvpx-vp9. Default libx264. @param crf Constant Rate Factor for quality-based encoding. Default 23 for H.264, 28 for H.265, 33 for VP9. @param bitrate Target video bitrate (for example 4M). Overrides crf when set. @param preset Encoding speed/compression preset. Default medium. @param profile H.264/H.265 profile (for example baseline, main, high). @param level H.264/H.265 level (for example 4.0, 4.1). @param resolution Output resolution as WxH (for example 1920x1080). Keeps original if omitted. @param audio_bitrate Output audio bitrate. Default 128k. @param pixel_format Output pixel format. Default yuv420p. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Extract image frames for multimodal vision prompts. @remarks Returns JSON in stdout with frame_paths and frame_count for direct LLM/prompt ingestion. @param input_path Source video path. @param output_dir Optional output directory. Falls back to FFMPEG_OUTPUT_DIR or SHELL_AS_MCP_OUTPUT_DIR. @param start_time Optional start timestamp. @param end_time Optional end timestamp. @param fps Optional extraction fps (for example 0.5 for one frame every two seconds). @param keyframes_only Whether to extract only keyframes (I-frames). @param max_resolution Optional longest-edge cap for generated frames. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Transcode high-bitrate source footage to an edit-friendly H.264 proxy. @remarks Generates a lower-bitrate proxy suitable for editing. Returns JSON in stdout with output_path and applied parameters. @param input_path Source video path. @param output_path Destination proxy video path. @param width Proxy output width in pixels. Height is auto-calculated to maintain aspect ratio. Default 1280. @param crf H.264 CRF quality factor (lower = better quality). Default 28. @param fps Optional output frame rate to unify mixed-fps footage. @param pixel_format Output pixel format. Default yuv420p for maximum compatibility. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Extract a single frame from a video at a specified timestamp to use as a thumbnail or poster image. @remarks Returns JSON in stdout with output_path and applied parameters. Output format is determined by output_path extension (jpg recommended). @param input_path Source video path. @param output_path Destination image path (for example thumbnail.jpg or poster.png). @param timestamp Timestamp to extract the frame from. Default 00:00:01. @param width Output image width in pixels. Height is auto-calculated. Default 1280. @param quality JPEG quality factor 1-31 (lower value = better quality). Default 2. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Check whether ffmpeg runtime dependency is available. @remarks Returns ffmpeg version and health status as JSON. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Mix two audio tracks (voice and background music) into a single output using the amix filter. @remarks Typical use: normalize voice first, then mix with BGM using a low bgm_volume (0.2–0.3). Returns JSON in stdout with output_path and applied volume parameters. @param voice_path Primary audio track path (for example voice or narration). @param bgm_path Background music track path. @param output_path Destination mixed audio path. @param voice_volume Volume multiplier for the primary track. Default 1.0. @param bgm_volume Volume multiplier for the background music track. Default 0.3. @param duration Output duration strategy: shortest (default), longest, or first. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Replace or attach an audio track to a video by muxing a separate audio file. @remarks The original video audio is discarded. Typical use: attach a mixed or dubbed audio track to a graded video. Returns JSON in stdout with output_path and applied parameters. @param video_path Source video path (its original audio track will be discarded). @param audio_path Replacement audio track path. @param output_path Destination video path with the new audio track. @param audio_delay_ms Audio track delay in milliseconds (positive = delay audio). Default 0. @param reencode_audio Whether to re-encode the audio to AAC. Default false uses stream copy. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Normalize audio loudness to a target EBU R128 LUFS using the ffmpeg loudnorm filter. @remarks Returns JSON in stdout with output_path and applied normalization parameters. Default target of -14 LUFS is suitable for most streaming platforms (YouTube, Spotify). @param input_path Source audio or video path. @param output_path Destination audio path. @param target_lufs Target integrated loudness in LUFS. Default -14. @param true_peak Maximum true peak level in dBTP. Default -1.0. @param loudness_range Target loudness range (LRA) in LU. Default 11. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Probe a media file and return full metadata as JSON using ffprobe. @remarks Returns ffprobe JSON output in stdout with streams and format information. @param input_path Source media file path (video or audio). @param stream_type Filter streams to probe: all (default), video, or audio. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Build a Whisper/STT-ready compact audio output from either audio or video input. @remarks Returns a JSON summary in stdout with output_path and normalization parameters for LLM-friendly parsing. @param input_path Source media path (video or audio). @param output_path Destination audio path. @param start_time Optional start timestamp (for example 00:04:30). @param end_time Optional end timestamp (for example 00:05:30). @param sample_rate Output sample rate in Hz, default 16000. @param channels Output channels count, default 1. @param remove_silence Whether to remove long silent regions, default true. @param audio_format Output container format, default mp3. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Build an LLM-ready video in one ffmpeg run (trim, scale, fps, speed, optional audio strip and watermark). @remarks Returns a compact JSON summary in stdout with output_path and applied options for LLM-friendly parsing. @param input_path Source video path. @param output_path Destination video path. @param start_time Optional start timestamp (for example 00:04:30). @param end_time Optional end timestamp (for example 00:05:30). @param max_resolution Optional longest-edge cap (for example 720). @param fps Optional output fps (for example 1.0). @param speed_factor Playback speed factor (for example 2.0). @param strip_audio Whether to remove audio track. @param watermark_path Optional watermark/subtitle image path. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Split a single video into multiple segments at specified timestamps. @remarks split_points is a comma-separated list of timestamps (HH:MM:SS or seconds). Returns JSON in stdout with output_dir, segment_count, and segments array. Falls back to FFMPEG_OUTPUT_DIR or SHELL_AS_MCP_OUTPUT_DIR if output_dir param is omitted. @param input_path Source video file path. @param output_dir Output directory for generated segments. Falls back to FFMPEG_OUTPUT_DIR or SHELL_AS_MCP_OUTPUT_DIR. @param split_points Comma-separated list of cut timestamps, for example 00:10:00,00:20:00,00:30:00. @param output_prefix Filename prefix for segment files, default segment. @param reencode Whether to re-encode segments. Default false uses stream copy (faster but may cause keyframe misalignment). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Collect host system context for code development tasks in a single call. @remarks Returns two sections: 'system' (OS, locale, timezone, hardware, current time) and 'dev_environments' (availability, path, and version for ~35 programming tools). Ideal as a first call before writing or running code on the host. @param include_hardware Whether to include CPU count and total memory size in system section. Default true. @param filter_tools Optional comma-separated list of tool names to probe (e.g. 'python3,node,rustc'). Empty = check all ~35 tools. @param output_format JSON indentation style: 'pretty' (default, 2-space indent) or 'compact'. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Check whether host_info bundle can access basic host context commands. @remarks Verifies uname availability and emits a compact JSON report. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Read recent run_safe_command execution audit records. @param limit Maximum number of most recent entries to return. Default 20. @param include_rotated Include rotated audit files in addition to the active audit file. Default true. @param rotated_file_limit Maximum number of rotated audit files to scan. Range 1-50. Default 10. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Rotate run_safe_command audit file immediately and enforce retention. @param max_files Optional retention count for rotated files. Range 1-100. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Execute a command safely with structured security and audit metadata. @remarks The command is executed without shell eval in a validated working directory. Runtime control behaviors are internal-only and not caller-configurable. On darwin/arm64, pre-execution auth prefers native Swift+WKWebView and automatically falls back to OSA. @param command Executable name to run (for example: ls, cat, grep). @param args_json JSON array string of positional arguments, for example ["-la", "./src"]. @param working_dir Absolute working directory where the command will run. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Check run_safe_command runtime dependencies and platform capabilities. @remarks Missing optional trace tools (for example strace on macOS) are reported as warnings, not hard failures. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Show usage and safety model for run_safe_command tools. @param topic Optional topic filter: execute, audit, healthz, security. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Execute a safe shell pipeline from structured stage definitions. @remarks Each stage is validated against a command allowlist before execution. The pipeline is assembled using Python subprocess chaining (Popen stdin chains), not via shell eval or bash -c with user-supplied data. Commands are restricted to a safe processing-only allowlist; destructive or network commands are not permitted. Unlike run_safe_command__execute, this tool accepts pipe-connected stage sequences but applies stricter per-stage command validation to compensate. On darwin/arm64, pre-execution auth prefers native Swift+WKWebView and automatically falls back to OSA. @param stages_json JSON array of pipeline stage objects. Each stage must have "command" (string) and "args" (string array). Commands must pass the pipeline allowlist: grep, awk, sed, cut, sort, uniq, wc, head, tail, cat, echo, tr, xargs, find, ls, ps, du, df, date, env, printenv, uname, hostname, id, whoami, pwd, dirname, basename. Example: [{"command":"ps","args":["aux"]},{"command":"grep","args":["python"]}] @param working_dir Absolute working directory shared by all pipeline stages. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Generate a shell-as-mcp bundle with runprompt under SHELL_AS_MCP_SPEC_DIR. @param artifact_type Artifact type: shell-as-mcp-bundle. @param requirements Natural language requirements used to generate file content. @param server_name Optional server folder for shell-as-mcp-bundle mode. @param tool_name Optional tool base name for shell-as-mcp-bundle mode. @param max_repair_rounds Optional max repair rounds when quality gates fail. @param run_tests Optional toggle for running tests in quality gates. @param run_code_review Optional toggle for running code review gate (default true). @param run_security_review Optional toggle for running security review gate (default true). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Check whether runprompt bundle runtime prerequisites are available. @remarks Verifies python3 availability and returns version in JSON. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Check whether shell bundle basic runtime is available. @remarks Verifies bash command presence and returns JSON status. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Run a local script and echo the input value with prefix. @param value Input value passed to the script. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Download audio from a video URL using yt-dlp, saving as m4a to output_dir or a configured default directory. @remarks Extracts best-quality audio track. Supports optional cookies file and proxy. @param url The video URL to download audio from (must start with http:// or https://). @param output_dir Optional output directory. Falls back to YTDLP_OUTPUT_DIR, SHELL_AS_MCP_OUTPUT_DIR, or ~/Downloads. @param cookies Optional path to a Netscape-format cookies file for authenticated downloads. @param proxy Optional proxy address (e.g. socks5://127.0.0.1:1080). @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Download and extract plain-text transcript from a video URL using yt-dlp. @remarks Downloads VTT subtitles (manual or auto-generated) to a temp dir, converts to plain text (strips timestamps, NOTE blocks, duplicate adjacent lines), then cleans up. @param url The video URL (must start with http:// or https://). @param language Subtitle language code. Defaults to "en". @param output_dir Optional output directory. If set, transcript text is also saved as a .txt file. @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address. @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Download a video from a URL using yt-dlp, saving to output_dir or a configured default directory. @remarks Supports resolution selection and optional time-range trimming via --download-sections. Both startTime and endTime must be provided together to enable trimming. @param url The video URL (must start with http:// or https://). @param resolution Target resolution: "480p", "720p" (default), "1080p", or "best". @param startTime Optional start time for clip extraction (e.g. "00:01:30"). @param endTime Optional end time for clip extraction (e.g. "00:05:00"). @param output_dir Optional output directory. Falls back to YTDLP_OUTPUT_DIR, SHELL_AS_MCP_OUTPUT_DIR, or ~/Downloads. @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address. @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Download subtitle files (VTT) for a video URL using yt-dlp, saving to output_dir or a configured default directory. @remarks Downloads both manual and auto-generated subtitles without downloading the video itself. @param url The video URL (must start with http:// or https://). @param language Subtitle language code. Defaults to "en". @param output_dir Optional output directory. Falls back to YTDLP_OUTPUT_DIR, SHELL_AS_MCP_OUTPUT_DIR, or ~/Downloads. @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address. @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Fetch video comments from a URL using yt-dlp and return structured JSON. @remarks Uses yt-dlp --write-comments -j to extract comments metadata, then filters/sorts via Python to return at most maxComments entries. @param url The video URL (must start with http:// or https://). @param maxComments Maximum number of comments to return (1-5000). Defaults to 100. @param sortOrder Comment sort order: "top" (default) or "new". @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address. @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Fetch and summarize top comments from a video URL using yt-dlp. @remarks Returns formatted comment list with author, like count, and text. @param url The video URL (must start with http:// or https://). @param maxComments Number of comments to return (1-50, default 10). @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address (e.g. socks5://127.0.0.1:1080). @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Fetch raw metadata JSON for a video URL using yt-dlp. @remarks Returns full or filtered metadata fields as JSON. @param url The video URL (must start with http:// or https://). @param fields Comma-separated field names to return (e.g. "title,uploader,view_count"); empty returns all. @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address (e.g. socks5://127.0.0.1:1080). @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Fetch and display a human-readable metadata summary for a video URL using yt-dlp. @remarks Returns title, channel, duration, upload date, views, likes, tags, and description snippet. @param url The video URL (must start with http:// or https://). @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address (e.g. socks5://127.0.0.1:1080). @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Check whether ytdlp bundle runtime dependency is available. @remarks Verifies yt-dlp, python3, node and _ytdlp_cookies_lib.sh availability, then returns yt-dlp version in JSON. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

List all available subtitle languages for a video URL using yt-dlp. @remarks Outputs subtitle language codes and formats without downloading. @param url The video URL (must start with http:// or https://). @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address (e.g. socks5://127.0.0.1:1080). @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

Search YouTube videos by keyword using yt-dlp and return results as summary or JSON. @remarks Uses ytsearch to query YouTube; supports pagination via offset and date filtering. @param query Search keywords (must not contain newlines). @param maxResults Number of results to return (1-50, default 10). @param offset Pagination offset (default 0). @param response_format Output format: "summary" (default) or "json". @param uploadDateFilter Filter by upload date: "today", "week", "month", or "year". @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address (e.g. socks5://127.0.0.1:1080). @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.

List all background tasks. Optionally filter by status.

Get full details of a background task by taskId, including stdout/stderr output.

Cancel a running background task. Sends SIGTERM followed by SIGKILL if needed.

Remove completed, failed, or cancelled tasks from memory. Optionally specify maxAgeMs to only remove tasks older than the given milliseconds.