Confirm font substitution before changing the template
| Observation | Next step |
|---|---|
| Letter skeletons, strokes, or numeral forms clearly differ | Check the old project's actual font file, the readable file on the new machine, and the internal family. These are the primary clues for substitution. |
| Letterforms match, but line width or wrapping differs | Continue with font version, missing-glyph fallback, and rendering environment while preserving the current size and subtitle band. |
| Letterforms match, but global position or scale changes | Check project canvas, PlayRes, margins, and delivery dimensions. A canvas mismatch is a separate fault. |
| Only a few characters change style | Check whether the main font covers those characters and whether rendering fell back for them. |
Capture the same subtitle from the old and new outputs, recording machine, project revision, canvas, template ID, font file, and family. A position change alone does not justify changing type size: a mismatched canvas can alter placement and proportion with the exact same font file. A system font menu's display name also does not establish file identity; the project needs a real file it can address.
Build a file-family-template-project chain
| Chain node | Required record |
|---|---|
| Font file | A real project-accessible .ttf, .otf, or .ttc file. This workflow uses the first registered real font file. |
| Internal family | The family name requested by the subtitle style. Read it from the real font information rather than treating a download filename as the family. |
| Font resource | A stable resource ID, file path, and family for templates to reference. |
| Subtitle template | A font resource <font-id> reference plus canvas, type size, outline, shadow, line count, and subtitle band. |
| Project binding | A recap_project.json subtitle_style binding to an adopted template version, resolved before the project starts. |
In the cited implementation, binding sends the font resource's first file as SUBTITLE_FONT_FILE and its font.family as SUBTITLE_FONT_NAME. ASS burning gives libass the file's directory, while drawn overlay text receives the same font-file path. The file answers where to load from; the family answers which family the style requests. They need to describe the same font.
Choose one migration path first. When the adopted template already references the correct font resource, restore the old project's real file and verified family behind that resource while leaving template ID, version, and parameters unchanged. If the old template contains only a family, references the wrong resource, or must move to another font resource, copy every non-font parameter into a new template version, change the font reference, obtain creator adoption, and then bind it. Keep the old version as the baseline.
This chain reduces reliance on fonts installed in the new computer's operating system. It does not compare the old and new file contents automatically, and it does not select among multiple faces inside a collection. For a .ttc, first establish that the registered first real file and family resolve the glyphs required by this project.
Original paper example: moving a coffee-roasting log video to a new computer
Roast Curve Notes is an original paper migration sheet created for this article. Its project name, captions, resource ID, and paths are teaching placeholders. No font file was created or read, neither machine rendered a frame, and no visual comparison was completed. A real repair must replace these fields with actual project records and outputs.
The old video uses subtitle template roast-log-caption@v3 to label milestones in one coffee roast. That template already references font resource roast-log-sans. On the new computer, 一爆开始 08:42 becomes visibly wider, while the numerals and degree sign in 186°C also change style. The paper sheet records:
| Project record | Example value |
|---|---|
| Existing font resource | roast-log-sans, already referenced by old template roast-log-caption@v3 |
| Designed file | resources/font/roast-log-sans/RoastLogSans-Regular.otf |
| Internal family to verify | Roast Log Sans, read from the old project's real font information rather than inferred from the filename |
| Existing subtitle template | roast-log-caption@v3, canvas 1920×1080; font reference, type size, outline, shadow, line count, and subtitle band remain unchanged |
| Project binding | bindings.subtitle_style = roast-log-caption@v3 |
| Representative captions | 一爆开始 08:42; 入豆温度 186°C; Washed Caturra |
| Comparison output | Old-machine v3 baseline and new-machine v3 frame after restoring the file, with the same canvas, non-font parameters, caption, and time |
This example chooses the existing-reference path. Recover the exact file and internal family used by roast-log-sans in the old project, make that same readable file available to the new project, and preserve the roast-log-caption@v3 record and binding. After a real render on the new computer, compare Chinese strokes, Latin letters, numerals, colon, degree sign, line width, and missing glyphs. If the numerals recover while ° still changes, inspect coverage and fallback for that character rather than redesigning the entire subtitle layout.
If real inspection instead finds that v3 never referenced roast-log-sans, stop this restoration path. Copy v3's canvas, type size, outline, shadow, line count, and subtitle band into roast-log-caption@v4, change only the font item to the correct resource, obtain adoption, and then bind v4. The comparison is now the old-machine v3 baseline against the new-machine v4 candidate, with every non-font parameter held constant; it is no longer described as the same template version.
The 1920×1080 value only keeps the template and comparison on one canvas. It is not a recommended delivery size and proves no review result for any font.
Compare representative rendered captions
Choose a small set of real captions that exposes relevant differences: ordinary Chinese, a project-critical uncommon character, numerals and punctuation, and any English or brand spelling. Hold text, canvas, time, background frame, and every non-font parameter constant. When restoring an existing resource file, keep the same template version. When changing the font reference, compare the adopted new version with the old-version baseline and state that only the font item changed.
| Comparison | Record |
|---|---|
| Letterform | Inspect the skeleton and strokes of the same character. Name the affected character instead of writing “looks wrong.” |
| Coverage | Look for boxes, blanks, or isolated characters in a second style, and record every fallback character. |
| Line width | Compare line endings and wrapping under the same text and canvas; investigate font version, spacing, and rendering environment together. |
| Position | Inspect subtitle band and margins. If the entire group shifts uniformly, return to canvas and template binding first. |
| Edges | Compare outline and shadow with their parameters held constant; rendering implementation also affects these edges. |
Matching file path and family establishes a consistent configuration chain. Acceptance comes from the representative outputs: required glyphs exist, primary letterforms match the accepted baseline, wrapping has no unintended change, and captions remain in the same band. Operating system, font version, and rendering library can still change edge rasterization, so define visible acceptance and record concrete observations rather than requiring pixel identity.
Separate project binding from visual approval
At the cited $video-recap revision, a font resource contains at least one .ttf, .otf, or .ttc file and can record font.family. A subtitle template references that resource ID, while the project binds an adopted template through subtitle_style. The actual run entry is:
```bash
python3 scripts/recap.py <video> --project <recap_project.json-or-directory> --work-dir <work_dir>
```
Project resolution checks the library, resources, and templates. It rejects invalid or unadopted templates, stops on canvas mismatch, and reports conflicts between explicit settings and bindings before the run. It can pass the selected font file and family to existing subtitle rendering. It cannot recover the correct file from the old machine, infer design intent, judge acceptable letterforms, or guarantee pixel identity across computers.
Keep a migration record after repair: actual font-file source, internal family, font resource ID, template version, project binding, representative captions, and comparison findings. When a template changes fonts, create a new version and compare again instead of silently replacing the old resource file and carrying forward its prior approval.
FAQ
Why can subtitles change after installing a font with the same name?
The same display name can point to a different file, version, internal family, or glyph set. Recover the actual old-project file and family, then compare renders of the same representative captions.
Does binding a font file guarantee pixel-identical output?
File binding reduces system-font fallback. Font version, glyph coverage, operating system, and rendering library can still affect output, so approve representative captions against visible requirements.
Do it with the skill
Use $video-recap to repair this cross-computer subtitle-font change. Identify the old project's actual font file and internal family. If the adopted template already references the correct font resource, restore the same real file and verified family without changing that template version. If the font reference must be added or replaced, copy every non-font parameter into a new version and adopt it. Bind the selected template through recap_project.json, hold canvas, caption text, and non-font parameters constant, render representative Chinese, critical glyphs, numerals, punctuation, and English, then record letterform, fallback, line-width, and position differences. Do not promise pixel identity.
Read the method: Font resources, subtitle template references, and project binding · Project resolution of font file and family · Subtitle rendering with font file and font directory · Subtitle font name and file environment settings · Project binding entry point and public skill handoff