<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\VideoFilter;

/**
 * Interface for services that contribute video filters to conversions.
 *
 * Implementations are collected via the 'ffmpeg_media.video_filter_provider'
 * service tag and invoked by the VideoFilterCollector during FFmpeg command
 * building. This allows submodules to inject filters (watermark, HDR tone
 * mapping, etc.) into the main conversion command without coupling to the
 * core conversion pipeline.
 *
 * Filters apply to all conversion types: single-output (MP4, WebM, MKV),
 * adaptive streaming (HLS, DASH), and any future output format.
 */
interface VideoFilterProviderInterface {

  /**
   * Returns video filters for a given conversion context.
   *
   * Called once per output during command building. Return NULL to abstain
   * (no filter contribution for this context).
   *
   * @param \Drupal\ffmpeg_media\VideoFilter\FilterContext $context
   *   The conversion context (source path, output type, profile, etc.).
   *
   * @return \Drupal\ffmpeg_media\VideoFilter\VideoFilterResult|null
   *   Filter result with filter_complex fragment and optional extra inputs,
   *   or NULL if this provider has nothing to contribute.
   */
  public function getFilter(FilterContext $context): ?VideoFilterResult;

  /**
   * Returns the weight for ordering among filter providers.
   *
   * Lower weights run first. Recommended ranges:
   * - 0-10: Input normalization (HDR tone mapping, deinterlace)
   * - 10-20: Scaling, cropping
   * - 20-30: Overlays (watermark, logo)
   * - 30-40: Output adjustments (subtitles burn-in)
   *
   * @return int
   *   The provider weight.
   */
  public function getWeight(): int;

}
