Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

47.8 KB
Raw Blame
//! Addon napi-rs : pont Electron ↔ `openscreen_compositor::live::LiveView`. Expose la vue
//! offscreen (Option B, post-readback `Vec<u8>` RGBA8 → `<canvas>` HTML) à la
//! glue TS (native-bridge domaine "compositor"). Les `#[napi]` sont appelés
//! depuis le thread principal Node (là où vit la `BrowserWindow`) ; le rendu et
//! la publication de la dernière frame vivent sur le thread dédié de `LiveView`
//! et sont récupérés via `read_frame`.

use napi::bindgen_prelude::*;
use napi::threadsafe_function::{ErrorStrategy, ThreadsafeFunction, ThreadsafeFunctionCallMode};
use napi::{Env, JsFunction, Task};
use napi_derive::napi;
use openscreen_compositor::compositor::{live_params_from_scene, Compositor};
use openscreen_compositor::d3d::{Backend, Gpu};
use openscreen_compositor::export_control::{ExportCancelled, ExportControl};
use openscreen_compositor::frame_geometry::FootageQuad;
use openscreen_compositor::gif_export::{GifExportParams, GifStats};
use openscreen_compositor::live::{LiveView, PausedPreviews};
use openscreen_compositor::scene::Scene;
use openscreen_compositor::{config, pipeline};
use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::{Mutex, OnceLock};

/// Résolution cible du preview en pixels device (largeur/hauteur du `<canvas>`
/// Electron affichant la preview). `x`/`y` ne sont plus utilisés (Option B :
/// la position est gérée par CSS côté web) — conservés dans l'objet pour
/// compatibilité structurelle avec l'ancien code de la glue TS, simplement
/// ignorés côté Rust.
#[napi(object)]
pub struct CompositorViewRect {
    pub x: i32,
    pub y: i32,
    pub width: i32,
    pub height: i32,
}

static REGISTRY: OnceLock<Mutex<HashMap<i32, LiveView>>> = OnceLock::new();
static NEXT_ID: Mutex<i32> = Mutex::new(1);

fn registry() -> &'static Mutex<HashMap<i32, LiveView>> {
    REGISTRY.get_or_init(|| Mutex::new(HashMap::new()))
}

/// Crée une vue **offscreen** (pas de HWND, pas de fenêtre native). Démarre juste
/// un thread de rendu qui compose chaque frame, blit-resize vers `rect.width`×
/// `rect.height` (réutilise le même `ensure_resize_target`/`blit_resized` que
/// l'export), lit le résultat vers CPU via staging `D3D11_USAGE_STAGING` +
/// `Map`/`Unmap` et stocke un `Vec<u8>` RGBA8 tightly-packed dans la vue pour
/// que `read_frame` le retourne à la glue TS.
///
/// `screen_path` est requis (F3 : le vrai enregistrement de l'app — deux
/// fichiers H264 séparés). `webcam_path`/`cursor_path` sont optionnels
/// (absents → pas de caméra / pas de curseur).
///
/// `rect` ne sert plus que pour `width`/`height` (résolution cible du preview) ;
/// `x`/`y` sont ignorés (compat structurelle — la position est gérée par CSS).
/// Quel backend cette machine utilisera : `"hardware"`, `"cpu"`, ou `"none"` si aucun
/// device D3D11 ne se crée (la vue échouera alors avec son propre message, plus précis).
///
/// Sert à PRÉVENIR : sur `"cpu"`, le rendu passe par WARP + décodage logiciel — la
/// preview tombe à ~8 fps avec tous les effets et l'export met des minutes au lieu de
/// secondes. L'utilisateur doit le savoir AVANT de lancer un export, pas après. D'où une
/// question posée au système et non à une vue : la modale d'export la pose sans qu'aucune
/// preview n'existe. Réponse mise en cache côté Rust — c'est une propriété de la machine.
#[napi]
pub fn probe_backend() -> String {
    match Gpu::probe() {
        Some(Backend::Hardware) => "hardware",
        Some(Backend::Cpu) => "cpu",
        None => "none",
    }
    .to_string()
}

/// Si cette machine peut produire un masque de segmentation, c'est-à-dire si la bibliothèque
/// ONNX Runtime est là où l'app l'a posée.
///
/// Sert à NE PAS MENTIR : le contrôle « fond de caméra » est le seul de l'éditeur dont l'effet
/// dépend d'un binaire optionnel. Sans lui, `Segmenter::load` refuse, le compositeur dessine la
/// webcam telle quelle, et l'utilisateur clique sur un réglage qui ne fait rien — exactement ce
/// qu'un contrôle ne doit jamais faire.
///
/// Une question posée au système plutôt que devinée depuis la plateforme : `darwin` ne suffit
/// pas à répondre, puisque l'amont ne publie aucun binaire ONNX pour les Macs Intel, et une
/// build de dev ou un `--dir` n'en ont pas davantage. Seul l'état réel de la machine le sait.
#[napi]
pub fn segmentation_runtime_available() -> bool {
    openscreen_compositor::segmentation::runtime_available()
}

pub struct SegmentFrameTask {
    model_path: String,
    rgba: Vec<u8>,
}

impl Task for SegmentFrameTask {
    type Output = Vec<u8>;
    type JsValue = Buffer;

    fn compute(&mut self) -> Result<Self::Output> {
        let rgb: Vec<u8> = self
            .rgba
            .chunks_exact(4)
            .flat_map(|p| [p[0], p[1], p[2]])
            .collect();
        // ponytail: une session ONNX chargée par appel (quelques dizaines de ms), parce qu'il
        // n'y a qu'un appel par caméra et par ouverture du panneau. À garder en cache si un
        // appelant se met à segmenter en continu.
        let mut segmenter = openscreen_compositor::segmentation::Segmenter::load(
            std::path::Path::new(&self.model_path),
        )
        .map_err(|e| Error::from_reason(format!("{e:#}")))?;
        segmenter
            .run(&rgb)
            .map(<[u8]>::to_vec)
            .map_err(|e| Error::from_reason(format!("{e:#}")))
    }

    fn resolve(&mut self, _env: Env, mask: Self::Output) -> Result<Self::JsValue> {
        Ok(mask.into())
    }
}

