src/domain/interfaces/audio_processing.py

"""
Audio processing service interface.

This module defines the core interface for audio processing pipeline orchestration.
The interface follows Domain-Driven Design principles, providing a clean contract
for the complete audio translation workflow.

Example:
    ```python
    from src.domain.interfaces.audio_processing import IAudioProcessingService
    from src.domain.models.audio_content import AudioContent
    from src.domain.models.voice_settings import VoiceSettings

    # Get service implementation from DI container
    audio_service = container.resolve(IAudioProcessingService)

    # Process audio through complete pipeline
    result = audio_service.process_audio_pipeline(
        audio=audio_content,
        target_language="zh",
        voice_settings=voice_settings
    )
    ```
"""

from abc import ABC, abstractmethod
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from ..models.audio_content import AudioContent
    from ..models.voice_settings import VoiceSettings
    from ..models.processing_result import ProcessingResult


class IAudioProcessingService(ABC):
    """
    Interface for audio processing pipeline orchestration.

    This interface defines the contract for the complete audio translation pipeline,
    coordinating Speech-to-Text, Translation, and Text-to-Speech services to provide
    end-to-end audio translation functionality.

    The interface is designed to be:
    - Provider-agnostic: Works with any STT/Translation/TTS implementation
    - Error-resilient: Handles failures gracefully with appropriate exceptions
    - Observable: Provides detailed processing results and metadata
    - Testable: Easy to mock for unit testing

    Implementations should handle:
    - Provider selection and fallback logic
    - Error handling and recovery
    - Performance monitoring and logging
    - Resource cleanup and management
    """

    @abstractmethod
    def process_audio_pipeline(
        self,
        audio: 'AudioContent',
        target_language: str,
        voice_settings: 'VoiceSettings'
    ) -> 'ProcessingResult':
        """
        Process audio through the complete pipeline: STT -> Translation -> TTS.

        This method orchestrates the complete audio translation workflow:
        1. Speech Recognition: Convert audio to text
        2. Translation: Translate text to target language (if needed)
        3. Speech Synthesis: Convert translated text back to audio

        The implementation should:
        - Validate input parameters
        - Handle provider failures with fallback mechanisms
        - Provide detailed error information on failure
        - Clean up temporary resources
        - Log processing steps for observability

        Args:
            audio: The input audio content to process. Must be a valid AudioContent
                  instance with supported format and reasonable duration.
            target_language: The target language code for translation (e.g., 'zh', 'es', 'fr').
                           Must be supported by the translation provider.
            voice_settings: Voice configuration for TTS synthesis including voice ID,
                          speed, and language preferences.

        Returns:
            ProcessingResult: Comprehensive result containing:
                - success: Boolean indicating overall success
                - original_text: Transcribed text from STT (if successful)
                - translated_text: Translated text (if translation was performed)
                - audio_output: Generated audio content (if TTS was successful)
                - processing_time: Total processing duration in seconds
                - error_message: Detailed error description (if failed)
                - metadata: Additional processing information and metrics

        Raises:
            AudioProcessingException: If any step in the pipeline fails and cannot
                                    be recovered through fallback mechanisms.
            ValueError: If input parameters are invalid or unsupported.

        Example:
            ```python
            # Create audio content from file
            with open("input.wav", "rb") as f:
                audio = AudioContent(
                    data=f.read(),
                    format="wav",
                    sample_rate=16000,
                    duration=10.5
                )

            # Configure voice settings
            voice_settings = VoiceSettings(
                voice_id="kokoro",
                speed=1.0,
                language="zh"
            )

            # Process through pipeline
            result = service.process_audio_pipeline(
                audio=audio,
                target_language="zh",
                voice_settings=voice_settings
            )

            if result.success:
                print(f"Original: {result.original_text}")
                print(f"Translated: {result.translated_text}")
                # Save output audio
                with open("output.wav", "wb") as f:
                    f.write(result.audio_output.data)
            else:
                print(f"Processing failed: {result.error_message}")
            ```
        """
        pass