Kinocut

Run Hyperframes environment diagnostics.

Find registered MCP tools by name, keyword, or a supported task phrase. Returns JSON {success, query, count, tools:[{name, description, required_params}]}. Use to find the right tool for a task without reading every description. Pass query with a term such as blur, resize, subtitle, audio, or trim, or a task such as "remove filler words", "resume render", or "keep face in frame". Exact names rank first. Discovery describes contracts, not installed backend availability. Args: query: Search term — e.g. "blur", "resize", "subtitle", "audio", "trim".

Add, replace, or mix an audio track into an existing video and render a new output file. Returns JSON {success, output_path}. Use to score or re-voice a video; source video and audio are read only. Pass video_path as the source video and audio_path as the audio file; set mix to combine or false to replace.

Overlay text on a video (titles, captions, watermarks). Returns JSON {success, output_path}. Use to burn a single text element into a video. Pass input_path as the source video, text with the string to draw, and position/size/color to style it; output_path is auto-named when omitted. Args: input_path: Absolute path to the input video. text: Text to overlay. position: Position on screen. Named (top-left, top-center, etc.), pixel" " {"x": 100, "y": 50}, or percentage {"x_pct": 0.5, "y_pct": 0.5}. font: Path to font file. Uses system default if omitted. size: Font size in pixels. color: Text color (CSS color name or hex). shadow: Add text shadow for readability. start_time: When the text appears (seconds). Null = always visible. duration: How long text is visible (seconds). Requires start_time. output_path: Where to save the output. Auto-generated if omitted. crf: Override CRF value (0-51, lower = better quality). Default 23. preset: Override FFmpeg encoding preset (ultrafast, fast, medium, slow, veryslow).

Overlay multiple text elements on a video in a single FFmpeg pass. Returns JSON {success, output_path}. Use when one video needs several captions at once. Pass input_path as the source video and texts as a list of overlay dicts (text plus optional position/size/color/timing). Args: input_path: Absolute path to the input video. texts: List of text overlay dicts. Each dict may contain: - text (str, required) - position (str|dict, default "center") - font (str, optional) - size (int, default 48) - color (str, default "white") - shadow (bool, default True) - start_time (float, optional) - duration (float, optional) output_path: Where to save the output. Auto-generated if omitted. crf: Override CRF value (0-51, lower = better quality). Default 23. preset: Override FFmpeg encoding preset (ultrafast, fast, medium, slow, veryslow). auto_layout: Automatically distribute vertically stacked texts at the same named position. Default True.

Transcode a video into a different container or codec (mp4, webm, gif, mov, ...). Returns JSON {success, output_path}. Use for format conversion; prefer video_export for delivery presets. Pass input_path as the source video and format as the target container; long renders stream MCP progress.

Return a read-only JSON readiness verdict for the next video job.

Extract a frame using the same sampling as CLI and Python frame extraction. Omitted timestamps use smart thumbnail selection when available, falling back to 10% of the clip duration. Pass 0 explicitly to extract the first frame. Args: input_path: Absolute path to the video. timestamp: Explicit time in seconds, or None for automatic sampling. output_path: Where to save the frame. Auto-generated if omitted.

Probe a video file for metadata. Returns JSON {success, info:{duration, resolution, codec, fps, size, ...}}. Use before any edit to learn the source's dimensions and length. Pass input_path as the absolute path to the existing video. Set exact=true to also get the decoded frame_count and the raw r_frame_rate/avg_frame_rate strings (slower: the whole video stream is decoded). Args: input_path: Absolute path to the video file. exact: Also report frame_count (decoded), frame_count_source, r_frame_rate and avg_frame_rate (raw ffprobe strings, null when not measurable).

Concatenate two or more existing video clips into one rendered output file. Returns JSON {success, output_path}. Use to join ordered clips into a single video. Pass clips as an ordered list of absolute paths (at least two); output is auto-named or written to output_path.

Scaffold a cinematic video project with style, storyboard, and refs folders. Args: slug: Project slug using lowercase letters, numbers, hyphens, or underscores. output_dir: Base directory for the projects/ folder. Defaults to the current working directory.

Run visual quality checks on a video. Analyzes brightness, contrast, saturation, audio levels, and color balance. Returns quality scores and recommendations. Args: input_path: Absolute path to video file fail_on_warning: If True, treat warnings as failures

Inspect a rescue plan or receipt and re-check artifact integrity.

Resize a video or change its aspect ratio. Returns JSON {success, output_path}. Use to fit a video to target dimensions or a preset ratio. Pass input_path as the source video (e.g. from video_info) and either width/height or aspect_ratio to define the target. Args: input_path: Absolute path to the input video. width: Target width in pixels. Use with height. height: Target height in pixels. Use with width. aspect_ratio: Preset aspect ratio (16:9, 9:16, 1:1, 4:3, 4:5, 21:9). Overrides width/height. quality: Quality preset (low, medium, high, ultra). output_path: Where to save the output. Auto-generated if omitted.

Assemble a review package and publish-gate verdict for a candidate artifact.

Trim, caption, make vertical, and export selected segments in one call.

Render a new video with playback speed changed; the source video is left unchanged. Returns JSON {success, output_path}. Use for slow-motion or fast-forward effects. Pass input_path as the source video and factor as the multiplier (below 1.0 slows, above 1.0 speeds up).

Trim a video clip by start time and duration. Returns JSON {success, output_path} pointing at the rendered clip. Use to cut a segment out of a longer video. Pass input_path as the absolute path to the source video (e.g. from video_info), start as a timestamp, and duration or end to define the segment. Args: input_path: Absolute path to the input video. start: Start timestamp (e.g. '00:02:15') or numeric seconds (e.g. 10.5). duration: Duration to keep (e.g. '00:00:30' or '30'). Exclusive with end. end: End timestamp. Exclusive with duration. output_path: Where to save the trimmed video. Auto-generated if omitted. accurate: Frame-accurate seeking (slower). Default False uses fast input seeking which may land on the nearest keyframe.

Validate a set of text overlays for visual failure modes before rendering. Checks for: text overlap, low contrast, unsafe positioning, excessive sequential overlays, and missing shadows. Args: overlays: List of overlay specs with keys: text, position, size, color, shadow (optional), start_time (optional), duration (optional). video_width: Video width in pixels. video_height: Video height in pixels. background_color: Background hex color for contrast checking. Returns: dict with warnings list and clean boolean.

Summarize any receipt this project emits, with a read-only integrity check. Reads a workflow render receipt, a dry-run ``workflow_plan`` artifact, or a ``layer_plan`` receipt (v1 legacy with NO ``receipt_kind`` field, or v2) at ``receipt_path`` and returns a NORMALIZED inspection: the kind (inferred from the ``tool`` field when ``receipt_kind`` is absent, per legacy tolerance), schema_version, tool, versions, a status summary (per-step statuses, failed step + error if any), a hash presence/integrity report (which recorded source/output hashes still match the bytes on disk NOW — a read-only re-check), outputs, warnings, cleanup state, plus human-review pointers and known limitations. Nothing is rendered or modified. A malformed/unreadable receipt fails closed with ``invalid_workflow_receipt``. Args: receipt_path: Absolute path to the receipt JSON file to inspect. compare_path: Optional second receipt; when set, also return a diff (N3).