<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Interface for FFmpeg/FFprobe binary path detection.
 *
 * @internal
 */
interface FFmpegPathDetectorInterface {

  /**
   * Detects the path to the ffmpeg binary.
   *
   * Scans standard system directories and PATH for the ffmpeg executable.
   *
   * @return string|null
   *   The absolute path to ffmpeg, or NULL if not found.
   */
  #[\NoDiscard]
  public function detectFfmpegPath(): ?string;

  /**
   * Detects the path to the ffprobe binary.
   *
   * Scans standard system directories and PATH for the ffprobe executable.
   *
   * @return string|null
   *   The absolute path to ffprobe, or NULL if not found.
   */
  #[\NoDiscard]
  public function detectFfprobePath(): ?string;

  /**
   * Detects both ffmpeg and ffprobe paths.
   *
   * @return array{ffmpeg: string|null, ffprobe: string|null}
   *   Detected paths for both binaries.
   */
  #[\NoDiscard]
  public function detectPaths(): array;

  /**
   * Checks whether a given path is a valid executable.
   *
   * @param string $path
   *   The file path to check.
   *
   * @return bool
   *   TRUE if the path exists and is executable.
   */
  #[\NoDiscard]
  public function isValidExecutable(string $path): bool;

}
