subsync

package
v0.10.0-dev.12 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: AGPL-3.0 Imports: 26 Imported by: 0

Documentation

Overview

Package subsync provides subtitle timing synchronization.

It supports multiple sync strategies:

  • Constant-offset alignment (alass algorithm port)
  • Framerate correction (known ratios + golden-section search)
  • Split-aware DP alignment (handles commercial breaks, different cuts)
  • Audio-based sync (energy VAD + FFT cross-correlation, no reference needed)
  • Encoding normalization (UTF-16 and the other forms subtitleenc names with no hint → UTF-8)

The entry point is SyncWithOptions, which takes already-parsed cues and returns the winning SyncResult; audio-only sync is the same call with a nil reference, EnableAudio and SyncOptions.VideoPath set. Callers own file I/O: read the subtitle, decode it (subtitleenc.Detect, then Decode), ParseSRT it, sync, then WriteSRT the corrected cues.

Index

Constants

View Source
const (
	// SourceNone marks a result that did not come from a voted reference
	// strategy (audio results and no-result placeholders).
	SourceNone candidateSource = iota
	// SourceCrosslang is the cross-language anchor alignment strategy.
	SourceCrosslang
	// SourceFramerate is the framerate correction strategy.
	SourceFramerate
	// SourceOffset is the constant-offset (alass) strategy.
	SourceOffset
	// SourceSplit is the split-aware DP alignment strategy.
	SourceSplit
)

Candidate sources in canonical arbitration order.

View Source
const MinCuesForSync = 5

MinCuesForSync is the minimum number of subtitle cues required for any timing-based sync strategy to produce meaningful results. Fewer than this provides insufficient signal for correlation or alignment.

Variables

This section is empty.

Functions

func IsASSContent

func IsASSContent(data []byte) bool

IsASSContent reports whether data looks like ASS/SSA subtitle content by checking for the [Script Info] header or Dialogue: lines.

func PostProcessBytes

func PostProcessBytes(data []byte, opts PostProcessOptions) []byte

PostProcessBytes applies encoding normalization and line ending fixes to raw subtitle bytes. Call this before parsing, or on the final output.

func WriteSRT

func WriteSRT(w io.Writer, cues []Cue) error

WriteSRT writes cues as an SRT file.

Types

type AudioSyncHints

type AudioSyncHints struct {
	// DialogueCues are pre-classified ASS dialogue cues from the native
	// parser. When set, audioSyncFromPCM uses these directly instead of
	// applying text-based heuristics (karaoke pair detection, SDH filtering)
	// to the flat cue list. This produces better results for ASS files
	// because style-based classification is more accurate than text patterns.
	DialogueCues []Cue

	// IsASS indicates the subtitle was ASS-extracted (clean cues, no tag remnants).
	IsASS bool
}

AudioSyncHints provides content characteristics for adaptive strategy selection. Zero values use the default strategy.

type Confidence

type Confidence float64

Confidence represents the quality of a sync operation (0.0 to 1.0).

const ShouldApplyThreshold Confidence = 0.5

ShouldApplyThreshold is the exported minimum confidence for a sync result to be considered applicable. Consumers comparing Result.Confidence against a threshold should use this constant instead of a magic 0.5 literal. It is also the sync engine's own default when no explicit threshold is provided (see DefaultSyncOptions and SyncWithOptions). The API layer's DefaultSyncMinConfidence (0.6) is intentionally stricter for user-facing auto-apply decisions.

type Cue

type Cue struct {
	Text  string
	Start time.Duration
	End   time.Duration
}

Cue represents a single subtitle cue with timing and text content. This is a local definition that mirrors subflux.SubtitleCue, decoupling the subsync package from the application's domain types.

func ExtractEmbeddedSRT

func ExtractEmbeddedSRT(ctx context.Context, videoPath, lang, excludeLang string, mapper ffmpeg.LangMapper) ([]Cue, error)

ExtractEmbeddedSRT extracts text-based subtitle data from a video file and returns it as parsed SRT cues. Uses ffprobe for track detection and ffmpeg for subtitle extraction.

Track selection priority:

  1. Matching language (if lang is non-empty)
  2. Prefer SRT/subrip over ASS/SSA
  3. Skip forced tracks (sparse cues)
  4. Skip tracks matching excludeLang

Returns nil cues if no suitable track is found.

func ParseASSDialogue

func ParseASSDialogue(data []byte) (dialogueCues, maskCues []Cue, err error)

ParseASSDialogue parses raw ASS content and returns dialogue cues and mask cues separately.

dialogueCues: only cues from classified dialogue styles (for subtitle envelope / correlation signal). maskCues: all cues regardless of style classification (for dialogue mask / time region detection). Even OP/ED/signs mark time regions with audio activity, giving broader mask coverage.

Two-pass: first collects all style names and cue counts, classifies them, then extracts cues.

func ParseSRT

func ParseSRT(r io.Reader) ([]Cue, error)

ParseSRT parses an SRT subtitle file into cues.

func PostProcess

func PostProcess(cues []Cue, opts PostProcessOptions) []Cue

