pysubs2 CLI is a practical tool for subtitle retiming, ASS-to-SRT conversion, WebVTT export and batch text-event processing. It helps localization teams fix a known constant offset or convert already reviewed captions for a particular platform. It does not translate dialogue, infer the right edit or preserve every advanced style automatically, so a reliable workflow still requires editorial review and playback testing.
This detailed pysubs2 tutorial covers –shift, –shift-back, –transform-framerate, multilingual Unicode encoding, format conversion, drift diagnosis and subtitle QA. Readers looking for ways to move SRT subtitles by 300 milliseconds, convert ASS without unexpected style loss, or check why captions drift after a frame-rate change will find tested command patterns and a decision-based release process.
- Identify approved source text, target locale and the exact picture edit.
- Read the installed tool’s help and preserve the original source file.
- Choose a fixed offset only when several timeline landmarks support it.
- Treat format, encoding, language and accessibility as separate dimensions.
- Inspect cue counts, special characters, visual rendering and output folders.
- Require a human-reviewed language and timing sign-off.
Five commands to learn first
Install pysubs2 in a controlled Python environment and try one short, approved subtitle file before processing any large collection. Shell paths, wildcards and installation commands vary among systems. The upstream CLI documentation and the help output of the installed release are the final references for option support.
pysubs2 --help pysubs2 --to srt sample.ass pysubs2 --to srt --clean sample.ass pysubs2 --shift 0.3s sample.srt pysubs2 --shift-back 0.3s sample.srt pysubs2 --transform-framerate 25 23.976 sample.srt python -m pysubs2 --to vtt sample.srt
Do not stack transformations merely because they are available. A constant 0.3-second error calls for a known offset; a progressive problem requires diagnosis; a new picture edit may require a manual subtitle conform. Technical operation and linguistic acceptance remain separate even when the file format is correct.
Choose the right tool for the right task
Use these cases to connect a tool capability with evidence, an ordinary failure mode and a decision a qualified reviewer can verify. That is more dependable than treating every successful file export as a completed subtitle translation.
What pysubs2 does
pysubs2 is a Python library and CLI for manipulating text-based subtitle events, including conversion and retiming. It does not translate dialogue, provide guaranteed speech recognition or prove that a subtitle is understandable.
Worked failure: A translator exports English captions from a French-language original and assumes conversion has translated them. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Preserve the approved target-language text and check the source separately. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
At this stage, the question for an editor is what the viewer will see and when, rather than whether the command returned successfully. Keep one verified source cue in sight so an unexpected text or timing difference can be investigated before it spreads to an entire language batch.
Choose CLI or Python API
Use the CLI for common, well-defined operations and the library API for custom event checks. A short command is easier to audit than bespoke code when all you need is a fixed shift or format conversion.
Worked failure: A producer wants to inspect every cue for overlong text, which the simple conversion command does not decide. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Use a tested Python script only when the project has clear rules not already served by the CLI. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
Think of the change as an experiment with a predicted result. Name the property that should change, the properties that must not change, and the evidence that would disprove the proposed fix. This makes the operation easier to teach and safer to repeat.
Recognise ASS capabilities
SSA and ASS can express styles, positioning, karaoke and event information beyond the simpler SRT format. Converting an ASS file to SRT does not guarantee equivalent visual presentation, even when words and timestamps survive.
Worked failure: A music subtitle loses its coloured syllable highlighting after export. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Check essential styling against the intended playback platform before accepting the output. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
A simple handoff note should include the asset identifier, installed version, exact operation and reviewed cue. Where the file is destined for a public audience, add the target player and the responsible language reviewer. It is difficult to audit a correction without these details.
Keep editor and translator responsibilities distinct
A subtitle engineer can repair timing without being qualified to interpret a legal term or cultural joke. Likewise, a bilingual editor may validate wording while needing technical help with encoding and delivery formats.
Worked failure: A proper name is changed during a styling cleanup and nobody notices. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Give language and technical sign-off to accountable reviewers. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
Production files can be technically valid and editorially wrong. Timing, translated meaning, accessible descriptions and actual rendering require distinct checks. A defect in any one can undermine the experience even if the others appear normal.
Recognise unsupported semantics
Some complex broadcast timed-text profiles have features outside a lightweight conversion library’s scope. If the receiving platform requires regions, accessibility semantics or advanced layout, a valid-looking converted file may still be unsuitable.
Worked failure: An IMSC delivery requires region settings that are not represented in a simplified SRT. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Use destination-specific validators instead of claiming full standards compliance. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
A useful practice method is to predict one cue’s start, end, text and visual form before running the conversion. Compare that prediction with the result and then review a cue much later in the timeline. Two distant checks often reveal assumptions one example cannot.
Prepare a repeatable working environment
Use these cases to connect a tool capability with evidence, an ordinary failure mode and a decision a qualified reviewer can verify. That is more dependable than treating every successful file export as a completed subtitle translation.
Install the right Python package
An executable may be installed in a different Python environment from the one used by the batch runner. Verify the tool and its version before processing production assets.
Worked failure: pysubs2 runs on one workstation but a CI runner reports command not found. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Record the environment and test pysubs2 –help or python -m pysubs2. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
When a transformation produces an unexplained change, keep it visible as an exception rather than rationalising it away. A known limitation can be reviewed and resolved; a silent loss of information is more likely to reach a viewer unnoticed.
Verify CLI flag availability
The documented CLI offers options including –to, –shift, –shift-back and –transform-framerate, but releases can differ. Confirm option spellings on the actual installation.
Worked failure: An old blog’s example contains an option unsupported by the installed release. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Use built-in help as the authority and pin the known-working version. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
At this stage, the question for an editor is what the viewer will see and when, rather than whether the command returned successfully. Keep one verified source cue in sight so an unexpected text or timing difference can be investigated before it spreads to an entire language batch.
Work from a multilingual test file
A fixture with Latin accents, Japanese or Arabic text, several events and one long cue can reveal encoding and line-break issues before a large batch is touched.
Worked failure: The sample tests only ASCII and misses corruption of Vietnamese diacritics. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Include target-language characters and atypical punctuation in test assets. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
Think of the change as an experiment with a predicted result. Name the property that should change, the properties that must not change, and the evidence that would disprove the proposed fix. This makes the operation easier to teach and safer to repeat.
Avoid source overwrite
Retiming and conversion should create versioned working files separate from approved source captions. A successful command cannot recover a master overwritten by an accidental filename collision.
Worked failure: A batch job writes corrected.srt over the editorially approved source. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Use separate input, output and approved directories with clear names. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
A simple handoff note should include the asset identifier, installed version, exact operation and reviewed cue. Where the file is destined for a public audience, add the target player and the responsible language reviewer. It is difficult to audit a correction without these details.
Understand shell quoting
Examples that use *.srt assume shell expansion rules that vary by operating system. Paths with spaces and non-Latin characters need careful quoting and enumeration.
Worked failure: A batch processes most files but overlooks lesson final review.srt. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Test explicit paths, reconcile file counts and inspect failures. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
Production files can be technically valid and editorially wrong. Timing, translated meaning, accessible descriptions and actual rendering require distinct checks. A defect in any one can undermine the experience even if the others appear normal.
Identify the exact video edit
Subtitle timestamps relate to a particular edition of picture and sound. An added intro or deleted passage can invalidate the source even when file durations look similar.
Worked failure: A version with a new title card delays all the speech by five seconds. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Document the picture master identity before choosing a timing adjustment. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
A useful practice method is to predict one cue’s start, end, text and visual form before running the conversion. Compare that prediction with the result and then review a cue much later in the timeline. Two distant checks often reveal assumptions one example cannot.
Convert text formats with care
Use these cases to connect a tool capability with evidence, an ordinary failure mode and a decision a qualified reviewer can verify. That is more dependable than treating every successful file export as a completed subtitle translation.
Export ASS to SRT
The command pysubs2 –to srt sample.ass makes a text subtitle edition suitable for workflows that accept SRT. It cannot preserve all ASS styling, and any stripped formatting must be reviewed.
Worked failure: A line positioned above a speaker returns to the bottom of the picture. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Compare critical frames and approve the destination layout. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
When a transformation produces an unexplained change, keep it visible as an exception rather than rationalising it away. A known limitation can be reviewed and resolved; a silent loss of information is more likely to reach a viewer unnoticed.
Use clean conversion deliberately
The –clean option can remove additional markup and special event types. Simplification may be desirable for plain captions but can erase important presentation information.
Worked failure: Karaoke cues become ordinary text and lose the intended progressive highlighting. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Review what was removed before labelling the file production-ready. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
At this stage, the question for an editor is what the viewer will see and when, rather than whether the command returned successfully. Keep one verified source cue in sight so an unexpected text or timing difference can be investigated before it spreads to an entire language batch.
Export WebVTT to a browser workflow
pysubs2 –to vtt sample.srt is a useful starting point, but a browser might render cues differently from a desktop subtitle editor. The extension itself cannot certify platform compatibility.
Worked failure: A converted caption wraps awkwardly in a video player. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Inspect actual WebVTT behaviour in the destination browser. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
Think of the change as an experiment with a predicted result. Name the property that should change, the properties that must not change, and the evidence that would disprove the proposed fix. This makes the operation easier to teach and safer to repeat.
Check actual file content
An extension is a hint, not an assurance that the file contains the intended format. Misnamed or malformed subtitle files should be investigated before forcing conversions.
Worked failure: A supplier renamed a WebVTT file to .srt without changing its contents. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Look at the header and timecode syntax and use explicit format options only when justified. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
A simple handoff note should include the asset identifier, installed version, exact operation and reviewed cue. Where the file is destined for a public audience, add the target player and the responsible language reviewer. It is difficult to audit a correction without these details.
Treat MicroDVD as frame-based
Older frame-number subtitle formats depend on an accurate frame-rate interpretation. The wrong input FPS produces timing defects throughout the file, even if wording remains unchanged.
Worked failure: An old MicroDVD asset was created for 25 fps but handled as another rate. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Determine original timebase before converting. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
Production files can be technically valid and editorially wrong. Timing, translated meaning, accessible descriptions and actual rendering require distinct checks. A defect in any one can undermine the experience even if the others appear normal.
Compare meaning, not just byte counts
A byte diff may flag harmless line-ending changes while missing a semantically serious word substitution. A subtitle needs both structural and editorial comparison.
Worked failure: The text length stays constant after a negation is replaced. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Review high-impact wording and actual cue events against the approved source. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
A useful practice method is to predict one cue’s start, end, text and visual form before running the conversion. Compare that prediction with the result and then review a cue much later in the timeline. Two distant checks often reveal assumptions one example cannot.
Repair timing with a diagnosis
Use these cases to connect a tool capability with evidence, an ordinary failure mode and a decision a qualified reviewer can verify. That is more dependable than treating every successful file export as a completed subtitle translation.
Positive shift moves cues later
The documented form pysubs2 –shift 0.3s sample.srt moves events forward. It is appropriate when a verified constant delay is needed, not when the subtitle is already late.
Worked failure: A caption appears at 11.7 seconds while speech begins at twelve seconds. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Test the first, middle and last cues before applying a fixed offset. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
When a transformation produces an unexplained change, keep it visible as an exception rather than rationalising it away. A known limitation can be reviewed and resolved; a silent loss of information is more likely to reach a viewer unnoticed.
Backward shift moves cues earlier
The documented –shift-back option moves events back, but cues near zero may need special treatment. A few milliseconds can matter at the first picture frame.
Worked failure: The first cue starts at 0.1 seconds and would shift before time zero. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Inspect opening captions, preserve dialogue and avoid silently losing events. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
At this stage, the question for an editor is what the viewer will see and when, rather than whether the command returned successfully. Keep one verified source cue in sight so an unexpected text or timing difference can be investigated before it spreads to an entire language batch.
Constant offset differs from drift
When an error stays the same at beginning, middle and end, a fixed shift may correct it. If it grows, a timing scale, changed edit or other cause needs investigation.
Worked failure: Captions align at minute one but are six seconds late by minute forty. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Measure multiple landmarks instead of trusting a single test. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
Think of the change as an experiment with a predicted result. Name the property that should change, the properties that must not change, and the evidence that would disprove the proposed fix. This makes the operation easier to teach and safer to repeat.
Frame-rate transformations need evidence
The command –transform-framerate 25 23.976 scales timings for a particular rate relationship. Modern conversions sometimes preserve running time despite a frame-rate change, so this must not be a default repair.
Worked failure: A producer applies frame-rate scaling solely because the metadata says 23.976. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Verify the original transfer method and reference timestamps. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
A simple handoff note should include the asset identifier, installed version, exact operation and reviewed cue. Where the file is destined for a public audience, add the target player and the responsible language reviewer. It is difficult to audit a correction without these details.
Inserted scenes are not a global timing problem
An editorial cut can remove dialogue or rearrange scenes, making a single offset or scale insufficient. Subtitles must be conformed to the new narrative order.
Worked failure: A trimmed interview leaves captions for speech that is no longer present. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Re-edit the affected events and review the complete picture. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
Production files can be technically valid and editorially wrong. Timing, translated meaning, accessible descriptions and actual rendering require distinct checks. A defect in any one can undermine the experience even if the others appear normal.
Check cue boundaries and overlaps
Cues that end before they start or overlap unintentionally may disappear or flicker. Some simultaneous captions are intentional, so blanket deletion is not safe.
Worked failure: An automated cleanup removes a legitimate second speaker’s cue. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Review event order, timing and accessibility meaning before changing overlaps. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
A useful practice method is to predict one cue’s start, end, text and visual form before running the conversion. Compare that prediction with the result and then review a cue much later in the timeline. Two distant checks often reveal assumptions one example cannot.
Review the final cue
A conversion can appear successful when the opening is aligned but the ending is truncated or extends past the video. A last-cue check is a quick way to catch timeline errors.
Worked failure: The final line remains visible after the credits end. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Compare the approved programme duration and final dialogue timestamp. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
When a transformation produces an unexplained change, keep it visible as an exception rather than rationalising it away. A known limitation can be reviewed and resolved; a silent loss of information is more likely to reach a viewer unnoticed.
Protect written language through conversion
Use these cases to connect a tool capability with evidence, an ordinary failure mode and a decision a qualified reviewer can verify. That is more dependable than treating every successful file export as a completed subtitle translation.
Use UTF-8 correctly
UTF-8 is a sensible baseline for multilingual text, but legacy assets may use another encoding. Wrongly decoded bytes can generate valid-looking files with broken characters.
Worked failure: French accents turn into replacement glyphs even though the command reports success. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Find the original encoding and reimport from the uncorrupted source. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
At this stage, the question for an editor is what the viewer will see and when, rather than whether the command returned successfully. Keep one verified source cue in sight so an unexpected text or timing difference can be investigated before it spreads to an entire language batch.
Separate input and output encodings
The input-encoding setting controls how existing bytes become characters, whereas output-encoding sets the new representation. Changing only the output cannot repair already misread characters.
Worked failure: A legacy Japanese subtitle is first opened with the wrong decoder. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Set the actual source encoding and inspect the export as rendered text. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
Think of the change as an experiment with a predicted result. Name the property that should change, the properties that must not change, and the evidence that would disprove the proposed fix. This makes the operation easier to teach and safer to repeat.
Unicode does not guarantee font support
Valid Korean, Arabic or Indic text may display as blank boxes or poorly shaped characters on a target player. Caption correctness and font coverage are distinct requirements.
Worked failure: Arabic cues are correct in an editor but disconnect on a television. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Test the target playback stack and fonts. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
A simple handoff note should include the asset identifier, installed version, exact operation and reviewed cue. Where the file is destined for a public audience, add the target player and the responsible language reviewer. It is difficult to audit a correction without these details.
Right-to-left mixing is delicate
Arabic or Hebrew captions containing Latin names, parentheses and numbers may reorder visually. Text transformation cannot guarantee the rendered direction and punctuation will remain natural.
Worked failure: A flight number appears on the wrong side of an Arabic sentence. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Review actual rendered bilingual lines. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
Production files can be technically valid and editorially wrong. Timing, translated meaning, accessible descriptions and actual rendering require distinct checks. A defect in any one can undermine the experience even if the others appear normal.
Preserve punctuation and negation
Small tokens can change the meaning of warnings or commands. An automatic cleaning step must not become an excuse to remove words whose linguistic role is essential.
Worked failure: Do not cross is accidentally turned into Do cross. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Require content comparison for instructions, numbers and qualifying phrases. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
A useful practice method is to predict one cue’s start, end, text and visual form before running the conversion. Compare that prediction with the result and then review a cue much later in the timeline. Two distant checks often reveal assumptions one example cannot.
Distinguish duplicate languages by role
An English full-subtitle file and an English deaf-and-hard-of-hearing caption file are distinct products, even if both use the same language code. A workflow that deduplicates only by language can destroy accessibility coverage.
Worked failure: A batch removes the second English file as a supposed duplicate. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Use language, target locale and caption purpose as separate manifest fields. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
When a transformation produces an unexplained change, keep it visible as an exception rather than rationalising it away. A known limitation can be reviewed and resolved; a silent loss of information is more likely to reach a viewer unnoticed.
Build a safe batch and release QA
Use these cases to connect a tool capability with evidence, an ordinary failure mode and a decision a qualified reviewer can verify. That is more dependable than treating every successful file export as a completed subtitle translation.
Count every expected input and output
Wildcard batches can miss files or write multiple formats to unexpected directories. Reconcile input manifests and actual outputs rather than trusting the number of successful log lines.
Worked failure: Twenty-four language assets were expected but only twenty-three were generated. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Stop release until every missing or rejected file is explained. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
At this stage, the question for an editor is what the viewer will see and when, rather than whether the command returned successfully. Keep one verified source cue in sight so an unexpected text or timing difference can be investigated before it spreads to an entire language batch.
Capture errors and exit status
One malformed subtitle can fail while other files still appear in an output folder. Scripts should check command failures and preserve error messages for investigation.
Worked failure: A deployment proceeds simply because the output directory is nonempty. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Fail on missing expected assets and review the error details. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
Think of the change as an experiment with a predicted result. Name the property that should change, the properties that must not change, and the evidence that would disprove the proposed fix. This makes the operation easier to teach and safer to repeat.
Separate stage outputs
When encoding changes, timing adjustments and format conversion happen together, a defect becomes difficult to locate. Explicit stages with checked intermediates make the cause visible.
Worked failure: A batch yields garbled accents and changed cue order. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Find the first stage where a known-good test failed. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
A simple handoff note should include the asset identifier, installed version, exact operation and reviewed cue. Where the file is destined for a public audience, add the target player and the responsible language reviewer. It is difficult to audit a correction without these details.
Test a no-op round trip
Reading and exporting a subtitle without intentional edits can reveal parser differences. Not every byte change matters, but missing events or altered dialogue are serious.
Worked failure: An ASS file loses a nonstandard event during re-export. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Compare parsed event counts, text and rendered examples. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
Production files can be technically valid and editorially wrong. Timing, translated meaning, accessible descriptions and actual rendering require distinct checks. A defect in any one can undermine the experience even if the others appear normal.
Automate warnings rather than deleting cues
Custom Python checks can flag excessive line length, unlikely duration or overlap, but human judgment is needed to decide whether the cue violates a platform’s rules.
Worked failure: A script deletes every caption shorter than a threshold. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Report exceptions for review instead of silently discarding them. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
A useful practice method is to predict one cue’s start, end, text and visual form before running the conversion. Compare that prediction with the result and then review a cue much later in the timeline. Two distant checks often reveal assumptions one example cannot.
Check viewer readability
A subtitle can be syntactically valid but unreadable because of dense text, bad breaks or cropping. The final release should be assessed on intended devices and viewing sizes.
Worked failure: A long SRT line wraps into four mobile lines and hides a speaker label. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Test real playback and approve line-break changes with a language reviewer. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
When a transformation produces an unexplained change, keep it visible as an exception rather than rationalising it away. A known limitation can be reviewed and resolved; a silent loss of information is more likely to reach a viewer unnoticed.
Keep a reversible manifest
A release record should identify input file, operation, output file, target language, translator, technical reviewer and final acceptance. This provides a traceable path for later corrections and avoids ‘final-final’ naming confusion.
Worked failure: A distributor asks which of several retimed files is authoritative. Check the corresponding media or source subtitle before attributing the problem to a converter.
Practical response: Document exact source and reviewed destination IDs. Preserve the source and review the result at more than one point in the timeline, including important lines whose meaning must not change.
At this stage, the question for an editor is what the viewer will see and when, rather than whether the command returned successfully. Keep one verified source cue in sight so an unexpected text or timing difference can be investigated before it spreads to an entire language batch.
Worked example: a documentary SRT and WebVTT release
A 24-minute documentary has approved English subtitles that appear 0.3 seconds early against its final soundtrack. The subtitle editor checks an opening cue, a cue near minute twelve and the last substantive cue. If all three show the same error, a global forward shift is justified. If the deviation changes through the programme, the editor investigates a timebase problem or an altered cut rather than changing every cue by the same amount.
The editor creates a retimed working copy, checks the first and last cues for valid boundaries, then exports the reviewed content into separate SRT and WebVTT deliverables. Another reviewer inspects proper names, negations, accented words, speaker changes and any formatting that changed through conversion. Each format is then opened in its intended player, because success in a text editor does not establish comfortable display.
Finally, the release manifest links each output to the same authorised source and explicitly notes the conversion command, file identity, locale, reviewer and exceptions. If a version is intended for viewers who are deaf or hard of hearing, the team also checks that meaningful sound cues have not been removed. A clean technical transformation is useful only when the resulting experience is still faithful to the approved content.
Release-ready verification checklist
- The exact approved subtitle and media versions are identified.
- The reason for shifting or transforming timecodes has been established.
- Text, punctuation, accents, scripts and accessibility content have been preserved or deliberately revised.
- Cue counts, timing boundaries and sample frames have been compared.
- All expected language files exist in separate destination folders.
- The intended player renders the reviewed subtitle acceptably.
- A responsible language and technical reviewer approves the final edition.
Frequently asked questions
Does pysubs2 translate languages?
No. It manipulates subtitle events and file formats; translated text still needs a proper translation and review.
How do I make subtitles 300 milliseconds later?
Use a documented command such as pysubs2 –shift 0.3s sample.srt, then verify cue positions.
How can I convert ASS to SRT?
The CLI supports pysubs2 –to srt sample.ass, but not all ASS styles can be represented in SRT.
What is –clean for?
It can discard extra formatting and special event content. Review potential loss before accepting the result.
Can one shift fix gradually growing drift?
No. A fixed offset cannot correct a scaling error or edited timeline. Diagnose the source first.
When should I use –transform-framerate?
Only when reference evidence shows the subtitles require a frame-rate-related timing transformation.
Why did accented text become corrupted?
A wrong original character encoding or unsupported rendering font may be responsible. Check both decoding and playback.
Will right-to-left characters display correctly?
Not necessarily. Test bidirectional text, punctuation and fonts in the target player.
Can I use wildcards for batches?
Yes in supported shells and workflows, but verify input enumeration, quoting, output count and errors.
Does successful conversion prove subtitle quality?
No. Human reviewers still need to check accuracy, timing, accessibility and display.
Upstream references and further reading
See the official pysubs2 CLI documentation and the pysubs2 project repository. The earlier Subtitle Edit seconv article describes a different command-line tool, while the FFmpeg and ffprobe guide covers source media inspection.
A strong subtitle release process gives automation the predictable file operations and gives people the judgments about language, time, meaning and audience. Keep those roles distinct, and every converted subtitle has a better chance of being both technically usable and genuinely helpful.