<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Interface for parsing FFmpeg progress output.
 *
 * @internal
 */
interface ProgressParserInterface {

  /**
   * Parses progress percentage from FFmpeg output.
   *
   * Supports three FFmpeg time formats:
   * - out_time_ms (microseconds)
   * - out_time (HH:MM:SS.microseconds)
   * - time (HH:MM:SS.XX)
   *
   * @param string $buffer
   *   FFmpeg stderr output buffer.
   * @param float|null $totalDuration
   *   Total video duration in seconds.
   *
   * @return int|null
   *   Progress percentage (0-99) or NULL if cannot parse.
   */
  #[\NoDiscard]
  public function parseProgress(string $buffer, ?float $totalDuration): ?int;

  /**
   * Parses elapsed encoding time from FFmpeg output.
   *
   * Extracts the current encoding position in seconds from FFmpeg output,
   * useful when total duration is unknown and percentage cannot be computed.
   *
   * @param string $buffer
   *   FFmpeg stderr output buffer.
   *
   * @return float|null
   *   Elapsed encoding time in seconds, or NULL if cannot parse.
   */
  #[\NoDiscard]
  public function parseElapsedTime(string $buffer): ?float;

}
