<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Plugin\FFmpegProcessor;

use Drupal\Component\Plugin\PluginInspectionInterface;

/**
 * Interface for FFmpeg processor plugins.
 */
interface FFmpegProcessorInterface extends PluginInspectionInterface {

  /**
   * Processes a video file.
   *
   * @param string $inputPath
   *   Path to input video file.
   * @param string $outputPath
   *   Path to output file.
   * @param array<string, mixed> $options
   *   Processing options specific to this processor.
   *
   * @return bool
   *   TRUE if processing succeeded.
   *
   * @throws \Drupal\ffmpeg_media\Exception\FFmpegException
   *   If processing fails.
   */
  #[\NoDiscard]
  public function process(string $inputPath, string $outputPath, array $options = []): bool;

  /**
   * Checks if this processor is available.
   *
   * @return bool
   *   TRUE if all required FFmpeg features are available.
   */
  #[\NoDiscard]
  public function isAvailable(): bool;

  /**
   * Returns a human-readable reason why the processor is unavailable.
   *
   * Only meaningful when isAvailable() returns FALSE. Returns NULL
   * when the processor is available or when no specific reason can be
   * determined.
   *
   * @return string|null
   *   Diagnostic message or NULL if available.
   */
  #[\NoDiscard]
  public function getUnavailableReason(): ?string;

  /**
   * Gets the human-readable label.
   *
   * @return string
   *   Label.
   */
  #[\NoDiscard]
  public function getLabel(): string;

  /**
   * Gets the type of output produced.
   *
   * @return string
   *   Output type (e.g., 'image', 'text', 'video').
   */
  #[\NoDiscard]
  public function getOutputType(): string;

  /**
   * Gets the default output file extension.
   *
   * @return string
   *   File extension without dot.
   */
  #[\NoDiscard]
  public function getOutputExtension(): string;

  /**
   * Gets the default options for this processor.
   *
   * @return array<string, mixed>
   *   Default processing options.
   */
  #[\NoDiscard]
  public function getDefaultOptions(): array;

  /**
   * Generates the output path for this processor.
   *
   * @param string $inputPath
   *   Path to input file.
   * @param array<string, mixed> $options
   *   Processing options.
   *
   * @return string
   *   Output file path.
   */
  #[\NoDiscard]
  public function generateOutputPath(string $inputPath, array $options = []): string;

}