/// Masque du sujet pour UNE image, sans vue : la vignette de recadrage du panneau caméra s'en
/// sert pour montrer le fond choisi sur sa propre frame.
///
/// `rgba` est une frame RGBA8 déjà réduite à la taille du modèle (`segmentation::MODEL_WIDTH` x
/// `MODEL_HEIGHT`), soit le `getImageData` d'un canvas tel quel. Le retour a le format de
/// `Segmenter::run` : un octet par pixel, 0 = fond, 255 = sujet.
///
/// `AsyncTask`, comme `remux_seekable` : charger la session prend plus longtemps que l'inférence,
/// et ce temps n'a rien à faire sur le thread principal de Node.
#[napi]
pub fn segment_frame(model_path: String, rgba: Buffer) -> AsyncTask<SegmentFrameTask> {
    AsyncTask::new(SegmentFrameTask {
        model_path,
        rgba: rgba.to_vec(),
    })
}

#[napi]
pub fn create_view(
    rect: CompositorViewRect,
    screen_path: Option<String>,
    webcam_path: Option<String>,
    cursor_path: Option<String>,
) -> Result<i32> {
    let screen = screen_path
        .ok_or_else(|| Error::from_reason("create_view: screen_path is required"))?;
    let webcam = webcam_path.unwrap_or_default();
    let cursor = cursor_path.unwrap_or_default();
    let view = LiveView::create(
        rect.width.max(1) as u32,
        rect.height.max(1) as u32,
        &screen,
        &webcam,
        &cursor,
    )
    .map_err(|e| Error::from_reason(format!("{e:#}")))?;
    let id = {
        let mut n = NEXT_ID.lock().unwrap();
        let id = *n;
        *n += 1;
        id
    };
    registry().lock().unwrap().insert(id, view);
    Ok(id)
}

/// Met à jour la résolution cible du preview. L'ancienne sémantique « position
/// + taille de la fenêtre overlay » (`x, y, w, h`) n'a plus lieu d'être (la
/// preview est un bitmap posé sur un `<canvas>` Electron, positionné en CSS) :
/// on garde la même forme d'objet `CompositorViewRect` côté TS pour ne pas
/// casser l'ABI, mais `x`/`y` sont silencieusement ignorés et seules
/// `width`/`height` sont propagées au thread de rendu. La résolution prend
/// effet au prochain tour (`compositor::readback_resized` reconstruit la
/// staging si `width`/`height` ont changé).
#[napi]
pub fn set_rect(id: i32, rect: CompositorViewRect) {
    if let Some(v) = registry().lock().unwrap().get(&id) {
        v.set_rect(rect.width.max(1) as u32, rect.height.max(1) as u32);
    }
}

/// Une frame de preview auto-descriptive : ses pixels PLUS tout ce qu'il faut pour
/// les interpréter (dimensions) et pour décider s'il faut les repeindre (génération).
/// Retournée par `read_frame`. Le consommateur JS n'a plus à deviner la taille depuis
/// `canvas.width` (ancien couplage implicite fragile) : elle voyage avec les octets.
#[napi(object)]
pub struct FramePacket {
    /// Génération monotone de CETTE frame (≥ 1). Le consommateur la retient et la
    /// repasse en `since_gen` au prochain appel ; tant qu'elle ne change pas, il n'y
    /// a rien de neuf à peindre. `f64` car napi n'expose pas `u64` — sans risque : la
    /// génération n'atteindra jamais 2^53 (ce serait des milliards d'années de rendu).
    pub gen: f64,
    pub width: u32,
    pub height: u32,
    /// R,G,B,A tightly-packed, `width * height * 4` octets — ce que `putImageData` /
    /// `ImageData` attendent côté JS (canvas 2D, format natif RGBA8).
    pub data: Buffer,
    /// Le métrage dans cette image : ses coins TL, TR, BR, BL (x, y en fractions de l'image,
    /// huit nombres), là où l'éditeur pose le gimbal d'un flou. Absent avant toute composition.
    pub footage: Option<Vec<f64>>,
    /// Le métrage passe de ses coins à l'image par leur homographie (caméra réelle), pas par
    /// leur interpolation bilinéaire.
    pub footage_projective: bool,
    /// Clip actif de la scène quand la frame a été composée (`FramePosition`).
    pub clip_index: u32,
    /// Temps source de la frame écran composée, en secondes.
    pub source_time_sec: f64,
}

/// Renvoie la dernière frame readback du thread de rendu SI elle est plus récente que
/// `since_gen`, sous forme de {@link FramePacket} (génération + dimensions + pixels).
///
/// `Ok(None)` — le consommateur n'a rien à peindre — si :
///   - la vue `id` n'existe pas dans le registre (jamais créée ou déjà détruite),
///   - aucune frame n'a encore été composée (1er appel avant que le thread de rendu
///     n'ait publié quoi que ce soit), OU
///   - le consommateur possède déjà la génération courante (`gen <= since_gen`). C'est
///     le cas dominant en édition (preview figée en pause) : on renvoie `None` SANS
///     cloner le buffer ni traverser l'IPC. Tout le coût `O(w·h)` par frame — clone
///     Rust + structured-clone IPC + copies canvas — disparaît tant que rien ne bouge.
///     Passer `since_gen = 0` force la livraison de la frame courante (1re lecture).
///
/// Quand une frame EST retournée, son `data` est détaché du `Vec<u8>` interne
/// (l'ownership passe au JS GC) ; le thread de rendu continue à composer sans bloquer
/// le thread Node.
#[napi]
pub fn read_frame(id: i32, since_gen: f64) -> Result<Option<FramePacket>> {
    // Snapshot le pixel buffer HORS du lock du registre : on en a besoin vivant
    // (r#[napi] retourne un Buffer qui consomme l'ownership du Vec). Sinon le
    // MutexGuard serait tenu pendant que la frame est consommée par JS, ce qui
    // bloquerait tout autre appel napi (`set_rect`, `destroy_view`, ...).
    let slot = match registry().lock().unwrap().get(&id) {
        None => return Ok(None),
        Some(v) => {
            // Le thread de rendu est mort (device D3D11 indisponible, décodeur en échec…) :
            // il ne publiera plus jamais de frame. Sans ce relais, `create_view` a déjà
            // répondu Ok et l'échec ne se voyait que dans un `eprintln!` — l'utilisateur
            // restait devant un canvas noir sans explication (PR #162). La boucle de pull
            // du renderer appelle ceci ~30×/s, donc l'erreur remonte tout de suite, et par
            // le chemin d'erreur que `read_frame` a déjà (`Result`), sans changer le contrat.
            if let Some(fatal) = v.fatal_error() {
                return Err(Error::from_reason(fatal));
            }
            v.latest_frame_since(since_gen.max(0.0) as u64)
        }
    };
    Ok(slot.map(|(gen, w, h, pixels, footage, position)| {
        debug_assert_eq!(pixels.len(), (w as usize) * (h as usize) * 4);
        FramePacket {
            gen: gen as f64,
            width: w,
            height: h,
            data: Buffer::from(pixels),
            footage: footage_corners(footage),
            footage_projective: footage.is_some_and(|q| q.projective),
            clip_index: position.clip_index,
            source_time_sec: position.source_time_sec,
        }
    }))
}

