Settings file, per-job clip folders, faster polling, voices/ rename

Poll interval
  wait_for_completion() polled every 3 s, which quantised every clip to a 3 s
  boundary — across 2075 existing clips, 91% of the gaps landed exactly on a
  multiple of 3 s. It now starts at 0.25 s and backs off to 2 s after 10 s, so
  short clips are picked up immediately without hammering the server on long
  ones. Measured over 34 clips: 4.75 s actual vs 6.35 s under the old poll,
  a 25% cut in TTS wait (~18 min on a 693-clip episode). Runs now print real
  generation time, e.g. "done (4.2s)".

  A WebSocket would remove polling entirely but needs a third-party client,
  which would cost this script its dependency-free property.

settings.ini
  voice, speed, temperature, max_tokens, strip_leading_ms, trailing_fade_ms,
  orig_volume, tts_volume, output_dir and comfy_url moved to an INI file next
  to the script. Precedence is CLI flag > settings.ini > built-in default,
  wired by feeding loaded values in as argparse defaults. --settings FILE
  selects an alternative profile.

  INI rather than TOML (tomllib is 3.11+, this runs on system Python 3.10) or
  JSON (no comments). A missing, partial, malformed or corrupt file degrades to
  built-in defaults with a warning instead of killing a long run.

  Run-specific flags are deliberately excluded: --start, --end, --seed,
  --regen, --rebuild, --resume-from, --embedded-subs, --skip-tts.

Per-job folders
  All state for one video now lives in <output_dir>/clips/<video name>/ —
  clips, tts_input.srt, tts_assembled.flac, embedded_sub.srt and
  video_fragment.mkv. Only <stem>_lektor.mkv stays at the top level.

  tts_input.srt moved with the clips because they are a matched pair: block N
  in the SRT is clip_NNNN.flac. Previously both sat at the top level and each
  new job overwrote the last one's, so rebuilding an older film silently
  paired its clips with the newest film's text. Any past job can now be
  rebuilt. A run against the old flat layout gets an explanatory message.

gudowski/ -> voices/
  VOICE_PROMPTS_DIR is now resolved relative to the script rather than
  hardcoded, so moving the project no longer breaks it. Voice filenames are
  unchanged, so --voice gudowski_short still works.

Docs updated throughout for the new layout, settings file and poll behaviour.

Known issue, not addressed here: with a non-zero --start the voiceover plays
early. extract_video_fragment() stream-copies, so it can only cut on a
keyframe and seeks backwards to it, while TTS timestamps are relative to the
requested start. On S01_E08 at --start 07:40 the nearest earlier keyframe is
458.375 s, putting the voiceover 1.625 s ahead of the picture. Runs with
--start 00:00 are unaffected, since 0 is always a keyframe.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/architecture.md

@@ -8,13 +8,13 @@ the straightforward version was tried first and broke.
 SRT / embedded track
    │  parse, clean, split dialogue
    ▼
-subtitle blocks ──────────────► output/tts_input.srt
+subtitle blocks ──────────────► <job>/tts_input.srt
    │  one HTTP job per block
    ▼
 ComfyUI + Higgs Audio V3
    │  per-clip atempo + fade
    ▼
-clips/clip_NNNN.flac
+<job>/clip_NNNN.flac
    │  adelay + amix, batched
    ▼
 tts_assembled.flac
@@ -49,15 +49,41 @@ in step 3 would silently miss it.
 `split_dialogue_blocks()` then divides a two-speaker block into one clip per
 line, apportioning the block's duration by character count.
 
-The result is written to `output/tts_input.srt`. That file is the source of
-truth for block numbering: block *N* there is `clips/clip_NNNN.flac` and the
+The result is written to `tts_input.srt` in that video's job folder
+(`output/clips/<video name>/`). It is the source of truth for block
+numbering: block *N* there is `clip_NNNN.flac` beside it and the
 argument to `--regen N`.
 
 ## 2. Speech generation
 
 For each block the script POSTs a workflow graph to `/prompt`, polls
-`/history/{id}` every 3 s, and reads the resulting file directly from ComfyUI's
-output directory.
+`/history/{id}` until it completes, and reads the resulting file directly from
+ComfyUI's output directory.
+
+**Polling cadence is a performance decision, not a detail.** A clip that
+finishes just after a poll waits for the next one, so the interval — not the
+GPU — sets the floor on throughput. It was originally a flat 3 s, which
+quantised every clip to a 3 s boundary: measured across 2075 real clips, 91% of
+the gaps landed exactly on a multiple of 3 s.
+
+`wait_for_completion()` now starts at 0.25 s and backs off to 2 s once a job
+passes 10 s, so the common case is picked up almost immediately while a stuck
+generation does not sit at 4 requests/second indefinitely. Measured over 34
+clips:
+
+| | mean | median | 34 clips |
+|---|---|---|---|
+| Actual generation | 4.75 s | 4.60 s | 162 s |
+| Old flat 3 s poll | 6.35 s | 6.00 s | 216 s |
+
+That is 1.60 s wasted per clip, a **25% reduction in TTS wait** — about 18
+minutes on a 693-clip episode. The run also now prints real generation time
+(`done (4.2s)`), which is what makes this measurable at all.
+
+ComfyUI also pushes completion events over a WebSocket, which would remove
+polling entirely. It is not used because Python has no standard-library
+WebSocket client, and that would cost this script its only real virtue as a
+dependency-free file. Polling at 0.25 s recovers most of the benefit.
 
 The graph has five nodes: