# Advanced settings reference

> Every configuration key in RoughCut with its default, range, effect, and the risk of changing it.
>
> Verified against the current RoughCut app on 28 August 2026
> https://www.roughcuteditor.com/docs/advanced-settings-reference

This is the complete reference for every key in RoughCut's configuration schema, grouped exactly as the Settings Full tab groups them: LLM, Pipeline v2, Transcription, Evals, and System. For each key it gives the interface label, the internal key name, the type, the shipping default, any enforced bounds, and what changing it actually does. Settings resolve in one order only — schema defaults, then your configuration file, then per-job overrides. Saving writes only values that differ from a default, and secrets never enter that file. Most users should change none of this: the ordinary workflow articles cover the controls that matter day to day.

## Read this first

**This page is advanced.** Nothing here is required for normal use. The defaults are the tested configuration, and the ordinary controls on the `New Rough Cut` screen — covered in [Create your first rough cut](/docs/first-rough-cut) — are what most users should change.

Change a key here only when you have a documented problem or an evaluation result that justifies it, and note how to return to the default: clear the field or set it back to the value in the table, then `Save Configuration`. A value equal to its default is removed from the configuration file entirely.

> Changing a provider, a model, or the transcription source invalidates comparability with earlier [evaluation](/docs/evaluation-overview) runs. Cached evaluation responses are keyed to those choices, so results before and after a change are not a clean comparison.

## How settings resolve

There is exactly one resolution order:

```text
schema default  <  configuration file  <  per-job override
```

A layer wins only when its value is meaningful — not missing, and not an empty string. Per-job overrides are the controls on the `New Rough Cut` and `Transcribe Only` screens; they apply to that job only.

The `modified` badge next to a field means the value differs from the shipping default. It does not mean unsaved. Secret fields never show it.

## LLM

Which provider runs the editor pass, and how it is called.

| Label | Key | Type | Default | Range or choices | Effect and when to change |
|---|---|---|---|---|---|
| `LLM provider` | `llm_provider` | select | `gemini` | `gemini`, `openai` | Which provider runs the editing pass and evaluations. Gemini is recommended: its long context usually fits a whole video in one pass. |
| `Gemini API key` | `gemini_api_key` | secret | empty | — | Your own key, stored in the Keychain. Requires billing enabled on its Google project. |
| `Gemini model` | `gemini_model` | string | `gemini-3.1-pro-preview` | — | The model used for editing. Change only if your project cannot access the default, and expect different editing behaviour. |
| `Gemini timeout (sec)` | `gemini_timeout_sec` | int | `600` | — | Raise for very long transcripts on slow connections. |
| `OpenAI API key` | `openai_api_key` | secret | empty | — | Your own key, stored in the Keychain. Also required for Cloud transcription. |
| `OpenAI model` | `openai_model` | string | `gpt-5.2` | — | The model used for editing when the provider is OpenAI. |
| `OpenAI timeout (sec)` | `openai_timeout_sec` | int | `600` | — | Also used as the Cloud transcription timeout. |

## Pipeline v2

How cuts are decided and shaped. **These are the settings most likely to damage a cut.**

| Label | Key | Type | Default | Range | Effect and when to change |
|---|---|---|---|---|---|
| `Min silence to cut (sec)` | `silence_min_cut_s` | float | `0.7` | min `0.1` | The configuration-level floor for cutting a silence. Distinct from the per-job `Min silence (sec)`, which defaults to 0.5. Raising it keeps more breathing room. |
| `Cut pad into removed (sec)` | `pad_into_removed_s` | float | `0.05` | `0.0`–`0.5` | How far a kept segment extends into removed material. Raising it softens cuts; too high reintroduces the noise you cut. |
| `Min keep island (sec)` | `min_keep_island_s` | float | `0.25` | min `0.0` | Kept fragments shorter than this are absorbed into the surrounding cut. Raising it removes more stray syllables. |
| `LLM editor max output tokens` | `llm_editor_max_output_tokens` | int | `65536` | min `1024` | Always set, to prevent silent truncation. Lowering it risks a truncated edit list. |
| `LLM editor chunk size (words)` | `llm_editor_chunk_words` | int | `24000` | min `2000` | How much transcript goes to the model at once. Also the ceiling above which Second Look cannot run. |
| `LLM editor chunk overlap (words)` | `llm_editor_overlap_words` | int | `600` | min `0` | Overlap between chunks so cuts near a boundary are not missed. |
| `LLM editor exemplars` | `llm_editor_exemplars` | int | `8` | min `0` | How many example removals are injected into the prompt. `0` disables exemplars. Needs an imported bank — see [Exemplars](/docs/exemplars). |
| `Exemplar bank path` | `exemplar_bank_path` | path | empty | — | Overrides the default bank location. Empty means the standard location inside the app's container. |
| `Second Look passes` | `second_look_passes` | int | `0` | `0`–`3` | `0` is off. The job toggle sets 1 when enabled. See [Second Look](/docs/second-look). |
| `Second Look min confidence` | `second_look_min_confidence` | float | `0.95` | `0.0`–`1.0` | Refine-pass proposals below this are never cut automatically; they become review suggestions. Lowering it makes automatic removal far more aggressive. |
| `Second Look max removal %` | `second_look_max_removal_pct` | float | `10.0` | `0.0`–`100.0` | Per-pass budget as a share of the words that survived so far. |
| `Second Look max spans` | `second_look_max_spans` | int | `10` | min `0` | Hard cap on automatically applied cuts per pass. |
| `Second Look auto categories` | `second_look_auto_categories` | string | `retake_verbatim,retake_reworded,false_start,noise` | — | Which categories may be applied automatically. `tangent` is deliberately excluded as the known over-cutting risk. |

