Module sync_command

Advanced subtitle synchronization command implementation.

This module provides sophisticated subtitle timing alignment capabilities, using advanced audio analysis techniques to automatically detect optimal subtitle timing or apply manual adjustments. It supports both automatic synchronization through dialogue detection and manual offset application.

Synchronization Methods

Automatic Synchronization

Uses cutting-edge audio analysis to achieve precise timing alignment:

Audio Analysis Pipeline

1. Audio Extraction: Extract audio track from video file
2. Speech Detection: Identify speech segments using voice activity detection
3. Dialogue Recognition: Classify speech vs. non-speech audio content
4. Pattern Matching: Correlate speech timing with subtitle timing
5. Offset Calculation: Determine optimal time shift for best alignment
6. Quality Assessment: Evaluate synchronization confidence and accuracy

Advanced Features

• Multi-language Support: Handle various spoken languages
• Background Noise Filtering: Robust operation in noisy environments
• Music Separation: Distinguish speech from background music
• Confidence Scoring: Quantify synchronization quality

Manual Synchronization

Provides precise control for specific timing adjustments:

• Fixed Offset: Apply uniform time shift to all subtitles
• Fractional Precision: Support for millisecond-level adjustments
• Positive/Negative Shifts: Advance or delay subtitle timing
• Preservation: Maintain relative timing between subtitle entries

Audio Processing Features

Dialogue Detection

• Voice Activity Detection (VAD): Identify speech segments
• Speaker Separation: Handle multiple speakers
• Language Adaptation: Optimize for different languages
• Noise Robustness: Function in challenging audio environments

Quality Analysis

• Speech Ratio: Percentage of audio containing speech
• Confidence Metrics: Reliability indicators for sync quality
• Timing Validation: Verify subtitle timing consistency
• Content Alignment: Ensure subtitles match spoken content

Configuration Integration

The synchronization system respects comprehensive configuration:

[sync]
max_offset_seconds = 30.0           # Maximum search range
correlation_threshold = 0.8         # Minimum correlation for acceptance
dialogue_detection_threshold = 0.6  # Speech detection sensitivity
min_dialogue_duration_ms = 500      # Minimum speech segment length
enable_dialogue_detection = true    # Enable advanced audio analysis

Performance Optimization

• Efficient Audio Processing: Optimized algorithms for speed
• Memory Management: Streaming processing for large files
• Parallel Processing: Multi-threaded analysis where possible
• Caching: Results cached for repeated operations

Examples

use subx_cli::cli::SyncArgs;
use subx_cli::commands::sync_command;
use std::path::PathBuf;

// Automatic synchronization
let auto_sync = SyncArgs {
    video: PathBuf::from("movie.mp4"),
    subtitle: PathBuf::from("subtitle.srt"),
    offset: None,
    batch: false,
    range: Some(20.0),
    threshold: Some(0.85),
};
sync_command::execute(auto_sync).await?;

// Manual offset adjustment
let manual_sync = SyncArgs {
    video: PathBuf::from("episode.mkv"),
    subtitle: PathBuf::from("episode.srt"),
    offset: Some(2.5), // Delay by 2.5 seconds
    batch: false,
    range: None,
    threshold: None,
};
sync_command::execute(manual_sync).await?;

Functions

execute

Execute advanced subtitle synchronization with audio analysis or manual adjustment.

execute_with_config

Execute audio-subtitle synchronization with injected configuration service.