/// Les coins du métrage (TL, TR, BR, BL) aplatis en huit nombres, tels que JS les lit.
fn footage_corners(footage: Option<FootageQuad>) -> Option<Vec<f64>> {
    footage.map(|q| q.corners.iter().flatten().map(|&v| v as f64).collect())
}

/// Une frame de preview posée dans une texture partagée : de quoi l'importer côté GPU
/// (`sharedTexture.importSharedTexture`) au lieu d'en recevoir les pixels.
#[napi(object)]
pub struct SharedFramePacket {
    pub gen: f64,
    /// Case de l'anneau qui porte la frame, à rendre avec `gen` par `release_shared_frame`
    /// quand Chromium l'a relâchée.
    pub slot: u32,
    /// Handle NT de la texture, 8 octets little-endian : la forme qu'attend Electron
    /// (`SharedTextureHandle.ntHandle`). Valable dans ce processus seulement.
    pub handle: Buffer,
    pub width: u32,
    pub height: u32,
    pub footage: Option<Vec<f64>>,
    pub footage_projective: bool,
    pub clip_index: u32,
    pub source_time_sec: f64,
}

/// Livrer les frames de la vue par textures partagées plutôt que par `read_frame`. Rend
/// `false` quand la machine ne le peut pas (hors Windows, backend logiciel) : la vue reste
/// alors au readback.
#[napi]
pub fn set_shared_frames(id: i32, enabled: bool) -> bool {
    registry()
        .lock()
        .unwrap()
        .get(&id)
        .is_some_and(|v| v.set_shared_frames(enabled))
}

/// Le pendant de `read_frame` pour une vue en textures partagées : la dernière frame posée
/// dans l'anneau, si elle est plus récente que `since_gen`. Sa case reste tenue jusqu'à
/// `release_shared_frame`. `Ok(None)` aussi quand la vue relit en RAM.
#[napi]
pub fn read_shared_frame(id: i32, since_gen: f64) -> Result<Option<SharedFramePacket>> {
    let frame = match registry().lock().unwrap().get(&id) {
        None => return Ok(None),
        Some(v) => {
            // Même relais que `read_frame` : sans lui, un thread de rendu mort ne se verrait
            // que par un canvas noir.
            if let Some(fatal) = v.fatal_error() {
                return Err(Error::from_reason(fatal));
            }
            v.take_shared_frame(since_gen.max(0.0) as u64)
        }
    };
    Ok(frame.map(|f| SharedFramePacket {
        gen: f.gen as f64,
        slot: f.slot,
        handle: f.handle.to_le_bytes().to_vec().into(),
        width: f.width,
        height: f.height,
        footage: footage_corners(f.footage),
        footage_projective: f.footage.is_some_and(|q| q.projective),
        clip_index: f.position.clip_index,
        source_time_sec: f.position.source_time_sec,
    }))
}

/// Chromium a relâché la frame `gen` de la case `slot` (`allReferencesReleased` côté
/// Electron) : le thread de rendu peut y réécrire. Sans effet sur une vue détruite.
#[napi]
pub fn release_shared_frame(id: i32, slot: u32, gen: f64) {
    if let Some(v) = registry().lock().unwrap().get(&id) {
        v.release_shared_frame(slot, gen.max(0.0) as u64);
    }
}

/// Param live (inspector). Le type de valeur route vers le bon setter :
/// bool = switch (webcamMirror…), number = slider (shadow/roundness/motionBlur/backgroundBlur),
/// string = sélection (backgroundColor "#rrggbb").
#[napi]
pub fn set_param(id: i32, key: String, value: Either3<bool, f64, String>) {
    if let Some(v) = registry().lock().unwrap().get(&id) {
        match value {
            Either3::A(b) => v.set_param_bool(&key, b),
            Either3::B(n) => v.set_param_num(&key, n),
            Either3::C(s) => v.set_param_str(&key, &s),
        }
    }
}

#[napi]
pub fn set_playing(id: i32, playing: bool) {
    if let Some(v) = registry().lock().unwrap().get(&id) {
        v.set_playing(playing);
    }
}

/// Positionne la vue au temps SOURCE du clip actif (conversion timeline faite côté renderer).
#[napi]
pub fn present_time(id: i32, seconds: f64) {
    if let Some(v) = registry().lock().unwrap().get(&id) {
        v.set_time(seconds);
    }
}

/// Remplace les sources du clip actif sans recréer la vue ni son thread de rendu. L'identité
/// timeline et le playhead source sont atomiques avec le switch : deux clips partageant les
/// mêmes fichiers restent distincts, et les deux décodeurs ouvrent directement la bonne frame.
#[napi]
pub fn set_active_clip(
    id: i32,
    screen_path: String,
    webcam_path: String,
    webcam_offset_sec: f64,
    clip_index: u32,
    source_time_sec: f64,
) {
    if let Some(v) = registry().lock().unwrap().get(&id) {
        v.set_active_clip(
            &screen_path,
            &webcam_path,
            webcam_offset_sec,
            clip_index as usize,
            source_time_sec,
        );
    }
}

/// Ce que l'outil de l'agent apprend d'un effet avant de l'accepter (`docs/shader-effects.md`, E.3).
#[napi(object)]
pub struct ShaderEffectCheck {
    /// L'erreur telle que l'agent doit la lire (ligne, colonne, extrait), ou `None` s'il est accepté.
    pub error: Option<String>,
    /// Le palier de coût : "light", "medium", "heavy" ou "very-heavy". Indicatif, jamais un refus.
    pub tier: Option<String>,
    /// Lectures de `frame()` par pixel, boucles multipliées par leur borne.
    pub frame_reads: Option<f64>,
    /// Itérations de boucle par pixel.
    pub iterations: Option<f64>,
}

pub struct CheckShaderEffectTask {
    code: String,
    params_json: String,
}

impl Task for CheckShaderEffectTask {
    type Output = ShaderEffectCheck;
    type JsValue = ShaderEffectCheck;

