go-astisub

You can install the library as a Go module for use in your projects, or install the standalone CLI tool for command-line subtitle manipulation.

To install the library:

go get github.com/asticode/go-astisub

To install the CLI:

go install github.com/asticode/go-astisub/cmd/astisub

STL files contain a GSI block that defines global metadata. go-astisub maps these to the Subtitles.Metadata field. Key metadata fields include:

• Framerate: The video framerate.
• STLCountryOfOrigin: The country code (e.g., stlCountryCodeFrance).
• STLDisplayStandardCode: Indicates if the file uses Open Subtitling or Teletext (Level 1/2).
• Language: Mapped from STL language codes (e.g., stlLanguageCodeEnglish).
• STLTimecodeStartOfProgramme: The starting timecode offset.

The parser uses specific character code tables (e.g., stlCharacterCodeTableNumberLatin) to decode text correctly based on the GSI block's specification.

WebVTT supports an X-TIMESTAMP-MAP header used for syncing cue times with MPEG-TS streams. The library parses this into Metadata.WebVTTTimestampMap.

You can use the Offset() method on a WebVTTTimestampMap to calculate the time offset between the local WebVTT time and the MPEG-TS time.

// Example of calculating offset from a timestamp map
if subtitles.Metadata != nil && subtitles.Metadata.WebVTTTimestampMap != nil {
	offset := subtitles.Metadata.WebVTTTimestampMap.Offset()
	fmt.Printf("Time offset: %v\n", offset)
}

The library uses a hierarchical model to represent subtitles:

1. Subtitles: The top-level container. It holds a slice of Items, global Metadata, Regions, and Styles.
2. Item: Represents a single subtitle cue shown between a StartAt and EndAt time. It contains Lines and can be associated with a Region or a Style.
3. Line: A collection of LineItems. This allows for complex formatting within a single subtitle cue.
4. LineItem: The smallest unit of text, which can have its own InlineStyle (e.g., a single word in a different color).

The TTML parser supports several ways to represent time and duration within the begin and end attributes. The TTMLInDuration type implements UnmarshalText to handle these formats:

1. Standard Clock Time: hh:mm:ss.mmm (e.g., 00:01:23.456)
2. Clock Time with Frames: hh:mm:ss:fff where fff represents frames (e.g., 00:01:23:12)
3. Offset Time: A numeric value followed by a metric:
   • h: hours
   • m: minutes
   • s: seconds
   • ms: milliseconds
   • f: frames
   • t: ticks (e.g., 100t)

Note: When using frames (f) or ticks (t), the resulting duration calculation depends on the frameRate or tickRate attributes defined in the TTML root element.

The STLOptions struct provides control over how the GSI block's timecode information is applied to the resulting subtitle items.

• IgnoreTimecodeStartOfProgramme (bool): When true, the parser will not use the timecodeStartOfProgramme from the GSI block to offset the StartAt and EndAt times of the subtitle items. By default, this is false.

opts := astisub.STLOptions{
	IgnoreTimecodeStartOfProgramme: true,
}

The TeletextOptions struct is used to control the behavior of the Teletext parser.

type TeletextOptions struct {
	Page int
	PID  int
}

The astisub CLI allows you to perform common subtitle operations directly from your terminal. Supported operations include conversion, linear correction, fragmentation, merging, optimization, unfragmenting, and syncing.

astisub convert -i example.srt -o example.ttml

astisub apply-linear-correction -i example.srt -a1 1s -d1 2s -a2 5s -d2 7s -o example.out.srt

astisub fragment -i example.srt -f 2s -o example.out.srt

astisub merge -i example.srt -i example.ttml -o example.out.srt

astisub optimize -i example.srt -o example.out.srt

astisub unfragment -i example.srt -o example.out.srt

astisub sync -i example.srt -s "-2s" -o example.out.srt

Use the WriteToSRT method on a Subtitles instance to export the subtitle data to an io.Writer in .srt format.

Note:

• If the Subtitles object contains no items, it returns ErrNoSubtitlesToWrite.
• The output includes a BOM header.
• It preserves inline styles like bold, italics, underline, color, and position (using {\anX} tags).

package main

import (
	"os"
	"github.com/asticode/asticode/go-astisub"
)

func main() {
	subtitles := astisub.NewSubtitles()
	// ... populate subtitles ...

	f, err := os.Create("output.srt")
	if err != nil {
		panic(err)
	}
	defer f.Close()

	err = subtitles.WriteToSRT(f)
	if err != nil {
		panic(err)
	}
}

Use ReadFromSTL to parse an .stl file from an io.Reader. This function handles the GSI (General Subtitle Information) block and all subsequent TTI (Text and Timing Information) blocks. It populates a Subtitles object containing metadata and subtitle items.

Options

STLOptions allows you to configure the parser:

• IgnoreTimecodeStartOfProgramme: If set to true, the STLTimecodeStartOfProgramme in the metadata will not be updated from the GSI block value.

import (
	"os"
	"github.com/asticode/go-astisub"
)

func main() {
	f, err := os.Open("subtitles.stl")
	if err != nil {
		return
	}
	defer f.Close()

	opts := astisub.STLOptions{
		IgnoreTimecodeStartOfProgramme: false,
	}

	subtitles, err := astisub.ReadFromSTL(f, opts)
	if err != nil {
		// handle error
	}
	// use subtitles
}