ASS Furiganizer

A CLI utility to easily generate beautiful Japanese subtitles with furigana.

Who can use it

• Japanese learners
• Video creators - you can fix any mistakes in the automatically generated furigana (see blueprint) then hardcode the subtitles into the video with a video editor of your choice.

Table of Contents

• Installation
• Basic Usage
• Configuration file
• Configuration options
  • positioning
    • position
    • align
    • furigana_offset
    • line_distance
    • margin
    • shift
  • styles.text, styles.furigana
    • fontsize
    • bold
    • italic
    • outline
    • shadow
    • color
    • outline_color
    • shadow_color
  • styles.furigana
    • scale_factor
  • styles.opaque_box
    • enable
    • padding
    • outline
    • shadow
    • border_radius
    • color
    • outline_color
    • shadow_color
  • styles.blur
    • text, furigana, opaque_box
  • styles.shadow_direction
    • text, furigana, opaque_box
  • styles
    • font_path
    • consistent_font_size
  • miscellaneous
    • output_dir
    • analyzer
    • add_suffix
    • suffix
    • interactive
  • substitute
    • text
    • furigana
• Configuration types
  • Color
  • AxesArray
  • Font
• Command Line options
  • --config-name
  • --font-path
  • --shift-time
  • --generate-blueprint
  • --ignore-output-dir
  • --print-all-chars
  • --no-embed-font
  • --resolution
• How does it work
• Examples

Installation

Install globally:

npm i -g ass-furiganizer

Run:

furiganize --help

Basic Usage

This program requires at least a subtitles file and a video file. Suppose you have both in the current directory:

furiganize -i sub.srt -v video.mkv

This will create a video.ass file next to the video.mkv file.

It can be used in bulk. Suppose you have subs and videos folders in the current directory containing equal amount of subtitle and video files respectively:

