subsync

type AudioSyncHints struct {
	// DialogueCues and MaskCues are pre-classified ASS 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
	MaskCues     []Cue

	// DurationSec is the total media duration in seconds.
	DurationSec int

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

	// DisableVAD skips the GMM VAD fallback (Strategy D). Used for benchmarking
	// to measure the energy-only pipeline's accuracy.
	DisableVAD bool
}

type Confidence float64

type ConfidenceCaps struct {
	Audio                  Confidence // audio-based sync
	Offset                 Confidence // constant-offset sync
	FramerateGSS           Confidence // golden-section framerate search
	FramerateKnown         Confidence // known-ratio framerate match
	FramerateFPS           Confidence // video FPS confirms the ratio
	Crosslang              Confidence // cross-language alignment
	SplitBase              Confidence // split-aware alignment (reduced by segment penalty)
	SplitPenaltyPerSegment Confidence // confidence penalty per additional segment
	SplitMinConf           Confidence // minimum confidence floor for split alignment
}

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

type LangMapper = ffmpeg.LangMapper

type Options struct {
	// PostProcess configures subtitle post-processing (HI removal, tag stripping, etc.).
	// Nil means no post-processing.
	PostProcess *PostProcessOptions

	// Framerate enables framerate correction detection.
	// nil = default (true), non-nil = explicit value.
	Framerate *bool

	// Splits enables split-aware alignment.
	// nil = default (true), non-nil = explicit value.
	Splits *bool

	// Reference is the path to a correctly-timed reference subtitle.
	Reference string

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

	// MinConfidence is the minimum confidence to accept a sync result (default: 0.5).
	MinConfidence float64

	// Audio enables audio-based sync (default: false).
	Audio bool
}

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 any detected encoding
	// (UTF-16 LE/BE, Windows-1252, ISO-8859-1). Also strips UTF-8 BOM.
	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
}

type Result struct {
	// Method describes which strategy produced the result.
	// One of: MethodOffset, MethodFramerate, MethodSplit, MethodAudio, MethodCrosslang, MethodNone.
	Method SyncMethod

	// Data is the synchronized subtitle file content (UTF-8, SRT format).
	Data []byte

	// OffsetMs is the constant offset applied (milliseconds).
	OffsetMs int64

	// Confidence is the quality score of the sync (0.0 to 1.0).
	Confidence Confidence

	// Rate is the framerate ratio applied (1.0 = no change).
	Rate float64

	// Applied is true if the sync changed timing and confidence was sufficient.
	Applied bool
}

type SyncMethod string

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
}

type SyncResult struct {
	Method     SyncMethod // MethodNone, MethodOffset, MethodFramerate, MethodSplit, MethodAudio, MethodCrosslang
	Cues       []Cue
	Offset     int64      // milliseconds (constant offset applied)
	Confidence Confidence // quality of the sync
	Rate       float64    // framerate ratio applied (1.0 = no change)
}

type TimeSpan struct {
	Start int64 // milliseconds
	End   int64
}