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.
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 ¶
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:
- 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.
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.
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. |