<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Resolves the preferred audio codec for a given container format.
 *
 * Negotiates between the user's global audio codec preference (from config)
 * and the target container's supported audio codecs. Returns the preferred
 * codec if compatible, otherwise falls back to the first supported
 * royalty-free codec for that container.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface AudioCodecResolverInterface {

  /**
   * Resolves the best audio codec for a container.
   *
   * @param string|null $containerId
   *   Output plugin ID (e.g., 'mp4', 'webm', 'flv', 'hls', 'dash').
   *   NULL returns the raw global preference.
   *
   * @return string
   *   FFmpeg encoder name (e.g., 'libopus', 'aac', 'mp3').
   */
  #[\NoDiscard]
  public function resolve(?string $containerId = NULL): string;

  /**
   * Returns the global default audio codec from config.
   *
   * @return string
   *   FFmpeg encoder name.
   */
  #[\NoDiscard]
  public function getGlobalDefault(): string;

  /**
   * Returns codecs compatible with a container, sorted by preference.
   *
   * The user's preferred codec is listed first if compatible.
   * Used by forms to populate dropdowns with only valid options.
   *
   * @param string $containerId
   *   Output plugin ID.
   *
   * @return array<string, string>
   *   Codec ID => human label, sorted by preference.
   */
  #[\NoDiscard]
  public function getCompatibleCodecs(string $containerId): array;

}
