<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Interface for progress label humanization service.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface ProgressLabelServiceInterface {

  /**
   * Converts a technical step label to a human-readable string.
   *
   * @param string $step
   *   The technical step string (e.g., "Converting to mp4").
   * @param string|null $currentOutput
   *   The current output format, if known.
   * @param int $currentOutputIndex
   *   Zero-based index of the current output being processed.
   * @param int $totalOutputs
   *   Total number of outputs to process.
   *
   * @return string
   *   Human-readable step label.
   */
  #[\NoDiscard]
  public function humanize(string $step, ?string $currentOutput, int $currentOutputIndex, int $totalOutputs): string;

  /**
   * Estimates time remaining based on elapsed time and progress.
   *
   * @param int $startedAt
   *   Unix timestamp when conversion started.
   * @param int $progressPercent
   *   Current progress percentage (0-100).
   *
   * @return string|null
   *   Human-readable ETA string, or NULL if insufficient data.
   */
  #[\NoDiscard]
  public function getEstimatedCompletion(int $startedAt, int $progressPercent): ?string;

}
