<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\ffmpeg_media\Plugin\FFmpegCodec\FFmpegCodecInterface;
use Drupal\ffmpeg_media\ValueObject\ConversionOptions;

/**
 * Interface for two-pass encoding service.
 *
 * @internal
 */
interface TwoPassEncodingServiceInterface {

  /**
   * Executes two-pass encoding.
   *
   * @param string $inputPath
   *   Path to input video file.
   * @param string $outputPath
   *   Path to output video file.
   * @param \Drupal\ffmpeg_media\Plugin\FFmpegCodec\FFmpegCodecInterface $codec
   *   Codec plugin to use.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionOptions $options
   *   Conversion options.
   *
   * @return bool
   *   TRUE if encoding succeeded.
   *
   * @throws \Drupal\ffmpeg_media\Exception\FFmpegException
   *   If encoding fails.
   */
  #[\NoDiscard]
  public function encode(
    string $inputPath,
    string $outputPath,
    FFmpegCodecInterface $codec,
    ConversionOptions $options,
  ): bool;

  /**
   * Generates a unique passlog file path.
   *
   * @param string $inputPath
   *   Input file path (used for naming).
   *
   * @return string
   *   Path to passlog file (without extension).
   */
  #[\NoDiscard]
  public function generatePasslogPath(string $inputPath): string;

  /**
   * Cleans up passlog files after encoding.
   *
   * @param string $passlogPath
   *   Base path to passlog files.
   */
  public function cleanupPasslog(string $passlogPath): void;

  /**
   * Checks if two-pass encoding is supported for the given codec.
   *
   * @param \Drupal\ffmpeg_media\Plugin\FFmpegCodec\FFmpegCodecInterface $codec
   *   Codec plugin to check.
   *
   * @return bool
   *   TRUE if two-pass is supported.
   */
  #[\NoDiscard]
  public function isTwoPassSupported(FFmpegCodecInterface $codec): bool;

}
