# How to Configure the Default Detail Mode in Claude Video

> Learn how to configure Claude Video's default detail mode. Easily change settings via config file or environment variables for custom video analysis.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-01

---

**The default detail mode in Claude Video is set to `"balanced"` via the `DEFAULT_DETAIL` constant in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), and you can override it for all runs using the `WATCH_DETAIL` environment variable or by modifying the configuration file directly.**

Claude Video, an open-source video analysis tool from the `bradautomates/claude-video` repository, uses a configurable **detail** setting to control how many frames are extracted from video content. This setting determines the balance between processing speed and visual analysis depth. When users don't specify a detail level via command-line arguments, the application falls back to a default value that can be customized through several mechanisms.

## Where the Default Detail Mode Is Defined

The primary definition for the default detail mode resides in the configuration module. In [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the constant `DEFAULT_DETAIL` is explicitly set to `"balanced"`:

```python

# skills/watch/scripts/config.py (lines 12-14)

DEFAULT_DETAIL = "balanced"

```

This constant serves as the authoritative fallback when no other configuration is provided.

## How the Configuration Fallback Works

When you run Claude Video without specifying a detail mode, the application follows a specific resolution path. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the script first checks for a `--detail` command-line argument. If omitted, it looks for the `detail` key in the configuration dictionary (`config["detail"]`). If that entry is missing or contains an invalid value, the code finally falls back to the `DEFAULT_DETAIL` constant defined in the configuration module.

According to the source code at lines 54-57 in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), this fallback chain ensures that `"balanced"` is always used as the safe default unless explicitly overridden.

## Methods to Configure the Default Detail Mode

You have three primary ways to configure or override the default detail mode in Claude Video.

### Method 1: Use the WATCH_DETAIL Environment Variable

The `WATCH_DETAIL` environment variable overrides the default before the configuration is loaded. This is the recommended approach for temporarily setting a different default without modifying source files.

Set the variable in your shell:

```bash

# Bash/Linux/macOS

export WATCH_DETAIL=efficient

# Windows PowerShell

$env:WATCH_DETAIL = "efficient"

```

The test suite in [`tests/test_config.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_config.py) (lines 49-50) confirms that setting `WATCH_DETAIL` correctly injects the override value before the configuration initializes.

### Method 2: Edit the Configuration File

To permanently change the default for all users of the installation, modify the `DEFAULT_DETAIL` constant in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py):

```python

# skills/watch/scripts/config.py

DEFAULT_DETAIL = "token-burner"  # Changed from "balanced"

```

After editing, all subsequent runs will use your new default unless overridden by environment variables or command-line flags.

### Method 3: Command-Line Override for Single Runs

For one-off executions, pass the `--detail` flag directly:

```bash
claude-video watch https://youtu.be/example --detail transcript

```

This overrides both the environment variable and the configuration file defaults.

## Available Detail Modes in Claude Video

Claude Video supports four distinct detail modes, each interpreted in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (lines 72-73 and 204-209) to select the appropriate frame-selection engine:

- **`efficient`**: Uses a key-frame extraction engine optimized for speed and token conservation.
- **`balanced`**: Uses a scene-aware engine that extracts frames at regular intervals (the default).
- **`token-burner`**: Aggressive frame extraction for maximum visual detail at higher token costs.
- **`transcript`**: Focuses primarily on audio transcription with minimal visual analysis.

## Practical Configuration Examples

**Set a persistent default via environment variable:**

```bash

# Add to your ~/.bashrc or ~/.zshrc for persistence

export WATCH_DETAIL=efficient

# Verify it works

claude-video watch https://youtu.be/example

```

**Modify the source configuration:**

```python

# skills/watch/scripts/config.py

DEFAULT_DETAIL = "token-burner"

```

**Override for a single execution:**

```bash
claude-video watch https://youtu.be/example --detail efficient

```

## Summary

- The default detail mode is `"balanced"`, defined as `DEFAULT_DETAIL` in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).
- You can override the default using the `WATCH_DETAIL` environment variable for session-level changes.
- For permanent changes, edit the `DEFAULT_DETAIL` constant in the configuration file.
- Four modes are available: `efficient`, `balanced`, `token-burner`, and `transcript`.
- Command-line `--detail` flags take highest precedence, followed by environment variables, then the configuration file constant.

## Frequently Asked Questions

### What is the default detail mode in Claude Video?

The default detail mode is `"balanced"`. This is hard-coded as the `DEFAULT_DETAIL` constant in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) (line 12) and is used whenever users don't specify a detail level via command-line arguments or environment variables.

### Can I change the default detail mode without editing code?

Yes. Set the `WATCH_DETAIL` environment variable to your preferred mode (`efficient`, `balanced`, `token-burner`, or `transcript`). This overrides the code-based default without requiring modifications to [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py), making it ideal for containerized or shared environments.

### Where does Claude Video process the detail mode setting?

The detail mode is interpreted in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). Lines 72-73 handle the initial CLI argument parsing, while lines 204-209 map the detail string to the appropriate frame-selection engine (key-frame, scene-aware, etc.). The fallback logic at lines 54-57 ensures the default is applied when no other value is specified.

### What happens if I specify an invalid detail mode?

If you provide an invalid detail mode via `--detail`, the script falls back to checking `config["detail"]`. If that is also missing or invalid, it uses the `DEFAULT_DETAIL` constant (`"balanced"`) as the final fallback, ensuring the application always runs with a valid configuration.