grio 0.1.1

A fast, pure Rust alternative to Gradio with zero frontend dependencies
Documentation
//! Utilitaires média : inspection des data URLs (type, taille, dimensions) et
//! statistiques des flux de streaming (micro/caméra).
//!
//! Les composants `Image`/`Audio`/`Video` transportent leurs données comme
//! **data URLs** (`data:<mime>;base64,…`), pageable par `ctx.get::<String>`.
//! `inspect` décode l'en-tête pour en extraire le type, la taille en octets
//! et les dimensions (PNG, JPEG, GIF — les autres: `None`).

use base64::Engine;
use serde::{Deserialize, Serialize};

/// Informations extraites d'une data URL média.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct MediaInfo {
    /// Type MIME (ex. `image/png`).
    pub mime: String,
    /// Taille du contenu décodé, en octets.
    pub size_bytes: usize,
    /// Largeur en pixels, si détectable (PNG/JPEG/GIF).
    pub width: Option<u32>,
    /// Hauteur en pixels, si détectable (PNG/JPEG/GIF).
    pub height: Option<u32>,
}

impl MediaInfo {
    /// Famille de contenu (`image`, `audio`, `video`).
    pub fn kind(&self) -> &str {
        self.mime.split('/').next().unwrap_or("")
    }

    /// Judgée affichable sous forme d'un résumé court et lisible.
    pub fn description(&self) -> String {
        let dims = match (self.width, self.height) {
            (Some(w), Some(h)) => format!("{w}×{h} px"),
            _ => "dimensions inconnues".to_string(),
        };
        format!("{} · {} · {} o", self.mime, dims, self.size_bytes)
    }
}

/// Statistiques d'un flux reçu en streaming (`{t:"stream"}`) pour un composant.
///
/// Sérialisé dans les valeurs partagées du serveur : un handler branché sur
/// l'événement `"stream"` peut le lire via `ctx.get::<StreamInfo>(id)`.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct StreamInfo {
    /// Type MIME du flux (ex. `audio/webm`).
    pub mime: String,
    /// Octets reçus au total.
    pub bytes: u64,
    /// Fragments reçus.
    pub chunks: u64,
}

impl StreamInfo {
    /// Octets reçus, arrondis en kilo-octets.
    pub fn kb(&self) -> f64 {
        self.bytes as f64 / 1024.0
    }
}

/// Sépare une data URL en `(mime, données_base64)`.
pub fn split_data_url(data_url: &str) -> Option<(String, String)> {
    let rest = data_url.strip_prefix("data:")?;
    let (meta, data) = rest.split_once(',')?;
    let mime = meta
        .split(';')
        .next()
        .unwrap_or("application/octet-stream")
        .to_string();
    Some((mime, data.to_string()))
}

/// Inspecte une data URL : type, taille et dimensions (quand détectable).
pub fn inspect(data_url: &str) -> Option<MediaInfo> {
    let (mime, data) = split_data_url(data_url)?;
    let bytes = decode(&data)?;
    let size = bytes.len();
    if size == 0 {
        return None;
    }
    let (width, height) = dimensions(&mime, &bytes);
    Some(MediaInfo {
        mime,
        size_bytes: size,
        width,
        height,
    })
}

/// Encode des octets en chaîne base64 standard.
pub fn encode(bytes: &[u8]) -> String {
    base64::engine::general_purpose::STANDARD.encode(bytes)
}

/// Décode des données base64 (URL-safe accepté).
pub fn decode(b64: &str) -> Option<Vec<u8>> {
    base64::engine::general_purpose::STANDARD
        .decode(b64)
        .or_else(|_| base64::engine::general_purpose::URL_SAFE.decode(b64))
        .ok()
}

/// Dimensions détectées dans l'en-tête. Non-détectable → `(None, None)`.
fn dimensions(mime: &str, b: &[u8]) -> (Option<u32>, Option<u32>) {
    match mime {
        "image/png" if b.len() >= 24 && &b[0..8] == b"\x89PNG\r\n\x1a\n" => (
            Some(u32::from_be_bytes([b[16], b[17], b[18], b[19]])),
            Some(u32::from_be_bytes([b[20], b[21], b[22], b[23]])),
        ),
        "image/gif" if b.len() >= 10 && &b[0..3] == b"GIF" => (
            Some(u16::from_le_bytes([b[6], b[7]]) as u32),
            Some(u16::from_le_bytes([b[8], b[9]]) as u32),
        ),
        "image/jpeg" => jpeg_dimensions(b),
        _ => (None, None),
    }
}