    fn compute(&mut self) -> Result<Self::Output> {
        Ok(match openscreen_compositor::shader_fx::check_for_agent_json(&self.code, &self.params_json) {
            Ok(report) => ShaderEffectCheck {
                error: None,
                tier: Some(report.tier.name().to_string()),
                frame_reads: Some(report.frame_reads as f64),
                iterations: Some(report.iterations as f64),
            },
            Err(error) => ShaderEffectCheck { error: Some(error), tier: None, frame_reads: None, iterations: None },
        })
    }

    fn resolve(&mut self, _env: Env, check: Self::Output) -> Result<Self::JsValue> {
        Ok(check)
    }
}

/// Vérifie le WGSL d'un effet shader : validation, bornes des boucles, compilation réelle pour le
/// backend de la machine (FXC sur Windows, Metal sur macOS, SPIR-V sur Linux), et palier de coût.
/// `params_json` : les paramètres déclarés, `[{ "name": "strength", "type": "number" }, …]`.
///
/// `AsyncTask`, comme `segment_frame` : la compilation Metal d'une source neuve prend 120 ms, et
/// jusqu'à 375 ms pour la première du processus. Ce temps n'a rien à faire sur le thread principal.
#[napi]
pub fn check_shader_effect(code: String, params_json: String) -> AsyncTask<CheckShaderEffectTask> {
    AsyncTask::new(CheckShaderEffectTask { code, params_json })
}

/// Installe la scène de l'app (JSON `SceneDescription`) sur la vue : layout preset piloté par
/// l'app au lieu de la fixture. JSON invalide → ignoré côté natif.
#[napi]
pub fn set_scene(id: i32, scene_json: String) {
    if let Some(v) = registry().lock().unwrap().get(&id) {
        v.set_scene(&scene_json);
    }
}

#[napi]
pub fn destroy_view(id: i32) {
    // remove hors du lock : le Drop (join du thread de rendu) ne le tient pas.
    let removed = registry().lock().unwrap().remove(&id);
    drop(removed);
}

/// Bilan d'un export natif (mesure §10 : une lecture d'horloge avant-après tout le run).
#[napi(object)]
pub struct ExportStats {
    pub frames: u32,
    pub wall_s: f64,
    pub fps: f64,
    /// Durée de la vidéo exportée (secondes) — distincte de `wall_s` (temps de rendu réel).
    pub video_duration_s: f64,
}

/// Bilan d'un export GIF natif. Mêmes champs que `ExportStats` (frames /
/// wall / fps / durée) plus la taille du fichier sur disque — le format
/// est petit (256-color indexed + LZW) et la taille est une mesure
/// d'utilité, pas un détail technique. Sert à la fois au bench et à
/// l'UI d'export, seul chemin GIF de l'app.
#[napi(object)]
pub struct GifExportStats {
    pub frames: u32,
    pub wall_s: f64,
    pub fps: f64,
    /// Durée du GIF exporté (s) — distincte de `wall_s` (temps de rendu).
    pub video_duration_s: f64,
    /// Taille du fichier `.gif` final sur disque (octets), mesurée après
    /// le drop de l'encodeur (donc après le flush du trailer GIF89a).
    pub file_bytes: f64,
}

/// Builds a `progress: &mut dyn FnMut(u64)` closure (the shape both `run_composited` and
/// `run_composited_multi` already call once per encoded frame, for free — measured to not
/// affect the C8 benchmark's fps) that forwards to `tsfn`, throttled to ~10/s. Encoding at
/// typical export rates would otherwise cross the JS thread boundary dozens of times a
/// second for no UI benefit; the throttle keeps that cost negligible regardless of encode
/// speed. Always reports the very first tick (frame <= 1) so a fast/short export still
/// shows at least one progress update instead of jumping straight to the final Promise
/// resolution.
fn throttled_progress(
    tsfn: Option<ThreadsafeFunction<u32, ErrorStrategy::Fatal>>,
) -> impl FnMut(u64) {
    let mut last_sent = std::time::Instant::now() - std::time::Duration::from_secs(1);
    move |frames: u64| {
        let Some(tsfn) = &tsfn else { return };
        let now = std::time::Instant::now();
        if frames <= 1 || now.duration_since(last_sent).as_millis() >= 100 {
            last_sent = now;
            tsfn.call(frames as u32, ThreadsafeFunctionCallMode::NonBlocking);
        }
    }
}

/// Pauses every live preview of this process for the duration of an export — their render
/// threads stop composing/presenting, which frees the GPU's 3D engine (measured: preview on
/// ~72 fps → preview off ~125 fps) — and gives each one back the transport it was found with
/// when dropped, including on an early `return Err` or a panic.
///
/// Restoring the saved state instead of resuming everything is the whole point; see
/// `PausedPreviews` for the bug the blanket resume caused (a preview left free-running behind
/// a paused editor, ending up on another clip's scene with the zoom regions filtered out).
struct PreviewPause(PausedPreviews<i32>);

impl PreviewPause {
    fn begin() -> Self {
        // A poisoned registry means some other napi call panicked mid-mutation; the export
        // itself is still worth running, we just have no previews we can speak for.
        Self(match registry().lock() {
            Ok(reg) => PausedPreviews::pause(reg.iter().map(|(id, view)| (*id, view))),
            Err(_) => PausedPreviews::default(),
        })
    }
}

impl Drop for PreviewPause {
    fn drop(&mut self) {
        if let Ok(reg) = registry().lock() {
            self.0.restore(reg.iter().map(|(id, view)| (*id, view)));
        }
    }
}

/// Convertit une fonction JS optionnelle en `ThreadsafeFunction` appelable depuis le thread
/// libuv qui exécute `Task::compute` — c'est la seule façon de rappeler JS depuis là. Chaque
/// appel transporte juste le nombre de frames encodées (`u32`) ; le JS connaît déjà le total
/// attendu (durée × fps des clips) et calcule le pourcentage lui-même.
fn make_progress_tsfn(
    f: Option<JsFunction>,
) -> Result<Option<ThreadsafeFunction<u32, ErrorStrategy::Fatal>>> {
    f.map(|f| f.create_threadsafe_function(0, |ctx| Ok(vec![ctx.value])))
        .transpose()
}

/// Un clip de la timeline pour l'export multiclip (JS : camelCase).
#[napi(object)]
pub struct ClipInput {
    pub screen_path: String,
    pub webcam_path: String,
    pub source_start_sec: f64,
    pub source_end_sec: f64,
    /// Décalage caméra (s) : temps source webcam = temps source screen - offset.
    pub webcam_offset_sec: f64,
    /// `false` évite une ouverture ffmpeg vouée à échouer et réserve du silence à ce clip.
    pub has_audio: bool,
}