PostProcess applies the configured processing steps to subtitle cues. Steps run in order: encoding normalization (on raw bytes before parsing) is handled by the caller; this function operates on parsed cues.

type LangMapper

type LangMapper = ffmpeg.LangMapper

LangMapper is a type alias for ffmpeg.LangMapper, preserving backward compatibility for consumers that reference subsync.LangMapper.

type PostProcessOptions

type PostProcessOptions struct {
	// StripHI removes hearing-impaired annotations:
	// [sound effects], (music playing), ♪ lyrics ♪, and speaker labels (JOHN:).
	StripHI bool

	// StripTags removes HTML-like tags: <i>, </i>, <b>, </b>, <u>, </u>, <font ...>, </font>.
	StripTags bool

	// NormalizeEncoding converts the subtitle to UTF-8 from what subtitleenc
	// names with no language hint (UTF-16, ISO-2022-JP) and strips a UTF-8 BOM;
	// bytes in a legacy page stay as they arrived.
	NormalizeEncoding bool

	// NormalizeLineEndings converts all line endings to CRLF (SRT standard)
	// and ensures a single trailing CRLF.
	NormalizeLineEndings bool

	// CleanWhitespace trims leading/trailing whitespace from each text line
	// and removes blank lines and bare dialogue dashes.
	CleanWhitespace bool

	// RemoveEmpty drops cues that have no text content after all other
	// processing steps. Cue numbers are assigned when writing SRT output.
	RemoveEmpty bool
}

PostProcessOptions configures subtitle post-processing. All fields default to false (no processing). Enable what you need.

type SyncMethod

type SyncMethod string

SyncMethod is a typed string identifying the sync algorithm used.

const (
	MethodNone SyncMethod = "none"

	MethodAudio SyncMethod = "audio"
)

Sync method identifiers.

func (SyncMethod) String

func (m SyncMethod) String() string

String implements fmt.Stringer.

type SyncOptions

type SyncOptions struct {
	// VideoPath is the path to the video file (required for audio sync).
	VideoPath string

	// AudioHints provides content characteristics for adaptive audio
	// sync strategy selection. Optional; zero value uses defaults.
	AudioHints AudioSyncHints

	// SplitPenalty controls split detection sensitivity (0 = default).
	SplitPenalty float64

	// MinConfidence is the minimum confidence to apply a sync result.
	// Default: 0.5.
	MinConfidence Confidence

	// EnableFramerate enables framerate correction detection.
	EnableFramerate bool

	// EnableSplits enables split-aware DP alignment.
	EnableSplits bool

	// EnableAudio enables audio-based sync (requires video file path).
	EnableAudio bool
}

SyncOptions configures the sync behavior.

func DefaultSyncOptions

func DefaultSyncOptions() SyncOptions

DefaultSyncOptions returns sensible defaults.

type SyncResult

type SyncResult struct {
	Method     SyncMethod // MethodNone, methodOffset, methodFramerate, methodSplit, MethodAudio, methodCrosslang
	Cues       []Cue
	Transform  transform       // descriptor of the correction applied to Cues (voted candidates)
	Offset     int64           // milliseconds (constant offset applied)
	Confidence Confidence      // quality of the sync (calibrated; gates read this)
	Rate       float64         // framerate ratio applied (1.0 = no change)
	Source     candidateSource // generating strategy identity (voted candidates)
}

SyncResult holds the output of any sync operation.

func SyncWithOptions

func SyncWithOptions(ctx context.Context, reference, incorrect []Cue, opts *SyncOptions) SyncResult

SyncWithOptions performs multi-strategy subtitle synchronization.

Strategy order:

  1. If reference subtitle available: try framerate correction, then split-aware alignment, then constant offset
  2. If no reference but video path provided and audio enabled: try audio-based sync

Returns the best result above the minimum confidence threshold.

func (*SyncResult) Applied

func (r *SyncResult) Applied() bool

Applied returns true if the sync actually changed the subtitle timing. Checks offset (constant shift), rate (framerate correction), and split method (multi-segment alignment where no single offset/rate captures the change).

func (*SyncResult) ShouldApply

func (r *SyncResult) ShouldApply() bool

ShouldApply returns true if the confidence is high enough to use the result. Threshold: ShouldApplyThreshold (moderate confidence or better). This is the post-hoc check used by callers after sync completes.

Directories

Path Synopsis
Package crosslang implements cross-language subtitle alignment using anchor-based matching and dynamic programming.
Package crosslang implements cross-language subtitle alignment using anchor-based matching and dynamic programming.
Package ffmpeg provides low-level ffmpeg/ffprobe subprocess wrappers for stream probing, subtitle extraction, and PCM audio extraction.
Package ffmpeg provides low-level ffmpeg/ffprobe subprocess wrappers for stream probing, subtitle extraction, and PCM audio extraction.
Package fft provides a radix-2 Cooley-Tukey FFT implementation for cross-correlation in the subsync package.
Package fft provides a radix-2 Cooley-Tukey FFT implementation for cross-correlation in the subsync package.
Package framerate provides framerate drift detection for subtitle alignment.
Package framerate provides framerate drift detection for subtitle alignment.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL