<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\ffmpeg_media\ValueObject\VideoInfo;

/**
 * Interface for bitrate ladder analysis and generation.
 *
 * Implements per-title encoding logic to generate optimized
 * bitrate ladders based on video content complexity.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface BitrateAnalyzerInterface {

  /**
   * Analyzes video and generates optimized bitrate ladder.
   *
   * @param string $inputPath
   *   Path to input video file.
   * @param \Drupal\ffmpeg_media\ValueObject\VideoInfo $videoInfo
   *   Video information from analysis.
   * @param array{max_rungs?: int, min_bitrate?: int, include_source?: bool} $options
   *   Analysis options:
   *   - 'max_rungs': Maximum number of rungs (default: 6)
   *   - 'min_bitrate': Minimum bitrate in kbps (default: 300)
   *   - 'include_source': Include source resolution rung (default: true)
   *
   * @return \Drupal\ffmpeg_media\ValueObject\BitrateRung[]
   *   Optimized bitrate ladder, sorted by resolution descending.
   */
  #[\NoDiscard]
  public function analyzeBitrateLadder(
    string $inputPath,
    VideoInfo $videoInfo,
    array $options = [],
  ): array;

  /**
   * Analyzes video complexity via sample encoding and scene detection.
   *
   * Performs a two-stage analysis to determine how visually complex the
   * video content is. The result drives per-title encoding decisions:
   * simple content (animations, static slides) receives lower bitrates,
   * while complex content (action scenes, detailed textures) receives
   * higher bitrates.
   *
   * Stage 1: Sample CRF encode (primary). Encodes a 10-second sample at
   * CRF 23 with libx264 veryfast preset and measures the resulting
   * bitrate. Low bitrate (500 kbps) indicates simple content; high
   * bitrate (8000+ kbps) indicates complex content.
   *
   * Stage 2: Scene detection (fallback). If the sample encode fails,
   * counts scene changes in the first 60 seconds using FFmpeg's
   * select filter with a 0.3 threshold.
   *
   * Performance: adds approximately 30-60 seconds per hour of source
   * video for the sample encode stage. The scene detection fallback
   * may take up to 3 minutes for a 60-second analysis window. For
   * very short videos (under 30 seconds), the sample encode may
   * produce less accurate results since the 30-second seek offset
   * may exceed the video duration.
   *
   * If both stages fail, returns 0.5 (medium complexity) as a safe
   * default that avoids both under- and over-allocation of bitrate.
   *
   * @param string $inputPath
   *   Absolute filesystem path to the input video file. Must be
   *   readable by the FFmpeg process.
   *
   * @return float
   *   Complexity score from 0.0 (simple, e.g. animation or static
   *   content) to 1.0 (complex, e.g. fast action or dense textures).
   *   Returns 0.5 if analysis fails entirely.
   */
  #[\NoDiscard]
  public function analyzeComplexity(string $inputPath): float;

  /**
   * Gets the standard bitrate ladder for a given resolution.
   *
   * @param int $width
   *   Source video width.
   * @param int $height
   *   Source video height.
   *
   * @return \Drupal\ffmpeg_media\ValueObject\BitrateRung[]
   *   Standard bitrate ladder.
   */
  #[\NoDiscard]
  public function getStandardLadder(int $width, int $height): array;

  /**
   * Adjusts a bitrate ladder based on complexity.
   *
   * @param \Drupal\ffmpeg_media\ValueObject\BitrateRung[] $ladder
   *   Base bitrate ladder.
   * @param float $complexity
   *   Complexity score (0.0-1.0).
   * @param int|null $sourceMaxBitrate
   *   Maximum bitrate from source (cap).
   *
   * @return \Drupal\ffmpeg_media\ValueObject\BitrateRung[]
   *   Adjusted bitrate ladder.
   */
  #[\NoDiscard]
  public function adjustLadderForComplexity(
    array $ladder,
    float $complexity,
    ?int $sourceMaxBitrate = NULL,
  ): array;

}
