README

A PHP library and command line tool that reads, edits and writes subtitles, transcripts and chapter lists in more than 30 formats.

Upgrading from 2.x? The package has a new name. See the upgrade guide.

Upgrading from 3.x? See the 4.0 upgrade guide.

Install

composer require yama6a/subtitle-toolbox-php
# Optional, for OCR of PGS, VobSub and DVB image subtitles:
composer require yama6a/php-glyph-ocr:^0.3   # php-glyph-ocr, the pure PHP OCR engine
apt install tesseract-ocr                    # or Tesseract on Debian and Ubuntu, for more than 100 languages

The core package needs neither OCR engine. See ocr.md for the install commands of other systems and languages.

The library needs PHP 8.2 or later with ext-dom, ext-iconv and ext-mbstring. These extensions are optional:

ext-zlib for PGS output and compressed MKV tracks
ext-curl for the translation engines

The command line tool also comes as a PHAR file and as two container images. The -tesseract image includes Tesseract for OCR. See Install without Composer for the commands.

Supported formats

Case is the case of the enum Format, for example Format::SubRip. Name is the format name for --from and --to. An image cue holds a bitmap in place of text.

Text subtitles

Format	Case	Name	Extensions	Read	Write	Notes
ASS, SSA	`Ass`	`ass`	`.ass`, `.ssa`	✅	✅
Cavena 890	`Cavena890`	`cavena890`	`.890`	✅	✅	binary, no public spec, not detected from the content
CSV, TSV	`Csv`, `Tsv`	`csv`, `tsv`	`.csv`, `.tsv`	✅	✅	not detected from the content
DCP subtitles: SMPTE ST 428-7, Interop	`Dcp`	`dcp`	`.xml`	✅	✅	digital cinema text subtitles
EBU STL	`EbuStl`	`stl`	`.stl`	✅	✅	binary, 25 or 30 fps
iTunes Timed Text	`Itt`	`itt`	`.itt`	✅	✅	needs a frame rate to write
JSON of this library	`Json`	`json`	`.json`	✅	✅
LRC	`Lyrics`	`lrc`	`.lrc`	✅	✅	with enhanced LRC word times
MCC	`Mcc`	`mcc`	`.mcc`	✅	✅	CEA-608 and CEA-708 closed captions of MacCaption and CaptionMaker
MicroDVD	`MicroDvd`	`microdvd`	`.sub`	✅	✅	needs the frame rate of the video
MPL2	`Mpl2`	`mpl2`	`.txt`	✅	✅
MPSub	`MpSub`	`mpsub`	`.mpsub`	✅	✅
PAC by Screen Electronics, PAC Unicode	`Pac`	`pac`	`.pac`, `.fpc`	✅	✅	binary, no public spec, code page detected
QuickTime text	`QuickTimeText`	`qttext`	`.txt`	✅	✅	`{QTtext}` text tracks of QuickTime
SAMI	`Sami`	`sami`	`.smi`, `.sami`	✅	✅	one language class per parse
SBV	`Sbv`	`sbv`	`.sbv`	✅	✅
SCC	`Scc`	`scc`	`.scc`	✅	✅	CEA-608 closed captions
Spruce STL	`SpruceStl`	`spruce-stl`	`.stl`	✅	✅	DVD Studio Pro text subtitles
SubRip	`SubRip`	`srt`	`.srt`	✅	✅
SubViewer 1 and 2	`SubViewer`	`subviewer`	`.sub`	✅	✅
TMPlayer	`TmPlayer`	`tmplayer`	`.txt`	✅	✅
TTML, IMSC, DFXP	`Ttml`	`ttml`	`.ttml`, `.dfxp`, `.xml`	✅	✅
WebVTT	`WebVtt`	`vtt`	`.vtt`	✅	✅	also chapters
YouTube timed text	`YouTubeTimedText`	`youtube`	`.srv3`, `.json3`, `.srv1`, `.ytt`	✅	✅	json3, srv1, srv2, srv3 and transcript XML

Image subtitles

Format	Case	Name	Extensions	Read	Write	Notes
PGS	`Pgs`	`pgs`	`.sup`	✅	✅	Blu-ray bitmaps as image cues
VobSub	`VobSub`	`vobsub`	`.idx` with `.sub`	✅	❌	DVD bitmaps as image cues

Transcripts

Format	Case	Name	Extensions	Read	Write	Notes
Cloud speech-to-text JSON: AWS Transcribe, Deepgram, AssemblyAI, Google Speech-to-Text	`AwsTranscribe`, `Deepgram`, `AssemblyAi`, `GoogleSpeech`	`aws-transcribe`, `deepgram`, `assemblyai`, `google-speech`	`.json`	✅	✅	not detected from the content
HTML transcript	`HtmlTranscript`	`html`	`.html`, `.htm`	✅	✅	the Podcasting 2.0 HTML format
Plain text	`PlainText`	`txt`	`.txt`	❌	✅	transcript
Podcasting 2.0 transcript JSON	`PodcastTranscript`	`podcast-transcript`	`.json`	✅	✅
Whisper JSON	`Whisper`	`whisper`	`.json`	✅	✅	OpenAI API, openai-whisper, faster-whisper, WhisperX, whisper.cpp

