"""Domain-specific plugin interface for media processing (write / file manipulation)"""

# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/processing_interface.ipynb.

# %% auto #0
__all__ = ['MediaProcessingPlugin']

# %% ../nbs/processing_interface.ipynb #637ec895
from abc import abstractmethod
from pathlib import Path
from typing import Any, Dict, Optional, Union

from cjm_plugin_system.core.interface import PluginInterface

from .core import MediaMetadata

# %% ../nbs/processing_interface.ipynb #8ceb559d
class MediaProcessingPlugin(PluginInterface):
    """
    Abstract base class for plugins that modify, convert, or extract media.
    
    Processing plugins perform write operations that produce new files
    (format conversion, segment extraction, re-encoding, etc.).
    """
    
    entry_point_group = "media.processing_plugins"

    @abstractmethod
    def execute(
        self,
        action: str = "get_info",  # Operation: 'get_info', 'convert', 'extract_segment'
        **kwargs
    ) -> Dict[str, Any]:  # JSON-serializable result (usually containing 'output_path')
        """Execute a media processing operation."""
        ...

    @abstractmethod
    def get_info(
        self,
        file_path: Union[str, Path]  # Path to media file
    ) -> MediaMetadata:  # File metadata (duration, codec, streams)
        """Get metadata for a media file."""
        ...

    @abstractmethod
    def convert(
        self,
        input_path: Union[str, Path],  # Source file path
        output_format: str,            # Target format (e.g., 'mp4', 'wav')
        **kwargs
    ) -> str:  # Path to converted file
        """Convert media to a different format."""
        ...

    @abstractmethod
    def extract_segment(
        self,
        input_path: Union[str, Path],      # Source file path
        start: float,                       # Start time in seconds
        end: float,                         # End time in seconds
        output_path: Optional[str] = None   # Custom output path (auto-generated if None)
    ) -> str:  # Path to extracted segment file
        """Extract a temporal segment from a media file."""
        ...
