subsync

package
v0.10.0-dev.34 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: AGPL-3.0 Imports: 27 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 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).

type Cue

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

Cue is one subtitle cue with its timing and text.

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.

type LangMapper

type LangMapper = ffmpeg.LangMapper

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

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