namespace ytLive.Services.Encoder;

/// <summary>
/// Resolves an absolute path to a usable <c>ffmpeg.exe</c>, downloading it on
/// first use if neither the user's PATH nor the local cache provides one — the
/// encoder's one external dependency is never shipped in the repo (TASK 4 ship
/// step 2; see TASKS.md). Seam so the encoder step and the tests can fake it.
/// </summary>
public interface IFfmpegLocator
{
    /// <summary>
    /// Returns the path to <c>ffmpeg.exe</c>: the first PATH candidate that
    /// exists, else the cached copy, else a freshly downloaded one (ffmpeg.exe +
    /// its libav DLLs extracted from the pinned BtbN LGPL-shared zip into the
    /// tools directory).
    /// </summary>
    /// <exception cref="IOException">The download/extract produced no usable
    /// binary (offline, expired pin, corrupt archive) — recoverable, logged.</exception>
    Task<string> LocateAsync(CancellationToken cancellationToken = default);
}