rsmediainfo 0.1.0

//! Top-level [`MediaInfo`] type and the parse pipeline that builds it.
//!
//! This module exposes the entrypoints for parsing media files (paths,
//! readers, URLs, raw XML strings), the [`ParseOptions`] builder that
//! configures the parse, the [`MediaInfoSource`] trait that lets a single
//! call accept any of the supported input shapes, and the [`LibVersion`]
//! helper used for runtime feature detection.

use crate::error::{EncodingErrorMode, MediaInfoError, Result};
use crate::ffi::{MediaInfoHandle, MediaInfoLib};
use crate::platform;
use crate::track::Track;
use crate::xml;
use log::{debug, warn};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::io::{Read, Seek, SeekFrom, Write};
use std::net::TcpStream;
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex, OnceLock};

/// Library version information.
///
/// Holds the parsed major / minor / patch components of the underlying media
/// library so callers can branch on the runtime version when deciding which
/// optional features (cover data, post-call reset, thread-safe handle reuse,
/// XML output naming) are available.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct LibVersion {
    /// Major version number, e.g. `20` in `20.09`.
    pub major: u32,
    /// Minor version number, e.g. `9` in `20.09`.
    pub minor: u32,
    /// Patch version number, or `0` when the library reports only
    /// `major.minor`.
    pub patch: u32,
}

impl LibVersion {
    /// Constructs a [`LibVersion`] from explicit `major`, `minor`, and
    /// `patch` components. Useful in tests and for hand-built sentinels.
    pub fn new(major: u32, minor: u32, patch: u32) -> Self {
        LibVersion {
            major,
            minor,
            patch,
        }
    }

    /// Parses a dotted version string into a [`LibVersion`].
    ///
    /// Accepts both `"major.minor"` and `"major.minor.patch"` shapes; a
    /// missing patch component defaults to `0`. Returns `None` only when
    /// the string is empty or the major component is not a valid integer.
    ///
    /// # Example
    ///
    /// ```
    /// use rsmediainfo::mediainfo::LibVersion;
    ///
    /// let v = LibVersion::parse("20.09").unwrap();
    /// assert_eq!(v.major, 20);
    /// assert_eq!(v.minor, 9);
    /// assert_eq!(v.patch, 0);
    /// ```
    pub fn parse(version_str: &str) -> Option<Self> {
        let parts: Vec<&str> = version_str.split('.').collect();
        if parts.is_empty() {
            return None;
        }

        let major = parts.first()?.parse().ok()?;
        let minor = parts.get(1).and_then(|s| s.parse().ok()).unwrap_or(0);
        let patch = parts.get(2).and_then(|s| s.parse().ok()).unwrap_or(0);

        Some(LibVersion {
            major,
            minor,
            patch,
        })
    }

    /// Returns `true` when this version supports the `Cover_Data` option
    /// (library 18.3 and newer).
    ///
    /// Older builds always emit cover data when present and have no way
    /// to suppress it; newer builds only emit it when the option is set.
    pub fn supports_cover_data(&self) -> bool {
        *self >= LibVersion::new(18, 3, 0)
    }

    /// Returns `true` when this version supports the `Reset` option
    /// (library 19.9 and newer).
    ///
    /// The reset is used after a parse that set custom options, so the
    /// next parse starts from a clean slate.
    pub fn supports_reset(&self) -> bool {
        *self >= LibVersion::new(19, 9, 0)
    }

    /// Returns the option name to use when requesting XML output from
    /// this version.
    ///
    /// Library 17.10 and newer use `"OLDXML"`; earlier builds use the
    /// plain `"XML"` option name.
    pub fn xml_option_name(&self) -> &'static str {
        if *self >= LibVersion::new(17, 10, 0) {
            "OLDXML"
        } else {
            "XML"
        }
    }

    /// Returns `true` when this version's option-handling code path is
    /// thread-safe (library 20.3 and newer).
    #[allow(dead_code)]
    pub fn is_thread_safe(&self) -> bool {
        *self >= LibVersion::new(20, 3, 0)
    }
}

/// Configuration for a single parse call.
///
/// All fields have sensible defaults (see [`ParseOptions::default`]) and
/// the type uses a chainable builder pattern so callers can override only
/// the options they care about. Every parse entrypoint accepts a
/// `&ParseOptions`, so the same builder can be reused across calls.
///
/// Parse calls are serialized internally so concurrent callers see
/// consistent option state regardless of which thread set them; see the
/// crate-level "Thread safety" section for details.
#[derive(Debug, Clone)]
pub struct ParseOptions {
    /// Explicit path to the shared library. When set, library
    /// auto-detection is bypassed and only this path is tried.
    /// Defaults to `None`.
    pub library_file: Option<PathBuf>,

    /// Directory to search for a bundled shared library before falling
    /// back to system paths. When unset, the parser uses the directory
    /// containing the current executable as the default bundled search
    /// location, falling back to the current working directory if that
    /// is not usable. Defaults to `None`.
    pub library_search_dir: Option<PathBuf>,

    /// When `true`, the parser extracts embedded cover art as base64
    /// text on the general track. Requires library version 18.3 or
    /// newer; older builds always emit cover data when present and have
    /// no way to suppress it. Defaults to `false`.
    pub cover_data: bool,

    /// Parse-speed knob, where `0.0` favors throughput and `1.0` favors
    /// completeness. Values outside the typical `[0.0, 1.0]` range are
    /// forwarded to the library unchanged. Defaults to `0.5`.
    pub parse_speed: f32,

    /// When `true`, the parser emits the full set of details on every
    /// track (the equivalent of the `--Full` flag on the library's
    /// command line). Defaults to `true`.
    pub full: bool,

    /// When `true`, the parser uses the legacy per-stream display
    /// formatting that some integrations rely on. Defaults to `false`.
    pub legacy_stream_display: bool,

    /// Extra option key/value pairs forwarded verbatim to the underlying
    /// option setter. The crate issues a `Reset` after the parse on
    /// library version 19.9 and newer so the next call starts clean; on
    /// older builds it cannot, and a warning is logged through the
    /// `log` crate. Defaults to `None`.
    pub mediainfo_options: Option<HashMap<String, String>>,

    /// When `Some`, parse calls return a raw text payload in the
    /// requested format instead of building a structured [`MediaInfo`].
    /// Common values include `""` (or `"text"`), `"JSON"`, `"XML"`,
    /// `"OLDXML"`, and `%`-delimited templates such as
    /// `"General;%FileSize%"`. Defaults to `None`.
    pub output: Option<String>,

    /// Buffer size in bytes for the reader-driven parse path. `None`
    /// means "consume the reader in a single `read_to_end` call".
    /// Defaults to `Some(64 * 1024)`.
    pub buffer_size: Option<usize>,

