<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

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

/**
 * Interface for subtitle track preparation and conversion.
 *
 * Handles extracting subtitle files from media entities, converting
 * formats to WebVTT, and language code detection/normalization.
 *
 * @internal
 */
interface SubtitleHandlerInterface {

  /**
   * Prepares subtitle tracks from a media entity.
   *
   * @param \Drupal\media\MediaInterface $media
   *   Media entity.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionContext $context
   *   Conversion context.
   *
   * @return array{tracks: array<\Drupal\ffmpeg_media\ValueObject\SubtitleTrack>, tempFiles: array<string>}
   *   Prepared subtitle tracks and temporary files to clean up.
   */
  #[\NoDiscard]
  public function prepareSubtitleTracks(
    MediaInterface $media,
    ConversionContext $context,
  ): array;

  /**
   * Converts a subtitle file to WebVTT format.
   *
   * @param string $inputPath
   *   Path to the subtitle file.
   *
   * @return string|null
   *   Path to the converted WebVTT file, or NULL on failure.
   */
  #[\NoDiscard]
  public function convertSubtitleToWebVtt(string $inputPath): ?string;

  /**
   * Extracts a language code from a subtitle filename.
   *
   * @param string $filename
   *   Filename to parse.
   *
   * @return string|null
   *   Language code if detected, or NULL.
   */
  #[\NoDiscard]
  public function extractLanguageFromFilename(string $filename): ?string;

  /**
   * Normalizes a language code to ISO 639-1 style.
   *
   * @param string $language
   *   Language code.
   *
   * @return string
   *   Normalized language code.
   */
  #[\NoDiscard]
  public function normalizeLanguageCode(string $language): string;

  /**
   * Builds a human-readable label for a subtitle track.
   *
   * @param string $language
   *   Language code.
   *
   * @return string
   *   Label for display.
   */
  #[\NoDiscard]
  public function buildSubtitleLabel(string $language): string;

}
