<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Provides cached access to frequently-read ffmpeg_media config values.
 *
 * Avoids repeated ConfigFactory::get() calls across multiple services
 * within the same request. The cache is per-request (not persistent).
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface ConfigValueProviderInterface {

  /**
   * Gets the hardware acceleration mode.
   *
   * @return string
   *   Hardware acceleration mode ('auto', 'none', etc.).
   */
  #[\NoDiscard]
  public function getHardwareAcceleration(): string;

  /**
   * Gets the output directory for converted files.
   *
   * @return string
   *   Output directory URI (e.g. 'public://ffmpeg_media').
   */
  #[\NoDiscard]
  public function getOutputDirectory(): string;

  /**
   * Gets the FFmpeg conversion timeout.
   *
   * @return int
   *   Timeout in seconds.
   */
  #[\NoDiscard]
  public function getFfmpegTimeout(): int;

  /**
   * Gets the maximum concurrent conversions.
   *
   * @return int
   *   Maximum concurrent conversions.
   */
  #[\NoDiscard]
  public function getMaxConcurrent(): int;

  /**
   * Gets the FFmpeg binary path.
   *
   * @return string
   *   Path to the FFmpeg binary.
   */
  #[\NoDiscard]
  public function getFfmpegPath(): string;

  /**
   * Gets the FFprobe binary path.
   *
   * @return string
   *   Path to the FFprobe binary.
   */
  #[\NoDiscard]
  public function getFfprobePath(): string;

  /**
   * Gets whether hardware fallback is enabled.
   *
   * @return bool
   *   TRUE if software fallback is enabled on HW encoder failure.
   */
  #[\NoDiscard]
  public function isHardwareFallbackEnabled(): bool;

  /**
   * Gets the enabled processor IDs.
   *
   * @return array<int, string>
   *   Array of enabled processor plugin IDs.
   */
  #[\NoDiscard]
  public function getEnabledProcessors(): array;

  /**
   * Resets the per-request cache.
   *
   * Useful in kernel tests that modify config mid-request.
   */
  public function resetCache(): void;

}