    /// How invalid UTF-8 in the library's XML output is handled. See
    /// [`EncodingErrorMode`] for the available strategies. Defaults to
    /// [`EncodingErrorMode::Strict`].
    pub encoding_errors: EncodingErrorMode,
}

/// Marker trait for reader inputs accepted by the parse pipeline.
///
/// Anything that implements both [`Read`] and [`Seek`] is automatically a
/// [`ReadSeek`]. The trait exists so the parser can take a
/// `&mut dyn ReadSeek` trait object without exposing both bounds at every
/// call site.
pub trait ReadSeek: Read + Seek {}

impl<T: Read + Seek + ?Sized> ReadSeek for T {}

/// A unified input handed to the internal parse pipeline.
///
/// Most callers will go through [`MediaInfoSource`] instead of constructing
/// this enum by hand, but the variants are public so callers that already
/// have one of these shapes can pass them directly.
pub enum MediaInfoInput<'a> {
    /// A path to a media file on disk.
    Path(&'a Path),
    /// A URL the underlying library knows how to open.
    Url(&'a str),
    /// A `Read + Seek` source that the parser will consume through the
    /// buffer-protocol path.
    Reader(&'a mut dyn ReadSeek),
}

/// Conversion trait that lets a single parse call accept any of the
/// supported input shapes (path, URL, reader, or a pre-built
/// [`MediaInfoInput`]).
///
/// Implementations exist for `&Path`, `&PathBuf`, `&str`, `&String`,
/// `&mut R: Read + Seek`, `&mut dyn ReadSeek`, and `MediaInfoInput<'_>`.
/// String inputs are routed to [`MediaInfoInput::Url`] when they contain
/// `://` and to [`MediaInfoInput::Path`] otherwise.
pub trait MediaInfoSource<'a> {
    /// Converts the value into a [`MediaInfoInput`] the parse pipeline
    /// can consume.
    fn into_input(self) -> MediaInfoInput<'a>;
}

impl<'a> MediaInfoSource<'a> for MediaInfoInput<'a> {
    fn into_input(self) -> MediaInfoInput<'a> {
        self
    }
}

impl<'a> MediaInfoSource<'a> for &'a Path {
    fn into_input(self) -> MediaInfoInput<'a> {
        MediaInfoInput::Path(self)
    }
}

impl<'a> MediaInfoSource<'a> for &'a PathBuf {
    fn into_input(self) -> MediaInfoInput<'a> {
        MediaInfoInput::Path(self.as_path())
    }
}

impl<'a> MediaInfoSource<'a> for &'a str {
    fn into_input(self) -> MediaInfoInput<'a> {
        if self.contains("://") {
            MediaInfoInput::Url(self)
        } else {
            MediaInfoInput::Path(Path::new(self))
        }
    }
}

impl<'a> MediaInfoSource<'a> for &'a String {
    fn into_input(self) -> MediaInfoInput<'a> {
        self.as_str().into_input()
    }
}

impl<'a, R: ReadSeek> MediaInfoSource<'a> for &'a mut R {
    fn into_input(self) -> MediaInfoInput<'a> {
        MediaInfoInput::Reader(self)
    }
}

impl<'a> MediaInfoSource<'a> for &'a mut dyn ReadSeek {
    fn into_input(self) -> MediaInfoInput<'a> {
        MediaInfoInput::Reader(self)
    }
}

impl Default for ParseOptions {
    fn default() -> Self {
        ParseOptions {
            library_file: None,
            library_search_dir: None,
            cover_data: false,
            parse_speed: 0.5,
            full: true,
            legacy_stream_display: false,
            mediainfo_options: None,
            output: None,
            buffer_size: Some(64 * 1024),
            encoding_errors: EncodingErrorMode::default(),
        }
    }
}

impl ParseOptions {
    /// Constructs a new [`ParseOptions`] with all defaults.
    ///
    /// Equivalent to `ParseOptions::default()`.
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets [`Self::library_file`] to an explicit shared library path,
    /// bypassing the auto-detection search.
    pub fn library_file<P: Into<PathBuf>>(mut self, path: P) -> Self {
        self.library_file = Some(path.into());
        self
    }

    /// Sets [`Self::library_search_dir`] to a directory the loader
    /// should look in before falling back to system paths.
    pub fn library_search_dir<P: Into<PathBuf>>(mut self, path: P) -> Self {
        self.library_search_dir = Some(path.into());
        self
    }

    /// Sets [`Self::cover_data`].
    ///
    /// When `true`, embedded cover art is exposed as a base64 string on
    /// the general track. Requires library version 18.3 or newer.
    pub fn cover_data(mut self, cover_data: bool) -> Self {
        self.cover_data = cover_data;
        self
    }

    /// Sets [`Self::parse_speed`].
    ///
    /// Values outside the typical `[0.0, 1.0]` range are forwarded to
    /// the library unchanged.
    pub fn parse_speed(mut self, speed: f32) -> Self {
        self.parse_speed = speed;
        self
    }

    /// Sets [`Self::full`].
    ///
    /// When `true`, every track is rendered with the complete attribute
    /// set rather than the abbreviated default.
    pub fn full(mut self, full: bool) -> Self {
        self.full = full;
        self
    }

    /// Sets [`Self::legacy_stream_display`].
    pub fn legacy_stream_display(mut self, legacy: bool) -> Self {
        self.legacy_stream_display = legacy;
        self
    }

    /// Sets [`Self::mediainfo_options`] to a map of extra option
    /// key/value pairs that the parse call will forward to the
    /// underlying library.
    ///
    /// The crate issues a `Reset` after the parse on library 19.9 and
    /// newer; on older builds it cannot, and a warning is logged
    /// through the `log` crate to make the limitation visible.
    pub fn mediainfo_options(mut self, options: HashMap<String, String>) -> Self {
        self.mediainfo_options = Some(options);
        self
    }

    /// Sets [`Self::output`].
    ///
    /// When set, parse calls return raw text instead of structured data.
    /// See the field doc for the list of accepted format strings.
    pub fn output<S: Into<String>>(mut self, output: S) -> Self {
        self.output = Some(output.into());
        self
    }

    /// Sets [`Self::buffer_size`].
    ///
    /// `None` reads the entire input in a single `read_to_end` call;
    /// `Some(n)` reads in `n`-byte chunks through the buffer protocol.
    pub fn buffer_size(mut self, size: Option<usize>) -> Self {
        self.buffer_size = size;
        self
    }

