How to Use Focus Mode for Specific Video Segments in Claude Video

Claude Video’s focus mode activates automatically when you supply --start and/or --end time parameters to the /watch command, concentrating the frame extraction budget exclusively on your specified window for higher visual detail.

Focus mode in the bradautomates/claude-video repository allows you to analyze specific portions of videos without processing the entire file. By defining a temporal window, you trigger denser frame sampling and reduce token costs while maintaining granular visual coverage exactly where you need it.

What Is Focus Mode?

Focus mode is a specialized extraction strategy that zooms in on arbitrary video segments. Instead of distributing frames evenly across an entire video, the system applies an aggressive frames-per-second budget only to your specified range. This delivers higher resolution visual analysis for short clips while keeping processing costs predictable.

The feature activates transparently through the same /watch slash command used across all Agent-Skills hosts. When the watch.py script detects boundary parameters, it switches from standard auto_fps() logic to auto_fps_focus() for enhanced density.

How Focus Mode Works

Triggering Focus Mode with Time Ranges

The entry point in skills/watch/scripts/watch.py defines --start and --end arguments that accept human-readable timestamps or raw seconds:

parser.add_argument("--start", help="Start time (e.g., 00:01:30 or 90)")
parser.add_argument("--end", help="End time (e.g., 00:02:00 or 120)")

These values are parsed using parse_time() from frames.py【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/scripts/watch.py#L40-L52】. Focus mode detection occurs immediately after parsing:

focused = start_sec is not None or end_sec is not None

If either boundary exists, focused becomes True, signaling the system to apply specialized budgeting logic【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/scripts/watch.py#L53-L54】.

Duration Calculation and Window Selection

The system calculates the effective analysis window using safe defaults for unspecified boundaries:

effective_start = start_sec if start_sec is not None else 0.0
effective_end   = end_sec   if end_sec   is not None else full_duration
effective_duration = max(0.0, effective_end - effective_start)

This yields the precise length of your requested segment, ensuring the frame budget applies only to this window【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/scripts/watch.py#L50-L52】.

Dense Frame Budgeting with auto_fps_focus()

When focused is True, the script invokes auto_fps_focus() rather than the standard auto_fps() function【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/scripts/watch.py#L55-L58】. Located in skills/watch/scripts/frames.py, this function applies aggressive sampling rates for short durations:

• ≤ 5 seconds: Maximum density sampling
• ≤ 15 seconds: High-density sampling
• Gradual relaxation for longer windows

This ensures small segments receive many frames per second, providing granular visual coverage where it matters most【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/scripts/frames.py#L41-L58】.

Frame Extraction and Transcript Filtering

The chosen fps and target values feed into extract() (or extract_at_timestamps()), which executes ffmpeg with -ss and -to arguments to limit decoding strictly to the focus range【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/scripts/frames.py#L86-L92】.

Simultaneously, filter_range() from transcribe.py trims any available transcript to match the same temporal window, ensuring text analysis aligns perfectly with the extracted frames【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/scripts/watch.py#L63-L66】.

Code Examples for Claude Video Focus Mode

Basic 30-Second Clip Focus

Analyze a specific 30-second segment from a YouTube video:

watch "https://www.youtube.com/watch?v=abc123" \
      --start "01:15" \
      --end   "01:45"

This command starts at 1 minute 15 seconds and ends at 1 minute 45 seconds. The system automatically applies auto_fps_focus, yielding denser frame coverage within that 30-second window while ignoring the rest of the video.

Focus with Custom Resolution

Extract frames from seconds 10 to 20 at 720px width:

watch "file.mp4" --start 10 --end 20 --resolution 720

The resolution parameter works independently of focus mode, allowing you to control image quality while maintaining the temporal window.

Combining Focus with Precise Timestamps

Add cue frames to a focused range for specific moments of interest:

watch "https://example.com/video.mov" \
      --start "00:30" \
      --end   "01:00" \
      --timestamps "00:45,00:55"

The range (30s–60s) determines the auto-fps budget, while additional frames at exactly 45 and 55 seconds are added on top of the budgeted frames.

Programmatic Usage in Python

Invoke focus mode directly from Python scripts:

from skills.watch.scripts.watch import main as watch_main
import sys

# Simulate CLI arguments

sys.argv = [
    "watch",
    "https://youtu.be/xyz",
    "--start", "00:10",
    "--end",   "00:20",
]
watch_main()

This behaves identically to the CLI, focusing analysis on the specified 10-second window.

Key Files and Functions

The focus mode implementation spans several modules in the bradautomates/claude-video repository:

• skills/watch/scripts/watch.py – Entry point that parses --start/--end, evaluates the focused boolean, and orchestrates the extraction pipeline
• skills/watch/scripts/frames.py – Contains auto_fps_focus(), extract(), and parse_time() utilities for frame budget calculation and ffmpeg execution
• skills/watch/scripts/transcribe.py – Provides filter_range() to synchronize transcript output with the focused temporal window
• skills/watch/scripts/config.py – Holds default detail settings and frame caps that influence focus mode budgeting limits
• skills/watch/SKILL.md – Defines the canonical /watch slash command contract used across Agent-Skills hosts

Summary

• Focus mode activates automatically when you provide --start or --end parameters to the /watch command in bradautomates/claude-video.
• Dense sampling occurs via auto_fps_focus() in frames.py, which applies higher frames-per-second budgets to short temporal windows.
• Cost efficiency is maintained by limiting token-heavy frame extraction to your specified segment rather than the full video.
• Transcript synchronization happens through filter_range(), ensuring text and visual analysis cover identical time ranges.
• Flexible input formats accept both HH:MM:SS timestamps and raw seconds for boundary definitions.

Frequently Asked Questions

What happens if I only specify --start without --end?

If only --start is provided, the system sets effective_end to the full video duration. Focus mode still activates, and frame extraction runs from your start time to the end of the file, applying the denser budgeting logic to that entire remaining segment.

Can I use focus mode with local video files?

Yes. The /watch command accepts both URLs and local file paths. Pass a local filename like "file.mp4" with --start and --end parameters to analyze specific segments of downloaded content using the same focus mode pipeline.

How does focus mode affect token usage?

Focus mode reduces token consumption for long videos by constraining frame extraction to your specified window. Instead of sampling across a 2-hour video, the budget applies only to your 30-second segment, drastically lowering API costs while increasing detail density for that specific portion.

Does focus mode work with timestamp-based frame extraction?

Yes. You can combine --timestamps with --start and --end. The time range determines the auto-fps budget for the window, while explicit timestamps ensure frames exist at specific moments. The system merges both strategies, guaranteeing coverage of your cue points within the focused segment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}