jiajunzeng789/cantonese-subtitle-skill

Cantonese Car Review Subtitle in Written Chinese (Single Line)

Execution Boundaries

• Speech recognition and media processing are performed locally; no audio/video is uploaded to recognition APIs. Public models and dependencies may be downloaded during preparation; offline processing does not automatically download or switch to cloud services.
• The assistant performs text calibration. When using an online model, transcribed text is sent to the online model; the workflow cannot be described as fully offline. If the user requires offline text processing, a local text model is used; if unavailable, the actual limitation is explained.
• Final delivery is a UTF-8 .srt file, with exactly one line of text per entry, aligned to the original media timeline, not a plain text transcript.
• Default output has no punctuation marks (periods, commas, etc.), but retains necessary symbols for numbers, units, and proper nouns, e.g., 1.8米, 30%, -5℃, 0—100km/h, CX-5. "No punctuation" does not mean deleting all non-Chinese characters.
• Input, raw recognition results, calibration records, and final subtitles are saved separately; original files are not overwritten.

Environment & Task Feedback

• Show the checklist first, then execute. Use the status conventions from references/task-progress.md; check off each step upon verification. Update immediately when entering a step, upon completion, failure, or waiting for user input. For long tasks, report the current step, elapsed time, and recent progress approximately every 60 seconds when execution is possible; do not fabricate percentages or promise background push that the software does not support.
• Unified script preparation and self-check. For initial setup or environment failures, first execute scripts/setup_runtime.py according to references/runtime-setup.md; do not improvise installation commands or arbitrarily change dependency versions. The script first performs a read-only check of local records, known environments, and user-specified interpreters; if valid, it reuses, otherwise it creates a dedicated environment step-by-step. Installation logs and progress are written to disk. Audio decoding, model loading, and short-sample inference are verified separately. For further dependency troubleshooting, see references/environment-recovery.md. Do not modify the system Python or hardcode developer machine paths.
• Check download sources for domestic networks first. When dependency installation is required, prioritize checking the availability and required versions from a trusted domestic HTTPS mirror, then temporarily specify it for the command; do not modify global pip settings. Notifications should show the actual package name, source, and available download progress; do not simply say "PyTorch is large, please wait," nor calculate the size of all dependencies as the size of PyTorch. See environment recovery instructions for details.
• Evidence first, then fix. Preserve complete error messages and exit codes; distinguish between network, build/version, permission, and confirmed security blocks. Judging a security block solely by pip failure, temporary directory, or deleted file keywords is not allowed; do not default to requiring disabling protections, allowing unknown files, or rebooting. When user action is needed, explain the specific basis, target action, impact, and recovery method.
• Failures can be resumed. Basic tools, Whisper, and Qwen are prepared step-by-step with logs saved. For the same error, after a justified fix, retry at most once automatically; if it still fails, stop that step, report the interruption point, and continue with work that does not depend on it. When the user says "continue," first verify the records and running tasks, resume from the still-valid interruption point, and do not restart installations or downloads.

Workflow

