deepshrink_core/engine/

mod.rs

//! The compression engine contract and shared types.
//!
//! Key architectural decision: `core` is designed around the [`Engine`]
//! interface even while there is exactly one engine (media/ffmpeg). This lets us
//! plug in images/PDF/office later without rewriting the skeleton.
//!
//! Principle: [`Engine::plan`] is a pure, testable function (bitrate math);
//! side effects are isolated in [`Engine::run`].

#[cfg(feature = "ffmpeg")]
pub mod media;
pub mod plan;

use std::path::{Path, PathBuf};
use thiserror::Error;

use crate::detect::MediaKind;
use crate::options::{AudioChoice, AudioCodec, FpsOpt, QualityPreset, ResolutionOpt, VideoCodec};
use crate::size::Preset;

/// Source file metadata — the result of [`Engine::probe`].
#[derive(Debug, Clone, PartialEq)]
pub struct MediaInfo {
    pub path: PathBuf,
    pub kind: MediaKind,
    pub duration_sec: f64,
    pub size_bytes: u64,
    pub width: Option<u32>,
    pub height: Option<u32>,
    pub fps: Option<f64>,
    pub video_codec: Option<String>,
    pub audio_codec: Option<String>,
    pub audio_channels: Option<u32>,
    /// Bit rate of the (first) audio stream in bits/s, when the probe reports
    /// it — the ceiling for re-encoding a video's audio track.
    pub audio_bitrate_bps: Option<u64>,
    /// When / where / with what it was shot (container tags), carried over to
    /// the output when metadata is kept.
    pub capture: CaptureMeta,
    /// The video is HDR (HLG or PQ transfer), `None` for SDR / unknown / audio.
    pub hdr: Option<Hdr>,
}

/// HDR transfer function of a source video.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Hdr {
    /// Hybrid Log-Gamma (`arib-std-b67`) — iPhone and most phone cameras.
    Hlg,
    /// Perceptual Quantizer (`smpte2084`) — HDR10 / Dolby Vision from cameras,
    /// screen recordings, films.
    Pq,
}

impl Hdr {
    /// From an ffprobe `color_transfer` value.
    pub fn from_transfer(transfer: &str) -> Option<Self> {
        match transfer {
            "arib-std-b67" => Some(Self::Hlg),
            "smpte2084" => Some(Self::Pq),
            _ => None,
        }
    }
}

/// Capture metadata read from the source's container tags. iPhone videos keep
/// these as `com.apple.quicktime.*` keys; others use plain `location` / `make`
/// / `model` / `creation_time`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct CaptureMeta {
    /// When it was shot, UTC ISO-8601 (`2026-09-26T17:01:54Z`): Apple's
    /// `creationdate` (local time + offset) when present — the container's
    /// `creation_time` can be the moment the file was exported or AirDropped.
    pub created_utc: Option<String>,
    /// The original local timestamp as written (`2026-09-26T20:01:54+0300`).
    pub created_local: Option<String>,
    /// ISO 6709 location (`+50.4160+030.2796+155.635/`).
    pub location: Option<String>,
    pub make: Option<String>,
    pub model: Option<String>,
}

impl MediaInfo {
    /// Whether the source carries an audio track.
    pub fn has_audio(&self) -> bool {
        self.audio_codec.is_some()
    }
}

/// What the user wants in terms of size.
#[derive(Debug, Clone, PartialEq)]
pub enum SizeGoal {
    /// Fit into an absolute size (bytes).
    Target(u64),
    /// Reduce by a fraction of the original (0.70 = "by 70%").
    Reduce(f64),
    /// Platform preset (sets the target size).
    Preset(Preset),
    /// Smart, quality-preserving shrink without a hard limit.
    Quality,
}

