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 ¶
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.
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 ¶
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.
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 ¶
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:
- Matching language (if lang is non-empty)
- Prefer SRT/subrip over ASS/SSA
- Skip forced tracks (sparse cues)
- Skip tracks matching excludeLang
Returns nil cues if no suitable track is found.
func ParseASSDialogue ¶
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 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.
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:
- If reference subtitle available: try framerate correction, then split-aware alignment, then constant offset
- 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.
Source Files
¶
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. |