Chapters

Format	Case	Name	Extensions	Read	Write	Notes
FFmpeg metadata chapters	`FfMetadataChapters`	`ffmeta-chapters`	`.ffmeta`	✅	✅	not detected from the content
OGM chapters	`OgmChapters`	`ogm-chapters`	`.txt`	✅	✅	not detected from the content
Podcasting 2.0 chapters	`PodcastChapters`	`podcast-chapters`	`.json`	✅	✅	not detected from the content
YouTube chapters	`YouTubeChapters`	`youtube-chapters`	`.txt`	✅	✅	not detected from the content

Containers

Format	Extensions	Read	Write	Notes
MKV and WebM tracks	`.mkv`, `.webm`	✅	❌	text, ASS, SSA, WebVTT, PGS, VobSub and DVB subtitle tracks
MP4 tracks	`.mp4`, `.m4v`, `.mov`	✅	❌	`tx3g` (`mov_text`) tracks, `c608` and `c708` closed caption tracks
MPEG-TS ARIB captions	`.ts`, `.m2ts`	✅	❌	Japanese ISDB and Brazilian ISDB-Tb captions with furigana and gaiji
MPEG-TS DVB subtitles	`.ts`	✅	❌	DVB bitmap subtitles as image cues
MPEG-TS teletext	`.ts`	✅	❌	DVB teletext subtitle pages, see ETS 300 706

Command line tool

Composer installs vendor/bin/stbox. Optional parts are in brackets.

stbox convert movie.srt --to vtt [--timing-fix-overlaps] [-o movie.vtt]
stbox convert movie.mkv --to srt --track 3 [-o movie.srt]
stbox convert movie.sup --to srt --ocr [--ocr-language deu] [-o movie.srt]
stbox convert movie.sub --input-fps 25 --from-fps 25 --to-fps 23.976 [-o movie.fixed.sub]
stbox info movie.srt [--json]
stbox validate movie.srt --preset netflix-en [--video-fps 23.976]
stbox sync movie.de.srt --reference movie.en.srt [-o movie.de.synced.srt]
stbox diff movie.v1.srt movie.v2.srt [--text-only]
stbox translate movie.de.srt --engine deepl --target-language en-US [-o movie.en.srt]
stbox dual --primary movie.en.srt --secondary movie.de.srt --to ass [--mode stack] [-o movie.en-de.ass]
stbox hls movie.vtt --output-dir hls/ [--segment 6]
stbox formats

Without -o, the output goes to standard output.
Several inputs need --output-dir, for example convert season1/ --shift 2 --output-dir fixed/.
No command overwrites a file.
When detection fails, pass --from.

stbox convert --help lists the option groups of convert. See cli.md for all commands and options.

Library

Load and write

use SubtitleToolbox\Format;
use SubtitleToolbox\LineEnding;
use SubtitleToolbox\Subtitle;
use SubtitleToolbox\WriteOptions;

$subtitle = Subtitle::load('movie.srt', Format::SubRip);
$subtitle = Subtitle::load('movie.srt');
$subtitle->findFormat();                           // Format::SubRip
$subtitle->save('movie.vtt');                     // the format comes from the extension
$vtt = $subtitle->toString(Format::WebVtt, new WriteOptions(lineEnding: LineEnding::Crlf, stripTags: true));

Read options

use SubtitleToolbox\Format;
use SubtitleToolbox\Parsers\Options\MicroDvdReadOptions;
use SubtitleToolbox\ReadOptions;
use SubtitleToolbox\Subtitle;

$latin1   = Subtitle::load('latin1.srt', Format::SubRip, new ReadOptions(encoding: 'Windows-1252'));
$microDvd = Subtitle::load('movie.sub', Format::MicroDvd, new ReadOptions(formats: [new MicroDvdReadOptions(frameRate: 23.976)]));

See read-options.md for the options of each format.

Edit

use SubtitleToolbox\CaseMode;
use SubtitleToolbox\Format;
use SubtitleToolbox\HearingImpaired\HearingImpairedOptions;
use SubtitleToolbox\HearingImpaired\HearingImpairedRemover;
use SubtitleToolbox\Subtitle;

$subtitle = Subtitle::load('movie.srt', Format::SubRip);
$subtitle->shift(-2.5)                            // all cues 2.5 s earlier
         ->convertFrameRate(25, 23.976)
         ->fixOverlaps(0.083)                     // a gap of at least 0.083 s between cues
         ->wrapLines(42)                          // at most 42 characters per line, 2 lines
         ->changeCase(CaseMode::Sentence);
$firstMinute = $subtitle->withSlice(0, 60);       // a new Subtitle, $subtitle stays as it is

