<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Resolver;

/**
 * Resolves converted video sources for a media entity field.
 *
 * Third-party formatters inject this service to get converted outputs
 * (HLS, DASH, MP4, WebM) along with poster and subtitle tracks for
 * a given media entity. Falls back gracefully when no outputs exist.
 *
 * @see \Drupal\ffmpeg_media\Resolver\ResolvedSources
 */
interface VideoSourceResolverInterface {

  /**
   * Resolves video sources for a media entity field.
   *
   * Returns converted outputs if available. Format priority is determined
   * by the conversion profile or explicit override. When no converted
   * outputs exist, returns an empty sources array with isConverted=false
   * so the formatter can fall back to the original source file.
   *
   * @param int $mediaId
   *   The media entity ID.
   * @param string $fieldName
   *   The source field name on the media entity.
   * @param string|null $profileId
   *   Optional conversion profile ID. When NULL, uses the default profile.
   * @param array<int, string> $formatPriority
   *   Explicit format priority override (e.g., ['hls', 'mp4']). When empty,
   *   the profile's enabled output keys are used.
   *
   * @return \Drupal\ffmpeg_media\Resolver\ResolvedSources
   *   Resolved video sources, poster, and subtitles.
   */
  #[\NoDiscard]
  public function resolveSources(
    int $mediaId,
    string $fieldName,
    ?string $profileId = NULL,
    array $formatPriority = [],
  ): ResolvedSources;

}
