{"id":40703495,"url":"https://github.com/mantas-done/subtitles","last_synced_at":"2026-01-21T12:07:58.581Z","repository":{"id":45080585,"uuid":"78287954","full_name":"mantas-done/subtitles","owner":"mantas-done","description":"Subtitle/caption converter","archived":false,"fork":false,"pushed_at":"2025-10-18T11:36:39.000Z","size":688,"stargazers_count":161,"open_issues_count":0,"forks_count":49,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-10-29T21:47:37.320Z","etag":null,"topics":["608","708","advanced-substation-alpha","ass","captions","ebu-stl","php","sami","scc","srt","subrip","subtitle-conversion","subtitle-converter","subtitle-formats","subtitles","ttml","webvtt"],"latest_commit_sha":null,"homepage":"https://gotranscript.com/subtitle-converter","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mantas-done.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-01-07T15:51:54.000Z","updated_at":"2025-10-25T04:42:32.000Z","dependencies_parsed_at":"2023-11-22T10:26:44.940Z","dependency_job_id":"a335906c-2606-49b1-88a4-6b67ed89912f","html_url":"https://github.com/mantas-done/subtitles","commit_stats":{"total_commits":121,"total_committers":9,"mean_commits":"13.444444444444445","dds":"0.12396694214876036","last_synced_commit":"d449c29985d6c106171611e3b6ae6c52ff3a86f2"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/mantas-done/subtitles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mantas-done%2Fsubtitles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mantas-done%2Fsubtitles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mantas-done%2Fsubtitles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mantas-done%2Fsubtitles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mantas-done","download_url":"https://codeload.github.com/mantas-done/subtitles/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mantas-done%2Fsubtitles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28632781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["608","708","advanced-substation-alpha","ass","captions","ebu-stl","php","sami","scc","srt","subrip","subtitle-conversion","subtitle-converter","subtitle-formats","subtitles","ttml","webvtt"],"created_at":"2026-01-21T12:07:58.512Z","updated_at":"2026-01-21T12:07:58.570Z","avatar_url":"https://github.com/mantas-done.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Caption And Subtitle Converter for PHP\n\n[\u003e\u003e live demo \u003c\u003c](https://gotranscript.com/subtitle-converter)\n\n🥳🎉👏 Probably the best subtitle parser 🥳🎉👏\n\n💣 Tested on thousands of user submitted files 🤯  \n🔥 Almost 100% unit test coverage 💥\n\n## Supported formats\n\n| Format                                                                                                | Extension | Internal format name |\n|-------------------------------------------------------------------------------------------------------|-----------|----------------------|\n| [SubRip](https://en.wikipedia.org/wiki/SubRip#SubRip_text_file_format)                                | .srt      | srt                  |\n| [WebVTT](https://en.wikipedia.org/wiki/WebVTT)                                                        | .vtt      | vtt                  |\n| [Scenarist](http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/SCC_FORMAT.HTML)                   | .scc      | scc                  |\n| [EBU STL (only reader)](https://tech.ebu.ch/docs/tech/tech3264.pdf)                                   | .stl      | ebu_stl              |\n| [Spruce Technologies SubTitles](https://pastebin.com/ykGM9qjZ)                                        | .stl      | stl                  |\n| [Youtube Subtitles](https://webdev-il.blogspot.lt/2010/01/sbv-file-format-for-youtube-subtitles.html) | .sbv      | sbv                  |\n| [SubViewer](https://wiki.videolan.org/SubViewer)                                                      | .sub      | sub_subviewer        |\n| [MicroDVD](https://en.wikipedia.org/wiki/MicroDVD)                                                    | .sub      | sub_microdvd         |\n| Advanced Sub Station                                                                                  | .ass      | ass                  |\n| [Netflix Timed Text](https://en.wikipedia.org/wiki/Timed_Text_Markup_Language)                        | .dfxp     | dfxp                 |\n| [TTML](https://en.wikipedia.org/wiki/Timed_Text_Markup_Language)                                      | .ttml     | ttml                 |\n| [SAMI](https://en.wikipedia.org/wiki/SAMI)                                                            | .smi      | smi                  |\n| QuickTime                                                                                             | .qt.txt   | txt_quicktime        |\n| Rich text format (only reader)                                                                        | .rtf      | rtf                  |\n| DOCX (only reader)                                                                                    | .docx  | docx                 |\n| [LyRiCs](https://en.wikipedia.org/wiki/LRC_(file_format))                                             | .lrc      | lrc                  |\n| Comma separated values                                                                                | .csv      | csv                  |\n| Plaintext                                                                                             | .txt      | txt                  |\n\n## Command line\nCan be used from the command line to convert from .srt to .vtt\n```\nphp subtitles.phar input.srt output.vtt\n```\nsubtitles.phar file can be found here - https://github.com/mantas-done/subtitles/releases\n\n## Installation (supports PHP 8.3...8.4)\n```\ncomposer require mantas-done/subtitles\n```\n\n## Usage\nConvert .srt file to .vtt:\n```php\n// add namespace\nuse \\Done\\Subtitles\\Subtitles;\n\n(new Subtitles())-\u003econvert('subtitles.srt', 'subtitles.vtt');\n```\n\n```php\n// if no input format is specified, library will determine file format by its content\n// if third parameter is specified, library will convert the file to specified format.\n// list of formats are in Subtitle::$formats, they are: ass, dfxp, sbv, srt, stl, sub, ttml, txt_quicktime, vtt \n(new Subtitles())-\u003econvert('subtitles1', 'subtitles2', ['output_format' =\u003e 'vtt']); \n```\n\nManually create file\n```php\n$subtitles = new Subtitles();\n$subtitles-\u003eadd(0, 5, 'This text is shown in the beggining of video for 5 seconds');\n$subtitles-\u003esave('subtitles.vtt');\n```\n\nLoad subtitles from existing file\n```php\n$subtitles = (new Subtitles())-\u003eloadFromFile('subtitles.srt');\n```\n\nLoad subtitles from string\n```php\n$string = \"\n1\n00:02:17,440 --\u003e 00:02:20,375\nSenator, we're making our final approach\n\";  \n\n$subtitles = (new Subtitles())-\u003eloadFromString($string);\n```\n\nSave subtitles to file\n```php\n$subtitles-\u003esave('subtitler.vtt');\n```\n\nGet file content without saving to file\n```php\necho $subtitles-\u003econtent('vtt');\n```\n\nAdd subtitles\n```php\n$subtitles-\u003eadd(0, 5, 'some text'); // from 0, till 5 seconds  \n\n// Add multiline text\n$subtitles-\u003eadd(0, 5, [\n    'first line',\n    'second line',\n]);\n\n// Add styles to VTT file format\n// Only VTT supports styles currently\n$subtitles-\u003eadd(0, 5, 'text', ['vtt_cue_settings' =\u003e 'position:50% line:15% align:middle']);\n````\n\nRemove subtitles\n```php\n$subtitles-\u003eremove(0, 5); // from 0, till 5 seconds\n```\n\nTrim subtitles\n```php\n$subtitles-\u003etrim(3, 4); // get only from 3, till 4 seconds\n```\n\nAdd 1 second to all subtitles\n```php\n$subtitles-\u003eshiftTime(1);\n```\n\nSubtract 0.5 second\n```php\n$subtitles-\u003eshiftTime(-0.5);\n```\n\nAdd 5 second to subtitles starting from 1 minute till 2 mintes \n```php\n$subtitles-\u003eshiftTime(5, 60, 120);\n```\n\nExample: 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.\n```php\n$subtitles-\u003eshiftTimeGradually(2, 0, 3600);\n```\n\n## Exceptions ##\n\nLibrary will throw UserException, it's message can be shown to the user.\n\n```php\ntry {\n    (new \\Done\\Subtitles\\Subtitles())-\u003eadd(0, 1, 'very long text... aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')-\u003econtent('scc');\n} catch (\\Done\\Subtitles\\Code\\Exceptions\\UserException $e) {\n    echo $e-\u003egetMessage(); // SCC file can't have more than 4 lines of text each 32 characters long. This text is too long: \u003ctext from user file that triggered this error\u003e\n}\n```\nBy default, library tries to detect different file errors that can be shown to the user, so he would be able to fix them. \nIf you want to relax the rules and allow the library to convert even somewhat invalid files, use ['strict' =\u003e false]\n```php\n(new Subtitles())-\u003econvert($input, $output, ['strict' =\u003e false]);\n(new Subtitles())-\u003eloadFromString($string, ['strict' =\u003e false]);\n(new Subtitles())-\u003eloadFromFile($input, ['strict' =\u003e false]);\n```\n\n## How to add new subtitle format?\n\nYou need to implement ConverterContract.php interface. It has two methods.\n```php\nfileContentToInternalFormat($file_content)  \n  \ninternalFormatToFileContent($internal_format)\n```\n\nBasically 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.\n\n\"Internal library's\" format is used like middle ground, to be able to convert between different formats.\n\nBest example is to look how [SrtConverter.php](https://github.com/mantas783/subtitle-converter/blob/master/src/code/Converters/SrtConverter.php) is implemented.  \nAnd this is example of [.srt file](https://github.com/mantas783/subtitle-converter/blob/master/tests/files/srt.srt).\n\n## Registering your converter\n\n```php\n(new Subtitles())-\u003eregisterConverter(FakeDocxConverter::class, 'docx_fake', 'docx', 'Fake docx converter');\n```\n\nYou can add a new converter or replace the existing one if the format name is the same (the second parameter).\n\n### \"Internal Format\" \n\n\"Internal Format\" is just a PHP array. It is used internally in library to be able to convert between different formats.\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [start] =\u003e 137.44\n            [end] =\u003e 140.375\n            [lines] =\u003e Array\n                (\n                    [0] =\u003e Senator, we're making\n                    [1] =\u003e our final approach into Coruscant.\n                )\n        )\n    [1] =\u003e Array\n        (\n            [start] =\u003e 140.476\n            [end] =\u003e 142.501\n            [lines] =\u003e Array\n                (\n                    [0] =\u003e Very good, Lieutenant.\n                )\n        )\n)\n```\n```\n[start] - when to start showing text (float - seconds)\n[end] - when to stop showing text (float -seconds)\n[lines] - one or more text lines (array)\n```\n\n## Running Tests\n\n```\nphp vendor/bin/phpunit\nphp vendor/bin/phpstan analyse\n```\n\n## Contribution\n\nYou can contribute in any way you want. If you need some guidance, choose something from this table:\n\n| Task | Difficulty | Description |\n| --- | --- | --- |\n| Add new formats | Medium | Supporting more formats is nice. Some popular formats: .mcc, .cap |\n| Refactor [StlConverter.php](https://github.com/mantas783/subtitle-converter/blob/master/src/code/Converters/StlConverter.php) file | Easy | .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) |\n| Add .scc format | Hard | [Format description](http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/SCC_FORMAT.HTML) |\n\nFor now library should support only basic features (several lines of text). No need to support different text styles or positioning of text.\n\n## Report Bugs\n\nIf some file is not working with the library, please create and issue and attach the file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmantas-done%2Fsubtitles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmantas-done%2Fsubtitles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmantas-done%2Fsubtitles/lists"}