furiganize -i subs/*.srt -v videos/*.mp4

Configuration file

During installation a configuration file is created in your data directory. furiganizer-config command is used for managing the config directory:

furiganizer-config --help

To see where the config directory is located run:

furiganizer-config --path

To generate a new configuration file:

furiganizer-config --generate

Configuration options

positioning

position

Type: number

Description: text position on the screen in Numpad style, e.g., 2 - bottom, 8 - top:

┌───────────────┐
│ 7     8     9 │
│ 4     5     6 │
│ 1     2     3 │
└───────────────┘

align

Type: 'start' | 'center' | 'end' | 'auto'

Description: text alignment. auto aligns text based on the position towards the closest border (start for 1,4,7; end for 3,6,9), otherwise centered.

furigana_offset

Type: number

Description: distance between text and furigana in px.

line_distance

Type: number

Description: distance between lines in px.

margin

Type: number

Description: offset from the border in px.

shift

Type: [number, number]

Description: optionally move the subtitles by the [x, y] axes in px (see AxesArray).

styles.text, styles.furigana

fontsize

Type: number

Description: text size (height) in px.

bold

Type: boolean

Description: make text bolder.

italic

Type: boolean

Description: make text italic.

outline

Type: number

Description: text border size in px.

shadow

Type: number

Description: distance of the shadow from the text in px.

color

Type: string

Description: color of the text. See Color.

outline_color

Type: string

Description: color of the text border. See Color.

shadow_color

Type: string

Description: color of the text shadow. See Color.

styles.furigana

scale_factor

Type: number

Description: if this is specified, everything in the styles.furigana block will be ignored and the text styles used for furigana. furigana.fontsize = text.fontsize * scale_factor. This should be a positive decimal number. If this is commented with a #, the furigana styles are provided separately.

styles.opaque_box

enable

Type: boolean

Description: display text background. For now this can't be used with subtitles that have overlaps (a subtitle starts before the last one ends).

padding

Type: number | [number, number]

Description: background padding in px. Can be a number or an array for separate horizontal and vertical padding (see AxesArray).

outline

Type: number

Description: background outline in px.

shadow

Type: number

Description: distance of the shadow from the background in px.

border_radius

Type: number

Description: make the corners of the box rounded. Radius in px.

color

Type: string

Description: color of the box. See Color.

outline_color

Type: string

Description: color of the box border. See Color.

shadow_color

Type: string

Description: color of the box shadow. See Color.

styles.blur

text, furigana, opaque_box

Type: number

Description: blur the outline if it is nonzero, otherwise blur text or box.

styles.shadow_direction

text, furigana, opaque_box

Type: [number, number]

Description: uncomment to override shadow direction. If shadow = <n>, it is the same as shadow_direction = [<n>, <n>]. These values unlike shadow can be negative. At least one of the values should be nonzero.

See AxesArray.

styles

font_path

Type: string

Description: see Font.

consistent_font_size

Type: boolean

Description: adjust font size for different video resolutions. This will make the proportion of the text size to the video height remain constant. This way if you open two videos of different resolutions in full screen the subtitles will look the same. All the values specified in px will remain as is for 1080p resolution and will be adjusted for other resolutions.

miscellaneous

output_dir

Type: string

Description: directory to save generated subtitles to. The directory where your video player looks for subtitles can be provided here.

analyzer

Type: string

Description: choose the morphological analyzer. Can be kuromoji or mecab. kuromoji does not require any configuration. If you want to use mecab you need to install it on your machine and make sure it's in the PATH.

add_suffix

Type: boolean

Description: add a language suffix to the name of the generated file (<video_name>.<suffix>.ass).

suffix

Type: string

Description: suffix to add.

interactive

Type: boolean

Description: you'll be prompted for options if a variable font or font collection is provided. If set to false the default variation or the first font from the collection will be used.

substitute

text

Type: [string, string][]

Description: substitute one or more characters. May be useful when there are unimportant characters that are unsupported by the font. Takes an array consisting of arrays that have two strings: [<match>, <substitute>]. <substitute> should be an empty string to remove the <match> character(s). <match> can be a Unicode string representing one character: U+0049, U+1F610.

furigana

Type: [string, string][]

Description: may be useful for furigana if you, for example, need a specific katakana phrase as the analyzer will turn everything to hiragana. Works the same as for text but will only match the full phrase.

Configuration types

Color

Color is a string that can be:

• a named color value: 'white', 'black', 'yellow'
• a HEX color: '#ffffff', '#ffffff80'
• an RGB color: 'rgb(255,255,255)', 'rgba(255,255,255,0.5)'
• a native SubStation Alpha color.

AxesArray

An array consisting of two numbers for the X and Y axes: [x, y].

Font

An absolute or relative path to the font file. Accepted extensions: ttf, otf and ttc. Variable fonts are supported.

The priority is: --font-path in CMD -> font_path in the config -> fallback font (Noto Sans JP Medium).

Command Line options

--config-name

If you want to use multiple configs, create a copy of config.toml, give it a name (<config_name>.toml). Use --config-name or -c to specify the name without the extension:

furiganize -i *.srt -v *.mkv -c <config_name>

By default, config.toml is used.

--font-path

furiganize -i *.srt -v *.mkv -f MyFont.ttf

See Font

--shift-time

Specify the time in seconds to shift the subtitles:

furiganize -i *.srt -v *.mkv -s 0.9

--generate-blueprint

If you want to fix any mistakes in the furigana and make the subtitles production ready:

furiganize -i subs.srt -v video.mkv -B

This will create a subs.bp file. It contains all the dialogues, each of them has the following structure:

• A line containing the dialogue counter and the timings
• One or more arrays, each representing a single line of that dialogue. Each of the arrays contains one or more objects with a text and furigana fields

After editing the file generate new subtitles one more time providing the .bp file instead of .srt:

furiganize -i subs.bp -v video.mkv

--ignore-output-dir

By default the generated subtitles are saved next to the video. If output_dir in the config is set but the default behavior is needed once, add the -O flag.

--print-all-chars

Use -U to dump all the unsupported characters to the console.

--no-embed-font

If there is a problem with creating font subset or you have it installed and don't want to embed it into the file you can skip it:

furiganize -i *.srt -v *.mkv --no-embed-font

It can't be skipped for a variable font.

--resolution

If the resolution can't be detected automatically from the video, this resolution will be used. Should be a string like 1920x1080.

How does it work

SubStation Alpha format does not have a proper support for furigana, so this library separates text into separate chunks and places them using positioning capability of this format calculating the correct position for each of them.

These calculations rely on the metrics of the font that is used, so to ensure the subtitles are displayed correctly, a subset of the font is created only containing a set of the necessary characters and embedded into the generated script.

It's also necessary to know the resolution of the video for correct positioning so a video file is required.

These subtitles are not guaranteed to work in every video player. It's recommended to use MPV or a recent version of VLC. Hardcoding (burning) them into a video might be a good option for public use.

Examples

This library can also work with non-Japanese languages.

To demonstrate how variable fonts work, here are three examples of the same font that has lots of adjustable variable axes such as Weight, Width, Slant, etc.: