<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\ffmpeg_media\ValueObject\ConversionOptions;
use Drupal\ffmpeg_media\ValueObject\ConversionProfile;

/**
 * Interface for conversion profile management service.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface ProfileManagerInterface {

  /**
   * Cache tag invalidated on profile CRUD operations.
   */
  public const string CACHE_TAG = 'ffmpeg_media_profiles';

  /**
   * Default profile ID.
   */
  public const string DEFAULT_PROFILE = 'av1_opus_webm_mp4';

  /**
   * Gets a conversion profile by ID.
   *
   * @param string $profileId
   *   The profile ID.
   *
   * @return \Drupal\ffmpeg_media\ValueObject\ConversionProfile|null
   *   Profile value object or NULL if not found.
   */
  #[\NoDiscard]
  public function getProfile(string $profileId): ?ConversionProfile;

  /**
   * Gets the default profile.
   *
   * @return \Drupal\ffmpeg_media\ValueObject\ConversionProfile
   *   Default profile value object.
   */
  #[\NoDiscard]
  public function getDefaultProfile(): ConversionProfile;

  /**
   * Gets all configured profiles.
   *
   * @return array<string, \Drupal\ffmpeg_media\ValueObject\ConversionProfile>
   *   Array of profile value objects keyed by ID.
   */
  #[\NoDiscard]
  public function getAllProfiles(): array;

  /**
   * Gets conversion options for a profile and output format.
   *
   * @param string $profileId
   *   The profile ID.
   * @param string $outputFormat
   *   Output format (e.g., 'webm', 'mp4').
   *
   * @return \Drupal\ffmpeg_media\ValueObject\ConversionOptions
   *   Conversion options for the format.
   */
  #[\NoDiscard]
  public function getOptionsForFormat(string $profileId, string $outputFormat): ConversionOptions;

  /**
   * Gets enabled output formats for a profile.
   *
   * @param string $profileId
   *   The profile ID.
   *
   * @return array<int, \Drupal\ffmpeg_media\ValueObject\ProfileOutput>
   *   Array of enabled output configurations.
   */
  #[\NoDiscard]
  public function getEnabledOutputs(string $profileId): array;

  /**
   * Gets enabled processors for a profile.
   *
   * Returns the profile-specific processor list if configured,
   * otherwise falls back to the global enabled_processors setting.
   *
   * @param string $profileId
   *   The profile ID.
   *
   * @return array<int, string>
   *   Array of enabled processor plugin IDs.
   */
  #[\NoDiscard]
  public function getEnabledProcessors(string $profileId): array;

  /**
   * Gets enabled output container names for a profile.
   *
   * @param string $profileId
   *   The profile ID.
   *
   * @return array<int, string>
   *   Array of container names (e.g., ['mp4', 'webm']).
   */
  #[\NoDiscard]
  public function getEnabledOutputContainers(string $profileId): array;

  /**
   * Gets unique output keys for enabled outputs in a profile.
   *
   * Returns codec-qualified keys (e.g., 'mp4:hevc') when the profile has
   * multiple outputs with the same container, and plain keys ('webm') when
   * each container is unique. These keys serve as unique identifiers for
   * output storage and filename generation.
   *
   * @param string $profileId
   *   The profile ID.
   *
   * @return array<int, string>
   *   Output keys (e.g., ['mp4:hevc', 'mp4:h264', 'webm']).
   */
  #[\NoDiscard]
  public function getEnabledOutputKeys(string $profileId): array;

  /**
   * Checks if a profile exists.
   *
   * @param string $profileId
   *   The profile ID.
   *
   * @return bool
   *   TRUE if profile exists.
   */
  #[\NoDiscard]
  public function profileExists(string $profileId): bool;

  /**
   * Validates a profile configuration.
   *
   * @param array{id?: string, label?: string, description?: string, outputs?: array<int, array<string, mixed>>, generate_thumbnail?: bool, thumbnail_timestamp?: float, enabled_processors?: array<int, string>, hardware_acceleration?: string|null} $config
   *   Profile configuration to validate.
   *
   * @return array<int, string>
   *   Array of validation errors (empty if valid).
   */
  #[\NoDiscard]
  public function validateProfile(array $config): array;

  /**
   * Applies global audio defaults as fallback to conversion options.
   *
   * Priority: Profile-specific > Global config > Constructor default.
   * Skips override for lossless audio codecs (flac, pcm_*, copy, alac).
   *
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionOptions $options
   *   Conversion options to apply defaults to.
   *
   * @return \Drupal\ffmpeg_media\ValueObject\ConversionOptions
   *   Options with global audio defaults applied where not already set.
   */
  #[\NoDiscard]
  public function applyGlobalAudioDefaults(ConversionOptions $options): ConversionOptions;

  /**
   * Gets the configured default profile ID.
   *
   * Reads the default_profile setting from config, falling back to
   * the DEFAULT_PROFILE constant if not configured.
   *
   * @return string
   *   The default profile ID.
   */
  #[\NoDiscard]
  public function getDefaultProfileId(): string;

  /**
   * Resets the in-memory profile cache.
   *
   * Call this after saving or deleting a profile to ensure subsequent
   * calls reflect the updated configuration.
   */
  public function resetCache(): void;

}
