<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media_image\Service;

/**
 * Interface for thumbnail generation service.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface ThumbnailGeneratorServiceInterface {

  /**
   * Generates thumbnail previews at intervals throughout a video.
   *
   * @param string $videoPath
   *   Path to the video file.
   * @param float $duration
   *   Video duration in seconds.
   * @param int|null $count
   *   Number of thumbnails to generate.
   * @param int|null $width
   *   Thumbnail width in pixels.
   *
   * @return array<int, array{path: string, uri: string, url: string, timestamp: float, time_formatted: string, index: int}>
   *   Array of thumbnail data with keys:
   *   - path: File path
   *   - uri: Stream wrapper URI
   *   - url: Public URL
   *   - timestamp: Position in video (seconds)
   *   - time_formatted: Human-readable time
   *   - index: Thumbnail index
   */
  #[\NoDiscard]
  public function generateThumbnails(
    string $videoPath,
    float $duration,
    ?int $count = NULL,
    ?int $width = NULL,
  ): array;

  /**
   * Finds existing recent thumbnails for a video.
   *
   * Checks if thumbnails were recently generated for the same video
   * path, duration, count, and width, returning them if still fresh.
   *
   * @param string $videoPath
   *   Path to the video file.
   * @param float $duration
   *   Video duration in seconds.
   * @param string|null $videoHash
   *   Pre-computed video hash, or NULL to compute from defaults.
   * @param int|null $count
   *   Expected thumbnail count for timestamp reconstruction.
   *
   * @return array<int, array{path: string, uri: string, url: string, timestamp: float, time_formatted: string, index: int}>|null
   *   Existing thumbnail data if found and recent, or NULL.
   */
  #[\NoDiscard]
  public function findExistingThumbnails(string $videoPath, float $duration, ?string $videoHash = NULL, ?int $count = NULL): ?array;

  /**
   * Generates a single thumbnail at a specific timestamp.
   *
   * @param string $videoPath
   *   Path to the video file.
   * @param string $outputPath
   *   Path for the output thumbnail.
   * @param float $timestamp
   *   Position in video (seconds).
   * @param int $width
   *   Thumbnail width.
   *
   * @return bool
   *   TRUE if successful.
   */
  public function generateSingleThumbnail(
    string $videoPath,
    string $outputPath,
    float $timestamp,
    int $width = 160,
  ): bool;

  /**
   * Generates a high-quality poster image at a specific timestamp.
   *
   * @param string $videoPath
   *   Path to the video file.
   * @param string $outputPath
   *   Path for the output poster.
   * @param float $timestamp
   *   Position in video (seconds).
   * @param int|null $width
   *   Poster width (NULL for original).
   *
   * @return bool
   *   TRUE if successful.
   */
  public function generatePoster(
    string $videoPath,
    string $outputPath,
    float $timestamp,
    ?int $width = NULL,
  ): bool;

  /**
   * Cleans up temporary thumbnail files.
   *
   * @param array<int, array{path: string, uri: string, url: string, timestamp: float, time_formatted: string, index: int}> $thumbnails
   *   Array of thumbnail data from generateThumbnails().
   */
  public function cleanup(array $thumbnails): void;

}
