<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\ffmpeg_media\Enum\HardwareType;
use Drupal\ffmpeg_media\Plugin\FFmpegCodec\FFmpegCodecInterface;
use Drupal\ffmpeg_media\Plugin\FFmpegOutput\FFmpegOutputInterface;
use Drupal\ffmpeg_media\ValueObject\ConversionOptions;
use Drupal\ffmpeg_media\ValueObject\VideoInfo;

/**
 * Executes FFmpeg conversions with hardware fallback and progress tracking.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface ConversionExecutorInterface {

  /**
   * Executes FFmpeg conversion with automatic software fallback on HW failure.
   *
   * @param string $sourcePath
   *   Source file path.
   * @param string $outputPath
   *   Output file path.
   * @param \Drupal\ffmpeg_media\Plugin\FFmpegCodec\FFmpegCodecInterface $codecPlugin
   *   Codec plugin.
   * @param \Drupal\ffmpeg_media\Plugin\FFmpegOutput\FFmpegOutputInterface $outputPlugin
   *   Output plugin.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionOptions $conversionOptions
   *   Conversion options.
   * @param \Drupal\ffmpeg_media\ValueObject\VideoInfo|null $videoInfo
   *   Video information.
   * @param int $mediaId
   *   Media entity ID.
   * @param int $baseProgress
   *   Base progress percentage for this output.
   * @param int $totalOutputs
   *   Total number of outputs being converted.
   * @param string $container
   *   Output container format name.
   * @param float|null $totalDuration
   *   Total video duration in seconds.
   * @param bool $synchronous
   *   Whether conversion is synchronous.
   * @param string $fieldName
   *   Scoped media field name for progress updates.
   *
   * @return \Drupal\ffmpeg_media\Enum\HardwareType|null
   *   Hardware type used for circuit breaker tracking.
   */
  public function executeWithFallback(
    string $sourcePath,
    string $outputPath,
    FFmpegCodecInterface $codecPlugin,
    FFmpegOutputInterface $outputPlugin,
    ConversionOptions $conversionOptions,
    ?VideoInfo $videoInfo,
    int $mediaId,
    int $baseProgress,
    int $totalOutputs,
    string $container,
    ?float $totalDuration,
    bool $synchronous,
    string $fieldName = '',
  ): ?HardwareType;

  /**
   * Executes two-pass encoding with progress tracking.
   *
   * @param string $sourcePath
   *   Source file path.
   * @param string $outputPath
   *   Output file path.
   * @param \Drupal\ffmpeg_media\Plugin\FFmpegCodec\FFmpegCodecInterface $codecPlugin
   *   The codec plugin.
   * @param \Drupal\ffmpeg_media\Plugin\FFmpegOutput\FFmpegOutputInterface $outputPlugin
   *   The output plugin.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionOptions $options
   *   Conversion options.
   * @param int $mediaId
   *   Media entity ID.
   * @param string $container
   *   Output container format.
   * @param int $baseProgress
   *   Base progress percentage.
   * @param int $totalOutputs
   *   Total number of outputs.
   * @param string $fieldName
   *   Scoped media field name for progress updates.
   *
   * @return \Drupal\ffmpeg_media\Enum\HardwareType|null
   *   Hardware type used (always NULL for two-pass).
   *
   * @throws \Drupal\ffmpeg_media\Exception\FFmpegException
   *   If encoding fails.
   */
  public function executeTwoPassConversion(
    string $sourcePath,
    string $outputPath,
    FFmpegCodecInterface $codecPlugin,
    FFmpegOutputInterface $outputPlugin,
    ConversionOptions $options,
    int $mediaId,
    string $container,
    int $baseProgress,
    int $totalOutputs,
    string $fieldName = '',
  ): ?HardwareType;

}