    /// Sets [`Self::encoding_errors`].
    ///
    /// Controls how invalid UTF-8 in the library's XML output is
    /// handled. See [`EncodingErrorMode`] for the available strategies.
    ///
    /// # Example
    ///
    /// ```
    /// use rsmediainfo::{ParseOptions, EncodingErrorMode};
    ///
    /// let strict_opts = ParseOptions::new()
    ///     .encoding_errors(EncodingErrorMode::Strict);
    ///
    /// let replace_opts = ParseOptions::new()
    ///     .encoding_errors(EncodingErrorMode::Replace);
    /// ```
    pub fn encoding_errors(mut self, mode: EncodingErrorMode) -> Self {
        self.encoding_errors = mode;
        self
    }
}

/// A parsed media file: an ordered list of [`Track`] values plus the
/// associated track-shortcut accessors.
///
/// Build a [`MediaInfo`] by calling one of the parse entrypoints
/// ([`MediaInfo::parse`], [`MediaInfo::parse_media_info`],
/// [`MediaInfo::parse_path`], [`MediaInfo::parse_from_reader`]) or by
/// passing a pre-generated XML string to [`MediaInfo::from_xml`]. The
/// resulting value is `Send + Sync + Clone` and can be moved across
/// threads freely.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MediaInfo {
    /// Tracks in source order, exposed through [`MediaInfo::tracks`].
    tracks: Vec<Track>,
}

/// Acquires the process-wide parse lock.
///
/// The underlying media library exposes a single global option store: every
/// `MediaInfo_Option` call (parse speed, output format, completion level,
/// custom options, the post-parse `Reset`, and so on) mutates state that is
/// shared by every handle in the process. Two threads that call into the
/// library with different options simultaneously can therefore observe each
/// other's settings, which produces non-deterministic results — or, on older
/// library builds without thread-safe option handling, outright crashes.
///
/// This guard serializes the entire parse pipeline so callers always see the
/// options they configured. The lock has no effect on `MediaInfo::from_xml`
/// (pure XML parsing does not touch the FFI) and is held only for the
/// duration of a single parse call. The cost is one extra mutex acquire per
/// parse, which is negligible compared to the work the library performs.
fn parse_lock() -> std::sync::MutexGuard<'static, ()> {
    static PARSE_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
    PARSE_LOCK
        .get_or_init(|| Mutex::new(()))
        .lock()
        .expect("parse lock poisoned")
}

/// Return value of the parse entrypoints that accept arbitrary
/// [`ParseOptions::output`] modes.
///
/// When the caller leaves `output` unset, parse calls return the
/// [`ParseOutput::MediaInfo`] variant carrying a structured value. When
/// the caller sets `output` (to `"JSON"`, `"text"`, a template string,
/// and so on), parse calls return [`ParseOutput::Output`] carrying the
/// raw text the underlying library produced.
///
/// Use [`MediaInfo::parse_media_info`] or
/// [`MediaInfo::parse_to_string`] when you know in advance which shape
/// you want and would rather not pattern-match on the result.
#[derive(Debug, Clone, PartialEq)]
pub enum ParseOutput {
    /// Structured parse result, returned when no `output` mode is set.
    MediaInfo(MediaInfo),
    /// Raw text payload, returned when an `output` mode is set.
    Output(String),
}

impl ParseOutput {
    /// Returns the inner [`MediaInfo`] by reference, or `None` when this
    /// is a raw-output result.
    pub fn as_media_info(&self) -> Option<&MediaInfo> {
        match self {
            ParseOutput::MediaInfo(mi) => Some(mi),
            ParseOutput::Output(_) => None,
        }
    }

    /// Returns the raw output text by reference, or `None` when this is
    /// a structured result.
    pub fn as_output(&self) -> Option<&str> {
        match self {
            ParseOutput::MediaInfo(_) => None,
            ParseOutput::Output(text) => Some(text.as_str()),
        }
    }

    /// Consumes the enum and yields the [`MediaInfo`] if present.
    pub fn into_media_info(self) -> Option<MediaInfo> {
        match self {
            ParseOutput::MediaInfo(mi) => Some(mi),
            ParseOutput::Output(_) => None,
        }
    }

    /// Consumes the enum and yields the raw output if present.
    pub fn into_output(self) -> Option<String> {
        match self {
            ParseOutput::MediaInfo(_) => None,
            ParseOutput::Output(text) => Some(text),
        }
    }
}

impl MediaInfo {
    /// Constructs a [`MediaInfo`] directly from an owned list of tracks.
    ///
    /// This is the lowest-level constructor and is mostly useful for
    /// tests and for callers that produce tracks through some path
    /// other than the parse entrypoints.
    pub fn new(tracks: Vec<Track>) -> Self {
        MediaInfo { tracks }
    }

    /// Constructs a [`MediaInfo`] from a pre-generated XML string using
    /// the default strict encoding mode.
    ///
    /// This entrypoint never touches the underlying media library, so it
    /// works in environments where the shared library is not available
    /// at runtime.
    ///
    /// # Errors
    ///
    /// Returns [`MediaInfoError::XmlParseError`] when the input is not
    /// well-formed XML or contains invalid UTF-8.
    ///
    /// # Example
    ///
    /// ```
    /// use rsmediainfo::MediaInfo;
    ///
    /// let xml = r#"<?xml version="1.0"?><File><track type="General"><Format>MKV</Format></track></File>"#;
    /// let mi = MediaInfo::from_xml(xml).unwrap();
    /// assert_eq!(mi.tracks().len(), 1);
    /// ```
    pub fn from_xml(xml: &str) -> Result<Self> {
        Self::from_xml_with_encoding(xml, EncodingErrorMode::Strict)
    }

    /// Constructs a [`MediaInfo`] from a pre-generated XML string with a
    /// caller-supplied [`EncodingErrorMode`].
    ///
    /// # Errors
    ///
    /// Returns [`MediaInfoError::XmlParseError`] when the input is not
    /// well-formed XML, or when invalid UTF-8 is encountered under
    /// [`EncodingErrorMode::Strict`].
    ///
    /// # Example
    ///
    /// ```
    /// use rsmediainfo::{MediaInfo, EncodingErrorMode};
    ///
    /// let xml = r#"<?xml version="1.0"?><File><track type="General"><Format>MKV</Format></track></File>"#;
    /// let mi = MediaInfo::from_xml_with_encoding(xml, EncodingErrorMode::Strict).unwrap();
    /// assert_eq!(mi.tracks().len(), 1);
    /// ```
    pub fn from_xml_with_encoding(xml: &str, encoding_mode: EncodingErrorMode) -> Result<Self> {
        let tracks = xml::parse_xml_with_encoding(xml, encoding_mode)?;
        Ok(MediaInfo { tracks })
    }

