PHPackages mantas-done/subtitles - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. mantas-done/subtitles ActiveLibrary[Utility & Helpers](/categories/utility) mantas-done/subtitles ===================== Subtitle converter and generator for PHP v2.0.2(6mo ago)163837.8k—7.4%492MITPHPPHP >=8.3CI passing Since Jan 9Pushed 4mo ago6 watchersCompare [ Source](https://github.com/mantas-done/subtitles)[ Packagist](https://packagist.org/packages/mantas-done/subtitles)[ RSS](/packages/mantas-done-subtitles/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (3)Versions (47)Used By (2) Caption And Subtitle Converter for PHP ====================================== [](#caption-and-subtitle-converter-for-php) [>> live demo <<](https://gotranscript.com/subtitle-converter) 🥳🎉👏 Probably the best subtitle parser 🥳🎉👏 💣 Tested on thousands of user submitted files 🤯 🔥 Almost 100% unit test coverage 💥 Supported formats ----------------- [](#supported-formats) FormatExtensionInternal format name[SubRip](https://en.wikipedia.org/wiki/SubRip#SubRip_text_file_format).srtsrt[WebVTT](https://en.wikipedia.org/wiki/WebVTT).vttvtt[Scenarist](http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/SCC_FORMAT.HTML).sccscc[EBU STL (only reader)](https://tech.ebu.ch/docs/tech/tech3264.pdf).stlebu\_stl[Spruce Technologies SubTitles](https://pastebin.com/ykGM9qjZ).stlstl[Youtube Subtitles](https://webdev-il.blogspot.lt/2010/01/sbv-file-format-for-youtube-subtitles.html).sbvsbv[SubViewer](https://wiki.videolan.org/SubViewer).subsub\_subviewer[MicroDVD](https://en.wikipedia.org/wiki/MicroDVD).subsub\_microdvdAdvanced Sub Station.assass[Netflix Timed Text](https://en.wikipedia.org/wiki/Timed_Text_Markup_Language).dfxpdfxp[TTML](https://en.wikipedia.org/wiki/Timed_Text_Markup_Language).ttmlttml[SAMI](https://en.wikipedia.org/wiki/SAMI).smismiQuickTime.qt.txttxt\_quicktimeRich text format (only reader).rtfrtfDOCX (only reader).docxdocx[LyRiCs](https://en.wikipedia.org/wiki/LRC_(file_format)).lrclrcComma separated values.csvcsvPlaintext.txttxtCommand line ------------ [](#command-line) Can be used from the command line to convert from .srt to .vtt ``` php subtitles.phar input.srt output.vtt ``` subtitles.phar file can be found here - Installation (supports PHP 8.3...8.4) ------------------------------------- [](#installation-supports-php-8384) ``` composer require mantas-done/subtitles ``` Usage ----- [](#usage) Convert .srt file to .vtt: ``` // add namespace use \Done\Subtitles\Subtitles; (new Subtitles())->convert('subtitles.srt', 'subtitles.vtt'); ``` ``` // if no input format is specified, library will determine file format by its content // if third parameter is specified, library will convert the file to specified format. // list of formats are in Subtitle::$formats, they are: ass, dfxp, sbv, srt, stl, sub, ttml, txt_quicktime, vtt (new Subtitles())->convert('subtitles1', 'subtitles2', ['output_format' => 'vtt']); ``` Manually create file ``` $subtitles = new Subtitles(); $subtitles->add(0, 5, 'This text is shown in the beggining of video for 5 seconds'); $subtitles->save('subtitles.vtt'); ``` Load subtitles from existing file ``` $subtitles = (new Subtitles())->loadFromFile('subtitles.srt'); ``` Load subtitles from string ``` $string = " 1 00:02:17,440 --> 00:02:20,375 Senator, we're making our final approach "; $subtitles = (new Subtitles())->loadFromString($string); ``` Save subtitles to file ``` $subtitles->save('subtitler.vtt'); ``` Get file content without saving to file ``` echo $subtitles->content('vtt'); ``` Add subtitles ``` $subtitles->add(0, 5, 'some text'); // from 0, till 5 seconds // Add multiline text $subtitles->add(0, 5, [ 'first line', 'second line', ]); // Add styles to VTT file format // Only VTT supports styles currently $subtitles->add(0, 5, 'text', ['vtt_cue_settings' => 'position:50% line:15% align:middle']); ``` Remove subtitles ``` $subtitles->remove(0, 5); // from 0, till 5 seconds ``` Trim subtitles ``` $subtitles->trim(3, 4); // get only from 3, till 4 seconds ``` Add 1 second to all subtitles ``` $subtitles->shiftTime(1); ``` Subtract 0.5 second ``` $subtitles->shiftTime(-0.5); ``` Add 5 second to subtitles starting from 1 minute till 2 mintes ``` $subtitles->shiftTime(5, 60, 120); ``` Example: shift time gradually by 2 seconds over 1 hour video. At the beginning of the video don't change time, in the middle shift time by 1 second. By the end of video, shift time by 2 seconds. ``` $subtitles->shiftTimeGradually(2, 0, 3600); ``` Exceptions ---------- [](#exceptions) Library will throw UserException, it's message can be shown to the user. ``` try { (new \Done\Subtitles\Subtitles())->add(0, 1, 'very long text... aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')->content('scc'); } catch (\Done\Subtitles\Code\Exceptions\UserException $e) { echo $e->getMessage(); // SCC file can't have more than 4 lines of text each 32 characters long. This text is too long: } ``` By default, library tries to detect different file errors that can be shown to the user, so he would be able to fix them. If you want to relax the rules and allow the library to convert even somewhat invalid files, use \['strict' => false\] ``` (new Subtitles())->convert($input, $output, ['strict' => false]); (new Subtitles())->loadFromString($string, ['strict' => false]); (new Subtitles())->loadFromFile($input, ['strict' => false]); ``` How to add new subtitle format? ------------------------------- [](#how-to-add-new-subtitle-format) You need to implement ConverterContract.php interface. It has two methods. ``` fileContentToInternalFormat($file_content) internalFormatToFileContent($internal_format) ``` Basically what your implementation should be able to do, is convert subtitle file to "internal library's format", and from internal library's format back to subtitle file. "Internal library's" format is used like middle ground, to be able to convert between different formats. Best example is to look how [SrtConverter.php](https://github.com/mantas783/subtitle-converter/blob/master/src/code/Converters/SrtConverter.php) is implemented. And this is example of [.srt file](https://github.com/mantas783/subtitle-converter/blob/master/tests/files/srt.srt). Registering your converter -------------------------- [](#registering-your-converter) ``` (new Subtitles())->registerConverter(FakeDocxConverter::class, 'docx_fake', 'docx', 'Fake docx converter'); ``` You can add a new converter or replace the existing one if the format name is the same (the second parameter). ### "Internal Format" [](#internal-format) "Internal Format" is just a PHP array. It is used internally in library to be able to convert between different formats. ``` Array ( [0] => Array ( [start] => 137.44 [end] => 140.375 [lines] => Array ( [0] => Senator, we're making [1] => our final approach into Coruscant. ) ) [1] => Array ( [start] => 140.476 [end] => 142.501 [lines] => Array ( [0] => Very good, Lieutenant. ) ) ) ``` ``` [start] - when to start showing text (float - seconds) [end] - when to stop showing text (float -seconds) [lines] - one or more text lines (array) ``` Running Tests ------------- [](#running-tests) ``` php vendor/bin/phpunit php vendor/bin/phpstan analyse ``` Contribution ------------ [](#contribution) You can contribute in any way you want. If you need some guidance, choose something from this table: TaskDifficultyDescriptionAdd new formatsMediumSupporting more formats is nice. Some popular formats: .mcc, .capRefactor [StlConverter.php](https://github.com/mantas783/subtitle-converter/blob/master/src/code/Converters/StlConverter.php) fileEasy.stl format is very similar to .srt. The only problem is that StlConverter.php code can be simplified a lot (check [SrtConverter.php](https://github.com/mantas783/subtitle-converter/blob/master/src/code/Converters/SrtConverter.php) as example)Add .scc formatHard[Format description](http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/SCC_FORMAT.HTML)For now library should support only basic features (several lines of text). No need to support different text styles or positioning of text. Report Bugs ----------- [](#report-bugs) If some file is not working with the library, please create and issue and attach the file. ### Health Score 67 — FairBetter than 100% of packages Maintenance73 Regular maintenance activity Popularity57 Moderate usage in the ecosystem Community27 Small or concentrated contributor base Maturity91 Battle-tested with a long release history Bus Factor1 Top contributor holds 88.1% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~84 days Recently: every ~156 days Total 39 Last Release 188d ago Major Versions v0.3.10 → v1.0.02023-06-12 v1.0.22 → v2.0.02025-05-13 PHP version history (4 changes)v1.0.15PHP ^8.1.0 v1.0.17PHP >=7.2 v1.0.21PHP >=7.4 v2.0.0PHP >=8.3 ### Community Maintainers ![](https://www.gravatar.com/avatar/a27dcc57cd92e476d505f5ee315c84efd25fe98fe2d72a5dbd0f17b50b883e49?d=identicon)[mantas783](/maintainers/mantas783) --- Top Contributors [![mantas-done](https://avatars.githubusercontent.com/u/17127206?v=4)](https://github.com/mantas-done "mantas-done (435 commits)")[![eijei521](https://avatars.githubusercontent.com/u/31096533?v=4)](https://github.com/eijei521 "eijei521 (42 commits)")[![kocoten1992](https://avatars.githubusercontent.com/u/7130705?v=4)](https://github.com/kocoten1992 "kocoten1992 (7 commits)")[![Andrius521](https://avatars.githubusercontent.com/u/82888955?v=4)](https://github.com/Andrius521 "Andrius521 (4 commits)")[![karenirenecano](https://avatars.githubusercontent.com/u/15527144?v=4)](https://github.com/karenirenecano "karenirenecano (2 commits)")[![ntninja](https://avatars.githubusercontent.com/u/246386?v=4)](https://github.com/ntninja "ntninja (1 commits)")[![scrutinizer-auto-fixer](https://avatars.githubusercontent.com/u/6253494?v=4)](https://github.com/scrutinizer-auto-fixer "scrutinizer-auto-fixer (1 commits)")[![ts-toh](https://avatars.githubusercontent.com/u/41636305?v=4)](https://github.com/ts-toh "ts-toh (1 commits)")[![vnali](https://avatars.githubusercontent.com/u/55586085?v=4)](https://github.com/vnali "vnali (1 commits)") --- Tags 608708advanced-substation-alphaasscaptionsebu-stlphpsamisccsrtsubripsubtitle-conversionsubtitle-convertersubtitle-formatssubtitlesttmlwebvtt ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/mantas-done-subtitles/health.svg) ``` [![Health](https://phpackages.com/badges/mantas-done-subtitles/health.svg)](https://phpackages.com/packages/mantas-done-subtitles) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)