## Transcription

| Label | Key | Type | Default | Choices | Effect and when to change |
|---|---|---|---|---|---|
| `Whisper model name` | `whisper_cpp_model_name` | string | `ggml-large-v3-turbo.bin` | — | The tested default for word timestamps in English and Arabic. |
| `Whisper model path` | `whisper_cpp_model_path` | path | empty | — | Overrides where the model is loaded from. Empty means the standard location. |
| `Whisper device` | `whisper_device` | select | `metal` | `auto`, `cpu`, `metal` | `metal` is correct on Apple Silicon. `cpu` is for debugging and much slower. |
| `Silence-gated transcription` | `asr_silence_gated` | bool | `true` | — | Transcribes speech regions rather than the whole file. Leave on. |
| `Hallucination loop recovery` | `asr_loop_recovery` | bool | `true` | — | Re-transcribes regions where the model looped. Leave on. On-device only. |
| `OpenAI transcription model` | `openai_transcribe_model` | string | `whisper-1` | — | Cloud transcription requires word timestamps; only `whisper-1` returns them today, and other models fail loudly. |
| `Cloud transcription by default` | `cloud_transcription_default` | bool | `false` | — | Pre-selects Cloud for new jobs. Requires Pro and your OpenAI key; each job still shows the choice. |

## Evals

Optional. See [Evaluate RoughCut against your own edits](/docs/evaluation-overview).

| Label | Key | Type | Default | Range | Effect |
|---|---|---|---|---|---|
| `Eval dataset root` | `eval_dataset_root` | path | empty | — | Your golden-set folder. Grant access through `Models & Data` rather than typing a path. |
| `Full eval max clips` | `eval_full_max_clips` | int | `15` | min `0` | Cap on a full run. `0` runs all clips. |
| `Langfuse public key` | `langfuse_public_key` | secret | empty | — | Keychain. Only needed for tracing. |
| `Langfuse secret key` | `langfuse_secret_key` | secret | empty | — | Keychain. Only needed for tracing. |
| `Langfuse base URL` | `langfuse_base_url` | string | `https://cloud.langfuse.com` | — | Change for a different region or a self-hosted instance. |
| `Langfuse tracing` | `langfuse_tracing` | bool | `false` | — | Off means fully local: no telemetry leaves the machine. |
| `Langfuse sample rate` | `langfuse_sample_rate` | float | `1.0` | `0.0`–`1.0` | Present in the schema. See the note below. |
| `Langfuse environment` | `langfuse_environment` | string | `revamp-v2` | — | Environment tag applied to traces. |

## System

| Label | Key | Type | Default | Effect |
|---|---|---|---|---|
| `Job TTL hours` | `job_ttl_hours` | int | `24` | Finished jobs older than this are cleaned up automatically. |
| `Max video GB` | `max_video_gb` | int | `12` | Present in the schema. See the note below. |
| `Max audio GB` | `max_audio_gb` | int | `10` | Present in the schema. See the note below. |
| `Max total GB` | `max_total_gb` | int | `25` | The jobs folder is trimmed oldest-first to stay under this. |
| `Keep analysis audio` | `keep_analysis_audio` | bool | `false` | Off deletes the extracted analysis audio (~115 MB per hour) when a cut finishes. Neither the FCPXML nor review needs it. |
| `Log level` | `log_level` | select | `INFO` | Present in the schema. See the note below. |

> ! Four keys — `Max video GB`, `Max audio GB`, `Langfuse sample rate`, and `Log level` — appear as editable fields but are not read anywhere in the current build. Setting them has no effect. In particular, do not rely on the two GB values as enforced file-size limits.

## Keeping this page honest

This table is generated from the app's configuration schema at the version stated in the page metadata, and the [drift check](/docs/changelog) treats a change to that schema as a documentation-affecting change. If the app adds or renames a key, this page is regenerated before the change is published.