Skip to content

Parses and compiles ASS subtitle format to easy-to-use data structure

License

Notifications You must be signed in to change notification settings

widatama/ass-compiler

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Aug 19, 2024
ec3b1d6 · Aug 19, 2024
Aug 19, 2024
Aug 19, 2024
Aug 19, 2024
Aug 19, 2024
Aug 19, 2024
Aug 19, 2024
Jun 19, 2022
Aug 19, 2024
Jun 17, 2022
Jul 10, 2022
Aug 19, 2024
Aug 19, 2024
Aug 19, 2024
Aug 19, 2024

Repository files navigation

ass-compiler

GitHub Action License

Parses and compiles ASS subtitle format to easy-to-use data structure.

Online Viewer

Installation

npm install ass-compiler

Usage

Use parse or compile as needed.

import { parse, stringify, compile, decompile } from 'ass-compiler';

// ASS file content
const text = `
[Script Info]
; ...
`;

// parse just turn ASS text into JSON
const parsedASS = parse(text);
const stringifiedText = stringify(parsedASS, options);

// compile will get rid of invalid tags, merge duplicated tags, transform drawings, etc.
const compiledASS = compile(text, options);
const decompiledText = decompile(compiledASS, options);

compile options

{
  // A Style named `Default` will be automatic generated by options.defaultStyle
  // if it is not exists in `[V4+ Style]` section.
  defaultStyle: {
    Name: 'Default',
    Fontname: 'Arial',
    Fontsize: '20',
    PrimaryColour: '&H00FFFFFF&',
    SecondaryColour: '&H000000FF&',
    OutlineColour: '&H00000000&',
    BackColour: '&H00000000&',
    Bold: '0',
    Italic: '0',
    Underline: '0',
    StrikeOut: '0',
    ScaleX: '100',
    ScaleY: '100',
    Spacing: '0',
    Angle: '0',
    BorderStyle: '1',
    Outline: '2',
    Shadow: '2',
    Alignment: '2',
    MarginL: '10',
    MarginR: '10',
    MarginV: '10',
    Encoding: '1',
  },
}

stringify and decompile options

{
  defaultMargin: '0000',
  processText: (inpText) => inpText,
  skipEmptyEvent: false,
  skipUnusedStyle: false,
}

defaultMargin

Default value: 0000

Default margin value for margins in event comments and dialogues.

Based on the spec it should be 4-digit long. But this adds up quite a bit to the subtitle file size and there is no problem with video players if this is only one digit. So override this to reduce subtitle file size.

Sample input

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:04.00,Default,,1,2,3,,This is a test of the ASS format and some basic features in it.
Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0,0,0,,This is a test of the ASS format and some basic features in it.

Default output

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:04.00,Default,,1,2,3,,This is a test of the ASS format and some basic features in it.
Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0000,0000,0000,,This is a test of the ASS format and some basic features in it.

Output with defaultMargin = '0'

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:04.00,Default,,1,2,3,,This is a test of the ASS format and some basic features in it.
Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0,0,0,,This is a test of the ASS format and some basic features in it.

processStyle

Default value: (inpText) => inpText

Function for processing style. Can be used for updating styles.

Sample input

[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Default,Arial,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,0

Default output

[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Default,Arial,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,0

Output with (inpStyle) => { inpStyle.Fontname = 'Open Sans'; return inpStyle; }

[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Default,Open Sans,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,0

processText

Default value: (inpText) => inpText

Function for processing event texts. Useful for things like applying smart quotes with smartypants.

Sample input

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:04.00,Default,,1,2,3,,This is a test of the ASS format and some basic features in it.
Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0,0,0,,This is a test of the ASS format and some basic features in it.

Default output

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:04.00,Default,,1,2,3,,This is a test of the ASS format and some basic features in it.
Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0000,0000,0000,,This is a test of the ASS format and some basic features in it.

Output with (inpText) => inpText.toUppercase()

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:04.00,Default,,1,2,3,,THIS IS A TEST OF THE ASS FORMAT AND SOME BASIC FEATURES IN IT.
Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0000,0000,0000,,THIS IS A TEST OF THE ASS FORMAT AND SOME BASIC FEATURES IN IT.

skipEmptyEvent

Default value: false

Skip yielding events with empty text. Useful for cleaning up subtitle file.

Sample input

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:04.00,Default,,1,2,3,,This is a test of the ASS format and some basic features in it.
Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0,0,0,,

Default output

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:04.00,Default,,1,2,3,,This is a test of the ASS format and some basic features in it.
Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0000,0000,0000,,

Output with skipEmptyEvent = true

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:04.00,Default,,1,2,3,,This is a test of the ASS format and some basic features in it.

skipUnusedStyle

Default value: false

Skip yielding styles that are not used in any event. Useful for cleaning up subtitle file.

Sample input

[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Default,Arial,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,0
Style: Alt,Times New Roman,40,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,8,10,10,10,0
Style: Unused,Arial,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,0

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:04.00,Default,,1,2,3,,This is a test of the ASS format and some basic features in it.
Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0,0,0,,

Default output

[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Default,Arial,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,0
Style: Alt,Times New Roman,40,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,8,10,10,10,0
Style: Unused,Arial,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,0

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:04.00,Default,,1,2,3,,This is a test of the ASS format and some basic features in it.
Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0000,0000,0000,,

Output with skipUnusedStyle = true

[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Default,Arial,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,0
Style: Alt,Times New Roman,40,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,8,10,10,10,0

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:04.00,Default,,1,2,3,,This is a test of the ASS format and some basic features in it.
Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0000,0000,0000,,

For details of data structure, please use the online viewer.

About

Parses and compiles ASS subtitle format to easy-to-use data structure

Topics

Resources

License

Stars

Watchers

Forks

Languages

  • JavaScript 100.0%