<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\ffmpeg_media\ValueObject\OutputExecutionRequest;
use Drupal\ffmpeg_media\ValueObject\ConversionResult;
use Drupal\media\MediaInterface;

/**
 * Executes configured output conversions for a media item.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface OutputExecutionRunnerInterface {

  /**
   * Runs all configured outputs for a conversion request.
   *
   * @param \Drupal\ffmpeg_media\ValueObject\OutputExecutionRequest $request
   *   Typed request data for the current output execution run.
   *
   * @return array{
   *   outputs: array<string, string>,
   *   failedOutputs: array<string, string>,
   *   hardwareType: \Drupal\ffmpeg_media\Enum\HardwareType|null
   *   }
   *   Successful outputs, failed outputs, and last hardware type used.
   */
  #[\NoDiscard]
  public function run(OutputExecutionRequest $request): array;

  /**
   * Delegates adaptive conversion to the streaming converter.
   *
   * @param \Drupal\media\MediaInterface $media
   *   Media entity being converted.
   * @param string $format
   *   Adaptive output format, for example `hls` or `dash`.
   * @param string|null $profileId
   *   Optional profile ID to use for conversion.
   * @param string $fieldName
   *   Source field name for multi-field scoping. Empty string uses
   *   the preferred-context fallback.
   *
   * @return \Drupal\ffmpeg_media\ValueObject\ConversionResult
   *   Conversion result for the adaptive output.
   */
  #[\NoDiscard]
  public function convertAdaptive(MediaInterface $media, string $format, ?string $profileId = NULL, string $fieldName = ''): ConversionResult;

}
