<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Plugin\FFmpegOutput;

use Drupal\Component\Plugin\PluginInspectionInterface;
use Drupal\ffmpeg_media\ValueObject\ConversionOptions;

/**
 * Interface for FFmpeg output format plugins.
 */
interface FFmpegOutputInterface extends PluginInspectionInterface {

  /**
   * Builds FFmpeg arguments for this output format.
   *
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionOptions $options
   *   Conversion options.
   *
   * @return array<int, string>
   *   Array of FFmpeg arguments.
   */
  #[\NoDiscard]
  public function buildArguments(ConversionOptions $options): array;

  /**
   * Generates output file path.
   *
   * @param string $inputPath
   *   Path to input file.
   *
   * @return string
   *   Output file path.
   */
  #[\NoDiscard]
  public function generateOutputPath(string $inputPath): string;

  /**
   * Gets the file extension for this output.
   *
   * @return string
   *   File extension without dot.
   */
  #[\NoDiscard]
  public function getExtension(): string;

  /**
   * Gets the MIME type for this output.
   *
   * @return string
   *   MIME type.
   */
  #[\NoDiscard]
  public function getMimeType(): string;

  /**
   * Gets the human-readable label.
   *
   * @return string
   *   Label.
   */
  #[\NoDiscard]
  public function getLabel(): string;

  /**
   * Gets supported codec plugin IDs.
   *
   * @return array<int, string>
   *   Array of supported codec IDs.
   */
  #[\NoDiscard]
  public function getSupportedCodecs(): array;

  /**
   * Gets the default codec plugin ID.
   *
   * @return string
   *   Default codec ID.
   */
  #[\NoDiscard]
  public function getDefaultCodec(): string;

  /**
   * Checks if a codec is supported by this output format.
   *
   * @param string $codecId
   *   Codec plugin ID.
   *
   * @return bool
   *   TRUE if codec is supported.
   */
  #[\NoDiscard]
  public function supportsCodec(string $codecId): bool;

  /**
   * Checks if this output is a streaming output (not a file).
   *
   * Streaming outputs like WHIP and RTP produce URLs instead of files.
   * This affects how the output is processed and stored.
   *
   * @return bool
   *   TRUE if this is a streaming output, FALSE for file-based outputs.
   */
  #[\NoDiscard]
  public function isStreamingOutput(): bool;

  /**
   * Gets supported audio codec IDs.
   *
   * @return array<int, string>
   *   Array of supported audio codec IDs. Empty array means all are allowed.
   */
  #[\NoDiscard]
  public function getSupportedAudioCodecs(): array;

  /**
   * Checks if an audio codec is supported by this output format.
   *
   * @param string $audioCodecId
   *   Audio codec ID (e.g. 'aac', 'libopus', 'libvorbis').
   *
   * @return bool
   *   TRUE if the audio codec is supported.
   */
  #[\NoDiscard]
  public function supportsAudioCodec(string $audioCodecId): bool;

  /**
   * Checks if this output format supports audio.
   *
   * Image-only formats like JPEG-XL do not support audio streams.
   *
   * @return bool
   *   TRUE if audio is supported, FALSE for image-only formats.
   */
  #[\NoDiscard]
  public function supportsAudio(): bool;

}
