<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Contract for optional player configuration resolvers.
 *
 * Implementations may live in optional submodules that provide richer player
 * integrations while core formatter code depends only on this neutral API.
 *
 * @internal
 */
interface PlayerConfigResolverInterface {

  /**
   * Resolves player configuration for a media entity.
   *
   * @param array<string, bool|int|string|null> $formatterSettings
   *   Formatter settings.
   * @param array<int, array{src: string, type: string, quality?: string}> $sources
   *   Video sources.
   * @param int $mediaId
   *   Media entity ID.
   * @param string|null $poster
   *   Poster image URL.
   * @param array<int, array{src: string, kind: string, language: string, label: string}> $subtitles
   *   Subtitle tracks.
   * @param string $title
   *   Media title for Media Session API.
   *
   * @return array<string, bool|int|float|string|array<int, array{src: string, type: string, quality?: string}>|array<int, array{src: string, kind: string, language: string, label: string}>|null>
   *   Player configuration array for JavaScript.
   */
  public function resolve(
    array $formatterSettings,
    array $sources,
    int $mediaId,
    ?string $poster = NULL,
    array $subtitles = [],
    string $title = '',
  ): array;

  /**
   * Gets the default player configuration.
   *
   * @return array<string, bool|int|string|null>
   *   Default configuration array.
   */
  public function getDefaults(): array;

}