/// The export's pixel size. The SHAPE belongs to the scene: `scene.output` is what the live
/// preview is sized from (`live.rs::preview_render_size`), so it is the only geometry an export
/// may have. Absent width/height take `scene.output`; a size of another shape is refused, because
/// the compositor would otherwise lay the preview's frame out on a different canvas and the file
/// would silently disagree with what the user saw (a 9:16 project exported 16:9). Only without a
/// scene does `default` apply. Both axes are snapped to even pixels (NV12 4:2:0).
fn resolve_output_size(
    scene: Option<&Scene>,
    width: Option<u32>,
    height: Option<u32>,
    default: (u32, u32),
) -> Result<(u32, u32)> {
    let even = |v: u32| v.max(2) & !1;
    let Some(scene) = scene else {
        return Ok((
            even(width.unwrap_or(default.0)),
            even(height.unwrap_or(default.1)),
        ));
    };
    let (ow, oh) = (
        scene.output.width.max(1) as u64,
        scene.output.height.max(1) as u64,
    );
    let (Some(w), Some(h)) = (width, height) else {
        return Ok((even(ow as u32), even(oh as u32)));
    };
    let (w, h) = (even(w), even(h));
    // 3% absorbs even-pixel snapping on small GIF sizes; a real shape change is far beyond it.
    if (w as u64 * oh).abs_diff(h as u64 * ow) * 100 > 3 * h as u64 * ow {
        return Err(Error::from_reason(format!(
            "export size {w}x{h} does not match the scene's output frame {ow}x{oh}"
        )));
    }
    Ok((w, h))
}

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

    fn portrait_scene() -> Scene {
        Scene::from_json(r##"{"clips":[],"layout":{"preset":"no-webcam","webcamSize":1,"webcamShape":"rectangle","webcamMirror":false,"webcamPosition":null,"webcamReactiveZoom":false},"effects":{"padding":0,"blur":false,"shadow":0,"roundnessFrac":0,"motionBlur":0},"background":{"kind":"color","color":"#000000"},"zoomRegions":[],"cursor":{"show":false,"size":1,"smoothing":0,"motionBlur":0,"clickBounce":0,"clipToBounds":false,"theme":"default"},"cropByClip":[],"output":{"width":1080,"height":1920,"fps":null}}"##).expect("parse")
    }

    #[test]
    fn export_size_follows_the_scene_shape() {
        let scene = portrait_scene();
        // No size sent: the scene's frame, never the 1920x1080 default (the 9:16 → 16:9 bug).
        assert_eq!(
            resolve_output_size(Some(&scene), None, None, (1920, 1080)).unwrap(),
            (1080, 1920)
        );
        // Same shape at another resolution (quality tier, GIF cap) is accepted.
        assert_eq!(
            resolve_output_size(Some(&scene), Some(720), Some(1280), (1920, 1080)).unwrap(),
            (720, 1280)
        );
        assert!(resolve_output_size(Some(&scene), Some(270), Some(480), (1920, 1080)).is_ok());
        // Another shape would stretch the preview's layout: refused.
        assert!(resolve_output_size(Some(&scene), Some(1920), Some(1080), (1920, 1080)).is_err());
        // Without a scene the default still applies.
        assert_eq!(resolve_output_size(None, None, None, (854, 480)).unwrap(), (854, 480));
    }
}

/// Taille/cadence/codec de sortie voulus par l'app (modale d'export). Tous optionnels :
/// taille absente → `scene.output` (cf. `resolve_output_size`), fps du 1er clip, h264.
#[napi(object)]
pub struct ExportParamsInput {
    pub width: Option<u32>,
    pub height: Option<u32>,
    pub fps: Option<u32>,
    /// "h264" | "h265". Toute autre valeur (ex. "vp9", pas d'équivalent matériel AMF) fait
    /// échouer l'export avec un message clair plutôt que de silencieusement retomber sur h264.
    pub codec: Option<String>,
    /// Débit vidéo visé, en bits/s, calculé par l'app d'après la taille et la cadence.
    /// Absent ou nul → le repli du pipeline, qui ignore la cadence.
    pub bitrate: Option<u32>,
}

/// Export multiclip mesuré (worker libuv). Rend la vraie timeline (clips + trims) en un MP4.
/// `scene_json` (optionnel) = la même scène que la preview live : fond/layout/webcam/curseur —
/// sans elle on ne retomberait QUE sur le layout fixture A↔B, plus du tout ce que l'utilisateur
/// a configuré (le bug corrigé ici). Layout/zoom restent statiques (pas encore de zoom regions
/// ni de camera-fullscreen animés côté export). Rend aux previews le transport qu'elles avaient
/// (même en erreur) — voir `PreviewPause`.
pub struct ExportMultiTask {
    out_path: String,
    clips: Vec<pipeline::ClipSource>,
    scene_json: Option<String>,
    params: Option<ExportParamsInput>,
    control: ExportControl,
    on_progress: Option<ThreadsafeFunction<u32, ErrorStrategy::Fatal>>,
}

impl Task for ExportMultiTask {
    type Output = (u32, f64, f64, f64);
    type JsValue = ExportStats;