$report = HearingImpairedRemover::apply($subtitle, new HearingImpairedOptions(parentheses: false));
echo "$report->removedLines lines removed\n";

A service such as HearingImpairedRemover changes the subtitle in place and returns a report.

Validate and count

use SubtitleToolbox\Format;
use SubtitleToolbox\Subtitle;
use SubtitleToolbox\SubtitleStatistics;
use SubtitleToolbox\Validation\ValidationRules;

$subtitle = Subtitle::load('movie.srt', Format::SubRip);
foreach ($subtitle->validate(ValidationRules::netflixEnglish(23.976)) as $violation) {
    echo "cue index $violation->cueIndex: {$violation->rule->value} is $violation->value\n";
}
$stats = SubtitleStatistics::of($subtitle);
echo "$stats->cueCount cues, $stats->wordCount words\n";

MKV and WebM tracks

use SubtitleToolbox\Subtitle;

foreach (Subtitle::tracks('movie.mkv') as $track) {
    echo "$track->number: $track->codecId, $track->language, $track->name\n";   // 3: S_TEXT/UTF8, de, Deutsch (Forced)
}
$subtitle = Subtitle::loadTrack('movie.mkv', 3);
$subtitle = Subtitle::loadTrack('recording.ts', 777);                          // teletext page 777 of a DVB recording
$subtitle = Subtitle::loadTrack('recording.ts', 2050);                         // DVB bitmap subtitles with PID 2050, as image cues

OCR

use SubtitleToolbox\Format;
use SubtitleToolbox\Ocr\OcrEngineChooser;
use SubtitleToolbox\Ocr\OcrEngineName;
use SubtitleToolbox\Subtitle;

$subtitle = Subtitle::load('movie.sup', Format::Pgs);
$subtitle->recognizeText(OcrEngineChooser::create());                       // Tesseract if installed, otherwise php-glyph-ocr
$subtitle->recognizeText(OcrEngineChooser::create(OcrEngineName::Glyph));   // always php-glyph-ocr
$subtitle->save('movie.srt');

create() takes the Tesseract language as its second argument, for example 'deu+eng'. For engine settings, pass TesseractOcrOptions to new TesseractOcrEngine() or GlyphOcrOptions to new GlyphOcrEngine().

Translate

use SubtitleToolbox\Format;
use SubtitleToolbox\Subtitle;
use SubtitleToolbox\Translation\DeepLEngine;
use SubtitleToolbox\Translation\DeepLOptions;
use SubtitleToolbox\Translation\TranslationRunner;

$subtitle = Subtitle::load('movie.de.srt', Format::SubRip);
(new TranslationRunner(new DeepLEngine(new DeepLOptions(apiKey: $apiKey))))->translate($subtitle, 'de', 'en-US');
$subtitle->save('movie.en.srt');

GoogleTranslateEngine works the same way. See translation.md.

Sync to a reference

use SubtitleToolbox\Format;
use SubtitleToolbox\Subtitle;
use SubtitleToolbox\Sync\ReferenceSync;
use SubtitleToolbox\Sync\ReferenceSyncOptions;

$german  = Subtitle::load('movie.de.srt', Format::SubRip);
$english = Subtitle::load('movie.en.srt', Format::SubRip);
$report  = ReferenceSync::apply($german, new ReferenceSyncOptions(reference: $english));
echo "offset $report->offset s, scale $report->scale, score $report->score\n";

Every exception implements SubtitleToolboxException. See errors.md.

OCR

OCR turns the bitmaps of PGS, VobSub and DVB subtitles into text. The library uses Tesseract when it is installed. Otherwise it uses php-glyph-ocr. When neither engine is installed, the call throws InvalidArgumentException that names both engines. Tesseract reads more than 100 languages. php-glyph-ocr reads only Latin-script fonts. See ocr.md for the install commands and a comparison of the engines.

Compatibility

See compatibility.md for the parts that semantic versioning covers and for what a minor or patch release can change.

Documentation

docs/README.md lists every page. The most used pages:

cli.md: all commands and options
formats.md: what each parser reads and each formatter writes
editing.md: retiming, cutting, joining and splitting cues
text.md: text changes, hearing-impaired removal, common error fixes
validation.md: rules and presets
sync.md: sync to a reference or to the speech
subtitle.md: metadata, comments, cue lookup, statistics

Contributing

Pull requests are welcome. See CONTRIBUTING.md for the licence rules and the credit rule. Run the tests with composer test. Each pull request carries one label that sets the version bump: major, minor, patch or skip-release. Every merge to master publishes a release.

License

MIT, see LICENSE. Material from third parties keeps its own licence, see THIRD_PARTY_NOTICES.md.

Credits

The PHP libraries mantas-done/subtitles and captioning/captioning shaped this library. Their formats, test files and user reports guided many decisions here. THIRD_PARTY_NOTICES.md lists every file copied from other projects.

yama6a / subtitle-toolbox-php

Package info

Security

Statistics