<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\ffmpeg_media\ValueObject\ConversionOptions;
use Drupal\ffmpeg_media\ValueObject\HwAccelOptions;

/**
 * Interface for hardware-accelerated encoding pipeline builder.
 *
 * @internal
 */
interface HardwarePipelineInterface {

  /**
   * Builds a complete hardware encoding pipeline.
   *
   * @param string $codec
   *   Target codec (h264, hevc, av1, vp9).
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionOptions $options
   *   Conversion options.
   * @param \Drupal\ffmpeg_media\ValueObject\HwAccelOptions|null $hwAccel
   *   Hardware acceleration options or NULL for auto-detect.
   *
   * @return array{init_args: array<string>, decode_args: array<string>, filter_complex: string|null, encode_args: array<string>, encoder: string|null}
   *   Array with keys:
   *   - 'init_args': Device initialization arguments.
   *   - 'decode_args': Hardware decoding arguments.
   *   - 'filter_complex': Filter chain string or NULL.
   *   - 'encode_args': Encoder arguments.
   *   - 'encoder': Hardware encoder name or NULL.
   */
  #[\NoDiscard]
  public function buildPipeline(
    string $codec,
    ConversionOptions $options,
    ?HwAccelOptions $hwAccel = NULL,
  ): array;

  /**
   * Builds the filter_complex string for hardware processing.
   *
   * @param \Drupal\ffmpeg_media\ValueObject\HwAccelOptions $hwAccel
   *   Hardware acceleration options.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionOptions $options
   *   Conversion options including scaling, etc.
   *
   * @return string|null
   *   Filter chain string or NULL if no filters needed.
   */
  #[\NoDiscard]
  public function buildFilterComplex(
    HwAccelOptions $hwAccel,
    ConversionOptions $options,
  ): ?string;

  /**
   * Builds encoder-specific arguments.
   *
   * @param string $codec
   *   Target codec.
   * @param \Drupal\ffmpeg_media\ValueObject\HwAccelOptions $hwAccel
   *   Hardware acceleration options.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionOptions $options
   *   Conversion options.
   *
   * @return array<string>
   *   Encoder arguments.
   */
  #[\NoDiscard]
  public function buildEncodeArgs(
    string $codec,
    HwAccelOptions $hwAccel,
    ConversionOptions $options,
  ): array;

  /**
   * Gets complete FFmpeg command arguments for hardware encoding.
   *
   * @param string $inputPath
   *   Input file path.
   * @param string $outputPath
   *   Output file path.
   * @param string $codec
   *   Target codec.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionOptions $options
   *   Conversion options.
   * @param \Drupal\ffmpeg_media\ValueObject\HwAccelOptions|null $hwAccel
   *   Hardware options or NULL for auto-detect.
   *
   * @return array<string>
   *   Complete FFmpeg arguments.
   */
  #[\NoDiscard]
  public function getFullCommandArgs(
    string $inputPath,
    string $outputPath,
    string $codec,
    ConversionOptions $options,
    ?HwAccelOptions $hwAccel = NULL,
  ): array;

}