    fn compute(&mut self) -> Result<Self::Output> {
        self.control.check().map_err(mp4_task_error)?;
        // Previews paused for the whole render (GPU 3D engine freed) and restored
        // exactly as found when this guard drops, including on the error paths.
        let _previews = PreviewPause::begin();
        // Même sélection que la preview : l'export d'un hôte sans GPU passe par
        // libopenh264 au lieu d'AMF, plutôt que d'échouer.
        let gpu = Gpu::create_auto(false).map_err(|e| Error::from_reason(format!("{e:#}")))?;
        self.control.check().map_err(mp4_task_error)?;
        let (cfg, scene) = export_cfg_and_scene(self.scene_json.as_deref());

        let mut export_params = pipeline::ExportParams::default();
        let (width, height) = resolve_output_size(
            scene.as_ref(),
            self.params.as_ref().and_then(|p| p.width),
            self.params.as_ref().and_then(|p| p.height),
            (export_params.width, export_params.height),
        )?;
        export_params.width = width;
        export_params.height = height;
        if let Some(p) = &self.params {
            export_params.fps = p.fps;
            export_params.bit_rate = p.bitrate.filter(|&b| b > 0).map(i64::from);
            if let Some(codec) = &p.codec {
                export_params.codec = match codec.as_str() {
                    "h264" => pipeline::ExportCodec::H264,
                    "h265" => pipeline::ExportCodec::H265,
                    other => {
                        return Err(Error::from_reason(format!(
                            "codec d'export \"{other}\" non supporté par le pipeline natif (h264/h265 seulement — pas d'équivalent matériel AMF pour VP9, et le chemin logiciel testé était trop lent pour être utile)"
                        )));
                    }
                };
            }
        }

        // Le compositeur rastérise à la taille RÉELLEMENT encodée — d'où sa
        // construction ici, une fois `export_params` résolu.
        //
        // Avant : il composait toujours en 1920×1080 puis `blit_resized` étirait
        // vers la taille d'export. Deux défauts, une seule cause — tout export
        // dépassant 1080p sur un axe était un AGRANDISSEMENT (un 4K portait le
        // quart de l'information), et tout ratio ≠ 16:9 devait passer par une
        // compensation géométrique. En construisant le compositeur à la
        // géométrie de sortie, `blit_resized` devient une identité et les pixels
        // sont rastérisés exactement là où ils seront encodés.
        let comp = Compositor::new_sized(&gpu, export_params.width, export_params.height)
            .map_err(|e| Error::from_reason(format!("{e:#}")))?;
        if let Some(scene) = &scene {
            comp.set_live_params(live_params_from_scene(scene));
        }
        comp.set_scene(scene);

        let mut progress = throttled_progress(self.on_progress.take());
        let s = pipeline::run_composited_multi_cancellable(
            &self.clips,
            &self.out_path,
            &gpu,
            &comp,
            &cfg,
            &export_params,
            &mut progress,
            &self.control,
        )
        .map_err(mp4_task_error)?;
        Ok((s.frames as u32, s.wall_s, s.fps, s.video_duration_s))
    }

    fn resolve(&mut self, _env: Env, out: Self::Output) -> Result<Self::JsValue> {
        Ok(ExportStats { frames: out.0, wall_s: out.1, fps: out.2, video_duration_s: out.3 })
    }
}

/// Le pendant MP4 de `create_gif_export_control` : même contrôle, passé à `export_multi`. Sa
/// présence dit aussi au TS que cet addon sait annuler un MP4 — un `.node` plus ancien ignore le
/// contrôle, et son export va au bout.
#[napi]
pub fn create_mp4_export_control() -> External<ExportControl> {
    External::new(ExportControl::default())
}

#[napi]
pub fn cancel_mp4_export(control: External<ExportControl>) -> bool {
    control.cancel()
}

fn mp4_task_error(error: anyhow::Error) -> Error {
    if error.is::<ExportCancelled>() {
        Error::from_reason("MP4_EXPORT_CANCELLED")
    } else {
        Error::from_reason(format!("{error:#}"))
    }
}

/// La config et la scène d'un rendu d'export (MP4, GIF, frames) : la C8 en layout statique, et ce
/// que la scène de l'app règle. Scène = même chemin que la preview live : fond, layout, webcam,
/// curseur. JSON absent ou invalide → pas de scène (fixture), pareil que si la preview n'en avait
/// jamais reçu : jamais un fallback masquant, juste rien de configuré.
fn export_cfg_and_scene(scene_json: Option<&str>) -> (config::Cfg, Option<Scene>) {
    let mut cfg = config::all().pop().expect("au moins une config"); // C8
    cfg.zoom = false;
    cfg.layout_anim = false;
    cfg.mblur_n = 1; // layout statique → pas de motion blur de layout (pas de surcoût)
    let scene = scene_json.and_then(|j| Scene::from_json(j).ok());
    match &scene {
        Some(scene) => {
            cfg.bg_blur = scene.effects.blur;
            cfg.cursor = scene.cursor.show;
        }
        None => cfg.cursor = false,
    }
    (cfg, scene)
}

fn clip_sources(clips: Vec<ClipInput>) -> Vec<pipeline::ClipSource> {
    clips
        .into_iter()
        .map(|c| pipeline::ClipSource {
            screen: c.screen_path,
            webcam: c.webcam_path,
            source_start_sec: c.source_start_sec,
            source_end_sec: c.source_end_sec,
            webcam_offset_sec: c.webcam_offset_sec,
            has_audio: c.has_audio,
        })
        .collect()
}

/// Une frame de `render_frames`.
#[napi(object)]
pub struct RenderedFrameOutput {
    /// Son indice sur la grille de sortie.
    pub index: u32,
    pub width: u32,
    pub height: u32,
    /// JPEG, qualité 85.
    pub jpeg: Buffer,
}

pub struct RenderFramesTask {
    clips: Vec<pipeline::ClipSource>,
    scene_json: Option<String>,
    fps: u32,
    frames: Vec<u32>,
    max_width: u32,
}

impl Task for RenderFramesTask {
    type Output = Vec<(u32, u32, u32, Vec<u8>)>;
    type JsValue = Vec<RenderedFrameOutput>;

    fn compute(&mut self) -> Result<Self::Output> {
        let reason = |e: anyhow::Error| Error::from_reason(format!("{e:#}"));
        let gpu = Gpu::create_auto(false).map_err(reason)?;
        let (cfg, scene) = export_cfg_and_scene(self.scene_json.as_deref());
        let default = pipeline::ExportParams::default();
        let (width, height) = resolve_output_size(scene.as_ref(), None, None, (default.width, default.height))?;
        // Un compositeur neuf attend la compilation des effets shader, comme celui de l'export.
        let comp = Compositor::new_sized(&gpu, width, height).map_err(reason)?;
        if let Some(scene) = &scene {
            comp.set_live_params(live_params_from_scene(scene));
        }
        comp.set_scene(scene);
        let wanted: Vec<u64> = self.frames.iter().map(|&f| u64::from(f)).collect();
        let frames = unsafe {
            openscreen_compositor::timeline_walk::render_frames(
                &self.clips,
                &gpu,
                &comp,
                &cfg,
                self.fps.max(1) as i32,
                &wanted,
            )
        }
        .map_err(reason)?;
        frames
            .into_iter()
            .map(|frame| {
                let index = frame.index as u32;
                let (w, h, jpeg) = frame.to_jpeg(self.max_width).map_err(reason)?;
                Ok((index, w, h, jpeg))
            })
            .collect()
    }

