PHPackages                             infureal/php-ass - 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. infureal/php-ass

ActiveLibrary[Utility & Helpers](/categories/utility)

infureal/php-ass
================

A library for reading Advanced Sub Station Alpha subtitle files

v1.1(5y ago)022MITPHPPHP >=5.3.3

Since Dec 28Pushed 5y agoCompare

[ Source](https://github.com/inFureal/php-ass)[ Packagist](https://packagist.org/packages/infureal/php-ass)[ Docs](http://github.com/johnnoel/php-ass)[ RSS](/packages/infureal-php-ass/feed)WikiDiscussions master Synced 6d ago

READMEChangelog (1)DependenciesVersions (10)Used By (0)

php-ass
=======

[](#php-ass)

A library for reading Advanced Substation Alpha subtitle files.

Specification
-------------

[](#specification)

The ASS file specs are available in various parts in various places:

1. [Wikipedia has a good overview](https://en.wikipedia.org/wiki/SubStation_Alpha#Advanced_SubStation_Alpha)
2. [The original format in Microsoft Word .doc format](http://www.perlfu.co.uk/projects/asa/ass-specs.doc)
3. [How the files are incorporated into Matroska (MKV) files](http://www.matroska.org/technical/specs/subtitles/ssa.html)

In short: ASS files are an advanced version of the original SSA (Sub Station Alpha) subtitle files and include several improvements in terms of styling and effects.

A valid script file starts with \[Script Info\] and contains several sections in INI style format.

Quick start
-----------

[](#quick-start)

Install using composer:

```
composer require chaostangent/php-ass
```

Then start using:

```
require __DIR__.'/vendor/autoload.php';

use ChaosTangent\ASS\Reader;

$reader = new Reader();
$script = $reader->fromFile(__DIR__.'/examples/example.ass');

foreach ($script as $block) {
    echo $block->getId().PHP_EOL;

    foreach ($block as $line) {
        echo $line->getKey().': '.$line->getValue();
    }
}
```

Parts
-----

[](#parts)

### Script

[](#script)

The [`ChaosTangent\ASS\Script`](src/ChaosTangent/ASS/Script.php) class represents the root object of an ASS script.

You instantiate a `Script` with the content of a script as well as an optional filename:

```
$script = new Script('[Script Info]', 'mytestscript.ass');
```

Once instantiated you can check whether what's been passed looks like a valid ASS script:

```
if ($script->isASSScript()) {
    // do more processing
}
```

This only checks the first few bytes for the "\[Script Info\]" string, it doesn't guarantee that a passed script is valid or readable.

To parse the passed script:

```
$script->parse();
```

This will go through the content passed when creating the script and parse it into blocks and lines.

To get the current collection of blocks, you can call `getBlocks()` or treat the script as an iterator:

```
foreach ($script as $block) {
    // block processing
}
```

To check if a script has a block:

```
if ($script->hasBlock('Script Info')) {
    $script->getBlock('Script Info');
}
```

### Block

[](#block)

Every ASS script is comprised of a few different blocks. The [`ChaosTangent\ASS\Block\Block`](src/ChaosTangent/ASS/Block/Block.php) abstract class represents one of these blocks.

At the moment php-ass supports the following blocks:

- Script Info as [`ChaosTangent\ASS\Block\ScriptInfo`](src/ChaosTangent/ASS/Block/ScriptInfo.php)
- V4+ Styles as [`ChaosTangent\ASS\Block\Styles`](src/ChaosTangent/ASS/Block/Styles.php)
- Events as [`ChaosTangent\ASS\Block\Events`](src/ChaosTangent/ASS/Block/Events.php)

Any other kind of block (e.g. "Aegisub Project Garbage", "Fonts") are silently ignored when parsing.

`ScriptInfo` blocks provide functions for common fields:

```
$scriptInfoBlock->getTitle();
$scriptInfoBlock->getWrapStyle();
$scriptInfoBlock->getScriptType();
```

Otherwise you can just treat blocks as containers for lines. You can use array access to get a specific line:

```
$scriptInfoBlock[123]; // line 124 of this block
```

Or treat the block as an iterator:

```
foreach ($scriptInfoBlock as $line) {
    // line processing
}
```

### Line

[](#line)

Lines are the core of a script file. Any line that isn't a comment (not to be confused with a comment event line) uses the base class [`ChaosTangent\ASS\Line\Line`](src/ChaosTangent/ASS/Line/Line.php).

Lines in some blocks are mapped according to a special "Format" line. These are represented by [`ChaosTangent\ASS\Line\Format`](src/ChaosTangent/ASS/Line/Format.php). Format lines have a special `getMapping()` method that returns an array that can be used to parse other lines.

If all of this sounds a bit complicated, you mostly won't have to worry about it if parsing files as it's all taken care of for you. All it means is that for Dialogue and Style lines, you can use methods to get the different parts:

```
$styleLine->getName();
$styleLine->getPrimaryColour();
$dialogueLine->getLayer();
$dialogueLine->getText();
```

Dialogue lines also have an extra method for getting the text of a line without any style override codes in it:

```
$dialogueLine->getTextWithoutStyleOverrides();
```

For all lines you can use the generic `getKey()` and `getValue()` methods which will return the key of the line (e.g. "Dialogue", "Format", "Style") and its unparsed value:

```
$dialogueLine->getKey(); // == 'Dialogue'
$dialogueLine->getValue(); // e.g. 0,0:00:00.98,0:00:05.43,ED_English,,0,0,0,,{\fad(100,200)\blur5\c&H000010&\3c&H80A0C0&}My destiny,
```

If you only want lines of a specific type, just do an `instanceof` check when iterating through:

```
foreach ($block as $line) {
    if ($line instanceof Dialogue) {
        echo $line->getTextWithoutStyleOverrides().PHP_EOL;
    }
}
```

Tests
-----

[](#tests)

There is a growing test suite for this library that you can use [phpunit](http://phpunit.de) to validate against. Any esoteric or known broken scripts would be a welcome addition.

TODO
----

[](#todo)

- Allow reading of embedded information (images, fonts etc.)
- Allow construction and writing of ASS files
- More line type support
- More block type support
- Test completion

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 89.6% 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 ~356 days

Recently: every ~475 days

Total

9

Last Release

2039d ago

Major Versions

v0.1.5.1 → v1.0.02015-08-01

### Community

Maintainers

![](https://www.gravatar.com/avatar/296ef439fee2f92e6d3512c96ecb1b5dc63a10aa1a4058771c830c48dd87dd16?d=identicon)[infureal](/maintainers/infureal)

---

Top Contributors

[![johnnoel](https://avatars.githubusercontent.com/u/1096330?v=4)](https://github.com/johnnoel "johnnoel (43 commits)")[![infureal](https://avatars.githubusercontent.com/u/22548823?v=4)](https://github.com/infureal "infureal (2 commits)")[![Aeolun](https://avatars.githubusercontent.com/u/1116482?v=4)](https://github.com/Aeolun "Aeolun (1 commits)")[![neokike](https://avatars.githubusercontent.com/u/2183963?v=4)](https://github.com/neokike "neokike (1 commits)")[![Shiox](https://avatars.githubusercontent.com/u/3194471?v=4)](https://github.com/Shiox "Shiox (1 commits)")

---

Tags

subtitlessubtitlessaassmp4mkv

### Embed Badge

![Health badge](/badges/infureal-php-ass/health.svg)

```
[![Health](https://phpackages.com/badges/infureal-php-ass/health.svg)](https://phpackages.com/packages/infureal-php-ass)
```

###  Alternatives

[captioning/captioning

A collection of tools to manipulate subtitles

2261.3M7](/packages/captioning-captioning)[kiwilan/php-audio

PHP package to parse and update audio files metadata, with `JamesHeinrich/getID3`.

3012.6k1](/packages/kiwilan-php-audio)[cleaniquecoders/blueprint-macro

Laravel Blueprint Macro

164.6k6](/packages/cleaniquecoders-blueprint-macro)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)