<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\media\MediaInterface;

/**
 * Resolves conversion configuration from media entities and options.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface ConversionConfigResolverInterface {

  /**
   * Resolves conversion configuration from media and options.
   *
   * @param \Drupal\media\MediaInterface $media
   *   Media entity.
   * @param string|null $profileId
   *   Profile ID override.
   * @param array{selected_outputs?: array<int, string>, streaming_options?: array<string, mixed>} $options
   *   Conversion options.
   * @param string $fieldName
   *   Source field name. If empty, uses the first configured context.
   *
   * @return array{context: \Drupal\ffmpeg_media\ValueObject\ConversionContext, sourceFile: \Drupal\file\FileInterface|null, sourcePath: string, enabledOutputs: array<int, \Drupal\ffmpeg_media\ValueObject\ProfileOutput>, profileId: string}
   *   Resolved conversion context.
   *
   * @throws \Drupal\ffmpeg_media\Exception\InvalidConfigurationException
   *   If no formatter configuration exists.
   */
  #[\NoDiscard]
  public function resolve(MediaInterface $media, ?string $profileId, array $options, string $fieldName = ''): array;

  /**
   * Applies streaming option overrides to output configurations.
   *
   * @param array<int, \Drupal\ffmpeg_media\ValueObject\ProfileOutput> $outputs
   *   Array of output configurations.
   * @param array{segment_duration?: int, playlist_type?: string, representations?: array<int, string>} $streamingOptions
   *   Streaming options to apply.
   *
   * @return array<int, \Drupal\ffmpeg_media\ValueObject\ProfileOutput>
   *   Modified output configurations.
   */
  #[\NoDiscard]
  public function applyStreamingOverrides(array $outputs, array $streamingOptions): array;

  /**
   * Builds bitrate ladder from quality level selection.
   *
   * @param array<int, string> $selectedLevels
   *   Selected quality levels (e.g., ['360p', '720p']).
   *
   * @return array<int, array<string, int|string>>
   *   Array of representation configurations.
   */
  #[\NoDiscard]
  public function buildRepresentationsFromSelection(array $selectedLevels): array;

}