    fn resolve(&mut self, _env: Env, out: Self::Output) -> Result<Self::JsValue> {
        Ok(out
            .into_iter()
            .map(|(index, width, height, jpeg)| RenderedFrameOutput { index, width, height, jpeg: jpeg.into() })
            .collect())
    }
}

/// Rend des frames de la timeline sans l'exporter : `getFrames` quand l'export manque ou date
/// (`docs/shader-effects.md`, E.4). Mêmes clips et même scène qu'`export_multi`, mêmes pixels :
/// la marche est celle de l'export (`timeline_walk::render_frames`), sans encodage. `frames` sont
/// des indices sur la grille `fps` ; ceux au-delà de la timeline ne rendent rien. Les images sont
/// en JPEG, réduites à `max_width` de large.
#[napi]
pub fn render_frames(
    clips: Vec<ClipInput>,
    scene_json: Option<String>,
    fps: u32,
    frames: Vec<u32>,
    max_width: u32,
) -> AsyncTask<RenderFramesTask> {
    AsyncTask::new(RenderFramesTask { clips: clip_sources(clips), scene_json, fps, frames, max_width })
}

/// Lance un export multiclip natif (vraie timeline → MP4) et résout `Promise<ExportStats>`.
/// `scene_json` : même `SceneDescription` que la preview (fond/layout/webcam/effets/curseur).
/// `params` : taille/cadence/codec de sortie voulus (absent → 1920x1080/fps du 1er clip/h264).
/// `on_progress(framesEncodées)` optionnel — rappelé côté JS à ~10 Hz max pendant le rendu ;
/// le JS calcule lui-même le pourcentage (il connaît déjà le total attendu, durée×fps des clips).
/// `control` optionnel (`create_mp4_export_control`) : l'annuler arrête le rendu entre deux
/// frames, rejette avec `MP4_EXPORT_CANCELLED` et ne laisse aucun fichier.
#[napi]
pub fn export_multi(
    clips: Vec<ClipInput>,
    out_path: String,
    scene_json: Option<String>,
    params: Option<ExportParamsInput>,
    on_progress: Option<JsFunction>,
    control: Option<External<ExportControl>>,
) -> Result<AsyncTask<ExportMultiTask>> {
    let clips = clip_sources(clips);
    Ok(AsyncTask::new(ExportMultiTask {
        out_path,
        clips,
        scene_json,
        params,
        control: control.map(|c| (*c).clone()).unwrap_or_default(),
        on_progress: make_progress_tsfn(on_progress)?,
    }))
}

/// Sortie GIF native (slice 1) — taille, cadence, compteur de loop, dithering.
/// Tout optionnel : absent → 854×480, 12 fps, boucle infinie, dithering
/// Floyd-Steinberg. GIF est un format 256-couleurs et 12 fps est la cadence
/// historique de `gif.js` côté renderer.
#[napi(object)]
pub struct GifParamsInput {
    pub width: Option<u32>,
    pub height: Option<u32>,
    pub fps: Option<u32>,
    /// Nombre de lectures du GIF : `None` ou `0` = en boucle, `1` = une fois, `n` = n fois.
    pub loop_count: Option<u16>,
    /// Floyd-Steinberg error diffusion à la quantification. Actif par défaut :
    /// sans lui, un fond en dégradé se découpe en bandes (cf. `GifExportParams`).
    pub dither: Option<bool>,
}

/// Tâche d'export GIF (worker libuv, comme `ExportMultiTask`). Le
/// pipeline natif vit dans `openscreen_compositor::gif_export` ; ce
/// binding n'est qu'un adaptateur qui :
///   1. résout la `screen.cursor.json` sidecar selon la convention
///      `ExportDialog` (même chemin que `run_composited_multi` côté
///      MP4 — voir `pipeline.rs:1199`),
///   2. construit un `GifExportParams` à partir du `GifParamsInput`,
///   3. appelle `gif_export::export_gif` et reporte le `GifStats` au JS.
///
/// `cursor_path` est optionnel : un export sans curseur (utile pour
/// tester la pipeline) est légitime. La fonction côté Rust prend
/// `Option<&str>`, et `None` désactive le rendu du curseur côté
/// `Compositor` (équivalent de `cfg.cursor = false` dans
/// `run_composited_multi`).
#[napi]
pub fn create_gif_export_control() -> External<ExportControl> {
    External::new(ExportControl::default())
}

#[napi]
pub fn cancel_gif_export(control: External<ExportControl>) -> bool {
    control.cancel()
}

fn gif_task_error(error: anyhow::Error) -> Error {
    if error.is::<ExportCancelled>() {
        Error::from_reason("GIF_EXPORT_CANCELLED")
    } else {
        Error::from_reason(format!("{error:#}"))
    }
}

pub struct ExportGifTask {
    /// Same clip list the MP4 export takes — GIF is now a multiclip export
    /// driven by the same walk, not a single-file special case.
    clips: Vec<pipeline::ClipSource>,
    /// Scene JSON from the app, exactly as `exportMulti` receives it: it
    /// carries background, layout, webcam and cursor. Absent/invalid → no
    /// scene, same as a preview that was never configured.
    scene_json: Option<String>,
    out_path: PathBuf,
    params: GifExportParams,
    control: ExportControl,
    on_progress: Option<ThreadsafeFunction<u32, ErrorStrategy::Fatal>>,
}

impl Task for ExportGifTask {
    type Output = GifStats;
    type JsValue = GifExportStats;

    fn compute(&mut self) -> Result<Self::Output> {
        self.control.check().map_err(gif_task_error)?;
        // Mêmes garanties que `ExportMultiTask` : previews paused for the
        // whole render et restored exactement comme trouvées, y compris
        // sur les chemins d'erreur. L'export GPU+CPU ne partage pas le
        // RT avec la preview (sa propre `Compositor::new_sized`) mais le
        // 3D engine de la preview pollue quand même, d'où la pause.
        let _previews = PreviewPause::begin();

        // Same construction as ExportMultiTask — GIF and MP4 differ only in the
        // encoder, so everything up to it is built identically. That includes the
        // device: `create_auto`, not `create`. `create` is hardware-strict (goldens
        // and benches want to fail rather than measure a software rasteriser), so a
        // host without a usable GPU could export an MP4 but not a GIF — the one path
        // where the CPU backend exists specifically so the export still completes.
        let gpu = Gpu::create_auto(false).map_err(|e| Error::from_reason(format!("{e:#}")))?;
        self.control.check().map_err(gif_task_error)?;
        let (cfg, scene) = export_cfg_and_scene(self.scene_json.as_deref());

        let (width, height) = resolve_output_size(
            scene.as_ref(),
            self.params.width,
            self.params.height,
            (
                openscreen_compositor::gif_export::DEFAULT_GIF_WIDTH,
                openscreen_compositor::gif_export::DEFAULT_GIF_HEIGHT,
            ),
        )?;
        // `export_gif` reads its size back from the params; keep them the resolved one.
        self.params.width = Some(width);
        self.params.height = Some(height);
        let comp = Compositor::new_sized(&gpu, width, height)
            .map_err(|e| Error::from_reason(format!("{e:#}")))?;
        if let Some(scene) = &scene {
            comp.set_live_params(live_params_from_scene(scene));
        }
        comp.set_scene(scene);

        let mut progress = throttled_progress(self.on_progress.take());
        openscreen_compositor::gif_export::export_gif_cancellable(
            &self.clips,
            &self.out_path,
            &gpu,
            &comp,
            &cfg,
            &self.params,
            &mut progress,
            &self.control,
        )
        .map_err(gif_task_error)
    }