/// Parcourt les segments JPEG à la recherche d'un cadre (SOF) pour les
/// dimensions.
fn jpeg_dimensions(b: &[u8]) -> (Option<u32>, Option<u32>) {
    if b.len() < 4 || b[0] != 0xFF || b[1] != 0xD8 {
        return (None, None);
    }
    let mut i = 2usize;
    while i + 9 < b.len() {
        if b[i] != 0xFF {
            i += 1;
            continue;
        }
        let marker = b[i + 1];
        let sof = (0xC0..=0xCF).contains(&marker) && !matches!(marker, 0xC4 | 0xC8 | 0xCC);
        if sof {
            let h = u16::from_be_bytes([b[i + 5], b[i + 6]]);
            let w = u16::from_be_bytes([b[i + 7], b[i + 8]]);
            return (Some(w as u32), Some(h as u32));
        }
        let len = u16::from_be_bytes([b[i + 2], b[i + 3]]);
        if len < 2 {
            break;
        }
        i += 2 + len as usize;
    }
    (None, None)
}

/// Format d'encodage pour le flux audio temps réel.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AudioFormat {
    /// PCM 16-bit signé (16 000 Hz, mono) - Standard pour Whisper et VAD.
    Pcm16KHzMono,
    /// PCM 16-bit signé (48 000 Hz, mono) - Qualité standard navigateur.
    Pcm48KHzMono,
    /// PCM 16-bit signé (48 000 Hz, stéréo).
    Pcm48KHzStereo,
    /// PCM 32-bit flottant (16 000 Hz, mono, plage [-1.0, 1.0]).
    F32_16KHzMono,
    /// Opus / Ogg compressé (faible bande passante).
    Opus,
    /// Données binaires brutes non typées.
    RawBytes,
}

impl Default for AudioFormat {
    fn default() -> Self {
        Self::Pcm16KHzMono
    }
}

/// Fragment audio temps réel échangé entre le client et le serveur.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct AudioChunk {
    /// Format audio.
    pub format: AudioFormat,
    /// Taux d'échantillonnage en Hz (ex: 16000, 48000).
    pub sample_rate: u32,
    /// Nombre de canaux (1 = mono, 2 = stéréo).
    pub channels: u16,
    /// Données binaires brutes du fragment.
    pub data: Vec<u8>,
}

impl AudioChunk {
    /// Crée un nouveau fragment audio avec métadonnées explicites.
    pub fn new(format: AudioFormat, sample_rate: u32, channels: u16, data: Vec<u8>) -> Self {
        Self {
            format,
            sample_rate,
            channels,
            data,
        }
    }

    /// Crée un fragment audio PCM 16kHz mono depuis des échantillons 16-bit entiers.
    pub fn pcm16_mono(samples: &[i16]) -> Self {
        let mut data = Vec::with_capacity(samples.len() * 2);
        for &s in samples {
            data.extend_from_slice(&s.to_le_bytes());
        }
        Self {
            format: AudioFormat::Pcm16KHzMono,
            sample_rate: 16000,
            channels: 1,
            data,
        }
    }

    /// Crée un fragment audio PCM depuis des échantillons flottants `f32` (plage [-1.0, 1.0]).
    pub fn from_f32_slice(samples: &[f32], sample_rate: u32) -> Self {
        let mut data = Vec::with_capacity(samples.len() * 2);
        for &s in samples {
            let clamped = s.clamp(-1.0, 1.0);
            let sample_i16 = (clamped * 32767.0) as i16;
            data.extend_from_slice(&sample_i16.to_le_bytes());
        }
        let format = if sample_rate == 16000 {
            AudioFormat::Pcm16KHzMono
        } else {
            AudioFormat::Pcm48KHzMono
        };
        Self {
            format,
            sample_rate,
            channels: 1,
            data,
        }
    }

    /// Décode le buffer sous forme d'échantillons flottants normalisés `f32` [-1.0, 1.0].
    pub fn as_f32_vec(&self) -> Vec<f32> {
        let mut out = Vec::with_capacity(self.data.len() / 2);
        for chunk in self.data.chunks_exact(2) {
            let s = i16::from_le_bytes([chunk[0], chunk[1]]);
            out.push(s as f32 / 32768.0);
        }
        out
    }

    /// Décode le buffer sous forme d'échantillons entiers signés 16-bit `i16`.
    pub fn as_i16_vec(&self) -> Vec<i16> {
        let mut out = Vec::with_capacity(self.data.len() / 2);
        for chunk in self.data.chunks_exact(2) {
            out.push(i16::from_le_bytes([chunk[0], chunk[1]]));
        }
        out
    }