/// Compression options passed to the engine — the decoded form of the flags.
#[derive(Debug, Clone, PartialEq)]
pub struct ShrinkOpts {
    pub goal: SizeGoal,
    pub video_codec: VideoCodec,
    /// What to do with the audio track *inside a video*.
    pub audio: AudioChoice,
    pub resolution: ResolutionOpt,
    pub fps: FpsOpt,
    pub quality: QualityPreset,
    /// Codec for a *pure-audio* input.
    pub audio_codec: AudioCodec,
    /// Downmix pure audio to mono.
    pub mono: bool,
    /// Force a sample rate (Hz) for pure audio; `None` keeps the source rate.
    pub sample_rate: Option<u32>,
    /// Prefer VBR where the codec supports it.
    pub vbr: bool,
    /// Target VMAF: in quality mode, search CRF for the smallest output that
    /// still scores at least this. `None` disables VMAF-aware encoding.
    pub target_vmaf: Option<f64>,
    /// Explicit output path; when `None` the engine derives one.
    pub output: Option<PathBuf>,
    /// Force two-pass on or off for a size-targeted video encode. `None` lets
    /// the engine decide (two-pass whenever it encodes to a bitrate budget).
    /// `Some(true)` is only meaningful in bitrate mode — a CRF encode has no
    /// budget for a first pass to measure.
    pub two_pass: Option<bool>,
    /// Target resolution (dots per inch) for raster images *embedded in a
    /// document*, measured at the size they are placed on the page. Only the
    /// document engines act on it — the media engine ignores it, as pixels in a
    /// video have no physical size.
    pub dpi: Option<u32>,
    /// Allow a quality-mode result that is not smaller than the source.
    /// Off by default: re-encoding an already-compact lossy file only loses
    /// quality, so the engine keeps the original instead (sample-predicted for
    /// video, bitrate-compared for audio, and checked after every encode).
    pub allow_larger: bool,
    /// Carry the source's metadata over (creation date, location, camera —
    /// QuickTime keys included) and its modification time. On by default;
    /// `false` strips metadata from the output.
    pub keep_metadata: bool,
    /// Encode video with Apple's hardware encoder (VideoToolbox) when this Mac
    /// has it — ~3–5× faster and a fraction of the memory, for a larger file
    /// (see [`QualityPreset::default_hw_quality`]). Off by default; ignored for
    /// AV1 and where `media::hardware_encoding_available` is false.
    pub hardware: bool,
}

impl Default for ShrinkOpts {
    fn default() -> Self {
        Self {
            goal: SizeGoal::Quality,
            video_codec: VideoCodec::H264,
            audio: AudioChoice::Keep,
            resolution: ResolutionOpt::Auto,
            fps: FpsOpt::Auto,
            quality: QualityPreset::Balanced,
            audio_codec: AudioCodec::Aac,
            mono: false,
            sample_rate: None,
            vbr: false,
            target_vmaf: None,
            output: None,
            two_pass: None,
            dpi: None,
            allow_larger: false,
            keep_metadata: true,
            hardware: false,
        }
    }
}

/// Video encoding parameters.
#[derive(Debug, Clone, PartialEq)]
pub struct VideoSpec {
    pub codec: VideoCodec,
    /// Target average bitrate (bits/s) for two-pass; `None` in CRF/quality mode.
    pub bitrate_bps: Option<u64>,
    /// CRF value for quality mode; `None` in bitrate mode.
    pub crf: Option<u8>,
    /// Downscale target of the *short* side ("1080p" = 1080 px on the short
    /// side, like phones and sites mean it); `None` keeps the source resolution.
    pub height: Option<u32>,
    /// The video is shown taller than wide: the short side is its width.
    pub portrait: bool,
    /// Frame-rate cap; `None` keeps the source rate.
    pub fps: Option<u32>,
    pub preset: QualityPreset,
    /// Encode with Apple's hardware encoder: `crf` then carries its `-q:v`
    /// quality (1–100, higher = better) and two-pass doesn't apply.
    pub hardware: bool,
    /// Tone-map this HDR source to 8-bit SDR (BT.709): set for size targets /
    /// platform presets, where the file has to play everywhere — 10-bit H.264
    /// (High 10) and HDR aren't decoded by most phones and browsers.
    pub to_sdr: Option<Hdr>,
}

/// Audio encoding parameters (absent means drop the track).
#[derive(Debug, Clone, PartialEq)]
pub struct AudioSpec {
    pub codec: AudioCodec,
    pub bitrate_bps: u64,
    /// Downmix to a single channel.
    pub mono: bool,
    /// Resample to this rate (Hz); `None` keeps the source rate.
    pub sample_rate: Option<u32>,
    /// Prefer VBR where the codec supports it.
    pub vbr: bool,
}

impl AudioSpec {
    /// A plain CBR/ABR track (used for the audio track inside a video).
    pub fn cbr(codec: AudioCodec, bitrate_bps: u64) -> Self {
        Self {
            codec,
            bitrate_bps,
            mono: false,
            sample_rate: None,
            vbr: false,
        }
    }
}

/// The full encode recipe.
#[derive(Debug, Clone, PartialEq)]
pub struct EncodeSpec {
    pub video: VideoSpec,
    /// `None` means `-an` (no audio).
    pub audio: Option<AudioSpec>,
    pub faststart: bool,
    pub two_pass: bool,
    /// Stream-copy remux only: the source already fits, so never re-encode
    /// (and never inflate). `video`/`audio` are ignored when set.
    pub passthrough: bool,
    /// Pure-audio encode: emit `-vn` and use `audio` only (`video` is ignored).
    pub audio_only: bool,
    /// Target DPI for a document's embedded images (see [`ShrinkOpts::dpi`]).
    /// Document engines only; ignored by the media engine.
    pub dpi: Option<u32>,
    /// Copy metadata + mtime from the source (see [`ShrinkOpts::keep_metadata`]).
    pub keep_metadata: bool,
    /// Explicit container tags written to the output (`creation_time`,
    /// `location`, `make`, `model`, `date`) — the capture metadata re-stated
    /// in the form Apple's readers (Photos, Finder) actually understand.
    pub tags: Vec<(String, String)>,
}