    /// Constructs a [`MediaInfo`] from a raw XML byte buffer with a
    /// caller-supplied [`EncodingErrorMode`].
    ///
    /// Use this when the source bytes may not be valid UTF-8 and the
    /// caller wants to control how invalid sequences are handled.
    ///
    /// # Errors
    ///
    /// Returns [`MediaInfoError::XmlParseError`] for malformed XML or
    /// for invalid UTF-8 under [`EncodingErrorMode::Strict`].
    pub fn from_xml_bytes_with_encoding(
        xml_bytes: &[u8],
        encoding_mode: EncodingErrorMode,
    ) -> Result<Self> {
        let tracks = xml::parse_xml_bytes_with_encoding(xml_bytes, encoding_mode)?;
        Ok(MediaInfo { tracks })
    }

    /// Constructs a [`MediaInfo`] from a raw XML byte buffer using the
    /// default strict encoding mode.
    ///
    /// # Errors
    ///
    /// Returns [`MediaInfoError::XmlParseError`] for malformed XML or
    /// for invalid UTF-8.
    pub fn from_xml_bytes(xml_bytes: &[u8]) -> Result<Self> {
        Self::from_xml_bytes_with_encoding(xml_bytes, EncodingErrorMode::Strict)
    }

    /// Returns `true` when the underlying media library can be loaded
    /// and a test handle can be created against it.
    ///
    /// This is the right way to probe whether parsing is possible at all
    /// before attempting a parse — it never panics and never returns an
    /// error, just `false` when the library is missing or unusable.
    ///
    /// When `library_file` is `Some`, only that path is tried; when it
    /// is `None`, the standard auto-detection search runs (see
    /// [`ParseOptions::library_search_dir`] for the resolution order).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use rsmediainfo::MediaInfo;
    /// use std::path::Path;
    ///
    /// if MediaInfo::can_parse(None) {
    ///     println!("library is available");
    /// }
    ///
    /// if MediaInfo::can_parse(Some(Path::new("/usr/lib/libmediainfo.so"))) {
    ///     println!("custom library is available");
    /// }
    /// ```
    pub fn can_parse(library_file: Option<&Path>) -> bool {
        Self::load_library(library_file, None).is_ok()
    }

    /// Loads the underlying library and returns its raw version string
    /// alongside the parsed [`LibVersion`].
    ///
    /// The raw string is whatever the library reports for the
    /// `Info_Version` option (typically `"20.09"`-shaped). The parsed
    /// [`LibVersion`] is the same value as a struct so callers can use
    /// the feature-detection helpers without re-parsing it.
    ///
    /// # Errors
    ///
    /// Returns [`MediaInfoError::LibraryNotFound`] when the library
    /// cannot be loaded, or [`MediaInfoError::VersionDetectionFailed`]
    /// when the loaded library reports a version string the crate
    /// cannot interpret.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use rsmediainfo::MediaInfo;
    ///
    /// if MediaInfo::can_parse(None) {
    ///     let (version_str, version) = MediaInfo::library_version(None).unwrap();
    ///     println!("library version: {version_str}");
    ///     if version.supports_cover_data() {
    ///         println!("cover data extraction is available");
    ///     }
    /// }
    /// ```
    pub fn library_version(library_file: Option<&Path>) -> Result<(String, LibVersion)> {
        let (_handle, version_number, version) = Self::load_library(library_file, None)?;
        Ok((version_number, version))
    }

    /// Parses any supported source (path, URL, or reader) using the
    /// default [`ParseOptions`].
    ///
    /// This is the primary entrypoint for the structured parse pipeline.
    /// The result is always [`ParseOutput::MediaInfo`] because the
    /// default options leave [`ParseOptions::output`] unset.
    ///
    /// # Errors
    ///
    /// Returns [`MediaInfoError::LibraryNotFound`] if the underlying
    /// library cannot be loaded, [`MediaInfoError::FileNotFound`] for a
    /// missing path, [`MediaInfoError::ParseError`] for an unparseable
    /// file or URL, [`MediaInfoError::IoError`] for reader I/O failures,
    /// and [`MediaInfoError::XmlParseError`] when the library produces
    /// XML output the crate cannot interpret.
    pub fn parse<'a, S>(source: S) -> Result<ParseOutput>
    where
        S: MediaInfoSource<'a>,
    {
        Self::parse_with_options(source, &ParseOptions::default())
    }

    /// Path-typed alias for [`MediaInfo::parse`] that accepts any
    /// `AsRef<Path>` value.
    ///
    /// Useful when the caller already has a `String`, `PathBuf`, or
    /// `&Path` and would rather not go through the [`MediaInfoSource`]
    /// generic dispatch.
    pub fn parse_path<P: AsRef<Path>>(path: P) -> Result<ParseOutput> {
        Self::parse(path.as_ref())
    }

    /// Parses any supported source and returns the result as a
    /// structured [`MediaInfo`] directly.
    ///
    /// This is the right entrypoint when the caller knows it does not
    /// want raw text output. Equivalent to calling [`MediaInfo::parse`]
    /// and pattern-matching for the [`ParseOutput::MediaInfo`] variant.
    ///
    /// # Errors
    ///
    /// Same as [`MediaInfo::parse`].
    pub fn parse_media_info<'a, S>(source: S) -> Result<Self>
    where
        S: MediaInfoSource<'a>,
    {
        Self::parse_media_info_with_options(source, &ParseOptions::default())
    }

    /// Path-typed alias for [`MediaInfo::parse_media_info`] that accepts
    /// any `AsRef<Path>` value.
    pub fn parse_media_info_path<P: AsRef<Path>>(path: P) -> Result<Self> {
        Self::parse_media_info(path.as_ref())
    }

    /// Parses any supported source with caller-supplied [`ParseOptions`]
    /// and returns the result as a structured [`MediaInfo`].
    ///
    /// # Errors
    ///
    /// In addition to the errors documented on [`MediaInfo::parse`],
    /// returns [`MediaInfoError::InvalidInput`] when `options.output`
    /// is set — that combination is rejected because the structured
    /// return type cannot represent raw text output.
    pub fn parse_media_info_with_options<'a, S>(source: S, options: &ParseOptions) -> Result<Self>
    where
        S: MediaInfoSource<'a>,
    {
        if options.output.is_some() {
            return Err(MediaInfoError::invalid_input(
                "output is only supported by parse or parse_with_options",
            ));
        }

        match Self::parse_with_options(source, options)? {
            ParseOutput::MediaInfo(mi) => Ok(mi),
            ParseOutput::Output(_) => Err(MediaInfoError::invalid_input(
                "output is only supported by parse or parse_with_options",
            )),
        }
    }

    /// Path-typed alias for [`MediaInfo::parse_media_info_with_options`].
    pub fn parse_media_info_path_with_options<P: AsRef<Path>>(
        path: P,
        options: &ParseOptions,
    ) -> Result<Self> {
        Self::parse_media_info_with_options(path.as_ref(), options)
    }

