Crate subx_core 

SubX Core: Reusable Subtitle Processing Library

subx-core is the library half of the SubX project: the configuration system, the processing engines, the shared error type and the external service integrations, packaged so they can be consumed without the command-line interface. It features AI-powered matching, format conversion, audio synchronization, and advanced encoding detection.

It is licensed under GPL-3.0-or-later and is designed to be consumed by the subx-cli command-line tool, by graphical frontends such as the Tauri GUI at https://github.com/jim60105/subx, and by any Rust program that needs subtitle processing capabilities.

Repository Relationship

In the subx-cli repository this crate is mounted as a git submodule at subx-cli/subx-core/ and built as a Cargo workspace member. It is also a fully standalone crate: a plain git clone of this repository followed by cargo build works without any other repository present, which is the contract that keeps crates.io consumers and docs.rs builds working.

This crate never references subx-cli — not in code, not in an intra-doc link, not in a doctest. The dependency only points the other way, so any such reference would be unresolvable rather than merely stale, and it is rejected by a boundary guard test in the subx-cli repository.

Modules

• config - Configuration management and validation
• core - Core processing engines (formats, matching, sync)
• error - Comprehensive error handling system
• services - External service integrations (AI, audio processing)

Module Path Stability (a deliberate decision, not an oversight)

Engine paths keep the redundant core:: segment: the canonical path of the match engine is core::matcher::MatchEngine, written subx_core::core::matcher::MatchEngine. This stutters, and a flatter subx_core::matcher::… surface would read better in isolation. It is rejected deliberately: these items were reachable at exactly these relative paths under the subx-cli crate’s name for the library’s entire history, and downstream consumers — chiefly the Tauri GUI — reach roughly thirty of them by path. Preserving the tree makes their migration a pure crate-name substitution. Flattening or otherwise reshaping these paths is therefore a breaking change that requires a major version of this crate, and no module is re-exported at the crate root alongside its canonical path, because a second public path would make intra-doc links ambiguous under broken_intra_doc_links = "deny".

Features

• archive-rar - enable RAR archive extraction (optional unrar dependency; without it the archive layer exposes a disabled-feature stub)
• slow-tests - compile long-running format round-trip tests

Examples

Configuration access through the injected service:

use subx_core::config::{ConfigService, TestConfigService};

// Create a configuration service
let config_service = TestConfigService::with_defaults();
let config = config_service.config();

// Use the configuration for processing...

All operations return a Result<T> type that wraps error::SubXError:

use subx_core::{error::SubXError, Result};

fn example_operation() -> Result<String> {
    // This could fail with various error types
    Err(SubXError::config("Missing configuration"))
}

Dependency-injected configuration with AI settings:

use subx_core::config::{Config, TestConfigService};

// Create configuration service with AI settings
let config_service = TestConfigService::with_ai_settings("openai", "gpt-4.1");
let config = config_service.config();

// Access configuration values
println!("AI Provider: {}", config.ai.provider);
println!("AI Model: {}", config.ai.model);

Re-exports

pub use config::Config;

pub use config::ConfigService;

pub use config::EnvironmentProvider;

pub use config::ProductionConfigService;

pub use config::SystemEnvironmentProvider;

pub use config::TestConfigBuilder;

pub use config::TestConfigService;

pub use config::TestEnvironmentProvider;

Modules

config

Configuration management module for SubX.

core

Core processing engine for SubX.

error

Comprehensive error types for the SubX CLI application operations.

services

External services integration for SubX.

Macros

create_default_test_config_service

Create a temporary test configuration service with default settings.

create_production_config_service_with_empty_env

Create a ProductionConfigService with empty environment variables for testing.

create_production_config_service_with_env

Create a temporary ProductionConfigService with environment variable provider for test functions.

create_test_config_service

Create a temporary test configuration service for use in test functions.

test_production_config_with_env

Execute ProductionConfigService tests with specified environment variable mapping.

test_production_config_with_openai_env

Execute ProductionConfigService tests with OPENAI environment variables.

test_with_ai_config

Run a test with specific AI configuration.

test_with_ai_config_and_key

Run a test with specific AI configuration including API key.

test_with_config

Run a test with a custom configuration builder.

test_with_default_config

Run a test with the default configuration.

test_with_parallel_config

Run a test with specific parallel processing configuration.

test_with_sync_config

Run a test with specific sync configuration.

Constants

VERSION

Library version string.

Type Aliases

Result

Convenient type alias for Result<T, SubXError>.