/// The encode plan — the result of [`Engine::plan`]. Usable for `--dry-run`.
#[derive(Debug, Clone, PartialEq)]
pub struct EncodePlan {
    pub input: PathBuf,
    pub output: PathBuf,
    /// Human-readable description of the plan (codec, bitrates, passes).
    pub summary: String,
    /// Expected final size in bytes, if predictable.
    pub expected_bytes: Option<u64>,
    /// The hard size cap, if any (drives the post-encode correction retry).
    pub target_bytes: Option<u64>,
    /// Target VMAF for a CRF search, if requested (quality mode only).
    pub target_vmaf: Option<f64>,
    /// Source duration in seconds (for progress reporting).
    pub source_duration_sec: f64,
    /// Source resolution and frame rate — the reference for VMAF measurement.
    pub source_width: Option<u32>,
    pub source_height: Option<u32>,
    pub source_fps: Option<f64>,
    pub spec: EncodeSpec,
    /// Keep the original instead of producing a result that isn't smaller
    /// (see [`ShrinkOpts::allow_larger`]). Engines without a guard set `false`.
    pub guard_larger: bool,
    /// Size targets only: the quality preset's CRF, used as a ceiling — when a
    /// CRF encode is predicted to land well under the target, it's used instead
    /// of spending the whole budget (a 2 s clip needn't take 10 MB for Discord).
    pub ceiling_crf: Option<u8>,
}

/// The execution result — the result of [`Engine::run`].
#[derive(Debug, Clone, PartialEq)]
pub struct Outcome {
    pub output: PathBuf,
    pub final_bytes: u64,
    /// Measured VMAF of the result vs the source, if a measurement was taken.
    pub vmaf: Option<f64>,
    /// The output is the source copied as-is (stream copy): it already fit the
    /// target, or re-encoding it would not have made it smaller.
    pub already_compact: bool,
}

/// Engine errors.
#[derive(Debug, Error)]
pub enum EngineError {
    #[error("input not supported by this engine: {0}")]
    Unsupported(String),
    #[error("cannot reach target size at a reasonable quality")]
    Infeasible,
    #[error("not yet implemented: {0}")]
    NotImplemented(&'static str),
    #[cfg(feature = "ffmpeg")]
    #[error(transparent)]
    Ffmpeg(#[from] deepshrink_ffmpeg::FfmpegError),
    #[error(transparent)]
    Io(#[from] std::io::Error),
}

/// A quality-mode re-encode has to save at least this share of the source to
/// be worth it; below that the original is kept. A minutes-long 4K encode for
/// a 1 % saving isn't a compression — just a generation of quality loss.
pub const MIN_SAVING: f64 = 0.05;

/// Whether a result of `expected` bytes isn't worth producing for a `source`
/// of `source` bytes (saves less than [`MIN_SAVING`]). The guard, dry runs and
/// UI previews all ask this, so a preview and the run agree.
pub fn not_worth_it(expected: u64, source: u64) -> bool {
    source > 0 && expected as f64 >= source as f64 * (1.0 - MIN_SAVING)
}

impl EngineError {
    /// The run was stopped through its cancel token (see
    /// `MediaEngine::with_cancel`) — not a failure to report.
    pub fn is_cancelled(&self) -> bool {
        #[cfg(feature = "ffmpeg")]
        return matches!(
            self,
            Self::Ffmpeg(deepshrink_ffmpeg::FfmpegError::Cancelled)
        );
        #[cfg(not(feature = "ffmpeg"))]
        false
    }
}

/// The compression engine contract. The one v0.1 implementation is `media::MediaEngine`.
pub trait Engine {
    /// Whether this engine handles the given file.
    fn supports(&self, input: &Path) -> bool;
    /// Read metadata (side effect: run a probe, e.g. ffprobe).
    fn probe(&self, input: &Path) -> Result<MediaInfo, EngineError>;
    /// Build the encode plan. Pure function — tested without encoding.
    fn plan(&self, info: &MediaInfo, opts: &ShrinkOpts) -> Result<EncodePlan, EngineError>;
    /// Execute the plan (side effect: run the encoder binary).
    fn run(&self, plan: &EncodePlan) -> Result<Outcome, EngineError>;
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_re_encode_must_save_at_least_five_percent() {
        assert!(not_worth_it(100, 100));
        assert!(not_worth_it(120, 100));
        assert!(not_worth_it(96, 100)); // −4 %: keep the original
        assert!(!not_worth_it(95, 1_000)); // −90 %
        assert!(!not_worth_it(949, 1_000)); // −5.1 %
        assert!(!not_worth_it(0, 0)); // unknown source: no call
    }
}