    fn resolve(&mut self, _env: Env, out: Self::Output) -> Result<Self::JsValue> {
        Ok(GifExportStats {
            frames: out.frames as u32,
            wall_s: out.wall_s,
            fps: out.fps,
            video_duration_s: out.video_duration_s,
            file_bytes: out.file_bytes as f64,
        })
    }
}

/// Lance un export GIF natif — le seul chemin GIF depuis la suppression de
/// l'exporteur `gif.js` — et résout `Promise<GifExportStats>`. `screen_path` et `webcam_path` sont
/// requis (la convention de l'app : deux fichiers H264 séparés, voir
/// `ClipInput` côté MP4). `cursor_path` est optionnel — s'il est `null` ou
/// pointe vers un fichier absent, l'export rend sans curseur (le `Player`
/// compose quand même les frames, la scène du curseur est juste vide).
/// `params` : taille, cadence, loop, dithering — tous optionnels, défauts
/// dans `GifExportParams::default`. `on_progress(framesProduced)` optionnel,
/// throttled à ~10/s comme l'export MP4 (voir `throttled_progress`).
#[napi]
pub fn export_gif(
    clips: Vec<ClipInput>,
    out_path: String,
    scene_json: Option<String>,
    params: Option<GifParamsInput>,
    on_progress: Option<JsFunction>,
    control: Option<External<ExportControl>>,
) -> Result<AsyncTask<ExportGifTask>> {
    // Deliberately the same argument shape as `export_multi`: the caller builds
    // one clip list and one scene, and picks the container. Cursor comes from
    // the scene like every other effect — there is no GIF-specific input left.
    let clips = clip_sources(clips);
    let gif_params = params
        .map(|p| GifExportParams {
            width: p.width,
            height: p.height,
            fps: p.fps,
            loop_count: p.loop_count,
            dither: p.dither.unwrap_or(GifExportParams::default().dither),
        })
        .unwrap_or_default();
    Ok(AsyncTask::new(ExportGifTask {
        clips,
        scene_json,
        out_path: PathBuf::from(out_path),
        params: gif_params,
        control: control.map(|c| (*c).clone()).unwrap_or_default(),
        on_progress: make_progress_tsfn(on_progress)?,
    }))
}

/// Bilan d'un remux, tel que le voit la glue TS.
#[napi(object)]
pub struct RemuxStats {
    /// Paquets recopiés, toutes pistes confondues. `f64` car napi n'expose pas
    /// `u64` — sans risque, un enregistrement plausible reste très loin de 2^53.
    pub packets: f64,
    pub streams: u32,
    pub wall_s: f64,
}

pub struct RemuxTask {
    input_path: String,
    output_path: String,
}

impl Task for RemuxTask {
    type Output = openscreen_compositor::remux::RemuxStats;
    type JsValue = RemuxStats;

    fn compute(&mut self) -> Result<Self::Output> {
        openscreen_compositor::remux::remux_to_seekable_matroska(&self.input_path, &self.output_path)
            .map_err(|e| Error::from_reason(format!("{e:#}")))
    }

    fn resolve(&mut self, _env: Env, out: Self::Output) -> Result<Self::JsValue> {
        Ok(RemuxStats {
            packets: out.packets as f64,
            streams: out.streams,
            wall_s: out.wall_s,
        })
    }
}

/// Recopie `input_path` vers `output_path` par le muxer matroska (aucun
/// ré-encodage) pour doter le fichier des `Cues`/`SeekHead` que `MediaRecorder`
/// n'écrit pas. Voir `openscreen_compositor::remux` pour le détail.
///
/// `AsyncTask` et pas une fonction synchrone : le remux lit et réécrit tout le
/// fichier, ce qui se compte en secondes sur un long enregistrement. Le faire
/// sur le thread principal de Node gèlerait la fenêtre pendant la sauvegarde,
/// exactement au moment où l'UI affiche « enregistrement en cours ».
///
/// `output_path` doit être un chemin TEMPORAIRE : c'est au caller TS de
/// renommer par-dessus l'original une fois la promesse résolue, pour qu'un échec
/// laisse l'enregistrement intact.
#[napi]
pub fn remux_seekable(input_path: String, output_path: String) -> AsyncTask<RemuxTask> {
    AsyncTask::new(RemuxTask {
        input_path,
        output_path,
    })
}

pub struct LoudnessGainTask {
    path: String,
}

impl Task for LoudnessGainTask {
    type Output = f64;
    type JsValue = f64;

    fn compute(&mut self) -> Result<Self::Output> {
        Ok(f64::from(openscreen_compositor::audio::loudness_gain_db(&self.path)))
    }

    fn resolve(&mut self, _env: Env, out: Self::Output) -> Result<Self::JsValue> {
        Ok(out)
    }
}

/// Le gain de normalisation de loudness (dB) que l'export applique à ce fichier voix — le
/// même nombre, par la même fonction, pour que la preview de l'éditeur joue la voix au
/// niveau où l'export l'écrira. Voir `openscreen_compositor::audio::loudness_gain_db`.
///
/// `AsyncTask` : la mesure décode tout l'audio du fichier, ce qui se compte en secondes sur
/// un long enregistrement. Le résultat est mis en cache dans le processus, donc l'export qui
/// suit ne le refait pas.
#[napi]
pub fn loudness_gain_db(path: String) -> AsyncTask<LoudnessGainTask> {
    AsyncTask::new(LoudnessGainTask { path })
}