docs: document the Stabilize pitch factor file format

CLAUDE.md

@@ -103,7 +103,7 @@ VapourBox/
 │   └── linux-arm64/
 │
 ├── licenses/                   # GPL, LGPL, NOTICES
-├── docs/                       # BUILDING, FILTER_SCHEMA, ADDONS, ENGINEERING_NOTES, FEATURE_MAP, …
+├── docs/                       # BUILDING, FILTER_SCHEMA, ADDONS, ENGINEERING_NOTES, FEATURE_MAP, PITCH_FACTOR_FILES, …
 │   └── reports/                # Investigation reports (evidence behind decisions)
 ├── Scripts/                    # Build, package, and release scripts
 │   └── models/                 # Model conversion scripts for self-hosted add-on files
@@ -1192,6 +1192,10 @@ Invariants that are easy to break:
   `<stem>.pitch.txt`, `<stem>_pitch.txt`) is picked up when a video is added.
 - **File mode without a usable file is an error**, raised by the script
   generator with the bad line's number — not a silent pass-through.
+- **The file format is documented for users in
+  [docs/PITCH_FACTOR_FILES.md](docs/PITCH_FACTOR_FILES.md)** (linked from the
+  README's pipeline table). Change it with `parse_pitch_factors`,
+  `PitchFactorFile.sidecarCandidates` or the factor's meaning (`invertFactors`).
 - **Pitch on a still-interlaced clip clears `_FieldBased`** (a vertical resample
   would mix the fields; film scans are progressive). Weave alone leaves it.
 - **`pipe_source` evicts silently.** It keeps `cache_frames` decoded frames and

README.md

@@ -125,7 +125,7 @@ Most sources need only a few of these, and the presets pick them for you. Filter
 | 14 | **Chroma Fixes** | Colour shifted off the picture, bleeding, rainbowing, dot crawl and leftover combing |
 | 15 | **Colourisation** | Black-and-white footage, coloured by AI (DDColor or DeOldify Video, optional downloads); the brightness of every pixel is kept exactly |
 | 16 | **Color Correction** | Brightness, contrast, saturation, levels, white balance, shadow detail and local contrast, set by hand or measured |
-| 17 | **Stabilize** | Shake and weave from telecine, film scans or a handheld camera, and the frame-height "breathing" of pull-through film scanners (8mm, Super 8): measured from the footage, or read per frame from a factor file (`reel.pitch.txt` next to `reel.mp4` is picked up automatically) |
+| 17 | **Stabilize** | Shake and weave from telecine, film scans or a handheld camera, and the frame-height "breathing" of pull-through film scanners (8mm, Super 8): measured from the footage, or read per frame from a factor file (`reel.pitch.txt` next to `reel.mp4` is picked up automatically; file format in [docs/PITCH_FACTOR_FILES.md](docs/PITCH_FACTOR_FILES.md)) |
 | 18 | **Rotate / Flip** | Sideways, upside-down or mirrored footage |
 | 19 | **Crop & Resize** | Black borders, tape blanking and head-switching noise (measured for you by **Detect borders**), scaling and upscaling (edge-directed or AI) with SD colour converted to HD's BT.709, and borders to reach an exact frame size |
 | 20 | **Face Restoration** | Blurry, low-resolution faces, redrawn by AI at the output resolution (optional download) |

docs/PITCH_FACTOR_FILES.md

@@ -0,0 +1,36 @@
+# Pitch factor files
+
+For the **Stabilize** pass (see [the filter pipeline](../README.md#the-filter-pipeline) in the README).
+
+Pull-through film scanners (8mm, Super 8) let the film slip in the gate, so each frame comes out slightly taller or shorter than the last. Stabilize's **Pitch Correction** evens this out. **Auto** measures it from the footage by comparing each frame with its neighbours. **From File** reads one factor per frame from a text file you supply, which is more accurate if you have the measurements: in testing, Auto removed about half of the breathing and a good file about three quarters.
+
+## Where the file goes
+
+Put it next to the video before adding the video to the queue: for `reel1.mp4`, name it `reel1.pitch.txt` (`reel1.mp4.pitch.txt` and `reel1_pitch.txt` also work), and it's picked up automatically. Each video in the queue keeps its own file. You can also pick one by hand under **Pitch Factor File** in the Stabilize panel. In From File mode, a video without a file can't be processed.
+
+## Format
+
+Plain text, one factor per line, starting at the first frame:
+
+```
+# reel1: comments and blank lines are ignored
+1.0000
+1.0021
+0.9987
+```
+
+Or a frame number and a factor on each line. Frames you leave out aren't corrected:
+
+```
+0,1.0000
+1,1.0021
+120,1.0035
+```
+
+- Separate the frame number and factor with a comma, semicolon, space or tab, and use one form throughout the file.
+- Every factor must be a positive number. A bad line stops the job with an error naming its line number, so a typo can't shift every frame after it.
+- Frame numbers count the **source's** frames, so trimming or deinterlacing doesn't change them.
+
+## What the number means
+
+By default, a factor is the frame's *measured* height: `1.004` means the frame came out 0.4% too tall, and it's shrunk back. If your file lists the stretch to *apply* instead, tick **Factors Are Corrections**, or every frame is corrected in the wrong direction. **Max Pitch Correction (%)** (1% by default) caps every factor, and **Pitch Edge Fill** chooses whether the rows a shrunk frame exposes are filled from the picture's edge or left black.