    /// Durée approximative du fragment en secondes.
    pub fn duration_sec(&self) -> f32 {
        if self.sample_rate == 0 || self.channels == 0 {
            return 0.0;
        }
        let bytes_per_sample = 2; // 16-bit
        let total_samples = self.data.len() / (bytes_per_sample * self.channels as usize);
        total_samples as f32 / self.sample_rate as f32
    }
}

/// État de détection de voix (Voice Activity Detection).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum VadState {
    /// Début de détection de parole (parole active).
    Start,
    /// Fin de détection de parole (silence).
    Stop,
}

/// Événement émis par le module VAD côté client.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct VadEvent {
    /// Identifiant du composant audio.
    pub id: String,
    /// État de la voix (début ou fin de parole).
    pub state: VadState,
    /// Timestamp Unix en millisecondes.
    pub timestamp_ms: u64,
    /// Niveau d'énergie audio détecté (optionnel, 0.0 - 1.0).
    pub energy: Option<f32>,
}

/// Masque de segmentation polygonal pour les flux de vision.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct PolygonMask {
    /// Points normalisés `[x, y]` dans la plage `0.0..=1.0`.
    pub points: Vec<[f64; 2]>,
    /// Étiquette de la segmentation (ex: `"person"`, `"road"`).
    pub label: String,
    /// Couleur de remplissage/contour (ex: `"#10b981"`).
    pub color: String,
    /// Opacité du masque (0.0 à 1.0).
    pub opacity: f32,
}

impl PolygonMask {
    /// Crée un nouveau masque polygonal.
    pub fn new(label: impl Into<String>, color: impl Into<String>, points: Vec<[f64; 2]>) -> Self {
        Self {
            points,
            label: label.into(),
            color: color.into(),
            opacity: 0.35,
        }
    }
}

/// Point clé (keypoint) pour la détection de squelette/pose ou de visages.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct Keypoint {
    /// Coordonnée X normalisée `0.0..=1.0`.
    pub x: f64,
    /// Coordonnée Y normalisée `0.0..=1.0`.
    pub y: f64,
    /// Nom ou rôle du point (ex: `"nose"`, `"left_eye"`, `"wrist"`).
    pub label: Option<String>,
    /// Score de confiance `0.0..=1.0`.
    pub score: Option<f64>,
    /// Couleur optionnelle spécifique au point.
    pub color: Option<String>,
}

/// Squelette de pose (pose estimation) composé de points clés connectés.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct PoseSkeleton {
    /// Liste des points clés du squelette.
    pub keypoints: Vec<Keypoint>,
    /// Paires d'indices reliant les points clés `(from_idx, to_idx)`.
    pub connections: Vec<(usize, usize)>,
    /// Couleur principale des lignes du squelette.
    pub color: String,
}

/// Ensemble complet d'overlays GPU de vision superposés sur un flux vidéo / caméra.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
pub struct VisionOverlay {
    /// Boîtes englobantes annotées.
    pub boxes: Vec<crate::components::BoundingBox>,
    /// Masques de segmentation polygonaux.
    pub polygons: Vec<PolygonMask>,
    /// Squelettes de pose.
    pub skeletons: Vec<PoseSkeleton>,
    /// Télémétrie optionnelle de cadence d'inférence (FPS).
    pub fps: Option<f64>,
}

impl VisionOverlay {
    /// Crée un overlay de vision vide.
    pub fn new() -> Self {
        Self::default()
    }

    /// Ajoute une boîte englobante.
    pub fn with_box(mut self, bbox: crate::components::BoundingBox) -> Self {
        self.boxes.push(bbox);
        self
    }

    /// Ajoute une liste de boîtes englobantes.
    pub fn with_boxes(mut self, boxes: Vec<crate::components::BoundingBox>) -> Self {
        self.boxes = boxes;
        self
    }

    /// Ajoute un masque polygonal.
    pub fn with_polygon(mut self, poly: PolygonMask) -> Self {
        self.polygons.push(poly);
        self
    }

    /// Ajoute un squelette de pose.
    pub fn with_skeleton(mut self, skeleton: PoseSkeleton) -> Self {
        self.skeletons.push(skeleton);
        self
    }

    /// Renseigne le badge de FPS.
    pub fn with_fps(mut self, fps: f64) -> Self {
        self.fps = Some(fps);
        self
    }
}