    /// Parses any supported source with caller-supplied [`ParseOptions`].
    ///
    /// The return type is [`ParseOutput`] because `options.output` may
    /// request raw text output, in which case the returned variant is
    /// [`ParseOutput::Output`]. When `options.output` is unset, the
    /// returned variant is always [`ParseOutput::MediaInfo`].
    ///
    /// # Errors
    ///
    /// Same as [`MediaInfo::parse`].
    pub fn parse_with_options<'a, S>(source: S, options: &ParseOptions) -> Result<ParseOutput>
    where
        S: MediaInfoSource<'a>,
    {
        let input = source.into_input();
        Self::parse_input_with_options(input, options)
    }

    /// Path-typed alias for [`MediaInfo::parse_with_options`].
    pub fn parse_path_with_options<P: AsRef<Path>>(
        path: P,
        options: &ParseOptions,
    ) -> Result<ParseOutput> {
        Self::parse_with_options(path.as_ref(), options)
    }

    /// Alias for [`MediaInfo::parse`]. Kept for symmetry with the
    /// `*_with_options` family.
    pub fn parse_source<'a, S>(source: S) -> Result<ParseOutput>
    where
        S: MediaInfoSource<'a>,
    {
        Self::parse(source)
    }

    /// Alias for [`MediaInfo::parse_with_options`]. Kept for symmetry.
    pub fn parse_source_with_options<'a, S>(
        source: S,
        options: &ParseOptions,
    ) -> Result<ParseOutput>
    where
        S: MediaInfoSource<'a>,
    {
        Self::parse_with_options(source, options)
    }

    /// Parses a media file from disk and returns the raw text output the
    /// underlying library produces in the requested format.
    ///
    /// `output_format` is forwarded as the library's `Inform` option and
    /// controls the shape of the returned string. Common values:
    ///
    /// - `""` — default human-readable text report
    /// - `"text"` — alias for the empty string
    /// - `"JSON"` — JSON document
    /// - `"XML"` / `"OLDXML"` — XML document
    /// - `%`-delimited templates such as `"General;%FileSize%"`
    ///
    /// # Errors
    ///
    /// Same as [`MediaInfo::parse`].
    pub fn parse_to_string<P: AsRef<Path>>(filename: P, output_format: &str) -> Result<String> {
        let options = ParseOptions::new().output(output_format.to_string());
        Self::parse_to_string_internal(filename, &options)
    }

    /// Parses a media file from disk with caller-supplied [`ParseOptions`]
    /// and returns the raw text output the library produces.
    ///
    /// Use this overload when you need to combine an explicit output
    /// format with other option overrides (parse speed, full mode, custom
    /// `mediainfo_options`, etc.). The `output_format` from the options
    /// value is the one that takes effect.
    ///
    /// # Errors
    ///
    /// Same as [`MediaInfo::parse`].
    pub fn parse_to_string_with_options<P: AsRef<Path>>(
        filename: P,
        options: &ParseOptions,
    ) -> Result<String> {
        Self::parse_to_string_internal(filename, options)
    }

    fn parse_to_string_internal<P: AsRef<Path>>(
        filename: P,
        options: &ParseOptions,
    ) -> Result<String> {
        let _parse_guard = parse_lock();
        Self::parse_to_string_internal_unlocked(filename, options)
    }

    fn parse_to_string_internal_unlocked<P: AsRef<Path>>(
        filename: P,
        options: &ParseOptions,
    ) -> Result<String> {
        let path = filename.as_ref();
        let path_str = path.to_string_lossy().to_string();

        // Strings that look like URLs are routed straight to the URL
        // entrypoint rather than being interpreted as filesystem paths.
        if path_str.contains("://") {
            return Self::parse_to_string_from_url_unlocked(&path_str, options);
        }

        let (handle, version_number, version) = Self::load_library(
            options.library_file.as_deref(),
            options.library_search_dir.as_deref(),
        )?;

        Self::configure_parse_options(&handle, &version, &version_number, options);
        Self::configure_output_options(&handle, &version, options);

        // Probe the filesystem first so missing-file errors surface as
        // FileNotFound rather than the more generic library parse error.
        if !path.exists() {
            return Err(MediaInfoError::file_not_found(path));
        }

        if handle.open(&path_str) == 0 {
            return Err(MediaInfoError::parse_error(&path_str));
        }

        let output = handle.inform();

        // Reset the global option store on library builds that support
        // it, so the next parse call starts from a clean slate.
        if options.mediainfo_options.is_some() && version.supports_reset() {
            handle.option("Reset", "");
        }

        Ok(output)
    }

    fn parse_to_string_from_url(url: &str, options: &ParseOptions) -> Result<String> {
        let _parse_guard = parse_lock();
        Self::parse_to_string_from_url_unlocked(url, options)
    }

    fn parse_to_string_from_url_unlocked(url: &str, options: &ParseOptions) -> Result<String> {
        let (handle, version_number, version) = Self::load_library(
            options.library_file.as_deref(),
            options.library_search_dir.as_deref(),
        )?;

        Self::configure_parse_options(&handle, &version, &version_number, options);
        Self::configure_output_options(&handle, &version, options);

        if handle.open(url) == 0 {
            if options.mediainfo_options.is_some() && version.supports_reset() {
                handle.option("Reset", "");
            }

            // The native opener could not handle the URL. For plain HTTP we
            // try a built-in fetch fallback so the caller still gets results
            // when the underlying library was built without CURL support.
            if url.starts_with("http://") {
                debug!(
                    "native URL opener could not handle {}; falling back to built-in HTTP fetch",
                    url
                );
                return Self::parse_url_via_http(url, options);
            }

            return Err(MediaInfoError::parse_error(url));
        }

        let output = handle.inform();

        if options.mediainfo_options.is_some() && version.supports_reset() {
            handle.option("Reset", "");
        }

        Ok(output)
    }

    /// Parses any `Read + Seek` source through the buffer-protocol path.
    ///
    /// The reader is consumed in `buffer_size`-sized chunks (or in a
    /// single `read_to_end` call when `buffer_size` is `None`). Readers
    /// must produce raw bytes — text-mode readers are not supported by
    /// the type system and would not produce the right results anyway.
    ///
    /// # Errors
    ///
    /// Same as [`MediaInfo::parse`].
    pub fn parse_from_reader<R: ReadSeek>(reader: &mut R) -> Result<ParseOutput> {
        Self::parse_from_reader_with_options(reader, &ParseOptions::default())
    }

    /// Parses any `Read + Seek` source with caller-supplied
    /// [`ParseOptions`].
    ///
    /// When `options.output` is set, this returns
    /// [`ParseOutput::Output`] carrying the raw text payload; otherwise
    /// it returns [`ParseOutput::MediaInfo`] carrying a structured
    /// value built from the library's XML output.
    ///
    /// # Errors
    ///
    /// Same as [`MediaInfo::parse`].
    pub fn parse_from_reader_with_options<R: ReadSeek>(
        reader: &mut R,
        options: &ParseOptions,
    ) -> Result<ParseOutput> {
        if options.output.is_some() {
            let output = Self::parse_reader_to_string_internal(reader, options)?;
            return Ok(ParseOutput::Output(output));
        }

        let output = Self::parse_reader_to_string_internal(reader, options)?;
        let mi =
            MediaInfo::from_xml_bytes_with_encoding(output.as_bytes(), options.encoding_errors)?;
        Ok(ParseOutput::MediaInfo(mi))
    }

    /// Parses a [`MediaInfoInput`] using the default [`ParseOptions`].
    ///
    /// Use this when you have a pre-built [`MediaInfoInput`] (for
    /// example, after threading one through your own dispatch logic).
    /// Most callers should prefer the more ergonomic [`MediaInfo::parse`]
    /// or one of its specialized helpers.
    pub fn parse_input(input: MediaInfoInput<'_>) -> Result<ParseOutput> {
        Self::parse_input_with_options(input, &ParseOptions::default())
    }

    /// Parses a [`MediaInfoInput`] with caller-supplied [`ParseOptions`].
    ///
    /// Behaves like [`MediaInfo::parse_with_options`] but takes the
    /// already-converted [`MediaInfoInput`] enum.
    pub fn parse_input_with_options(
        input: MediaInfoInput<'_>,
        options: &ParseOptions,
    ) -> Result<ParseOutput> {
        if options.output.is_some() {
            let output = Self::parse_input_to_string_with_options(input, options)?;
            return Ok(ParseOutput::Output(output));
        }

        let output = Self::parse_input_to_string_with_options(input, options)?;
        let mi =
            MediaInfo::from_xml_bytes_with_encoding(output.as_bytes(), options.encoding_errors)?;
        Ok(ParseOutput::MediaInfo(mi))
    }

    /// Parses a [`MediaInfoInput`] in raw-output mode.
    ///
    /// `output_format` is forwarded as the library's `Inform` option;
    /// see [`MediaInfo::parse_to_string`] for the list of common values.
    pub fn parse_input_to_string(input: MediaInfoInput<'_>, output_format: &str) -> Result<String> {
        let options = ParseOptions::new().output(output_format.to_string());
        Self::parse_input_to_string_with_options(input, &options)
    }

    /// Parses a [`MediaInfoInput`] in raw-output mode with
    /// caller-supplied [`ParseOptions`].
    pub fn parse_input_to_string_with_options(
        input: MediaInfoInput<'_>,
        options: &ParseOptions,
    ) -> Result<String> {
        match input {
            MediaInfoInput::Path(path) => Self::parse_to_string_with_options(path, options),
            MediaInfoInput::Url(url) => Self::parse_to_string_from_url(url, options),
            MediaInfoInput::Reader(reader) => {
                Self::parse_reader_to_string_with_options(reader, options)
            }
        }
    }

    /// Parses any `Read + Seek` source and returns the raw text payload
    /// the library produces in the requested format.
    ///
    /// `output_format` is forwarded as the library's `Inform` option.
    /// See [`MediaInfo::parse_to_string`] for the list of common values.
    pub fn parse_reader_to_string<R: ReadSeek + ?Sized>(
        reader: &mut R,
        output_format: &str,
    ) -> Result<String> {
        let options = ParseOptions::new().output(output_format.to_string());
        Self::parse_reader_to_string_internal(reader, &options)
    }

    /// Parses any `Read + Seek` source with caller-supplied
    /// [`ParseOptions`] and returns the raw text payload.
    pub fn parse_reader_to_string_with_options<R: ReadSeek + ?Sized>(
        reader: &mut R,
        options: &ParseOptions,
    ) -> Result<String> {
        Self::parse_reader_to_string_internal(reader, options)
    }

    fn parse_reader_to_string_internal<R: ReadSeek + ?Sized>(
        reader: &mut R,
        options: &ParseOptions,
    ) -> Result<String> {
        let _parse_guard = parse_lock();
        Self::parse_reader_to_string_internal_unlocked(reader, options)
    }

    fn parse_reader_to_string_internal_unlocked<R: ReadSeek + ?Sized>(
        reader: &mut R,
        options: &ParseOptions,
    ) -> Result<String> {
        // Discover the total stream length up front so the buffer
        // protocol can give the library a meaningful file size hint, then
        // rewind to the start before the read loop kicks off.
        let file_size = reader.seek(SeekFrom::End(0))?;
        reader.seek(SeekFrom::Start(0))?;

        let (handle, version_number, version) = Self::load_library(
            options.library_file.as_deref(),
            options.library_search_dir.as_deref(),
        )?;

        Self::configure_parse_options(&handle, &version, &version_number, options);
        Self::configure_output_options(&handle, &version, options);

        handle.open_buffer_init(file_size, 0);

        if let Some(buffer_size) = options.buffer_size {
            let mut buffer = vec![0u8; buffer_size];

            loop {
                let bytes_read = reader.read(&mut buffer)?;
                if bytes_read == 0 {
                    break;
                }

                // Bit 3 (0x08) of the buffer-continue result is the
                // library's "I have everything I need" signal. When it
                // is set we stop reading even though there may be more
                // bytes left in the stream.
                let result = handle.open_buffer_continue(&buffer[..bytes_read]);
                if result & 0x08 != 0 {
                    break;
                }

                // The library may also ask us to seek to a specific
                // offset before delivering the next chunk; honor the
                // request and re-initialize the buffer protocol so the
                // file-position bookkeeping stays consistent.
                let seek_pos = handle.open_buffer_continue_goto_get();
                if seek_pos != u64::MAX {
                    reader.seek(SeekFrom::Start(seek_pos))?;
                    let current_pos = reader.stream_position()?;
                    handle.open_buffer_init(file_size, current_pos);
                }
            }
        } else {
            // Single-shot path: feed the entire stream to the library
            // in one call. The same finished/seek bits are still
            // honored so the loop terminates correctly even when the
            // library wants to seek around.
            let mut buffer = Vec::new();

            loop {
                buffer.clear();
                reader.read_to_end(&mut buffer)?;
                if buffer.is_empty() {
                    break;
                }

                let result = handle.open_buffer_continue(&buffer);
                if result & 0x08 != 0 {
                    break;
                }

                let seek_pos = handle.open_buffer_continue_goto_get();
                if seek_pos != u64::MAX {
                    reader.seek(SeekFrom::Start(seek_pos))?;
                    let current_pos = reader.stream_position()?;
                    handle.open_buffer_init(file_size, current_pos);
                } else {
                    break;
                }
            }
        }

        handle.open_buffer_finalize();

        let output = handle.inform();

        // Reset the global option store on library builds that support
        // it, so the next parse call starts from a clean slate.
        if options.mediainfo_options.is_some() && version.supports_reset() {
            handle.option("Reset", "");
        }

        Ok(output)
    }

    fn parse_url_via_http(url: &str, options: &ParseOptions) -> Result<String> {
        let bytes = Self::fetch_http_bytes(url).map_err(|_| MediaInfoError::parse_error(url))?;
        let mut cursor = std::io::Cursor::new(bytes);
        Self::parse_reader_to_string_internal_unlocked(&mut cursor, options)
    }

    fn fetch_http_bytes(url: &str) -> Result<Vec<u8>> {
        let (host, host_header, path, port) =
            Self::split_http_url(url).ok_or_else(|| MediaInfoError::parse_error(url))?;

        let mut stream = TcpStream::connect((host.as_str(), port))?;
        let request = format!(
            "GET {} HTTP/1.1\r\nHost: {}\r\nConnection: close\r\n\r\n",
            path, host_header
        );
        stream.write_all(request.as_bytes())?;

        let mut response = Vec::new();
        stream.read_to_end(&mut response)?;

        let header_end = Self::find_http_header_end(&response)
            .ok_or_else(|| MediaInfoError::parse_error(url))?;
        let status_line = response
            .get(..header_end)
            .and_then(|header| header.split(|b| *b == b'\n').next())
            .and_then(|line| line.strip_suffix(b"\r"))
            .ok_or_else(|| MediaInfoError::parse_error(url))?;
        let status_str =
            std::str::from_utf8(status_line).map_err(|_| MediaInfoError::parse_error(url))?;
        let status_code = status_str
            .split_whitespace()
            .nth(1)
            .and_then(|code| code.parse::<u16>().ok())
            .ok_or_else(|| MediaInfoError::parse_error(url))?;
        if status_code != 200 && status_code != 206 {
            return Err(MediaInfoError::parse_error(url));
        }

        Ok(response[(header_end + 4)..].to_vec())
    }

    fn split_http_url(url: &str) -> Option<(String, String, String, u16)> {
        let without_scheme = url.strip_prefix("http://")?;
        let mut parts = without_scheme.splitn(2, '/');
        let host_port = parts.next().unwrap_or("");
        if host_port.is_empty() {
            return None;
        }

        let path = format!("/{}", parts.next().unwrap_or(""));
        let mut host = host_port;
        let mut port = 80u16;
        if let Some((left, right)) = host_port.rsplit_once(':')
            && right.chars().all(|c| c.is_ascii_digit())
        {
            host = left;
            port = right.parse().ok()?;
        }

        let host_header = if host_port.contains(':') {
            host_port
        } else {
            host
        };

        Some((host.to_string(), host_header.to_string(), path, port))
    }

    fn find_http_header_end(response: &[u8]) -> Option<usize> {
        response.windows(4).position(|window| window == b"\r\n\r\n")
    }

    /// Returns every parsed track in source order.
    pub fn tracks(&self) -> &[Track] {
        &self.tracks
    }

    /// Returns a mutable reference to the track list, so callers can
    /// reorder, filter, or otherwise mutate the parsed tracks in place.
    pub fn tracks_mut(&mut self) -> &mut Vec<Track> {
        &mut self.tracks
    }

    /// Consumes the [`MediaInfo`] and yields its owned track list.
    pub fn into_tracks(self) -> Vec<Track> {
        self.tracks
    }

    /// Returns the parsed tracks whose `track_type` is exactly `"General"`.
    ///
    /// Track type matching is byte-exact and case-sensitive: a track with
    /// type `"GENERAL"` would not be returned here.
    pub fn general_tracks(&self) -> Vec<&Track> {
        self.tracks
            .iter()
            .filter(|t| t.track_type() == "General")
            .collect()
    }

    /// Returns the parsed tracks whose `track_type` is exactly `"Video"`.
    pub fn video_tracks(&self) -> Vec<&Track> {
        self.tracks
            .iter()
            .filter(|t| t.track_type() == "Video")
            .collect()
    }

    /// Returns the parsed tracks whose `track_type` is exactly `"Audio"`.
    pub fn audio_tracks(&self) -> Vec<&Track> {
        self.tracks
            .iter()
            .filter(|t| t.track_type() == "Audio")
            .collect()
    }

    /// Returns the parsed tracks whose `track_type` is exactly `"Text"`.
    pub fn text_tracks(&self) -> Vec<&Track> {
        self.tracks
            .iter()
            .filter(|t| t.track_type() == "Text")
            .collect()
    }

    /// Returns the parsed tracks whose `track_type` is exactly `"Other"`.
    pub fn other_tracks(&self) -> Vec<&Track> {
        self.tracks
            .iter()
            .filter(|t| t.track_type() == "Other")
            .collect()
    }

    /// Returns the parsed tracks whose `track_type` is exactly `"Image"`.
    pub fn image_tracks(&self) -> Vec<&Track> {
        self.tracks
            .iter()
            .filter(|t| t.track_type() == "Image")
            .collect()
    }

    /// Returns the parsed tracks whose `track_type` is exactly `"Menu"`.
    pub fn menu_tracks(&self) -> Vec<&Track> {
        self.tracks
            .iter()
            .filter(|t| t.track_type() == "Menu")
            .collect()
    }

    /// Renders the [`MediaInfo`] as a flat JSON object.
    ///
    /// The returned [`serde_json::Map`] contains a single `tracks` key
    /// whose value is an ordered array of per-track dictionaries built
    /// by [`Track::to_data`]. Insertion order is preserved at both
    /// levels — the array follows source order, and each track map
    /// follows attribute encounter order.
    pub fn to_data(&self) -> serde_json::Map<String, serde_json::Value> {
        let tracks_data: Vec<serde_json::Value> = self
            .tracks
            .iter()
            .map(|t| serde_json::Value::Object(t.to_data()))
            .collect();

        let mut data = serde_json::Map::new();
        data.insert("tracks".to_string(), serde_json::Value::Array(tracks_data));
        data
    }

    /// Serializes [`MediaInfo::to_data`] to a JSON string.
    ///
    /// Keys are emitted in the same order they appear in the underlying
    /// maps, which is the order of attributes encountered during parse.
    ///
    /// # Errors
    ///
    /// Returns [`MediaInfoError::InvalidInput`] when `serde_json` cannot
    /// serialize the value (in practice this never happens because the
    /// values produced by [`MediaInfo::to_data`] are always
    /// JSON-representable).
    pub fn to_json(&self) -> Result<String> {
        serde_json::to_string(&self.to_data())
            .map_err(|e| MediaInfoError::invalid_input(e.to_string()))
    }

    fn load_library(
        library_file: Option<&Path>,
        library_search_dir: Option<&Path>,
    ) -> Result<(MediaInfoHandle, String, LibVersion)> {
        let search_dir = library_search_dir
            .map(PathBuf::from)
            .or_else(Self::default_library_search_dir);

        let paths = if let Some(path) = library_file {
            vec![path.to_path_buf()]
        } else {
            platform::get_library_paths(search_dir.as_deref())
        };

        let lib = Arc::new(MediaInfoLib::load_from_paths(&paths)?);

        let handle = MediaInfoHandle::new(lib);
        let version_str = handle.option("Info_Version", "");

        let version_number = Self::extract_version_number(&version_str)?;
        let version =
            LibVersion::parse(&version_number).ok_or(MediaInfoError::VersionDetectionFailed)?;

        Ok((handle, version_number, version))
    }

    fn default_library_search_dir() -> Option<PathBuf> {
        // Highest precedence: an explicit runtime override.
        if let Ok(dir) = std::env::var("RS_MEDIAINFO_LIBRARY_DIR")
            && !dir.trim().is_empty()
        {
            return Some(PathBuf::from(dir));
        }

        // Next: the directory the build script staged the bundled
        // library into, recorded at compile time.
        if let Some(dir) = option_env!("RS_MEDIAINFO_BUNDLED_DIR") {
            return Some(PathBuf::from(dir));
        }

        // Then: the directory containing the running executable, which
        // is the conventional place to ship a bundled library next to
        // the binary.
        if let Ok(exe) = std::env::current_exe()
            && let Some(parent) = exe.parent()
        {
            return Some(parent.to_path_buf());
        }

        // Last resort: the current working directory.
        std::env::current_dir().ok()
    }

    fn extract_version_number(version_str: &str) -> Result<String> {
        // The library reports the version as a leading prefix followed
        // by free-form text, e.g. `"MediaInfoLib - v20.09"` or
        // `"MediaInfoLib - v20.09 (build 123)"`. Both lowercase and
        // historical capital-V variants are accepted.
        let version_part = version_str
            .strip_prefix("MediaInfoLib - v")
            .or_else(|| version_str.strip_prefix("MediaInfoLib - V"))
            .ok_or(MediaInfoError::VersionDetectionFailed)?;

        let version_num = version_part
            .split_whitespace()
            .next()
            .ok_or(MediaInfoError::VersionDetectionFailed)?;

        Ok(version_num.to_string())
    }

    fn configure_parse_options(
        handle: &MediaInfoHandle,
        version: &LibVersion,
        version_number: &str,
        options: &ParseOptions,
    ) {
        // The Cover_Data option only exists on library 18.3 and newer;
        // older builds always emit cover data unconditionally.
        if version.supports_cover_data() {
            handle.option("Cover_Data", if options.cover_data { "base64" } else { "" });
        }

        handle.option("ParseSpeed", &options.parse_speed.to_string());

        if let Some(ref custom_options) = options.mediainfo_options {
            // On builds without a working Reset option there is no way
            // to undo whatever the caller's custom options changed, so
            // we surface a warning through the logger to make the
            // limitation visible to applications that watch logs.
            if !version.supports_reset() {
                let message = format!(
                    "This version of MediaInfo (v{}) does not support resetting all options to their default values, passing it custom options is not recommended and may result in unpredictable behavior, see https://github.com/MediaArea/MediaInfoLib/issues/1128",
                    version_number
                );
                Self::emit_warning(&message);
            }

            for (key, value) in custom_options {
                handle.option(key, value);
            }
        }
    }

    fn configure_output_options(
        handle: &MediaInfoHandle,
        version: &LibVersion,
        options: &ParseOptions,
    ) {
        handle.option("CharSet", "UTF-8");

        // The library has both an `Output` option and an `Inform`
        // option, and the two interact in surprising ways. Clearing
        // `Output` first guarantees that whatever we set on `Inform`
        // is the value that takes effect.
        handle.option("Output", "");

        let inform_value = if let Some(output) = options.output.as_deref() {
            Self::normalize_output_option(output)
        } else {
            version.xml_option_name()
        };
        handle.option("Inform", inform_value);

        handle.option("Complete", if options.full { "1" } else { "" });

        handle.option(
            "LegacyStreamDisplay",
            if options.legacy_stream_display {
                "1"
            } else {
                ""
            },
        );
    }

    fn normalize_output_option(value: &str) -> &str {
        // The friendly `"text"` alias maps to the empty string, which
        // is the value the library actually expects for plain text
        // output.
        if value.eq_ignore_ascii_case("text") {
            ""
        } else {
            value
        }
    }

    fn emit_warning(message: &str) {
        warn!("{}", message);
    }
}