1. Determine the final video canvas aspect ratio. For videos, use scripts/subtitle_profile.py to detect display dimensions, considering rotation and pixel aspect ratio, ignoring embedded covers like MP3 covers. The final edited canvas size takes precedence over the source video; when the user specifies portrait, do not apply a landscape preset based on a landscape source. Audio has no canvas: use the user-provided final video settings; if unknown, ask for landscape or portrait, or generate both if the user requests, without presenting guessing as automatic detection. See references/subtitle-layout.md.
2. Local recognition and cross-checking. Check model integrity, use Whisper large-v3 and Qwen3-ASR-1.7B, preserving original text and timing data. Qwen's default output text is used for cross-calibration; timing references rely on Whisper and the original audio. Only load the optional ForcedAligner if additional alignment is needed and validation passes; do not make it a required download for basic operation. Compare based on the same source material and background vocabulary. Run short samples sequentially; for segments exceeding 180 seconds, use scripts/transcribe_long.py to manage overlapping windows, unique filenames, time offsets, and reuse of completed results; do not write an ad-hoc shell loop. The script only conservatively removes duplicate segments where both time and text match; remaining seams go into review. Perform semantic deduplication using both models and the original audio; do not directly concatenate window transcripts as the final draft. See references/local-testing.md for operation details. The first comparison uses the no-prompt baseline. For missed segments, duplicates, or suspicious extra content, re-test using short clips of the original audio; do not rely on a single model for correctness.
3. Calibrate first, then split sentences. The assistant compares the raw outputs from both models, adjacent context, and local terminology resources, corrects proper nouns and homophone candidates according to references/editorial-rules.md, and generates a working draft in simplified written Chinese with punctuation retained. Preserve conditions, negations, numbers, speculations, and stances. Language inference only generates candidates; it does not equal listening or external verification.
4. Split into single-line semantic units based on canvas aspect ratio. No longer require a full sentence to occupy one subtitle line. Allow rewriting long sentences into consecutive, natural semantic short phrases, where each line conveys a clear, small idea. Do not hard-cut by a fixed character count, do not split brand/model names, personal names, fixed terms, numbers and units, and do not produce isolated connectors or incomplete subject-predicate/verb-object structures. Strive to stay within the recommended length for the canvas; do not pad content for short answers. Do not drop conditions, numbers, or change the stance just to shorten. When the length limit is exceeded, rewrite or re-split; do not use line breaks or truncation.
5. Handle multiple speakers separately. Do not combine questions and answers from different people into one sentence or one line; do not use two-line dialogues on the same screen to avoid short subtitles. Short responses use the actual speech interval; display time can be appropriately extended during silence gaps, but must not overflow into the next speaker. Without speaker diarization, do not fabricate speaker identities based solely on text; ambiguous turns or overlapping voices go into review, without guaranteeing that speaker confusion has been resolved.
6. Match each semantic unit to its timing. Use the start and end points of the corresponding original word/phrase, preserving source mapping and media offset. Newly split short sentences must be re-aligned with the audio; do not distribute old long sentence times evenly by character count. Only use the original Cantonese transcription for forced alignment; do not align rewritten Mandarin text against Cantonese pronunciation. If alignment fails, re-listen/re-align; do not fabricate precise timestamps.
7. Final cleanup of punctuation and export. After sentence splitting and timing are finalized, the exporter cleans up punctuation (periods, commas, etc.), merges extra spaces, and converts to simplified Chinese, while protecting necessary symbols. After cleanup, verify single-line, width, speed, overlap, and out-of-bounds conditions. The subtitle JSON includes media_duration, subtitle_profile, cues, and optionally protected_terms; schema and invocation details are in the canvas aspect ratio description. scripts/export_srt.py rejects export upon encountering line breaks, excessive width, or obvious Cantonese remnants; the semantics/timing must be corrected and retried, without bypassing the check.
8. Preview and acceptance. When configuring final video font, font size, and safe zone, prioritize measuring font width. If relying solely on Chinese character width estimation, explicitly note its limitations. SRT cannot reliably carry canvas or style information; video editing software may still auto-wrap; must match the same subtitle preset and preview within the final canvas. Report verified synchronization only when actual back-listening/playback has occurred; structural checks alone do not constitute accuracy or A/V sync qualification.

Delivery

• <MaterialName>_landscape.srt / <MaterialName>_portrait.srt; for unresolved proper nouns, content, turn order, or timing doubts, flag as .review.srt to indicate a review draft.
• Maintain an independent list of doubts, recording the time position, original recognition, candidate, basis, and unresolved reason for each; do not embed explanations into the final subtitle body.
• Record the source of the final video preset: actual detection, user specification, or merely a canvas option; do not equate the source video dimensions with the final canvas dimensions.
• Testing preserves raw results from each model and consolidated calibration records, distinguishing between recognition, rewriting, sentence splitting, and timing issues. Do not present the consolidated calibration draft as the independent accuracy of a single model; do not report accuracy figures unsupported by a manual reference transcript.