<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Plugin\FFmpegCodec;

use Drupal\Component\Plugin\PluginInspectionInterface;
use Drupal\ffmpeg_media\ValueObject\ConversionOptions;

/**
 * Interface for FFmpeg codec plugins.
 */
interface FFmpegCodecInterface extends PluginInspectionInterface {

  /**
   * Builds FFmpeg arguments for this codec.
   *
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionOptions $options
   *   Conversion options.
   *
   * @return array<int, string>
   *   Array of FFmpeg arguments.
   */
  #[\NoDiscard]
  public function buildArguments(ConversionOptions $options): array;

  /**
   * Checks if this codec is available in the current FFmpeg build.
   *
   * @return bool
   *   TRUE if codec is available.
   */
  #[\NoDiscard]
  public function isAvailable(): bool;

  /**
   * Gets the default conversion options for this codec.
   *
   * @return \Drupal\ffmpeg_media\ValueObject\ConversionOptions
   *   Default options.
   */
  #[\NoDiscard]
  public function getDefaultOptions(): ConversionOptions;

  /**
   * Gets supported container formats for this codec.
   *
   * @return array<int, string>
   *   Array of container format IDs.
   */
  #[\NoDiscard]
  public function getSupportedContainers(): array;

  /**
   * Gets the FFmpeg encoder name.
   *
   * @return string
   *   Encoder name.
   */
  #[\NoDiscard]
  public function getEncoder(): string;

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

  /**
   * Checks if this codec supports hardware acceleration.
   *
   * @return bool
   *   TRUE if hardware accelerated.
   */
  #[\NoDiscard]
  public function isHardwareAccelerated(): bool;

  /**
   * Checks if this codec supports two-pass encoding.
   *
   * @return bool
   *   TRUE if two-pass encoding is supported.
   */
  #[\NoDiscard]
  public function supportsTwoPass(): bool;

  /**
   * Gets recommended options for high quality encoding.
   *
   * @return \Drupal\ffmpeg_media\ValueObject\ConversionOptions
   *   High quality options.
   */
  #[\NoDiscard]
  public function getHighQualityOptions(): ConversionOptions;

  /**
   * Gets recommended options for fast encoding.
   *
   * @return \Drupal\ffmpeg_media\ValueObject\ConversionOptions
   *   Fast encoding options.
   */
  #[\NoDiscard]
  public function getFastEncodingOptions(): ConversionOptions;

}
