<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\ffmpeg_media\ValueObject\ConversionResult;
use Drupal\media\MediaInterface;

/**
 * Handles HLS/DASH adaptive streaming conversion workflow.
 *
 * @internal
 */
interface AdaptiveStreamingConverterInterface {

  /**
   * Converts a media entity to adaptive streaming format (HLS or DASH).
   *
   * @param \Drupal\media\MediaInterface $media
   *   The media entity to convert.
   * @param string $format
   *   The streaming format: 'hls' or 'dash'.
   * @param string|null $profileId
   *   Optional conversion profile ID.
   * @param string $fieldName
   *   Source field name. When non-empty, this field's formatter context
   *   is used instead of the preferred-context fallback. Required for
   *   multi-field media entities to prevent cross-field collisions.
   *
   * @return \Drupal\ffmpeg_media\ValueObject\ConversionResult
   *   Result of the conversion.
   *
   * @throws \Drupal\ffmpeg_media\Exception\FFmpegException
   *   If conversion fails.
   * @throws \Drupal\ffmpeg_media\Exception\InvalidConfigurationException
   *   If configuration is invalid.
   */
  #[\NoDiscard]
  public function convert(
    MediaInterface $media,
    string $format,
    ?string $profileId = NULL,
    string $fieldName = '',
  ): ConversionResult;

}