impl std::str::FromStr for MediaInfo {
    type Err = MediaInfoError;

    /// Parses a pre-generated XML string by delegating to
    /// [`MediaInfo::from_xml`].
    fn from_str(s: &str) -> Result<Self> {
        MediaInfo::from_xml(s)
    }
}

impl TryFrom<&str> for MediaInfo {
    type Error = MediaInfoError;

    /// Parses a pre-generated XML string by delegating to
    /// [`MediaInfo::from_xml`].
    fn try_from(value: &str) -> Result<Self> {
        MediaInfo::from_xml(value)
    }
}

impl std::fmt::Display for MediaInfo {
    /// Renders the value in a stable, debuggable single-line form:
    /// `<MediaInfo N tracks>`.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "<MediaInfo {} tracks>", self.tracks.len())
    }
}

#[cfg(test)]
mod tests {
    //! Unit tests for items that intentionally remain private to this module.
    //!
    //! Tests that exercise the public API live alongside the rest of the
    //! integration suite under `tests/`.

    use super::*;

    #[test]
    fn test_default_library_search_dir_env_override() {
        let key = "RS_MEDIAINFO_LIBRARY_DIR";
        let original = std::env::var(key).ok();

        unsafe {
            std::env::set_var(key, "/tmp/rsmediainfo-test");
        }
        let resolved = MediaInfo::default_library_search_dir();
        assert_eq!(resolved, Some(PathBuf::from("/tmp/rsmediainfo-test")));

        unsafe {
            if let Some(value) = original {
                std::env::set_var(key, value);
            } else {
                std::env::remove_var(key);
            }
        }
    }

    #[test]
    fn test_normalize_output_option_text_alias() {
        assert_eq!(MediaInfo::normalize_output_option("text"), "");
        assert_eq!(MediaInfo::normalize_output_option("TEXT"), "");
        assert_eq!(MediaInfo::normalize_output_option("JSON"), "JSON");
    }
}