Function execute

pub async fn execute(
    args: &SyncArgs,
    config_service: &dyn ConfigService,
) -> Result<()>

Execute advanced subtitle synchronization with audio analysis or manual adjustment.

This function orchestrates the complete synchronization workflow, supporting both automatic audio-based timing correction and manual offset application. It includes comprehensive audio analysis, dialogue detection, and timing validation to ensure optimal subtitle-audio alignment.

Synchronization Workflow

Automatic Mode (no offset specified)

1. Configuration Setup: Load sync parameters and thresholds
2. Audio Analysis: Extract and analyze audio from video file
3. Dialogue Detection: Identify speech segments and timing patterns
4. Pattern Correlation: Match speech timing with subtitle timing
5. Offset Optimization: Find optimal time shift for best alignment
6. Quality Validation: Assess synchronization confidence and accuracy
7. Application: Apply calculated offset to subtitle file

Manual Mode (offset specified)

1. Configuration Loading: Load basic sync settings
2. Subtitle Loading: Parse and validate subtitle file
3. Offset Application: Apply specified time shift uniformly
4. Validation: Verify timing consistency after adjustment
5. Output: Save synchronized subtitle file

Audio Analysis Features

When dialogue detection is enabled, the system provides:

• Speech Segment Detection: Identify when characters are speaking
• Speech Ratio Analysis: Calculate percentage of audio containing speech
• Quality Metrics: Assess suitability for automatic synchronization
• Confidence Scoring: Quantify reliability of detected patterns

Configuration Parameters

The function uses configuration settings to optimize performance:

• max_offset_seconds: Maximum search range for automatic sync
• correlation_threshold: Minimum correlation required for acceptance
• dialogue_detection_threshold: Sensitivity for speech detection
• min_dialogue_duration_ms: Minimum length of valid speech segments

Arguments

• args - Synchronization arguments containing:
  • video: Video file path for audio analysis
  • subtitle: Subtitle file path to be synchronized
  • offset: Optional manual offset in seconds (overrides auto-detection)
  • batch: Enable batch processing mode
  • range: Override maximum offset search range
  • threshold: Override correlation threshold

Returns

Returns Ok(()) on successful synchronization, or an error describing:

• Configuration loading failures
• Video file access or audio extraction problems
• Subtitle file parsing or validation issues
• Synchronization processing errors
• Output file creation problems

Error Handling

Comprehensive error handling addresses:

• Input Validation: File existence, format support, accessibility
• Audio Processing: Codec support, extraction failures, analysis errors
• Synchronization: Pattern matching failures, correlation issues
• Output Generation: File writing, format validation, backup creation

Quality Assurance

The synchronization process includes multiple quality checks:

• Input Validation: Verify video and subtitle file integrity
• Audio Quality: Assess audio suitability for analysis
• Sync Confidence: Evaluate reliability of calculated offsets
• Output Verification: Validate synchronized subtitle timing

Examples

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

// High-precision automatic sync
let precise_sync = SyncArgs {
    video: PathBuf::from("documentary.mp4"),
    subtitle: PathBuf::from("documentary.srt"),
    offset: None,
    batch: false,
    range: Some(10.0),    // Narrow search range
    threshold: Some(0.9), // High confidence required
};
sync_command::execute(precise_sync).await?;

// Permissive automatic sync for challenging content
let permissive_sync = SyncArgs {
    video: PathBuf::from("action_movie.mkv"),
    subtitle: PathBuf::from("action_movie.srt"),
    offset: None,
    batch: false,
    range: Some(45.0),    // Wide search range
    threshold: Some(0.7), // Lower confidence threshold
};
sync_command::execute(permissive_sync).await?;

// Fine manual adjustment
let fine_tune = SyncArgs {
    video: PathBuf::from("episode.mp4"),
    subtitle: PathBuf::from("episode.srt"),
    offset: Some(0.75), // 750ms delay
    batch: false,
    range: None,
    threshold: None,
};
sync_command::execute(fine_tune).await?;

Performance Notes

• Audio Processing: CPU-intensive, may take time for long videos
• Memory Usage: Proportional to video length and audio quality
• Disk I/O: Temporary files created during audio extraction
• Optimization: Results cached for repeated operations on same files

Execute advanced subtitle synchronization with dependency injection.

This function orchestrates the complete synchronization workflow using dependency injection for configuration management, supporting both automatic audio-based timing correction and manual offset application.

Arguments

• args - Synchronization arguments including video/subtitle paths and settings
• config_service - Configuration service providing access to sync settings

Returns

Returns Ok(()) on successful completion, or an error if synchronization fails.

Examples

use subx_cli::commands::sync_command;
use subx_cli::cli::SyncArgs;
use subx_cli::config::ProductionConfigService;
use std::path::PathBuf;
use std::sync::Arc;

let config_service = Arc::new(ProductionConfigService::new()?);
let args = SyncArgs {
    video: PathBuf::from("movie.mp4"),
    subtitle: PathBuf::from("movie.srt"),
    offset: None,
    batch: false,
    range: Some(15.0),
    threshold: Some(0.8),
};

sync_command::execute(&args, config_service.as_ref()).await?;