<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\ffmpeg_media\ValueObject\ConversionContext;
use Drupal\ffmpeg_media\ValueObject\VideoInfo;
use Drupal\media\MediaInterface;

/**
 * Interface for running the FFmpeg processor pipeline.
 *
 * Orchestrates enabled processors (thumbnail, GIF, HDR, watermark, etc.)
 * against a source video, storing outputs to mapped fields.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface ProcessorPipelineRunnerInterface {

  /**
   * Runs all enabled processors against a source video.
   *
   * @param \Drupal\media\MediaInterface $media
   *   Media entity.
   * @param string $sourcePath
   *   Path to source video file.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionContext $context
   *   Conversion context.
   * @param \Drupal\ffmpeg_media\ValueObject\VideoInfo|null $videoInfo
   *   Video information, if available.
   * @param string|null $profileId
   *   Conversion profile ID. If NULL, uses global processor settings.
   *
   * @return array<string, string>
   *   Array of processor outputs keyed by processor type.
   */
  #[\NoDiscard]
  public function runProcessorPipeline(
    MediaInterface $media,
    string $sourcePath,
    ConversionContext $context,
    ?VideoInfo $videoInfo,
    ?string $profileId = NULL,
  ): array;

  /**
   * Checks if video content is HDR.
   *
   * @param \Drupal\ffmpeg_media\ValueObject\VideoInfo|null $videoInfo
   *   Video information.
   *
   * @return bool
   *   TRUE if content appears to be HDR.
   */
  #[\NoDiscard]
  public function isHdrContent(?VideoInfo $videoInfo): bool;

  /**
   * Gets MIME type for a processor's output.
   *
   * @param string $processorId
   *   Processor ID.
   *
   * @return string
   *   MIME type.
   */
  #[\NoDiscard]
  public function getMimeTypeForProcessor(string $processorId): string;

}
